Type:	Package
Title:	Integrative Visualizations of the Lipidome
Version:	0.1.2
Description:	Create lipidome-wide heatmaps of statistics with the 'lipidomeR'. The 'lipidomeR' provides a streamlined pipeline for the systematic interpretation of the lipidome through publication-ready visualizations of regression models fitted on lipidomics data. With 'lipidomeR', associations between covariates and the lipidome can be interpreted systematically and intuitively through heatmaps, where lipids are categorized by the lipid class and are presented on two-dimensional maps organized by the lipid size and level of saturation. This way, the 'lipidomeR' helps you gain an immediate understanding of the multivariate patterns in the lipidome already at first glance. You can create lipidome-wide heatmaps of statistical associations, changes, differences, variation, or other lipid-specific values. The heatmaps are provided with publication-ready quality and the results behind the visualizations are based on rigorous statistical models.
License:	GPL-3
Encoding:	UTF-8
LazyData:	true
URL:	https://tommi-s.github.io/
RoxygenNote:	7.0.2
Depends:	R (≥ 3.5.0)
Imports:	BiocManager, dplyr, ggplot2, knitr, limma, reshape2, shadowtext, stringr, tableone, tidyr
NeedsCompilation:	no
Packaged:	2020-03-06 18:08:12 UTC; tomsuv
Author:	Tommi Suvitaival [aut, cre]
Maintainer:	Tommi Suvitaival <TSUV0001@RegionH.DK>
Repository:	CRAN
Date/Publication:	2020-03-15 10:20:02 UTC

Levels of lipids in benign and malignant breast tumors in humans.

Description

This data set contains levels of 409 named lipids in 118 human breast tumor tissue samples.

Usage

data( cancerlipidome )

Format

A long-format data frame with 48262 rows and 7 variables:

ID

Participant number

Group

Diagnosis of the type tumor: benign, cancer, or metastasis

Race

Ethnic background of the participant

Stage

Diagnosis of the stage of the tumor

Type

Sub-type of the breast tumor. IDC: Invasive Ductal Carcinoma

Lipid_Name

Name of the lipid. The names are in the format 'XY(C:D)', where 'XY' is the abbreviation of the lipid class, 'C' is the total number of carbon atoms in the fatty-acid chains, and 'D' is the total number of double-bonds in the fatty acid chains.

Lipid_Level

Measured level of the lipid.

Source

This data is available at the NIH Common Fund's National Metabolomics Data Repository (NMDR) website, the Metabolomics Workbench, https://www.metabolomicsworkbench.org, where it has been assigned Project ID PR000742. The data can be accessed directly via its Project DOI: 10.21228/M8RX01. This work was supported by NIH grant, U2C- DK119886.

References

Purwaha, P., et al. Unbiased lipidomic profiling of triple-negative breast cancer tissues reveals the association of sphingomyelin levels with patient disease-free survival. Metabolites 8, 41 (2018) (doi: 10.3390/metabo8030041)

Examples

# Import the data set.
data( cancerlipidome )

# Convert the data into wide format, where each lipid is one column and
# each sample is one row.
cancerlipidome.wide <-
   tidyr::pivot_wider(
       data = cancerlipidome,
       names_from = Lipid_Name,
       values_from = Lipid_Level
   )
# Inspect the data frame.
# View( cancerlipidome.wide )
# Create a mapping of the lipid names.
names.mapping <-
   map_lipid_names( x = unique( cancerlipidome$"Lipid_Name" ) )
# Compute the regression models.
result.limma <-
   compute_models_with_limma(
       x = cancerlipidome.wide,
       dependent.variables = names.mapping$"Name",
       independent.variables = c( "Group" )
   )

# Create a figure of all lipids and factors.
figure.output <-
  heatmap_lipidome_from_limma(
    x = result.limma$"model",
    names.mapping = names.mapping,
    axis.x.carbons = FALSE,
    class.facet = "row",
    plot.all = TRUE,
    plot.individual = FALSE,
    print.figure = TRUE,
    scales = "free",
    space = "free"
  )

# Create individual figures for each factor.
figure.output <-
   heatmap_lipidome_from_limma(
       x = result.limma$"model",
       names.mapping = names.mapping,
       axis.x.carbons = FALSE,
       class.facet = "wrap",
       omit.class = "PA",
       plot.all = FALSE,
       plot.individual = TRUE,
       print.figure = FALSE,
       scales = "free",
       space = "free"
   )
