volcano3D (version 1.2.0)

polar_coords: Coordinates for Three Way Polar Plot

Description

This function creates a polar object of S4 class for downstream plots containing the p-values from a three-way group comparison, expression data sample data and polar coordinates.

Usage

polar_coords(
  sampledata,
  contrast,
  pvalues,
  expression,
  groups = NULL,
  p_col_suffix = "pvalues",
  padj_col_suffix = "padj",
  fc_col_suffix = NULL,
  padjust_method = "BH",
  multi_group_prefix = NULL,
  non_sig_name = "Not Significant",
  significance_cutoff = 0.01,
  fc_cutoff = 0.3,
  label_column = NULL,
  cutoff_criteria = "pvalue"
)

Arguments

sampledata

A data frame containing the sample information. This must contain: an ID column containing the sample IDs which can be matched to the `expression` data and a contrast column containing the three-level factor used for contrasts.

contrast

The column name in `sampledata` which contains the three-level factor used for contrast.

pvalues

A data frame containing:

• three `p_col_suffix` columns: one for the pvalue for each comparison between groups;

• three optional `fc_col_suffix` columns for the fold change between each comparison (if NULL, no Fold Change columns are included);

• three optional `padj_col_suffix` columns (if NULL adjusted p values are calculated using `padjust_method`);

• and optional 'p', 'padj and 'fc' columns for a three-way test, such as ANOVA or likelihood ratio test, defined by `multi_group_prefix`.

expression

An optional data frame containing expression data for downstream analysis and visualisation. The rows must contain probes which match the rows in pvalues and the columns must contain samples which match sampledata$ID.

groups

The groups to be compared (if NULL this defaults to levels(sampledata[, 'contrasts'])).

p_col_suffix

The suffix word to define columns containing p values (default = 'pvalues'). These must not contain underscores;

padj_col_suffix

The suffix word to define columns containing adjusted p values (default = 'padj'). These must not contain underscores. If NULL these will be calculated using padjust_method

fc_col_suffix

The optional suffix word to define columns containing log fold change values (default = 'logFC'). These must not contain underscores.

padjust_method

The method used to calculate adjusted p values if padj_col_suffix is NULL (default = 'BH'). See p.adjust. If NULL no adjusted pvalue is calculated.

multi_group_prefix

Optional column prefix for statistics (p, padj, and fold change) across all three groups (typically ANOVA or likelihood ratio tests). default = NULL. These must not contain underscores

non_sig_name

Category name to assign to non-significant points

significance_cutoff

Value defining the significance cut-off (points with pvalues below this point will be classed as non_sig_name)

fc_cutoff

The cut-off for fold change, below which markers will be classed as non_sig_name` (default = 0.3).

label_column

Optional column name in pvalues for markers to be labelled with at plotting stage. If NULL the rownames of pvalues are used.

cutoff_criteria

Whether to use pvalue or padj for the colour coding significance cutoff.

Value

Returns an S4 polar object containing:

• 'polar' A data.frame containing:

  • The mean expression for each of the three groups in comparison

  • The z-score polar coordinates: 'y_zscore', 'x_zscore' and 'r_zscore'

  • The fold-change polar coordinates: 'y_fc', 'x_fc' and 'r_fc'

  • 'angle': The angle in radians for polar coordinates

  • 'angle_degrees': The angle in degrees

  • 'max_exp': The maximally expressed group

  • 'sig': The significance group

• 'pvalues' A data frame containing the p-values, adjusted p-values, and optional log(fold changes) for all three comparisons between groups in the contrast factor, as well as optional multi-group tests.

• 'sampledata' Sample data with column ID and contrast

• 'contrast' The column name in `sampledata`` which contains the three-group contrast factor used for comparisons.

• 'multi_group_test' Column name prefix for statistical tests between all three groups

• 'expression' An optional data frame or matrix containing the expression data

• 'non_sig_name' The category name for variables which are classed as not significant

References

Lewis, Myles J., et al. (2019). Molecular portraits of early rheumatoid arthritis identify clinical and treatment response phenotypes. Cell reports, 28:9

Examples

# NOT RUN {
data(example_data)
syn_polar <- polar_coords(sampledata=syn_example_meta,
                    contrast="Pathotype",
                    groups = NULL,
                    pvalues = syn_example_p,
                    expression = syn_example_rld,
                    p_col_suffix = "pvalue",
                    padj_col_suffix = "padj",
                    fc_col_suffix = NULL,
                    padjust_method = "BH",
                    multi_group_prefix = NULL,
                    non_sig_name = "Not Significant",
                    significance_cutoff = 0.01, 
                    fc_cutoff=0.3, 
                    label_column = NULL)
table(syn_polar@polar$sig) 
# }