[arena-ai-coding-agent]

Work in progress. Opened early so CI runs against the scaling module while the wiring
lands; the checklist below is filled in as each part arrives.

What this closes

Issue #16 asked for TSS, CSS and RSS as offsets rather than aliases to relative,
and carried the line "Deferred — DO NOT IMPLEMENT IN MILESTONE 3". That line is a scope
decision; it is lifted explicitly at the top of the new conditions document.

What the code did before:

Declared	What ran
TSS + nb_glm	counts kept, offset log(lib_sizes) (the one honest case)
TSS + anything else	proportions — the compositional transform the issue existed to avoid
CSS, RSS	aliased to relative, with a warning; under nb_glm a count model was fitted with fractions
size_factors	described as "DESeq2 median-of-ratios", computed as library size divided by its own geometric mean

What replaces it

src/analysis/scaling.jl (conditions published first, in
docs/statistics/method-conditions/scaling-and-offsets.md):

• TSS — log(library size).
• CSS — cumulative sum of counts at or below the declared per-sample quantile
  (Paulson et al. 2013), css_quantile default 0.75. Refused, by name, when the
  cumulative sum is zero: log(0) is not a small number. cumNormStatFast's data-driven
  choice of the quantile is deliberately not implemented — a parameter chosen from the
  data is a decision the run has to record.
• RSS/TMM — trimmed weighted mean of log-ratios to a reference sample
  (Robinson & Oshlack 2010), tmm_log_ratio_trim 0.3, tmm_sum_trim 0.05,
  tmm_ref_column optional, reference otherwise chosen the way edgeR chooses it.
• size_factors — median-of-ratios (RLE), which is what the name claimed.

All four return factors centred to geometric mean 1, the log-offset, the declared
parameters, the uncentred quantities and a SHA-256 of the offset vector. Refusals are
unsuccessful states: a zero-total sample, an all-zero cumulative sum, a sample with no
positive feature in common with the reference, or no feature positive in every sample all
raise with the reason attached, and none of them is replaced by a factor of 1.

Evidence

test/unit/test_scaling.jl: known answers whose arithmetic is written next to the
expected number, properties a wrong implementation fails (feature-permutation
invariance, a sample that is a multiple of another, the CSS outlier property that TSS
does not have), negative controls for every refusal, and the integration path through
prepare_analysis_table down to the offset in the manifest.

Stated limit, not hidden: parity with metagenomeSeq::cumNorm and
edgeR::calcNormFactors at 1e-6 is not verified here. Neither package is in the pinned
R environment, and this repository does not add an unpinned R dependency to make a test
pass. That acceptance item is recorded as outstanding rather than claimed.

Closes #16 (with the residual condition recorded in the issue thread).

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 6368eaea-f4d8-42a8-8bb1-d7135c78227e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}