# Print the figure of differences between cancer and benign tumors.
print( figure.output[[ "GroupCancer" ]] )

Compute an F-test for a multi-level factor independent variable

Description

Use this to achieve analysis of variance (ANOVA) or analysis of covariance (ANCOVA). The F-test is based on a model produced by the function compute_models_with_limma. To use this function, first call the function compute_models_with_limma.

Usage

compute_F_test_with_limma(x, p.adj.threshold = 0.05, print.table = FALSE)

Arguments

Value

List x supplemented by the results of the F-test.

See Also

compute_models_with_limma for the model computation step that is required prior to calling this function.

compute_post_hoc_test_with_limma for the pairwise post-hoc comparisons that may follow the F-test done with this function.

Compute lipid-specific regression models

Description

Use this function to computing multiple regression models that can be directly supplied to the visualization functions of the 'lipidomeR'.

Usage

compute_models_with_limma(
  x,
  dependent.variables,
  independent.variables,
  random.effect = NULL,
  formula = NULL,
  F.test = FALSE,
  print.table1 = FALSE,
  scale.dependent.variables = TRUE,
  scale.independent.variables = FALSE,
  verbose = TRUE
)

Arguments

Value

List of regression results the that can be directly supplied as an argument to the function heatmap_lipidome_from_limma and other visualization functions of the lipidomeR.

See Also

heatmap_lipidome_from_limma for visualizing the output of this function.

Compute pairwise post-hoc comparisons for a multi-level factor

Description

Use this function to achieve the post-hoc comparisons between the multiple levels of an independent variable. These comparisons follow analysis of variance (ANOVA) or analysis of covariance (ANCOVA). The pairwise comparisons are based on a result of an F-test produced by the function compute_F_test_with_limma. To use this function, first call the functions compute_models_with_limma and compute_F_test_with_limma consecutively.

Usage

compute_post_hoc_test_with_limma(
  x,
  p.adj.threshold = NULL,
  remap.level.names = FALSE
)

Arguments

Value

List x supplemented by the results of the pairwise post-hoc comparisons.

See Also

compute_models_with_limma for the model computation step that is required prior to calling this function.

compute_F_test_with_limma for the F-test step that is required prior to calling this function.

Create 'lipidomeR' heatmaps of arbitrary lipid-specific values.

Description

Use this function to create a heatmap of any lipid-specific values. Note: Use the function heatmap_lipidome_from_limma to create heatmaps of model statistics.

Usage

heatmap_lipidome(
  x,
  names.mapping,
  axis.x.carbons = TRUE,
  class.facet = "row",
  fill.direction = "increasing",
  fill.limits = c(0, 40),
  fill.midpoint = 20,
  melt.value.name = "CV",
  melt.variable.name = NULL,
  melt.x = TRUE,
  range.min.N.carbons = 5,
  range.min.N.double.bonds = 5,
  scale.fill.log = NULL,
  scales = "free_y",
  space = "free",
  x.names = "row.names",
  x.variables = NULL
)

Arguments

Create 'lipidomeR' heatmaps of model statistics

Description

Use this function to creating heatmaps of model statistics from the output of the compute_models_with_limma function or related functions (compute_F_test_with_limma and compute_post_hoc_test_with_limma).

Usage

heatmap_lipidome_from_limma(
  x,
  names.mapping = NULL,
  axis.x.carbons = TRUE,
  baseline.adjusted = FALSE,
  class.facet = "row",
  class.subset = NULL,
  F.test = FALSE,
  omit.class = NULL,
  omit.factor = NULL,
  order.factor = FALSE,
  p.val.thresholds = c(0.01, 0.05, 0.1),
  p.val.labels = c(8, 4, 3),
  p.val.label.bg.size = 2,
  p.val.label.size = 1,
  p.adj.method = "BH",
  plot.individual = FALSE,
  plot.all = TRUE,
  print.figure = TRUE,
  print.formula = TRUE,
  formula.width = 110,
  legend.key.size.multiplier = 2,
  range.min.N.carbons = 5,
  range.min.N.double.bonds = 5,
  scales = "fixed",
  shadowtext = FALSE,
  space = "free",
  survival = FALSE,
  verbose = FALSE,
  wrap.contrast.name = TRUE
)

