Skip to contents

as_summarized_experiment

Source: R/utils-df.R
as_summarized_experiment.Rd

Constructs a SummarizedExperiment object from input data frames for downstream lipidomics analysis.

Usage

as_summarized_experiment(
  abundance,
  goslin_annotation = NULL,
  group_info = NULL,
  se_type = "profiling",
  paired_sample = FALSE
)

Arguments

abundance

A data frame of lipid abundance data with the following structure:

  • Column 1 (feature): a character column of unique lipid species names used for feature-level analysis and lipid recognition/mapping. Must be named "feature". No duplicate or missing values are allowed.

  • Columns 2 to N: numeric columns of sample abundance values, one column per sample. Column names must match the sample_name values in group_info. NAs are allowed.

goslin_annotation

A data frame of lipid structural annotations returned by parseLipidNames from the rgoslin package. Before passing this data frame to the function, remove any rows where the Grammar column is 'NOT_PARSEABLE', as these entries represent lipid names that could not be mapped to a recognised lipid grammar and are not supported for downstream analysis. The corresponding lipids should also be removed from abundance. Required for all lipidomics se_type options ("profiling", "de_two", "de_multiple", "ml", "corr"). Must be NULL when se_type = "rna", since non-lipidomics abundance data has no lipid structural annotation.

group_info

A data frame containing sample metadata. The required structure depends on the se_type selected:

"profiling"

No group_info is required; this argument is optional and can be omitted.

"de_two"

Required. Compares lipid abundance between exactly two groups, with optional paired design support. Must contain the following columns in order: sample_name, label_name, group, pair.

  • sample_name: unique sample identifiers that match the column names in abundance exactly. No NAs allowed.

  • label_name: human-readable label for each sample (e.g., ctrl1, hfref9). No NAs allowed.

  • group: biological group used for differential abundance testing. Must contain exactly 2 unique values. No NAs allowed.

  • pair: paired design indicator. If samples are paired, provide sequential integer identifiers (e.g., 1 to N) with no gaps or missing values. If samples are unpaired, set all values to NA.

"de_multiple"

Required. Same structure as "de_two" but for comparisons across more than two groups. The group column must contain more than 2 unique values. The pair column is not required and should be omitted. Must contain the following columns in order: sample_name, label_name, group.

"ml"

Required. Provides the outcome label for model training. Must contain the following columns in order: sample_name, group.

  • sample_name: unique sample identifiers that match the column names in abundance exactly. No NAs allowed.

  • group: the class label the model learns to predict. For binary classification, must be encoded as 0/1. No NAs allowed. Note: this is a prediction outcome label, not an experimental group for statistical testing.

"corr"

Required. Associates lipid abundance with continuous or categorical phenotype variables for correlation and/or regression analysis. Must contain the following columns:

  • sample_name: unique sample identifiers that match the column names in abundance exactly. No NAs allowed.

  • Two or more phenotype or clinical variable columns (e.g., Age, BMI, Smoking). Unlike other se_type options, there is no single group column; multiple phenotype columns are provided instead. Categorical variables must be pre-encoded as numeric values (e.g., binary categories as 0/1) before input.

"rna"

Required. se_type = "rna" builds a SummarizedExperiment for non-lipidomics abundance data (e.g. RNA expression) that is meant to feed downstream Multi-Omics analysis (see as_MultiAssayExperiment) rather than one of the 4 lipidomics analysis designs above. group_info must be provided; its format is auto-detected from the column layout and must match one of the following two lipidomics layouts ("ml"/"corr" layouts are not supported for "rna"):

  • 4 columns, sample_name, label_name, group, pair (same layout as "de_two"): group must contain exactly 2 unique values; paired design is inferred directly from the pair column (all NA = unpaired, sequential integers = paired) rather than a separate paired_sample argument.

  • 3 columns, sample_name, label_name, group (same layout as "de_multiple"): group must contain more than 2 unique values, each with more than 2 samples.

