import-rna: add --min-sample-fraction for sparse/single-cell cohorts (#448)

[etal]

Summary

import-rna hard-coded its gene-expression filter at "expressed in at least half of the samples" (filter_probes: median(counts) >= 1). As reported in #448, this is too strict for single-cell or otherwise sparse cohorts, where most genes are legitimately expressed in fewer than half of cells and the default discards informative genes.

This adds a --min-sample-fraction option (default 0.5) plumbed through the CLI → do_import_rna → filter_probes.

Design: bit-exact at the default

The legacy filter kept a gene when median(counts) >= 1. This generalizes it to keep a gene when its (1 - min_sample_fraction) quantile of per-sample counts is >= 1. Since the median is the 0.5 quantile, the default reduces to the old rule bit-exact — verified end-to-end on the RNA fixture (summary table and every .cnr log2 column identical).

A naive "fraction of samples with count ≥ 1" reimplementation would not be bit-exact — e.g. counts [0, 1] have median 0.5 (dropped) but a 0.5 expressed-fraction (kept) — so the quantile form is the correct generalization.

Changes

• cnvlib/rna.py: filter_probes gains min_sample_fraction (default 0.5); validates [0, 1]; short-circuits empty input (quantile(axis=1) raises ValueError: no types given on an empty frame, where the old median(axis=1) returned empty).
• cnvlib/import_rna.py: do_import_rna gains min_sample_fraction, forwarded to filter_probes.
• cnvlib/commands.py: new --min-sample-fraction flag on import-rna.
• doc/rna.rst: documents the flag, the single-cell use case, and a noise warning for values below ~0.2.

Tests (test/test_rna.py)

• Gene retained iff N/M >= min_sample_fraction across the full N=0..10 grid and fractions 0.1..1.0.
• Lower fraction is monotonically more permissive; rescues a sparsely-expressed gene at 0.2 that 0.5 drops.
• Default reproduces the legacy median >= 1 filter bit-exact on a random matrix.
• Edge cases: empty frame (regression guard), single-sample, invalid fractions raise.
• AST-walk plumbing guards that the kwarg is forwarded CLI → do_import_rna → filter_probes.

Clinical impact

None at the default (output preserved bit-exact). Users who lower the threshold retain more genes in the output .cnr, which may shift downstream segmentation — a deliberate, documented trade-off for sparse data.

Closes #448.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 70.75%. Comparing base (240aca1) to head (7933b6d).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1107      +/-   ##
==========================================
+ Coverage   70.73%   70.75%   +0.01%     
==========================================
  Files          73       73              
  Lines        7946     7951       +5     
  Branches     1405     1407       +2     
==========================================
+ Hits         5621     5626       +5     
  Misses       1881     1881              
  Partials      444      444              

Flag	Coverage Δ
unittests	70.75% <100.00%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.