Arguments

Value

List of 'lipidomeR' heatmap figure(s).

See Also

compute_models_with_limma for computing the argument x for this function.

Concentrations of lipids in a human plasma reference sample

Description

This data set contains concentrations of 403 named lipids in the 'National Institute of Standards and Technology Human Plasma Standard Reference Material' (NIST SRM 1950).

Usage

data( humanlipidome )

Format

A data frame with 403 rows and 2 variables:

Name

Name of the lipid. The names are in the format 'XY(C:D)', where 'XY' is the abbreviation of the lipid class, 'C' is the total number of carbon atoms in the fatty-acid chains, and 'D' is the total number of double-bonds in the fatty acid chains.

Concentration

Concentration of the lipid (umol/mL)

Source

This data is available at the NIH Common Fund's National Metabolomics Data Repository (NMDR) website, the 'Metabolomics Workbench', https://www.metabolomicsworkbench.org, where it has been assigned Project ID PR000004. The data can be accessed directly via its Project DOI: 10.21228/M8MW26. This work was supported by NIH grant, U2C- DK119886.

References

Quehenberger, O. et al. Lipidomics reveals a remarkable diversity of lipids in human plasma. J Lipid Res. 51, 3299-3305 (2010) (doi: 10.1194/jlr.M009449)

Examples

# Load the data set.
data( humanlipidome )
# Transform the concentrations into log-10 scale.
humanlipidome$"Concentration_log10_umol_per_mL" <-
   log10( humanlipidome$"Concentration" )
# Enumerate the lipid names into values.
names.mapping <- map_lipid_names( x = humanlipidome$"Name" )
# Create the lipidomeR heatmap of lipid concentrations.
heatmap_lipidome(
   x = humanlipidome[ , c( "Name", "Concentration_log10_umol_per_mL" ) ],
   names.mapping = names.mapping,
   class.facet = "wrap",
   x.names = "Name",
   fill.limits =
       range(
           x = humanlipidome$"Concentration_log10_umol_per_mL",
           na.rm = TRUE
       ),
   fill.midpoint =
       sum(
           range(
               x = humanlipidome$"Concentration_log10_umol_per_mL",
               na.rm = TRUE
           )
       ) / 2,
   melt.value.name = "Concentration_umol_per_mL_log10",
   scales = "free"
)

Install the Bioconductor dependencies for the 'lipidomeR'

Description

Run this function, if you encounter an error with missing packages, such as, limma.

Usage

install_Bioconductor_dependencies(pkgs.bioconductor = c("limma"))

Arguments

Levels of lipids in the human liver with or without non-alcoholic liver disease (NAFLD).

Description

This data set contains levels of 383 named lipids in 88 liver tissue samples.

Usage

data( liverlipidome )

Format

A long-format data frame with 33704 rows and 13 variables:

ID

Participant number

Diagnosis

Diagnosis of the liver: normal, steatosis, non-alcoholic steatohepatitis (NASH), or cirrhosis

Gender

Gender of the participant

BMI

Body-mass-index (BMI) of the participant

Ethnicity

Ethnicity of the participant

Age

Age of the participant

AST

Aspartate aminotransferase blood test (U/l)

ALT

Alanine aminotransferase blood test (U/l)

ALKP

Alkaline phosphatase blood test (U/l)

TBIL

Total bilirubin blood test (mg/dl)

Glucose

Glucose blood test (mg/dl)

Type

Sub-type of the breast tumor. IDC: Invasive Ductal Carcinoma

Lipid_Name

Name of the lipid. The names are in the format 'XY(C:D)', where 'XY' is the abbreviation of the lipid class, 'C' is the total number of carbon atoms in the fatty-acid chains, and 'D' is the total number of double-bonds in the fatty acid chains.

Lipid_Level

Measured level of the lipid.

Source

This data is available at the NIH Common Fund's National Metabolomics Data Repository (NMDR) website, the 'Metabolomics Workbench', https://www.metabolomicsworkbench.org, where it has been assigned Project ID PR000633. The data can be accessed directly via its Project DOI: 10.21228/M8MW26. This work was supported by NIH grant, U2C- DK119886.

References

