Q (sonnet): What are the top 5 most frequently altered genes in a structural variant in the Osteosarcoma study from TARGET? ▶ list_studies { "search": "osteosarcoma target" } ▶ read_guide { "uri": "cbioportal://mutation-frequency-guide" } ◀ result {"result":[{"cancer_study_identifier":"os_target_gdc","name":"Osteosarcoma (TARGET GDC, 2025)","type_of_cancer_id":"os","sample_count":159,"has_guide":true,"url":"https://www.cbioportal.org/study/summary?id=os_target_gdc"}]} ◀ 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 … (36467 more chars) ▶ clickhouse_run_select_query { "query": "SELECT * FROM top_sv_genes_in_study(study = 'os_target_gdc', top_n = 5)" } ◀ result {"rows":[]} ▶ clickhouse_run_select_query { "query": "SELECT cancer_study_identifier, sample_count, resource_sample_counts FROM cancer_study WHERE cancer_study_identifier = 'os_target_gdc'" } ▶ clickhouse_list_table_columns { "table": "cancer_study" } ◀ result {"rows":[{"cancer_study_identifier":"os_target_gdc","sample_count":159,"resource_sample_counts":{}}]} ◀ result {"columns":[{"name":"cancer_study_id","type":"Int64","comment":"Internal numeric ID. Prefer cancer_study_identifier for queries as it is more readable and stable."},{"name":"cancer_study_identifier","type":"Nullable(String)","comment":"Stable string identifier for the study (e.g., \"msk_chord_2024\", \"brca_tcga\"). Use this for filtering, not cancer_study_id."},{"name":"type_of_cancer_id","type":"String"},{"name":"name","type":"String","comment":"Full descriptive name of the study (e.g., \"MSK-CHORD (MSK, Nature 2024)\")."},{"name":"description","type":"String"},{"name":"public","type":"Int32"},{"name":"pmid","type":"Nullable(String)"},{"name":"citation","type":"Nullable(String)"},{"name":"groups","type":"Nullable(String)"},{"name":"status","type":"Nullable(Int64)"},{"name":"import_date","type":"Nullable(DateTime64(6))"},{"name":"reference_genome_id","type":"Nullable(Int64)"},{"name":"sample_count","type":"UInt32","comment":"Samples in the study (members of _all), as shown in the portal study list. Precomputed daily at LLM-prep time."},{"name":"mutation_sample_count","type":"UInt32","comment":"Samples profiled for mutations (_sequenced) — portal \"Data type\" filter: \"Mutations\". 0 = no mutation data."},{"name":"cna_sample_count","type":"UInt32","comment":"Samples profiled for copy-number alterations (_cna) — \"CNA\". 0 = no CNA data."},{"name":"structural_variant_sample_count","type":"UInt32","comment":"Distinct samples with at least one structural variant (fusions etc.). 0 = none."},{"name":"rna_seq_sample_count","type":"UInt32","comment":"Samples with RNA-Seq expression (_rna_seq_v2_mrna) — \"RNA-Seq\"."},{"name":"mrna_microarray_sample_count","type":"UInt32","comment":"Samples with microarray mRNA expression (_mrna) — \"RNA (microarray)\"."},{"name":"mirna_sample_count","type":"UInt32","comment":"Samples with microRNA expression (_microrna) — \"miRNA\"."},{"name":"rppa_sample_count","type":"UInt32","comment":"Samples with RPPA protein levels (_rppa) — \"RPPA\"."},{"name":"mass_spectrometry_sample_count","type":"UInt32","comment":"Samples with mass-spectrometry protein quantification (_protein_quantification) — \"Protein Mass-Spectrometry\"."},{"name":"treatment_patient_count","type":"UInt32","comment":"PATIENTS (not samples) with treatment clinical events — \"Treatment\". 0 = no treatment data."},{"name":"resource_sample_counts","type":"Map(String, UInt32)","comment":"Samples with each linked resource, keyed by display name: imaging and pathology such as 'Slide Microscopy', 'Computed Tomography', 'Magnetic Resonance', 'H&E Slide', 'MxIF Image'. Query with mapKeys(resource_sample_counts) or resource_sample_counts['Slide Microscopy'] > 0."},{"name":"mrna_expression_sample_count","type":"UInt32","comment":"Samples in any mRNA expression profile (RNA-Seq, microarray, TPM, z-scores; from sample_profile). Use this for \"does the study have expression data\" — rna_seq_sample_count and mrna_m … (136 more chars) ▶ clickhouse_run_select_query { "query": "SELECT structural_variant_sample_count FROM cancer_study WHERE cancer_study_identifier = 'os_target_gdc'" } ◀ result {"rows":[{"structural_variant_sample_count":0}]} ═ answer (success) The Osteosarcoma (TARGET GDC, 2025) study — [`os_target_gdc`](https://www.cbioportal.org/study/summary?id=os_target_gdc), 159 samples — does not contain any structural variant data (0 samples with structural variants recorded). So there are no genes to rank by structural variant frequency in this study. Note that "TARGET" also has other cohorts that were revised/renamed over time (e.g. an older `os_target_2018` version may exist on the public portal). If you'd like, I can check whether an older TARGET Osteosarcoma study version has structural variant data, or show you the mutation/CNA frequency data instead, which this study does have.