Package 'RhyME'

Fit Cosinor Models Across CpG Sites

Description

Fits beta cosinor models using PQL, with optional random intercepts, adjustment covariates, and an empirical Bayes (EB) prior on log precision. A null-model score test assesses rhythmicity; a full model estimates rhythm parameters.

Usage

fitCosinor(
  se,
  time_col = "time",
  subject_col = NULL,
  assay_name = NULL,
  period = 24,
  prior = c("auto", "none"),
  BPPARAM = BiocParallel::bpparam(),
  verbose = TRUE,
  covariates = NULL
)

Arguments

se	A SummarizedExperiment with CpGs in rows and samples in columns. The assay contains numeric beta values in $[0,1]$, with missing values allowed.
time_col	Name of the collection-time column in colData(se), in hours.
subject_col	Name of the subject column for a random-intercept model, or NULL for a fixed-effects model of independent samples.
assay_name	Assay name, or NULL to use the first assay.
period	Oscillation period in hours. Default is 24.
prior	"auto" estimates an EB prior; "none" uses no prior. A named list with mean and positive sd supplies a normal prior on log precision. EB estimation requires at least 1,000 usable pilot fits.
BPPARAM	A BiocParallelParam object. Defaults to BiocParallel::bpparam(), which uses the user's registered default backend.
verbose	Whether to print fitting progress.
covariates	Names of numeric or categorical colData(se) columns for adjustment. Covariate coefficients are not returned.

Value

The input SummarizedExperiment with these rowData(se) columns:

• RhyME_b0, RhyME_b_sin, RhyME_b_cos: logit-scale intercept and sine/cosine coefficients.

• RhyME_log_phi, RhyME_tau: log precision and random-intercept SD.

• RhyME_score_chisq, RhyME_pvalue, RhyME_padj: score statistic, p-value, and BH-adjusted p-value across all input CpGs.

• RhyME_logit_amplitude, RhyME_amplitude: logit-scale amplitude and half the marginal mean curve's peak-to-trough difference on the methylation scale.

• RhyME_phase, RhyME_mesor: peak time in hours in $[0,\mathrm{period})$ and the marginal mean curve averaged over one period.

• RhyME_converged: whether both null and full fits converged.

Unusable null fits have NA p-values; unusable full fits have NA parameter estimates. Usable results from either fit are retained. Phase is undefined at zero amplitude. Existing row annotations are retained; refitting replaces only the result columns listed above. Unprefixed columns from earlier versions are retained as annotations. metadata(se)$RhyME stores design, ebPrior, and fitSummary.

See Also

plotCosinorFit()

Examples

# Independent samples: default fixed-effects model and automatic EB prior.
set.seed(123)
n_cpg <- 1200
time <- rep(seq(0, 20, by = 4), 8)
amplitude <- c(rep(0.6, 240), rep(0, 960))
mu <- plogis(outer(amplitude, sin(2 * pi * time / 24)))
beta <- matrix(rbeta(length(mu), mu * 40, (1 - mu) * 40),
    nrow = n_cpg, dimnames = list(paste0("cg", seq_len(n_cpg)),
        paste0("sample", seq_along(time))))
se_independent <- SummarizedExperiment::SummarizedExperiment(
    assays = list(beta = beta), colData = S4Vectors::DataFrame(time = time))
fit_fixed <- fitCosinor(se_independent,
    BPPARAM = BiocParallel::SerialParam(), verbose = FALSE)
S4Vectors::metadata(fit_fixed)$RhyME$ebPrior

# Repeated measurements: disable EB for this small subset.
ex <- readRDS(system.file("extdata", "example_data.rds", package = "RhyME"))
fit <- fitCosinor(ex$se[seq_len(5), ], subject_col = "subject",
    prior = "none", verbose = FALSE)
head(SummarizedExperiment::rowData(fit), 3)

---

Plot Fitted Cosinor Curves

Description

Plots observed beta values and fitted marginal mean curves over the observed time range, using the design saved by fitCosinor(). Curves describe the mean covariate profile; points are not covariate-adjusted.

Usage

plotCosinorFit(se, cpgs = NULL, ncol = 3)

Arguments

se	A SummarizedExperiment returned by fitCosinor(), with RhyME_-prefixed result columns. Refit objects from earlier versions that have only unprefixed results.
cpgs	CpG identifiers in panel order. NULL selects up to six CpGs with usable estimates, ordered by p-value.
ncol	Number of panels per row.

Value

A ggplot2 object.

See Also

fitCosinor()

Examples

ex <- readRDS(system.file("extdata", "example_data.rds", package = "RhyME"))
fit <- fitCosinor(ex$se[1, ], subject_col = "subject", prior = "none",
    verbose = FALSE)
plotCosinorFit(fit)

---