Gorden, D. Lee, et al. Biomarkers of NAFLD Progression: a Lipidomics Approach to an Epidemic. J Lip Res. 56(3) 722-36 (2015) (doi: 10.1194/jlr.P056002

Examples

# Load the data set.
data( liverlipidome )
# Convert the data into wide format, where each lipid is one column and
# each sample is one row.
liverlipidome.wide <-
   tidyr::pivot_wider(
       data = liverlipidome,
       names_from = Lipid_Name,
       values_from = Lipid_Level
   )
# Create a mapping of the lipid names.
names.mapping <-
   map_lipid_names( x = unique( liverlipidome$"Lipid_Name" ) )
# Compute the regression models.
result.limma <-
   compute_models_with_limma(
       x = liverlipidome.wide,
       dependent.variables = names.mapping$"Name",
       independent.variables = c( "Diagnosis" ),
       F.test = TRUE # Compute an F-test for a factor variable.
   )
# Compute the F-test.
result.limma <- compute_F_test_with_limma( x = result.limma )
# Print a figure of the F-test.

figure.output <-
  heatmap_lipidome_from_limma(
      x = result.limma,
      names.mapping = names.mapping,
      F.test = TRUE,
      axis.x.carbons = FALSE,
      class.facet = "wrap",
      plot.all = FALSE,
      plot.individual = TRUE,
      scales = "free",
      space = "free"
  )

# Compute pairwise post-hoc comparisons between the factor levels for
# the dependent variables (i.e., lipids) with a significant F-test result.
result.limma <-
   compute_post_hoc_test_with_limma(
       x = result.limma,
       remap.level.names = TRUE
   )
# Print a figure of all post-hoc comparisons.

figure.output <-
    heatmap_lipidome_from_limma(
    x = result.limma$"result.post.hoc.test",
    names.mapping = names.mapping,
    axis.x.carbons = FALSE,
    plot.all = TRUE,
    plot.individual = FALSE,
    scales = "free",
    space = "free"
)

# Specify the contrasts of the post-hoc comparison that will be included
# in the figure.
contrasts.included <-
   c( "DiagnosisSteatosis", "DiagnosisNASH", "DiagnosisCirrhosis" )
# Get the omitted contrasts based on the above definition.
contrasts.omitted <-
   colnames( result.limma$"result.post.hoc.test"$"p.value" )[
       !(
           colnames( result.limma$"result.post.hoc.test"$"p.value" ) %in%
           contrasts.included
       )
   ]
# Find dependent variables (i.e., lipids) that have any significant
# difference.
has.any.significant <-
   apply(
       X =
           result.limma$"result.post.hoc.test"$"p.value"[
               ,
               contrasts.included
           ],
       MAR = 2,
       FUN = p.adjust,
       method = "BH"
   )
has.any.significant <-
   rownames(
       has.any.significant[
           apply(
               X = has.any.significant < 0.05,
               MAR = 1,
               FUN = any
           ),
       ]
   )
# Include in the figure only lipid classes that have at least four
# significant differences.
classes.included <-
   names(
       which(
           table(
               names.mapping[
                   make.names( has.any.significant ), "Class"
               ]
           ) > 4
       )
   )
classes.omitted <- unique( names.mapping$"Class" )
classes.omitted <-
   classes.omitted[ !( classes.omitted ) %in% classes.included ]
# Print a figure of the selected post-hoc-comparisons.
figure.output <-
   heatmap_lipidome_from_limma(
       x = result.limma$"result.post.hoc.test",
       names.mapping = names.mapping,
       axis.x.carbons = FALSE,
       omit.class = classes.omitted,
       omit.factor = contrasts.omitted,
       plot.all = TRUE,
       plot.individual = FALSE,
       scales = "free",
       space = "free"
   )

Enumerate lipid names into values about lipid class, size and saturation

Description

Use this function to create a mapping of the lipids to values, which can be used to creating 'lipidomeR' heatmaps.

Usage

map_lipid_names(x)

Arguments

Value

Data frame with lipid names in various formats for R and the enumerated values of lipid class (Class), lipid size (N.carbons) and lipid unsaturation (N.double.bonds).

See Also

heatmap_lipidome_from_limma for creating 'lipidomeR' heatmaps of regression model results based on the output of this function.

heatmap_lipidome for creating 'lipidomeR' heatmaps of any lipid-specific values based on the output of this function.