tiangzlab/omicsclaw/bulkrna-cosinor-rhythm

bulkrna-cosinor-rhythm

Purpose

Use this Skill for a bulk RNA time-course CSV whose sample columns follow T{hour}_R{replicate} and require a deterministic 24-hour, single-component cosinor OLS fit per gene. Use another method when the period must be estimated, the design has covariates, or multi-harmonic/non-sinusoidal rhythms are needed.

Inputs & Outputs

Outputs

• report.md
• result.json
• cosinor_results.csv
• semantic_summary.json

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

fit(timecourse)

Fit a fixed 24-hour sinusoid independently to each gene.

:param timecourse: Gene-indexed DataFrame with T00_R1-style sample columns. :returns: Parameter DataFrame with descriptive rhythmic flags and diagnostics. :raises ValueError: Empty data, missing time columns or infinite expression.

run_info(result, *, keep=True)

Read gene counts and time-column filtering decisions.

:param result: DataFrame returned by fit. :param keep: Default True; False removes diagnostic attrs. :returns: Diagnostic dictionary, empty after removal.

rhythm_figure(result)

Plot fitted amplitude against phase, without writing files.

:param result: Parameter DataFrame returned by fit. :returns: matplotlib Figure. :raises KeyError: Parameter columns are missing.

<!-- api:end -->

Flow

1. Load --input <csv> or the repository-bound demo dataset via --demo.
2. Parse time and replicate identities from the sample columns.
3. Fit mesor + beta_cos*cos(2*pi*t/24) + beta_sin*sin(2*pi*t/24) by OLS.
4. Derive amplitude, phase, fit statistics, and the per-gene rhythmicity verdict.
5. Write cosinor_results.csv, semantic_summary.json, report.md, and the standard result envelope.

Gotchas

• cosinor_results.csv marks rhythmic genes with descriptive thresholds (R-squared ≥ 0.8 and amplitude/mesor ≥ 0.2), not a significance test.
• semantic_summary.json lists columns dropped for more than 20% missing values. Duplicate gene identifiers keep their first row; fits with insufficient observations or a singular design return missing parameters.
• cosinor_results.csv uses a fixed 24-hour period; --method is retained as a report label, not a backend selector.

Key CLI

# Demo
python skills/bulkrna/run-derived/bulkrna-cosinor-rhythm/bulkrna_cosinor_rhythm.py --demo --output /tmp/bulkrna-cosinor-rhythm_demo
 
# Real input
python skills/bulkrna/run-derived/bulkrna-cosinor-rhythm/bulkrna_cosinor_rhythm.py \
  --input <data.ext> --output results/ \
  --method fixed-period-cosinor-ols

See also

• references/parameters.md — every CLI flag, per-method tunables
• references/methodology.md — the WHY behind the algorithm
• references/output_contract.md — result.json envelope + downstream paths

Dependencies

Python packages this skill's script needs. They are not installed for you — check before a long run.

numpy, pandas, matplotlib