[alisman]

What was wrong

A cohort compiled to a set of patients, and every view joined on <patient> IN (SELECT pid FROM cohort). A sample-level clause therefore pulled in every other sample of the patients it matched. The gallery's NSCLC cohort (msk_chord_2024) held 7,876 samples, 67 of them colorectal, breast, pancreatic and so on, and its gene frequencies counted mutations found only in those samples:

NSCLC, mutated	before	after	cbioportal.org
TP53	4,020	4,005	4,005
APC	327	312	312
PIK3CA	457	443	443
KRAS	2,194	2,183	2,183

check:portal never saw it: it compared filtered cohorts only by patient count, which is right by construction, and compared gene tables only under a patient-level filter (SEX = Female) and only through Explore's code path.

What this changes (cBioPortal's semantics)

• A cohort is a set of samples. Every clause compiles to (pid, sid) rows of the study's samples.
  • Sample-level clauses select the matching samples: sample attributes, OQL alterations, sample lists, profiled, genomicData, proteinPosition, caseList.
  • Patient-level clauses select every sample of the matching patients: patient attributes, event, derived, patient lists, the held-out split.
  • all/any/not are intersection, union and complement over samples.
• A clinical attribute is matched at the level each study records it. For example, GRADE is sample-level in pancan_pcawg_2020 and patient-level in lihc_tcga, and one clause now matches each study its own way. per is removed from the DSL and refused by name. No backward compatibility, as agreed.
• One join rule. A cohort's patients are the owners of its samples. inCohortSamples and inCohortPatients (lib/cohort2.ts) replace all 127 hand-written joins.
  • Gene counts, pair counts, co-expression and differential expression count samples, as the portal does.
  • Patient-unit views (survival, Cox, timelines, …) take a patient's genomic state from its in-cohort samples only.
• Locks freeze the cohort's samples, with each arm's samples as parts. Lock drift is measured in samples.
• Splits are decided per sample (first match wins), and their conservation is checked in samples.
• Explore treats the draft as a sample set. The oncoprint builds patient columns from the cohort's samples, resolved once and shipped as an external table.
• The patient-data boundary is unchanged in kind. Cohort SQL stays a subquery, and aggregate-only or remote peers never send or receive ids. The boundary and sql-kinds suites pass.

Verification

• check:portal: 724/724 agree with cbioportal.org. Two new sections:
  • Sample-level selections: NSCLC; SAMPLE_TYPE = Primary; Metastasis + SEX = Female; GRADE = IV in difg_glass_2019, where 56 patients have samples of different grades; OQL TP53: MUT. Each is compared on sizes, every row of Explore's gene tables, and the views' gene counts.
  • Mixed levels: pancan_pcawg_2020 + lihc_tcga under GRADE = G3, giving 75 + 125 samples.
  • These new sections failed 75 of 83 comparisons on the old code.
• check:cohorts: 41/41. The reference evaluator now works over sample ids.
• check:mutants: 21/21. Two new planted bugs bring the leak back, and both are caught:
  • a sample-level clause that takes whole patients (by check:cohorts);
  • gene counts joined on patients (by check:portal).
• Unit tests, the Postgres suite, the examples and their method scripts, and lint all pass.
• View snapshots are re-recorded and pass, including the reverse-order run.
• Example counts are re-pinned. Mutant cohorts shrink to the portal's numbers; wild-type cohorts grow, because a patient with any non-mutant sample now has samples in them.
• scripts/gate.sh: everything up to e2e passed: lint, build, unit, Postgres, access, Python conformance, the splitBy cost check, and the warehouse checks. The e2e stage was still running when this PR was opened. Please don't merge until it, or CI, is green.

Performance (docs/PERFORMANCE.md)

Base commit and this branch, run back to back and interleaved, uncached:

	base	this branch	change
all 92 gallery examples, end to end	191.0 s	204.9 s	+7.3% (median example 1.07×)
oncoprint bench (three cases)			6–17% faster

• Not the neutral result expected. Patient-level-clause cohorts now expand through sample_derived, and patient-unit views join on in-cohort samples. Two suspected causes were measured and ruled out; details are in the doc.
• The first version of the oncoprint was 3× slower. That's fixed by resolving the column samples once.

Left for follow-up

• Overlap exclusion (step 2, agreed): cBioPortal's group-comparison rule, which excludes overlapping samples from sample views and overlapping patients from patient views. This matters now, because a patient whose primary is TP53-mutant and whose metastasis isn't has samples in both "TP53 mut" and "TP53 wt".
• Generic-assay facets in Explore still count patients (the owners of in-cohort rows); the portal counts samples. Fixing it needs a unit label in the UI.
• drivernegative keeps patients as its unit, built from in-cohort samples. cBioPortal's group comparison would count samples.
• The patient page's tables still list all of a patient's samples, as cBioPortal's patient view does. The ?sampleId= mode (session/patient) will need an optional sample filter on alterationSource, patientSamplesSource and patientEventsSql.
• bench.mjs imported ./lib/oncoprint.js and could not run. Fixed here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Q3ezTZdin1WVnUH8kzqcMC

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
cbiolab-genie	Ready	Preview	Oct 28, 2026 1:43am UTC
cohort-lab	Ready	Preview	Oct 28, 2026 1:43am UTC

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.