Q (haiku): What percentage of colorectal cancer samples have KRAS mutations in the MSK-CHORD Study? ▶ read_guide { "uri": "cbioportal://mutation-frequency-guide" } ▶ get_study_guide { "study_id": "msk_chord" } ▶ list_studies { "search": "MSK-CHORD" } ◀ result # Mutation Frequency Analysis Guide ## IMPORTANT: Reporting Mutation Frequencies - **ALWAYS report frequencies as percentages**, not raw counts: `frequency = (altered_samples / total_profiled_samples) × 100` - For quick frequency lookups, **prefer the TCGA Pan-Cancer Atlas study first**, then offer to expand to other studies - When reporting across multiple studies, show **ranges** (e.g., "TP53 is mutated in 30–60% of samples") rather than a single average - **NEVER** sum mutation events across studies to compute an aggregate frequency — this can exceed 100% due to double-counting - Warn users that samples may overlap across cohorts (e.g., MSK studies may share patients) - **Choose and state the counting unit**: use patient-level frequencies for prevalence/rate questions unless the user explicitly asks for samples; use sample-level frequencies when the user asks about samples. - **For "across cancer types" questions**, jump to the [Cross-Cancer-Type Mutation Frequency](#cross-cancer-type-mutation-frequency) section below — there is one correct recipe and several common wrong ones. ## Counting Unit: Samples vs Patients Before answering any mutation count or frequency question, decide whether the unit is samples or patients and state that choice in the answer. | User wording | Counting unit | |--------------|---------------| | "prevalence", "rate", "fraction of patients", "patients with", "how common is" | Patient-level: `COUNT(DISTINCT patient_unique_id)` | | "samples", "specimens", "biopsies", sample-level cohort composition | Sample-level: `COUNT(DISTINCT sample_unique_id)` | | Ambiguous | Ask, or default to patient-level for prevalence/rate language and say so | ### Cross-study sample-count caveat When an answer touches more than one study and reports a sample count, prepend a one-line caveat: > Sample IDs are unique within cBioPortal study prefixes, not guaranteed biological-sample identifiers across studies; overlapping cohorts can count the same patient/sample more than once. Prefer one of these safer approaches: - Use a shipped `cancer_study_query_preferences` cohort such as `pan_cancer_tcga` or `all_studies_non_redundant`. - Restrict to one named study. - Aggregate by `patient_unique_id` when the biological question is patient prevalence. ## STOP rule: a frequency above 100% means your query is wrong If your query returns a frequency over 100%, **do not try to debug or explain the data inconsistency to the user**. The cause is always one of these query bugs: - Summing mutation events instead of `COUNT(DISTINCT sample_unique_id)` for the numerator - Using a study-wide sample count as the denominator instead of the gene-specific profiled count - Cross-study aggregation where the same biological sample appears under multiple `sample_unique_id` values (e.g., MSK-IMPACT and MSK-CHORD share patients) - **Joining the profiled CTE through `gene_panel` / `gene_panel_list` without a WES branch.** `gene_panel_id = 'WES'` is *not* a row in … (35166 more chars) ◀ result Identifier 'msk_chord' did not match any study in the database this deployment is connected to. This is NOT proof the study does not exist. Before you tell the user it is unavailable, rule out all three of these: 1. **Different identifier.** Search rather than guess: `SELECT cancer_study_identifier, name FROM cancer_study WHERE lower(name) LIKE '%%'`. 2. **Another cBioPortal instance.** Public cbioportal.org, pedcbioportal, and GENIE hold different study sets — read `cbioportal://study-resolution-guide`. 3. **Access restriction.** A study the current credentials cannot read is absent from these results, which is a permissions outcome, not a missing study. Studies in this deployment with a similar identifier: - `acyc_mskcc_2013` — Adenoid Cystic Carcinoma (MSK, Nat Genet 2013) - `blca_dfarber_mskcc_2014` — Bladder Urothelial Carcinoma (DFCI/MSK, Cancer Discov 2014) - `appendiceal_msk_2022` — Appendiceal Cancer (MSK, J Clin Oncol 2022) - `bladder_columbia_msk_2018` — Bladder Cancer (Columbia University/MSK, Cell 2018) - `bladder_msk_2023` — Bladder Cancer (MSK, Clin Cancer Res 2023) - `asclc_msk_2024` — Atypical Small Cell Lung Cancer (MSK, Cancer Discov 2024) - `blca_plasmacytoid_mskcc_2016` — Bladder Cancer (MSK, Nat Genet 2016) - `blca_mskcc_solit_2012` — Bladder Cancer (MSK, J Clin Onco 2013) - `blca_mskcc_solit_2014` — Bladder Cancer (MSK, Eur Urol 2014) - `bowel_colitis_msk_2022` — Colorectal Adenocarcinoma (MSK, Nat Commun 2022) Do not tell the user that 'msk_chord' does not exist. Say it is not in this deployment, and offer the candidates above or the other instances. ◀ result {"result":[{"cancer_study_identifier":"msk_chord_2024","name":"MSK-CHORD (MSK, Nature 2024)","type_of_cancer_id":"mixed","sample_count":25040,"has_guide":true,"url":"https://www.cbioportal.org/study/summary?id=msk_chord_2024"}]} ▶ clickhouse_run_select_query { "query": " SELECT * FROM gene_mutation_frequency_in_study( study = 'msk_chord_2024', gene = 'KRAS' ) WHERE cancer_type LIKE '%Colorectal%' OR cancer_type LIKE '%Colon%' ORDER BY frequency_pct DESC " } ◀ result {"rows":[{"cancer_type":"Colorectal Cancer","altered_samples":2355,"profiled_samples":5543,"frequency_pct":42.5}]} ▶ resolve_and_route { "studyIds": [ "msk_chord_2024" ] } ◀ result {"success":true,"message":"Found 1 study. Use the metadata to call the appropriate navigation tool(s).","data":{"totalCount":1,"studiesWithMetadata":[{"studyId":"msk_chord_2024","name":"MSK-CHORD (MSK, Nature 2024)","sampleCount":25040,"studyViewUrl":"https://www.cbioportal.org/study?id=msk_chord_2024","metadata":{"clinicalAttributeIds":["ADRENAL_GLANDS","BONE","CANCER_TYPE","CANCER_TYPE_DETAILED","CLINICAL_GROUP","CLINICAL_SUMMARY","CNS_BRAIN","CURRENT_AGE_DEID","DIAGNOSIS_DESCRIPTION","ETHNICITY","FRACTION_GENOME_ALTERED","GENDER","GENE_PANEL","GLEASON_FIRST_REPORTED","GLEASON_HIGHEST_REPORTED","GLEASON_SAMPLE_LEVEL","HER2","HISTORY_OF_PDL1","HR","ICD_O_HISTOLOGY_DESCRIPTION","INTRA_ABDOMINAL","LIVER","LUNG","LYMPH_NODES","METASTATIC_SITE","MSI_COMMENT","MSI_SCORE","MSI_TYPE","MUTATION_COUNT","NUM_ICDO_DX","ONCOTREE_CODE","OS_MONTHS","OS_STATUS","OTHER","PATHOLOGICAL_GROUP","PDL1_POSITIVE","PLEURA","PRIMARY_SITE","PRIOR_MED_TO_MSK","RACE","REPRODUCTIVE_ORGANS","SAMPLE_CLASS","SAMPLE_COUNT","SAMPLE_COVERAGE","SAMPLE_TYPE","SMOKING_PREDICTIONS_3_CLASSES","SOMATIC_STATUS","STAGE_HIGHEST_RECORDED","TMB_NONSYNONYMOUS","TUMOR_PURITY"],"molecularProfileIds":["msk_chord_2024_cna","msk_chord_2024_mutations","msk_chord_2024_structural_variants"],"availableComparisonTabs":["overlap","clinical","survival","alterations","mutations"]}}]}} ▶ navigate_to_results_view { "studyIds": [ "msk_chord_2024" ], "genes": [ "KRAS" ], "studyViewFilter": { "clinicalDataFilters": [ { "attributeId": "CANCER_TYPE", "values": [ { "value": "Colorectal Cancer" } ] } ] }, "tab": "oncoprint" } ◀ result {"success":true,"message":"Navigating to https://www.cbioportal.org/results/oncoprint?session_id=6ab42840c2115c492d88493c","url":"https://www.cbioportal.org/results/oncoprint?session_id=6ab42840c2115c492d88493c","data":{"studyIds":["msk_chord_2024"],"studies":[{"studyId":"msk_chord_2024","name":"MSK-CHORD (MSK, Nature 2024)","sampleCount":25040}],"genes":["KRAS"],"filteredSampleCount":5543,"caseSetId":"-1","sessionId":"6ab42840c2115c492d88493c","studyViewUrl":"https://www.cbioportal.org/study?id=msk_chord_2024#filterJson=%7B%22clinicalDataFilters%22%3A%5B%7B%22attributeId%22%3A%22CANCER_TYPE%22%2C%22values%22%3A%5B%7B%22value%22%3A%22Colorectal%20Cancer%22%7D%5D%7D%5D%7D","pageDescription":"Visual summary of alterations in queried genes across samples."}} ═ answer (success) ## Results **In the MSK-CHORD study, 42.5% of colorectal cancer samples have KRAS mutations.** **Details:** - **Altered samples:** 2,355 / 5,543 profiled - **Study:** MSK-CHORD (MSK, Nature 2024) - **Cancer type:** Colorectal Cancer - **Counting unit:** Sample-level frequency --- ### Explore the Data **[View KRAS mutations in colorectal cancer (OncoPrint)](https://www.cbioportal.org/results/oncoprint?session_id=6ab42840c2115c492d88493c)** Visual alteration summary filtered to colorectal cancer samples. **[Browse the full MSK-CHORD colorectal cohort](https://www.cbioportal.org/study?id=msk_chord_2024#filterJson=%7B%22clinicalDataFilters%22%3A%5B%7B%22attributeId%22%3A%22CANCER_TYPE%22%2C%22values%22%3A%5B%7B%22value%22%3A%22Colorectal%20Cancer%22%7D%5D%7D%5D%7D)** Explore all 5,543 colorectal cancer samples in MSK-CHORD.