In both cases sample_name must match the column names in abundance exactly with no duplicates, and no NAs are allowed in sample_name, label_name, or group.

se_type

A character string specifying the analysis type for which the SummarizedExperiment object is constructed. Default is 'profiling'. Must be one of:

  • "profiling": lipid profiling and visualisation.

  • "de_two": differential abundance analysis between two groups.

  • "de_multiple": differential abundance analysis across multiple groups.

  • "ml": machine learning classification.

  • "corr": correlation and regression analysis with phenotype variables.

  • "rna": non-lipidomics (e.g. RNA) abundance data intended for downstream Multi-Omics analysis. When se_type = "rna", goslin_annotation is not used and must be NULL (no lipid characteristics table is built).

paired_sample

Logical or NULL. For two-group analysis (se_type = "de_two"), set to TRUE if the samples are paired or FALSE if unpaired. For all other se_type options (including "de_multiple", "ml", "corr"), set to NULL. For se_type = "rna" the argument is not used and any value is ignored.

Value

A SummarizedExperiment object configured for the specified analysis type.

Examples

library(dplyr)
data("abundance_twoGroup")
data("group_info_twoGroup")
parse_lipid <- rgoslin::parseLipidNames(lipidNames=abundance_twoGroup$feature)
#> Encountered an error while parsing 'SE 27:1;0-14:0;0': Expecting a single string value: [type=character; extent=4].
#> Encountered an error while parsing 'SE 27:1;0-15:0;0': Expecting a single string value: [type=character; extent=4].
#> Encountered an error while parsing 'SE 27:1;0-16:0;0': Expecting a single string value: [type=character; extent=4].
#> Encountered an error while parsing 'SE 27:1;0-16:1;0': Expecting a single string value: [type=character; extent=4].
#> Encountered an error while parsing 'SE 27:1;0-17:0;0': Expecting a single string value: [type=character; extent=4].
#> Encountered an error while parsing 'SE 27:1;0-17:1;0': Expecting a single string value: [type=character; extent=4].
#> Encountered an error while parsing 'SE 27:1;0-18:1;0': Expecting a single string value: [type=character; extent=4].
#> Encountered an error while parsing 'SE 27:1;0-18:2;0': Expecting a single string value: [type=character; extent=4].
#> Encountered an error while parsing 'SE 27:1;0-18:3;0': Expecting a single string value: [type=character; extent=4].
#> Encountered an error while parsing 'SE 27:1;0-19:2;0': Expecting a single string value: [type=character; extent=4].
#> Encountered an error while parsing 'SE 27:1;0-19:3;0': Expecting a single string value: [type=character; extent=4].
#> Encountered an error while parsing 'SE 27:1;0-20:2;0': Expecting a single string value: [type=character; extent=4].
#> Encountered an error while parsing 'SE 27:1;0-20:4;0': Expecting a single string value: [type=character; extent=4].
#> Encountered an error while parsing 'SE 27:1;0-20:5;0': Expecting a single string value: [type=character; extent=4].
#> Encountered an error while parsing 'SE 27:1;0-22:6;0': Expecting a single string value: [type=character; extent=4].
#> Encountered an error while parsing 'ST 27:1;0': Expecting a single string value: [type=character; extent=4].
recognized_lipid <- parse_lipid$Original.Name[which(parse_lipid$Grammar != 'NOT_PARSEABLE')]
abundance <- abundance_twoGroup %>% dplyr::filter(feature %in% recognized_lipid)
goslin_annotation <- parse_lipid %>% dplyr::filter(Original.Name %in% recognized_lipid)
se <- as_summarized_experiment(abundance, goslin_annotation,
     group_info=group_info_twoGroup, se_type='de_two', paired_sample=FALSE)
#> Input data info 
#> se_type: de_two
#> Number of lipids (features) available for analysis: 192
#> Number of samples: 23
#> Number of group: 2
#> Not paired samples.