| 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.1 |
| Built: | 2026-10-08 11:02:12 UTC |
| Source: | https://github.com/bioc/LipidTrend |
Example lipid abundance data for two-dimensional LipidTrend analysis
data(abundance_2D)data(abundance_2D)
A matrix object of lipid abundance with 137 lipids over 6 samples
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.
data(abundance_2D)data(abundance_2D)
Example lipid abundance data for one-dimensional LipidTrend analysis
data(abundance_CL)data(abundance_CL)
A matrix object of lipid abundance with 29 lipids over 6 samples
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.
data(abundance_CL)data(abundance_CL)
Performs region-based statistical analysis to identify lipidomic trends between groups. This function applies a two-stage procedure:
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.
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). The kernel weights a feature's own marginal statistic equally against its neighbors' (fixed 0.5 self-contribution, not user-adjustable, to prevent tuning this parameter toward a desired result). 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.
analyzeLipidRegion(lipid_se, ref_group, split_chain=FALSE, chain_col=NULL, radius=3, test="t.test", abund_weight=TRUE, permute_time=100000)analyzeLipidRegion(lipid_se, ref_group, split_chain=FALSE, chain_col=NULL, radius=3, test="t.test", abund_weight=TRUE, permute_time=100000)
lipid_se |
A SummarizedExperiment object. Must contain following data:
|
ref_group |
Character. Group name of the reference group. It must be
one of the group names in the |
split_chain |
Logical. If |
chain_col |
Character. The column name in |
radius |
Numeric. Distance of neighboring features to be included in
the smoothing kernel. Default is |
test |
Character. Type of statistical test: either |
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 |
permute_time |
Integer. Number of permutations used to calculate
empirical p-values in the region-based permutation test. Default is
|
A LipidTrendSE object containing lipidomic feature testing result.
plotRegion1D for one-dimensional visualization
plotRegion2D for two-dimensional visualization
data("lipid_se_CL") res_se <- analyzeLipidRegion( lipid_se=lipid_se_CL, ref_group="sgCtrl", split_chain=FALSE, chain_col=NULL, radius=3, test="t.test", abund_weight=TRUE, permute_time=100)data("lipid_se_CL") res_se <- analyzeLipidRegion( lipid_se=lipid_se_CL, ref_group="sgCtrl", split_chain=FALSE, chain_col=NULL, radius=3, test="t.test", abund_weight=TRUE, permute_time=100)
Example lipid characteristics table for two-dimensional LipidTrend analysis
data(char_table_2D)data(char_table_2D)
A data.frame object of total chain length and total double bond
characteristics over 137 lipids
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.
data(char_table_2D)data(char_table_2D)
Example lipid characteristics table for one-dimensional LipidTrend analysis
data(char_table_CL)data(char_table_CL)
A data.frame object of chain characteristics over 29 lipids
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.
data(char_table_CL)data(char_table_CL)
Get Even Chain Result from LipidTrendSE
even_chain_result(object) ## S4 method for signature 'LipidTrendSE' even_chain_result(object)even_chain_result(object) ## S4 method for signature 'LipidTrendSE' even_chain_result(object)
object |
A LipidTrendSE object |
A data frame containing even chain result. The result table includes the following columns:
Feature columns: Lipid feature values from the input rowData,
such as chain length or double bond count. Column names vary depending on
input.
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.
direction: Sign of the smoothed statistic:
+ : Trend increases in the case group.
- : Trend decreases in the case group.
smoothing.pval.BH: Benjamini–Hochberg adjusted p-value from the region-based permutation test.
marginal.pval.BH: Benjamini–Hochberg adjusted p-value from the marginal test (per lipid).
log2.FC: Log2 fold-change in abundance between case and control groups.
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.
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, permute_time=100) # Get complete result summary results <- even_chain_result(res_se)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, permute_time=100) # Get complete result summary results <- even_chain_result(res_se)
Example group information table for LipidTrend analysis
data(group_info)data(group_info)
A data.frame object of sample name, lable name, and group name
over 6 samples
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.
data(group_info)data(group_info)
Example Dataset for two-dimensional data
data(lipid_se_2D)data(lipid_se_2D)
A SummarizedExperiment object with the following slots:
colDataA data frame with 6 observations on the following 3 variables, containing sample name, label name, and group name
assayA 137*6 matrix containing lipid abundance data
rowDataA data frame with 137 observations on the following 2 variables containing total chain length and total double bond characteristic information
data(lipid_se_2D)data(lipid_se_2D)
Example Dataset for one-dimensional data
data(lipid_se_CL)data(lipid_se_CL)
A SummarizedExperiment object with the following slots:
colDataA data frame with 6 observations on the following 3 variables, containing sample name, label name, and group name
assayA 29*6 matrix containing lipid abundance data
rowDataA data frame with 29 observations on the following 1 variables containing chain characteristic information
data(lipid_se_CL)data(lipid_se_CL)
This class extends SummarizedExperiment to store analyzeLipidRegion analysis results
split_chainLogical. 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.
resultData frame of analysis results (for non-split data)
even_chain_resultData frame of results for even chains (when split_chain is TRUE)
odd_chain_resultData frame of results for odd chains (when split_chain is TRUE)
abund_weightLogical. Logical. Set to TRUE to incorporate average lipid abundance as a weight in the test statistic.
Validate LipidTrendSE object
object |
A LipidTrendSE object to validate |
TRUE if valid, otherwise an error message
Get Odd Chain Result from LipidTrendSE
odd_chain_result(object) ## S4 method for signature 'LipidTrendSE' odd_chain_result(object)odd_chain_result(object) ## S4 method for signature 'LipidTrendSE' odd_chain_result(object)
object |
A LipidTrendSE object |
A data frame containing odd chain result. The result table includes the following columns:
Feature columns: Lipid feature values from the input rowData,
such as chain length or double bond count. Column names vary depending on
input.
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.
direction: Sign of the smoothed statistic:
+ : Trend increases in the case group.
- : Trend decreases in the case group.
smoothing.pval.BH: Benjamini–Hochberg adjusted p-value from the region-based permutation test.
marginal.pval.BH: Benjamini–Hochberg adjusted p-value from the marginal test (per lipid).
log2.FC: Log2 fold-change in abundance between case and control groups.
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.
data("lipid_se_CL") res_se <- analyzeLipidRegion( lipid_se=lipid_se_CL, ref_group="sgCtrl", split_chain=TRUE, chain_col="chain", radius=3, permute_time=100) # Get complete result summary results <- odd_chain_result(res_se)data("lipid_se_CL") res_se <- analyzeLipidRegion( lipid_se=lipid_se_CL, ref_group="sgCtrl", split_chain=TRUE, chain_col="chain", radius=3, permute_time=100) # Get complete result summary results <- odd_chain_result(res_se)
Visualize lipid trends from one-dimensional analysis
results. Blue and red ribbons highlight regions where the trend
significantly decreases or increases, respectively, in the case group
compared to the control group; a direction is shaded only after its
region-level paired t-test (see regionalTestFC) passes at
regional_p_cutoff. 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.
The paired t-test is only reliable with more than 5 significant
features in a direction. When either direction in a figure has 5 or
fewer, there are too few features to run the test, and the whole figure
falls back to shading by the smoothed permutation test alone
(smoothing.pval.BH < p_cutoff) instead, so a single figure never
mixes two different statistical criteria.
plotRegion1D(object, p_cutoff=0.05, regional_p_cutoff=0.05, y_scale="identity")plotRegion1D(object, p_cutoff=0.05, regional_p_cutoff=0.05, y_scale="identity")
object |
A LipidTrendSE object generated by |
p_cutoff |
Numeric. Significance threshold that defines region
membership: a feature belongs to a region when its smoothed permutation
p-value falls below this threshold ( |
regional_p_cutoff |
Numeric. Significance threshold applied
afterward to the region-level paired t-test p-value itself (see
|
y_scale |
Character. Scale of the y-axis. Choose from |
If split_chain=TRUE in the analysis, the function returns a list
containing two plots:
even_result: A ggplot object visualizing trends for
even-chain lipids, or NULL if no such lipids exist.
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.
analyzeLipidRegion for generating the input LipidTrendSE object
regionalTestFC for the region-level validation statistics
data("lipid_se_CL") res_se <- analyzeLipidRegion( lipid_se=lipid_se_CL, ref_group="sgCtrl", split_chain=FALSE, chain_col=NULL, radius=2, test="t.test", abund_weight=TRUE, permute_time=100) plot <- plotRegion1D(res_se, p_cutoff=0.05, y_scale='identity')data("lipid_se_CL") res_se <- analyzeLipidRegion( lipid_se=lipid_se_CL, ref_group="sgCtrl", split_chain=FALSE, chain_col=NULL, radius=2, test="t.test", abund_weight=TRUE, permute_time=100) plot <- plotRegion1D(res_se, p_cutoff=0.05, y_scale='identity')
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; a
direction is shaded only after its region-level paired t-test (see
regionalTestFC) passes at regional_p_cutoff.
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.
The paired t-test is only reliable with more than 5 significant
features in a direction. When either direction in a figure has 5 or
fewer, there are too few features to run the test, and the whole figure
falls back to shading by the smoothed permutation test alone
(smoothing.pval.BH < p_cutoff) instead, so a single figure never
mixes two different statistical criteria.
plotRegion2D(object, p_cutoff=0.05, regional_p_cutoff=0.05, log2FC_cutoff=3)plotRegion2D(object, p_cutoff=0.05, regional_p_cutoff=0.05, log2FC_cutoff=3)
object |
A LipidTrendSE object generated by |
p_cutoff |
Numeric. Significance threshold that defines region
membership: a feature belongs to a region when its smoothed permutation
p-value falls below this threshold ( |
regional_p_cutoff |
Numeric. Significance threshold applied
afterward to the region-level paired t-test p-value itself (see
|
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
|
If split_chain=TRUE in the analysis, the function returns a list with:
even_result: A ggplot object for even-chain lipids,
or NULL if none exist.
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.
analyzeLipidRegion for generating the input LipidTrendSE object
regionalTestFC for the region-level validation statistics
data("lipid_se_2D") res_se <- analyzeLipidRegion( lipid_se=lipid_se_2D, ref_group="sgCtrl", split_chain=FALSE, chain_col=NULL, radius=3, test="t.test", abund_weight=TRUE, permute_time=100) plot_2D <- plotRegion2D(res_se, p_cutoff=0.05)data("lipid_se_2D") res_se <- analyzeLipidRegion( lipid_se=lipid_se_2D, ref_group="sgCtrl", split_chain=FALSE, chain_col=NULL, radius=3, test="t.test", abund_weight=TRUE, permute_time=100) plot_2D <- plotRegion2D(res_se, p_cutoff=0.05)
For each significant trend region identified by
analyzeLipidRegion (Increase / Decrease), performs an
independent region-level paired t-test on feature-wise group-mean abundances
(feature = pairing unit), and summarizes the region's fold-change. This
provides an explainable, permutation-free statistic to accompany the
smoothed permutation test result, and is also used internally by
plotRegion1D/ plotRegion2D to validate large
regions before coloring them (see their regional_p_cutoff argument
for the significance level applied to regional.test.pval in that
decision).
regionalTestFC(object, p_cutoff = 0.05) ## S4 method for signature 'LipidTrendSE' regionalTestFC(object, p_cutoff = 0.05)regionalTestFC(object, p_cutoff = 0.05) ## S4 method for signature 'LipidTrendSE' regionalTestFC(object, p_cutoff = 0.05)
object |
A LipidTrendSE object generated by |
p_cutoff |
Numeric. Significance threshold used to define which
features belong to a region, based on the smoothed permutation test
( |
A data frame with one row per direction (Increase/Decrease):
"Increase" or "Decrease".
Number of significant features in that direction.
Paired t-test p-value on feature-wise
group-mean abundance across the significant features. NA when
n.features <= 5 (a paired t-test on 5 or fewer pairs is too
underpowered to be trustworthy).
Regional fold-change on the linear scale. This is the median fold-change across the significant features in that direction – a median rather than a mean, so that a single extreme feature cannot dominate the summary of the region.
The same quantity on the log2 scale: the median
log2 fold-change across those features. Equal to
log2(regional.FC).
If split_chain=TRUE in the analysis, a list with
even_result/odd_result data frames as above.
analyzeLipidRegion for generating the input LipidTrendSE object
plotRegion1D and plotRegion2D for visualization
data("lipid_se_CL") res_se <- analyzeLipidRegion( lipid_se=lipid_se_CL, ref_group="sgCtrl", split_chain=FALSE, chain_col=NULL, radius=3, permute_time=100) tab <- regionalTestFC(res_se)data("lipid_se_CL") res_se <- analyzeLipidRegion( lipid_se=lipid_se_CL, ref_group="sgCtrl", split_chain=FALSE, chain_col=NULL, radius=3, permute_time=100) tab <- regionalTestFC(res_se)
Get Result from LipidTrendSE
result(object) ## S4 method for signature 'LipidTrendSE' result(object)result(object) ## S4 method for signature 'LipidTrendSE' result(object)
object |
A LipidTrendSE object |
A data frame containing analysis results. The result table includes the following columns:
Feature columns: Lipid feature values from the input rowData,
such as chain length or double bond count. Column names vary depending on
input.
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.
direction: Sign of the smoothed statistic:
+ : Trend increases in the case group.
- : Trend decreases in the case group.
smoothing.pval.BH: Benjamini–Hochberg adjusted p-value from the region-based permutation test.
marginal.pval.BH: Benjamini–Hochberg adjusted p-value from the marginal test (per lipid).
log2.FC: Log2 fold-change in abundance between case and control groups.
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.
data("lipid_se_CL") res_se <- analyzeLipidRegion( lipid_se=lipid_se_CL, ref_group="sgCtrl", split_chain=FALSE, chain_col=NULL, radius=3, permute_time=100) # Get complete result results <- result(res_se)data("lipid_se_CL") res_se <- analyzeLipidRegion( lipid_se=lipid_se_CL, ref_group="sgCtrl", split_chain=FALSE, chain_col=NULL, radius=3, permute_time=100) # Get complete result results <- result(res_se)
Show method for LipidTrendSE objects
## S4 method for signature 'LipidTrendSE' show(object)## S4 method for signature 'LipidTrendSE' show(object)
object |
A LipidTrendSE object |
LipidTrendSE object information