Highlight each locus of a gene name in scatter --gene

[etal]

CopyNumArray.by_gene groups a gene's bins per locus, but plots.gene_coords_by_name still reported a name's position as the minimum start and maximum end over every bin naming it anywhere in the array. CNVkit therefore held two answers to "where is gene X":

$ cnvkit.py genemetrics test/formats/wgs-chr17.cnr -t 0 | grep -c Y_RNA
26
$ cnvkit.py scatter test/formats/wgs-chr17.cnr -g Y_RNA
Showing 160038 probes and 1 selected genes in region chr17:3046728.0-81407638.0

One gold band 76 Mb wide, asserting that every bin between the first and last Y_RNA occurrence is Y_RNA.

What the fix does

gene_coords_by_name now walks the same runs as by_gene, through the newly public cnvlib.cnary.gene_runs, and returns one region per locus. A locus spans its run's first and last bin, which is precisely the start and end genemetrics publishes for it (reports.group_by_genes emits rows[0] with end = rows.end.iat[-1]), so the two surfaces now agree by construction rather than by coincidence: the 26 loci genemetrics reports for Y_RNA are exactly 26 of the 29 regions scatter highlights, coordinate for coordinate. The three it omits are single-bin loci dropped by its own -t threshold.

The per-locus rule also retires the assumption that a name occupies one chromosome. core.check_unique asserted that, and its AssertionError: Inconsistent DUPGENE keys: chr1 chr2 fired before scatter could report the ambiguity — which is why select_range_genes' own "split across chromosomes" error had been unreachable since 2014. The assertion and its now-unused definition are gone; the ambiguity is resolved by selecting a chromosome with -c, or refused with a message naming both candidates.

Numerical effect on plotted regions

Every gene name in both fixtures, old rule (reimplemented inline) against new:

fixture	names	span unchanged	span changed
test/formats/wgs-chr17.cnr	2276	2270	6
test/formats/amplicon.cnr	79	79	0

All six that move are repeat families, and each shrinks from one span to a set of loci:

name	was	now
snoU13	1 region, 79,133,335 bp	16 regions, 2,785,752 bp
Y_RNA	1 region, 76,360,910 bp	29 regions, 3,392,141 bp
U3	1 region, 14,391,943 bp	3 regions, 487,087 bp
Vault	1 region, 7,079,244 bp	2 regions, 270,544 bp
SNORA70	1 region, 2,164,137 bp	2 regions, 626,062 bp
SNORA74	1 region, 1,614,279 bp	2 regions, 257,476 bp

cnvkit.py scatter test/formats/amplicon.cnr -g ERBB2 renders a byte-identical PNG before and after (md5 a27dbfd2c98d737c02a9ee4ecd5ac9a5), the control case for the whole class of single-locus genes.

Behaviour changes to be aware of

• A gene name on several chromosomes now needs one chosen with -c; without it, the refusal names the chromosomes rather than dying in an assert.
• With an explicit region, only the loci inside it are highlighted, and how many were left out is logged. A named gene with no locus in the region is still refused with the pre-existing message.
• -g '' alongside -c no longer raises KeyError('popitem(): dictionary is empty'). gene_names was a filter object, always truthy, so the empty-gene-list branch documented in doc/plots.rst was unreachable.
• A placeholder name such as Antitarget, Background, - or . is no longer findable by -g, since the grouping honours params.IGNORE_GENE_NAMES. It previously plotted a span from the first such bin to the last. genemetrics has always hidden these.
• A locus straddling the region boundary is dropped rather than aborting the plot, when another locus of the same gene lies inside. The containment test is unchanged; only its consequence for the remaining loci is.

Alternatives measured and rejected

Implementing the lookup on by_gene() itself was the obvious route and costs 1750 ms per call on wgs-chr17.cnr (165,626 bins) against 65 ms for the superseded targeted scan, because it materializes a CopyNumArray for every group on the chromosome merely to read two coordinates. Sharing gene_runs instead costs 147 ms, so scatter --gene keeps its latency and there is still exactly one grouping rule. Moving the lookup into cnary as a CopyNumArray method, as the deleted XXX comment mused, would carry the requested-name filtering and label joining across a layer boundary in the wrong direction; those are presentation concerns and stay in plots.

Left for later

plots.gene_coords_by_range, 25 lines further down the same module, still applies the first-to-last rule within its window: over the whole of chr17 in wgs-chr17.cnr it returns a single Y_RNA region at 7,440,413-46,556,560, a 39 Mb band, so scatter -c chr17 and scatter -c chr17 -g Y_RNA still disagree. That body also carries the comma-joined pseudo-gene defect (ERBB2,MIR4728 returned as one label), which needs a decision about tabular breaks output before either can be fixed; both live in the same twelve lines and one rewrite over gene_runs settles them together.

Tests

test/test_plots.py gains four cases in GeneCoordsTests and a new ScatterSelectionTests class of seven. Run against the previous commit, ten of them fail and four pass, so each guard bites the defect it names. The per-locus case includes a placeholder bin interrupting a run, which is the only cheap way to pin that the ignore set is honoured; one case cross-checks all 29 real Y_RNA loci against by_gene on the fixture. Full suite: 721 passed, 147 subtests.

[codecov]

Codecov Report

❌ Patch coverage is 97.56098% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 76.25%. Comparing base (0431f17) to head (f47647a).
⚠️ Report is 4 commits behind head on master.

Files with missing lines	Patch %	Lines
cnvlib/scatter.py	96.15%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1177      +/-   ##
==========================================
+ Coverage   76.08%   76.25%   +0.17%     
==========================================
  Files          75       75              
  Lines        8421     8428       +7     
  Branches     1489     1492       +3     
==========================================
+ Hits         6407     6427      +20     
+ Misses       1578     1568      -10     
+ Partials      436      433       -3     

Flag	Coverage Δ
unittests	76.25% <97.56%> (+0.17%)	⬆️

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.