Package 'LipidTrend'

Title: LipidTrend: Analysis and Visualization of Lipid Feature Tendencies
Description: "LipidTrend" is an R package that implements a permutation-based statistical test to identify significant differences in lipidomic features between groups. The test incorporates Gaussian kernel smoothing of region statistics to improve stability and accuracy, particularly when dealing with small sample sizes. This package also includes two plotting functions for visualizing significant tendencies in 1D and 2D feature data, respectively.
Authors: Wei-Chung Cheng [aut, cre, cph] (ORCID: <https://orcid.org/0000-0002-1229-4857>), Chia-Hsin Liu [aut, ctb], Pei-Chun Shen [aut, ctb], Wen-Jen Lin [aut, ctb], Hung-Ching Chang [aut, ctb], Meng-Hsin Tsai [aut, ctb]
Maintainer: Wei-Chung Cheng <[email protected]>
License: MIT + file LICENSE
Version: 1.3.0
Built: 2026-05-30 07:48:17 UTC
Source: https://github.com/bioc/LipidTrend

Help Index

Example lipid abundance data for two-dimensional LipidTrend analysis

Description

Example lipid abundance data for two-dimensional LipidTrend analysis

Usage

data(abundance_2D)

Format

An object of class matrix (inherits from array) with 137 rows and 6 columns.

Value

A matrix object of lipid abundance with 137 lipids over 6 samples

Source

Tomoyuki Shiota et al. ,Hepatoviruses promote very-long-chain fatty acid and sphingolipid synthesis for viral RNA replication and quasi-enveloped virus release. Sci Adv. 9(42):eadj4198 https://www.science.org/doi/10.1126/sciadv.adj4198.

Examples

data(abundance_2D)

Example lipid abundance data for one-dimensional LipidTrend analysis

Description

Example lipid abundance data for one-dimensional LipidTrend analysis

Usage

data(abundance_CL)

Format

An object of class matrix (inherits from array) with 29 rows and 6 columns.

Value

A matrix object of lipid abundance with 29 lipids over 6 samples

Source

Tomoyuki Shiota et al. ,Hepatoviruses promote very-long-chain fatty acid and sphingolipid synthesis for viral RNA replication and quasi-enveloped virus release. Sci Adv. 9(42):eadj4198 https://www.science.org/doi/10.1126/sciadv.adj4198.

Examples

data(abundance_CL)

Conduct statistical to analyze lipid features tendencies

Description

Performs region-based statistical analysis to identify lipidomic trends between groups. This function applies a two-stage procedure:

  1. Marginal Test: Each lipid feature is first tested individually using either a t-test (with glog10 transformation) or a Wilcoxon test to obtain marginal statistics and p-values.

  2. Region-Based Permutation Test with Smoothing: Marginal statistics are smoothed using a Gaussian kernel that incorporates neighborhood information (e.g., proximity in chain length or double bond count). Statistical significance is assessed by comparing the smoothed statistic against a null distribution generated through permutation.

This approach enhances statistical robustness, especially for small-sample datasets. It supports both one-dimensional and two-dimensional analyses depending on the number of features provided in the input.

The input must be a SummarizedExperiment object, and the output is a LipidTrendSE object, which can be used for result visualization or further downstream analysis.

Usage

analyzeLipidRegion(
  lipid_se,
  ref_group,
  split_chain = FALSE,
  chain_col = NULL,
  radius = 3,
  own_contri = 0.5,
  test = "t.test",
  abund_weight = TRUE,
  permute_time = 1e+05
)

Arguments

lipid_se

A SummarizedExperiment object. Must contain following data:

  1. Assay: A matrix containing lipid abundance data, where rows represent lipids and columns represent samples.

  2. RowData: A data frame of lipid features (e.g., double bond count, chain length), with rows as lipids and columns as lipid features ( limited to 1 or 2 columns). The order of lipids must match the abundance data. If RowData contains one column, a one-dimensional analysis will be performed. If rowData includes two columns, a two-dimensional analysis will be conducted.

  3. ColData: A data frame containing group information, where rows represent sample names and columns must include sample name, label name, and group, arranged accordingly.

ref_group

Character. Group name of the reference group. It must be one of the group names in the colData$group column.
split_chain

Logical. If TRUE the results will split to shown by odd and even chain. Default is FALSE.
chain_col

Character. The column name in rowData that specifies chain length. Must be provided if split_chain=TRUE, otherwise should be set to NULL. Default is NULL.
radius

Numeric. Distance of neighboring features to be included in the smoothing kernel. Default is 3.
own_contri

Numeric. Proportion of self-contribution when smoothing. Default is 0.5. Recommended range: 0.5–1 to avoid over-emphasizing neighbors.
test

Character. Type of statistical test: either "t.test" or "Wilcoxon". Default is "t.test".
abund_weight

Logical. Whether to use average abundance as a weight in calculating the region-based smoothed statistic. When set to TRUE, lipid species with higher mean abundance contribute more to the smoothed trend. Default is TRUE.
permute_time

Integer. Number of permutations used to calculate empirical p-values in the region-based permutation test. Default is 100000. For the Wilcoxon test (i.e., test="Wilcoxon"), we recommend setting permute_time to fewer than 10,000 to ensure reasonable runtime.

Value

A LipidTrendSE object containing lipidomic feature testing result.

See Also

plotRegion1D for one-dimensional visualization plotRegion2D for two-dimensional visualization

Examples

data("lipid_se_CL")
res_se <- analyzeLipidRegion(
    lipid_se=lipid_se_CL, ref_group="sgCtrl", split_chain=FALSE,
    chain_col=NULL, radius=3, own_contri=0.5, test="t.test",
    abund_weight=TRUE, permute_time=100)

Example lipid characteristics table for two-dimensional LipidTrend analysis

Description

Example lipid characteristics table for two-dimensional LipidTrend analysis

Usage

data(char_table_2D)

Format

An object of class data.frame with 137 rows and 2 columns.

Value

A data.frame object of total chain length and total double bond characteristics over 137 lipids

Source

Tomoyuki Shiota et al. ,Hepatoviruses promote very-long-chain fatty acid and sphingolipid synthesis for viral RNA replication and quasi-enveloped virus release. Sci Adv. 9(42):eadj4198 https://www.science.org/doi/10.1126/sciadv.adj4198.

Examples

data(char_table_2D)

Example lipid characteristics table for one-dimensional LipidTrend analysis

Description

Example lipid characteristics table for one-dimensional LipidTrend analysis

Usage

data(char_table_CL)

Format

An object of class data.frame with 29 rows and 1 columns.

Value

A data.frame object of chain characteristics over 29 lipids

Source

Tomoyuki Shiota et al. ,Hepatoviruses promote very-long-chain fatty acid and sphingolipid synthesis for viral RNA replication and quasi-enveloped virus release. Sci Adv. 9(42):eadj4198 https://www.science.org/doi/10.1126/sciadv.adj4198.

Examples

data(char_table_CL)

Get Even Chain Result from LipidTrendSE

Description

Get Even Chain Result from LipidTrendSE

Usage

even_chain_result(object)

## S4 method for signature 'LipidTrendSE'
even_chain_result(object)

Arguments

object

A LipidTrendSE object

Value

A data frame containing even chain result. The result table includes the following columns:

  1. Feature columns: Lipid feature values from the input rowData, such as chain length or double bond count. Column names vary depending on input.

  2. avg.abund: Mean abundance of each lipid across all samples. For one-dimensional analysis, this may also include avg.abund.ctrl and avg.abund.case for group-wise means.

  3. direction: Sign of the smoothed statistic:

    • + : Trend increases in the case group.

    • - : Trend decreases in the case group.

  4. smoothing.pval.BH: Benjamini–Hochberg adjusted p-value from the region-based permutation test.

  5. marginal.pval.BH: Benjamini–Hochberg adjusted p-value from the marginal test (per lipid).

  6. log2.FC: Log2 fold-change in abundance between case and control groups.

  7. significance: Overall significance label based on smoothed test and FC direction:

    • Increase: Significant positive trend in case group.

    • Decrease: Significant negative trend in case group.

    • NS: Not significant.

Examples

data("lipid_se_CL")
sub <- lipid_se_CL[seq_len(10), ]
res_se <- analyzeLipidRegion(
    lipid_se=sub, ref_group="sgCtrl", split_chain=TRUE,
    chain_col="chain", radius=3, own_contri=0.5, permute_time=100)
# Get complete result summary
results <- even_chain_result(res_se)

Example group information table for LipidTrend analysis

Description

Example group information table for LipidTrend analysis

Usage

data(group_info)

Format

An object of class data.frame with 6 rows and 3 columns.

Value

A data.frame object of sample name, lable name, and group name over 6 samples

Source

Tomoyuki Shiota et al. ,Hepatoviruses promote very-long-chain fatty acid and sphingolipid synthesis for viral RNA replication and quasi-enveloped virus release. Sci Adv. 9(42):eadj4198 https://www.science.org/doi/10.1126/sciadv.adj4198.

Examples

data(group_info)

Example Dataset for two-dimensional data

Description

Example Dataset for two-dimensional data

Usage

data(lipid_se_2D)

Format

An object of class SummarizedExperiment with 137 rows and 6 columns.

Value

A SummarizedExperiment object with the following slots:

colData

A data frame with 6 observations on the following 3 variables, containing sample name, label name, and group name

assay

A 137*6 matrix containing lipid abundance data

rowData

A data frame with 137 observations on the following 2 variables containing total chain length and total double bond characteristic information

Examples

data(lipid_se_2D)

Example Dataset for one-dimensional data

Description

Example Dataset for one-dimensional data

Usage

data(lipid_se_CL)

Format

An object of class SummarizedExperiment with 29 rows and 6 columns.

Value

A SummarizedExperiment object with the following slots:

colData

A data frame with 6 observations on the following 3 variables, containing sample name, label name, and group name

assay

A 29*6 matrix containing lipid abundance data

rowData

A data frame with 29 observations on the following 1 variables containing chain characteristic information

Examples

data(lipid_se_CL)

Class for storing analyzeLipidRegion analysis results

Description

This class extends SummarizedExperiment to store analyzeLipidRegion analysis results

Slots

split_chain

Logical. Indicates whether chains were split by parity (even vs. odd). When TRUE, results are stored in even_chain_result and odd_chain_result slots. When FALSE, results are stored in the result slot.

result

Data frame of analysis results (for non-split data)

even_chain_result

Data frame of results for even chains (when split_chain is TRUE)

odd_chain_result

Data frame of results for odd chains (when split_chain is TRUE)

abund_weight

Logical. Logical. Set to TRUE to incorporate average lipid abundance as a weight in the test statistic.

Validate LipidTrendSE object

Description

Validate LipidTrendSE object

Arguments

object

A LipidTrendSE object to validate

Value

TRUE if valid, otherwise an error message

Get Odd Chain Result from LipidTrendSE

Description

Get Odd Chain Result from LipidTrendSE

Usage

odd_chain_result(object)

## S4 method for signature 'LipidTrendSE'
odd_chain_result(object)

Arguments

object

A LipidTrendSE object

Value

A data frame containing odd chain result. The result table includes the following columns:

  1. Feature columns: Lipid feature values from the input rowData, such as chain length or double bond count. Column names vary depending on input.

  2. avg.abund: Mean abundance of each lipid across all samples. For one-dimensional analysis, this may also include avg.abund.ctrl and avg.abund.case for group-wise means.

  3. direction: Sign of the smoothed statistic:

    • + : Trend increases in the case group.

    • - : Trend decreases in the case group.

  4. smoothing.pval.BH: Benjamini–Hochberg adjusted p-value from the region-based permutation test.

  5. marginal.pval.BH: Benjamini–Hochberg adjusted p-value from the marginal test (per lipid).

  6. log2.FC: Log2 fold-change in abundance between case and control groups.

  7. significance: Overall significance label based on smoothed test and FC direction:

    • Increase: Significant positive trend in case group.

    • Decrease: Significant negative trend in case group.

    • NS: Not significant.

Examples

data("lipid_se_CL")
res_se <- analyzeLipidRegion(
    lipid_se=lipid_se_CL, ref_group="sgCtrl", split_chain=TRUE,
    chain_col="chain", radius=3, own_contri=0.5, permute_time=100)
# Get complete result summary
results <- odd_chain_result(res_se)

Plot region trends for one-dimensional lipid feature

Description

Visualize lipid trends from one-dimensional analysis results. The plot highlights regions of significant group differences based on the smoothed permutation test. Blue and red ribbons mark where the trend significantly decreases or increases, respectively, in the case group compared to the control group. Each point represents the mean abundance within each group (case vs. control) for a specific lipid feature. This visualization helps identify not only abundance differences but also the specific lipid feature regions where trends diverge between groups.

Usage

plotRegion1D(object, p_cutoff = 0.05, y_scale = "identity")

## S4 method for signature 'LipidTrendSE'
plotRegion1D(object, p_cutoff = 0.05, y_scale = "identity")

Arguments

object

A LipidTrendSE object generated by analyzeLipidRegion() for one-dimensional feature analysis.
p_cutoff

Numeric. Significance threshold for highlighting regions based on smoothed permutation p-values. Default is 0.05.
y_scale

Character. Scale of the y-axis. Choose from "identity", "log2", "log10", or "sqrt". Default is "identity".

Value

If split_chain=TRUE in the analysis, the function returns a list containing two plots:

  1. even_result: A ggplot object visualizing trends for even-chain lipids, or NULL if no such lipids exist.

  2. odd_result: A ggplot object visualizing trends for odd-chain lipids, or NULL if no such lipids exist.

If split_chain=FALSE, the function returns a single ggplot object visualizing the trend for all lipids combined.

See Also

analyzeLipidRegion for generating the input LipidTrendSE object

Examples

data("lipid_se_CL")
res_se <- analyzeLipidRegion(
    lipid_se=lipid_se_CL, ref_group="sgCtrl", split_chain=FALSE,
    chain_col=NULL, radius=2, own_contri=0.5, test="t.test",
    abund_weight=TRUE, permute_time=100)
plot <- plotRegion1D(res_se, p_cutoff=0.05, y_scale='identity')

Plot region trends for two-dimensional lipid features

Description

Visualize lipid trend analysis results in two-dimensional feature space (e.g., chain length vs. double bond count). The resulting heatmap highlights regions with significant trends between groups based on the smoothed permutation test.

Each point in the heatmap represents a lipid defined by two continuous features (such as chain length and double bond). Color indicates the log2 fold-change between groups, and asterisks denote levels of marginal significance. If abund_weight=TRUE during analysis, the point size reflects the mean abundance of each lipid. If abund_weight=FALSE, all points are displayed with equal size.

Usage

plotRegion2D(object, p_cutoff = 0.05, log2FC_cutoff = 3)

## S4 method for signature 'LipidTrendSE'
plotRegion2D(object, p_cutoff = 0.05, log2FC_cutoff = 3)

Arguments

object

A LipidTrendSE object generated by analyzeLipidRegion() for two-dimensional analysis.
p_cutoff

Numeric. Significance threshold for smoothed permutation p-values. Default is 0.05.
log2FC_cutoff

Numeric. Threshold for absolute log2 fold-change used to truncate the color scale in the heatmap. Values exceeding this threshold will be capped at the cutoff value for visualization purposes. Default is 3.

Value

If split_chain=TRUE in the analysis, the function returns a list with:

  1. even_result: A ggplot object for even-chain lipids, or NULL if none exist.

  2. odd_result: A ggplot object for odd-chain lipids, or NULL if none exist.

If split_chain=FALSE, the function returns a single ggplot object visualizing all lipids together.

See Also

analyzeLipidRegion for generating the input LipidTrendSE object

Examples

data("lipid_se_2D")
res_se <- analyzeLipidRegion(
    lipid_se=lipid_se_2D, ref_group="sgCtrl", split_chain=FALSE,
    chain_col=NULL, radius=3, own_contri=0.5, test="t.test",
    abund_weight=TRUE, permute_time=100)
plot_2D <- plotRegion2D(res_se, p_cutoff=0.05)

Get Result from LipidTrendSE

Description

Get Result from LipidTrendSE

Usage

result(object)

## S4 method for signature 'LipidTrendSE'
result(object)

Arguments

object

A LipidTrendSE object

Value

A data frame containing analysis results. The result table includes the following columns:

  1. Feature columns: Lipid feature values from the input rowData, such as chain length or double bond count. Column names vary depending on input.

  2. avg.abund: Mean abundance of each lipid across all samples. For one-dimensional analysis, this may also include avg.abund.ctrl and avg.abund.case for group-wise means.

  3. direction: Sign of the smoothed statistic:

    • + : Trend increases in the case group.

    • - : Trend decreases in the case group.

  4. smoothing.pval.BH: Benjamini–Hochberg adjusted p-value from the region-based permutation test.

  5. marginal.pval.BH: Benjamini–Hochberg adjusted p-value from the marginal test (per lipid).

  6. log2.FC: Log2 fold-change in abundance between case and control groups.

  7. significance: Overall significance label based on smoothed test and FC direction:

    • Increase: Significant positive trend in case group.

    • Decrease: Significant negative trend in case group.

    • NS: Not significant.

Examples

data("lipid_se_CL")
res_se <- analyzeLipidRegion(
    lipid_se=lipid_se_CL, ref_group="sgCtrl", split_chain=FALSE,
    chain_col=NULL, radius=3, own_contri=0.5, permute_time=100)
# Get complete result
results <- result(res_se)

Show method for LipidTrendSE objects

Description

Show method for LipidTrendSE objects

Usage

## S4 method for signature 'LipidTrendSE'
show(object)

Arguments

object

A LipidTrendSE object

Value

LipidTrendSE object information