/bulkrna-cosinor-rhythm

name: bulkrna-cosinor-rhythm
description: Load when the user needs Deterministic fixed-period 24-hour single-component cosinor OLS
  rhythm analysis for a bulk RNA time-course CSV. Skip when an existing bulkrna skill already covers the
  request.
trigger: cosinor, circadian rhythmicity, 24-hour rhythm, bulk RNA time course
tags:
- bulkrna
- autogenerated
- skill-scaffold

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`