Q (sonnet): what's the best way to put clinical data into cbioportal?

═ answer (success)
The best way to add clinical data to cBioPortal depends on whether you're loading a new study locally/on-premises or contributing to the public portal. Since this is a general "how-to" question rather than a data query against the current database, here's the standard guidance:

## Standard approach: Clinical data files (TSV format)

cBioPortal expects clinical data as **tab-delimited files** with a specific metadata header block, loaded alongside a `meta_clinical_*.txt` descriptor. There are two levels:

1. **Patient-level clinical data** — `data_clinical_patient.txt`
   - One row per patient
   - Attributes like `PATIENT_ID`, `SEX`/`GENDER`, `AGE`, `OS_STATUS`, `OS_MONTHS`, etc.

2. **Sample-level clinical data** — `data_clinical_sample.txt`
   - One row per sample
   - Requires `PATIENT_ID` and `SAMPLE_ID`, plus attributes like `CANCER_TYPE`, `SAMPLE_TYPE`, `TUMOR_PURITY`, etc.

### Required header format (5 lines, `#`-prefixed) before the column header row:
```
#Cancer Study Identifier: 
#Patient Identifier
#Number of Patients
#Number of Samples
```
Each data file needs a matching `meta_clinical_patient.txt` / `meta_clinical_sample.txt`:
```
cancer_study_identifier: your_study_id
genetic_alteration_type: CLINICAL
datatype: PATIENT_ATTRIBUTES  (or SAMPLE_ATTRIBUTES)
data_filename: data_clinical_patient.txt
```

### Loading mechanism
- Use cBioPortal's `metaImport.py` / `cbioportalImporter.py` scripts (from the [cBioPortal GitHub repo](https://github.com/cBioPortal/cbioportal)) to validate and import the study folder into your instance.
- Run the **Validator** (`validateData.py`) first — it checks required columns, attribute type consistency, and cross-references sample/patient IDs against your mutation/CNA/expression files.

### Special/reserved clinical attributes
Certain column names have reserved meaning and drive portal features (survival plots, oncoprint annotations): `OS_STATUS`, `OS_MONTHS`, `DFS_STATUS`, `DFS_MONTHS`, `SEX`, `AGE`, `SAMPLE_TYPE`, `CANCER_TYPE`, `CANCER_TYPE_DETAILED`. Use these exact names if you want that functionality to work automatically.

### If updating an existing/public study
For contributing to the public cBioPortal.org instance, you'd typically open a pull request against the [datahub repository](https://github.com/cBioPortal/datahub) with your clinical files formatted as above, or contact the cBioPortal team directly for curation review.

---

Since this is a general onboarding/data-loading question rather than a query against a specific study already in this database, there's no direct navigation link for it — this process happens outside the web UI, via the backend import scripts. If you're trying to add clinical data to a **specific study you already see in this cBioPortal instance**, let me know which one and what data you're adding, and I can help you verify the schema/format against what's already loaded.