Tests each protein for a temporal trend treating time as a NUMERIC covariate. A natural-spline basis of the (optionally transformed) time is fitted by limma and all the spline coefficients are tested jointly by a moderated F-test: this results in a single test per protein, hence no contrast has to be defined. The proteins showing a trend are then soft-clustered on the shape of their fitted trajectory.
analyze.timecourse(
DEprot.object,
time.column,
group.column = NULL,
replicate.column = NULL,
include.rep.model = FALSE,
time.transform = "none",
spline.df = NULL,
which.data = "imputed",
padj.method = "BH",
padj.th = 0.05,
log2.amplitude.th = 0,
n.clusters = NULL,
k.range = 2:8,
clustering.method = "cmeans",
fuzzifier = NULL,
clara.samples = 50,
clara.sampsize = NULL,
rank.by = "score",
grid.n = 100,
seed = 1234,
verbose = TRUE
)An object of class DEprot or DEprot.analyses.
String indicating a column of the metadata containing NUMERIC time values (e.g., hours). The values must be coercible to numeric.
String indicating a column of the metadata defining sample groups (e.g., treatment). When provided, the group x time interaction is tested, meaning that the question becomes 'do the trajectories differ between the groups?'. Default: NULL (a single trend is tested).
String indicating a column of the metadata containing the replicate IDs. Used only when include.rep.model is TRUE. Default: NULL.
Logic value indicating whether the intra-replicate correlation should be estimated by limma::duplicateCorrelation and included in the fit. It requires a replicate.column. Default: FALSE.
String indicating a transformation to apply to the time values. One among: 'none', 'log2', 'log10', 'log1p', 'log', 'ln', 'sqrt'. The log transformations are computed as log(t + 1), hence time zero is allowed. Strongly recommended ('log2') when the timepoints are log-spaced (e.g., 0, 1, 2, 6, 24 h), otherwise the last timepoint dominates the fit. Default: "none".
Numeric value indicating the degrees of freedom of the natural-spline basis. When NULL, it is set to min(3, n.timepoints - 2); with less than 4 timepoints a linear trend (df = 1) is fitted instead. Default: NULL.
String indicating which type of counts should be used. One among: 'raw', 'normalized', 'norm', 'imputed', 'imp', 'randomized', 'random'. Default: "imputed".
String indicating the multiple-testing correction, any method accepted by stats::p.adjust. Default: "BH".
Numeric value indicating the adjusted p-value threshold used to call a trend. Default: 0.05.
Numeric value indicating the minimal amplitude (max - min of the fitted curve, in log2 units) required to call a trend. The proteins passing padj.th but not this threshold are labelled as 'unresponsive'. Default: 0.
Numeric value indicating the number of clusters. When NULL, it is estimated by silhouette over k.range; when 0, the clustering is skipped. Default: NULL.
Numeric vector of the candidate numbers of clusters tested when n.clusters is NULL. Default: 2:8.
String indicating the clustering algorithm. One among: 'cmeans' (soft, the default), 'pam' (hard, exact) or 'clara' (hard, approximated). CLARA runs PAM on subsamples instead of building the full dissimilarity matrix: it is only useful when the trending proteins are too many for an exact PAM, roughly above 10000, an exact PAM being preferable whenever it runs. Default: "cmeans".
Numeric value indicating the fuzzifier 'm' used by c-means. When NULL, it is estimated with the Schwämmle & Jensen relation. Default: NULL.
Numeric value indicating the number of subsamples drawn by CLARA. Used only when clustering.method is 'clara'. Default: 50.
Numeric value indicating the size of each CLARA subsample. When NULL, it is set to 140 + 2*k, the default of cluster::clara being too small to be representative. Default: NULL.
String indicating the metric used to rank the proteins within each cluster. One among: 'score' (amplitude * -log10(padj), consistent with the differential score used elsewhere in DEprot), 'membership' (how prototypical a protein is for its cluster, c-means only), 'amplitude', 'padj', or 't.half' (time to half-maximum, which orders the proteins by when they respond). Default: "score".
Numeric value indicating the number of points at which the fitted curves are evaluated. Default: 100.
Numeric value indicating the seed used for the clustering. Default: 1234.
Logic value indicating whether the messages should be printed. Default: TRUE.
An object of class DEprot.timecourse.
The model spends (spline.df + 1) coefficients for each level of the group.column, hence
every group must provide at least two samples more than that: a group fitted with as many samples as
coefficients is saturated, its residual variance is not estimable, and the moderated F-test would rest
entirely on the empirical Bayes prior rather than on the data. When this is not the case the function
stops: lowering the spline.df is usually preferable to dropping timepoints.
With less than four timepoints there is no room for any curvature and a linear trend is fitted instead of
a spline (a warning is raised). In that case, as well as with a single group, the joint test reduces to a
single coefficient: the F.statistic column then reports the square of the moderated t-statistic,
which is the F statistic of that test (1 numerator degree of freedom) and returns exactly the same p-value.
Ritchie M.E., Phipson B., Wu D., et al. (2015). limma powers differential expression analyses for RNA-sequencing and microarray studies. Nucleic Acids Research, 43(7), e47. doi:10.1093/nar/gkv007
Schwämmle V. & Jensen O.N. (2010). A simple and fast method to determine the parameters for fuzzy c-means cluster analysis. Bioinformatics, 26(22), 2841-2848. doi:10.1093/bioinformatics/btq534
Rousseeuw P.J. (1987). Silhouettes: a graphical aid to the interpretation and validation of cluster analysis. Journal of Computational and Applied Mathematics, 20, 53-65. doi:10.1016/0377-0427(87)90125-7
Schubert E. & Rousseeuw P.J. (2021). Fast and eager k-medoids clustering: O(k) runtime improvement of the PAM, CLARA, and CLARANS algorithms. Information Systems, 101, 101804. doi:10.1016/j.is.2021.101804