Find Peaks and Valleys in Time-Series Omics Data

Identifies significant local peaks or valleys (excursions) in time-series omics data using a Union-Intersection Test (UIT)-based approach. This function wraps the detection and plotting steps, returning visualizations of all features with at least one excursion.

Usage

find_pvc(
  splineomics,
  alphas = 0.05,
  padjust_method = "BH",
  plot_info = list(y_axis_label = "Value", time_unit = "min", treatment_labels = NA,
    treatment_timepoints = NA),
  report_dir = here::here()
)

Arguments

splineomics: A list containing the preprocessed time-series input data. Must include named elements `"data"` (a numeric matrix), `"meta"` (a metadata data frame with a `"Time"` column), `"meta_batch_column"` (name of the column in `meta` identifying replicates or batches), and `"padjust_method"` (a string specifying the method for p-value adjustment).
alphas: A single numeric value or a named list of numeric thresholds used to identify significant excursion points. If a single value is provided (either as a numeric scalar or a list of length 1), the same threshold is applied to all condition levels. If a named list is provided, it must contain one numeric value per condition level, with names matching the condition levels exactly. This input is normalized internally to ensure consistent per-level access.
padjust_method: A character string specifying the method for multiple testing correction. Defaults to `"BH"` (Benjamini-Hochberg).
plot_info: List containing the elements y_axis_label (string), time_unit (string), treatment_labels (character vector), treatment_timepoints (integer vector). All can also be NA. This list is used to add this info to the spline plots. time_unit is used to label the x-axis, and treatment_labels and -timepoints are used to create vertical dashed lines, indicating the positions of the treatments (such as feeding, temperature shift, etc.).
report_dir: Character string specifying the directory path where the HTML report and any other output files should be saved.

Value

A named list of ggplot objects, where each element corresponds to a feature with at least one detected peak or valley. Each plot shows expression profiles across timepoints, highlights excursion points in red, and annotates statistically significant excursions with significance stars.

Details

A **peak** or **valley** is defined as a timepoint whose expression value is significantly different from both its immediate neighbors and deviates in the same direction — i.e., it is either significantly higher than both (a peak) or significantly lower than both (a valley).

Statistically, this is tested using a compound contrast in limma: $$(T - T_{prev}) + (T - T_{next}) = 2T - T_{prev} - T_{next}$$ This compound contrast has power only when the timepoint `T` is an outlier compared to both neighbors in the same direction. The resulting p-value is FDR-adjusted and compared to the `alpha` threshold.

- Performs internal input validation via `check_splineomics_elements()` and `InputControl`. - Detects local excursions using the `pvc_test()` function. - Displays the number of total excursion hits found. - Generates plots using `plot_pvc()`, with each excursion point evaluated for significance based on the provided `alpha`.