fg_get_summary {flowGraph} | R Documentation

## Retrieves a summary statistic.

### Description

Retrieves a summary statistic from a given flowGraph object; while `fg` is required, the user can choose to input parameters `summary_meta`, `index`, or all of `type`, `feat`, `test_name`, `class`, `label1`, and `label2`. See `fg_get_summary_desc` for details.

### Usage

    fg_get_summary(
      fg,
      type = "node",
      index = NULL,
      summary_meta = NULL,
      adjust_custom = "byLayer",
      SpecEnr_filt = TRUE,
      summary_fun = colMeans,
      adjust0_lim = c(-0.1, 0.1),
      filter_adjust0 = 1,
      filter_es = 0,
      filter_btwn_tpthres = 0.05,
      filter_btwn_es = 0.5,
      default_p_thres = 1
    )

### Arguments

`fg` | flowGraph object.
`type` | A string indicating feature type the summary was created for 'node' or 'edge'.
`index` | The user must provide `type` and additionally, one of `summary_meta` or `index`. `index` is an integer indicating the row in `fg_get_summary_desc(<flowGraph>)` of the corresponding type and summary the user would like to retrieve.
`summary_meta` | The user must provide `type` and additionally, one of `summary_meta` or `index`. `summary_meta` is a list containing `feat` (feature name), `test_name` (summary statistic name), `class` (class), `label1`, and `label2` (class labels compared). See `fg_get_summary_desc` for details.
`adjust_custom` | A function or a string indicating the test adjustment method to use. If a string is provided, it should be one of `c("holm", "hochberg", "hommel", "bonferroni", "BH", "BY", "fdr", "none")` (see `p.adjust.methods`). If a function is provided, it should take as input a numeric vector and output the same vector adjusted.
`SpecEnr_filt` | A logicle indicating whether or not to filter p-values for SpecEnr.
`summary_fun` | A function that takes in a matrix and outputs a vector the same length as the number of columns this matrix has. Set to `NULL` to not calculate this summary (i.e. returned list will not contain `m1` and `m2`). See `fg_get_feature_means`.
`adjust0_lim` | A vector of two numeric values indicating a range around 0, default set to -0.1 and 0.1.
`filter_adjust0` | A numeric variable indicating what percentage of SpecEnr values compared (minimum) should be not close to 0. Set to 1 to not conduct filtering. Original p-values stored in `values_original`.
`filter_es` | A numeric variable between 0 and 1 indicating what the Cohen's D value of the nodes/edges in question must be greater or equal to, to be significant.
`filter_btwn_tpthres` | A numeric variable between 0 and 1 indicating the unadjusted T-test p-value threshold used to test whether the actual and expected feature values used to calculate the specified SpecEnr feature are significantly different for each sample class. Note this only needs to be specified for SpecEnr features. Combined with `filter_btwn_es`, we conduct three tests to understand if there is an actual large difference between actual and expected features: (1,2) T-test of significance between the actual and expected raw feature value (e.g. proportion) for samples in each of the compared classes, (3) and the T-test of significance between the differences of actual and expected feature values of the two classes. If any two of the three tests come out as insignificant, we set the p-value for the associated node/edge to 1.
`filter_btwn_es` | A numeric variable between 0 and 1 indicating what the Cohen's D value of the nodes/edges in question must be greater or equal to, to be significant – see `filter_btwn_tpthres`.
`default_p_thres` | A numeric variable indicating the p-value threshold user is using. Currently, all nodes/edges not passing the `filter` criterion will be defaulted to 1; if this parameter is set, then all of these nodes/edges will be set to a minimum of `default_p_thres`.

### Value

A list containing elements on feature summary retrieved by the user as in the `summary` slot of `flowGraph-class`. If `summary_fun` is not `NULL`, this list also includes:

- `m1`: a numeric vector the same length as `values`; this is a summary of the samples compared e.g. mean.

- `m2`: a numeric vector the same length as `values`; this is a summary of the samples compared e.g. mean.

- `cohensd`: a numberic vector indicating cohen's d values considering effect size.

- `cohensd_size`: a factor vector interpreting cohen's d values.

- `adjust0`: a numeric vector indicating the percentage of samples that have a SpecEnr value in the range of `adjust0_lim` around 0; if there are two classes of samples being compared, we output the smaller percentage between the two classes.

- `btwn`: a data frame containing columns:

  - `tpv1`: unadjusted p-value calculated between the actual and expected raw feature values of class 1.

  - `tpv2`: unadjusted p-value calculated between the actual and expected raw feature values of class 2.

  - `cd1`: Cohen's D between the actual and expected raw feature values of class 1.

  - `cd2`: Cohen's D between the actual and expected raw feature values of class 2.

  - `btp`: unadjusted p-value calculated between the difference between actual and expected raw feature of the two classes.

  - `bcd`: Cohen's D calculated between the difference between actual and expected raw feature of the two classes.

  - `btp_`: unadjusted p-value calculated between the log ratio between actual and expected raw feature of the two classes.

  - `bcd_`: Cohen's D calculated between the log ratio between actual and expected raw feature of the two classes.

### See Also

`flowGraph-class` `fg_get_feature_means` `fg_get_summary_desc` `fg_add_summary` `fg_rm_summary` `fg_get_feature`

### Examples

     no_cores <- 1
     data(fg_data_pos30)
     fg <- flowGraph(fg_data_pos30$count, class=fg_data_pos30$meta$class,
                     no_cores=no_cores)

     # set features to NULL to apply summary statistic to all features.
     fg <- fg_summary(fg, no_cores=no_cores, class="class", label1="control",
                      overwrite=FALSE, test_name="t", diminish=FALSE,
                      node_features=NULL, edge_features=NULL)
     show(fg)

     feat_summ <- fg_get_summary(fg, type="node", summary_meta=list(
         feature="SpecEnr", test_name="t", class="class",
         label1="control", label2="exp"))

[Package flowGraph version 1.2.0 Index]