---
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

```bash
# 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`