> For the complete documentation index, see [llms.txt](https://docs.bcbi.brown.edu/codiac-for-health/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bcbi.brown.edu/codiac-for-health/ursa-ri/datasets/cbioportal-for-cancer-genomics/data-dictionary.md).

# Data Dictionary

## 1. Discrete Copy Number Data

<table data-search="false"><thead><tr><th>Field</th><th>Required?</th><th>Description</th></tr></thead><tbody><tr><td>Hugo_Symbol</td><td>Required*</td><td>HUGO gene symbol (*one of Hugo_Symbol or Entrez_Gene_Id required)</td></tr><tr><td>Entrez_Gene_Id</td><td>Required*</td><td>Entrez Gene numeric identifier (*one of Hugo_Symbol or Entrez_Gene_Id required)</td></tr><tr><td>[SAMPLE_ID columns]</td><td>Required</td><td>A sample ID. This field can only contain numbers, letters, points, underscores and hyphens.</td></tr><tr><td>cbp_driver</td><td>Optional</td><td>Custom driver annotation: Putative_Driver, Putative_Passenger, Unknown, NA</td></tr><tr><td>cbp_driver_annotation</td><td>Optional</td><td>Free-text description of driver annotation (max 80 chars). *This field must be present if the cbp_driver is also present in the MAF file</td></tr><tr><td>cbp_driver_tiers</td><td>Optional</td><td>Driver tier label, e.g. 'Highly actionable' (max 20 chars). *This field must be present if the cbp_driver_tiers_annotation is also present in the MAF file</td></tr><tr><td>cbp_driver_tiers_annotation</td><td>Optional</td><td>Description of driver tier (max 80 chars). *This field must be present if the cbp_driver_tiers is also present in the MAF file</td></tr></tbody></table>

## 2. Continuous Copy Number Data

| Field                 | Required?  | Description                                                                         |
| --------------------- | ---------- | ----------------------------------------------------------------------------------- |
| Hugo\_Symbol          | Required\* | HUGO gene symbol (\*one of Hugo\_Symbol or Entrez\_Gene\_Id required)               |
| Entrez\_Gene\_Id      | Required\* | Entrez Gene numeric identifier (\*one of Hugo\_Symbol or Entrez\_Gene\_Id required) |
| \[SAMPLE\_ID columns] | Required   | One column per sample; continuous copy number or log2 value per gene-sample pair    |

## 3. Segmented Data (SEG)

[Should follow this format](https://igv.org/doc/desktop/#FileFormats/DataTracks/#igv). Link does not work from cBioPortal.

| Field     | Required? | Description                                                                          |
| --------- | --------- | ------------------------------------------------------------------------------------ |
| ID        | Required  | Sample identifier                                                                    |
| chrom     | Required  | Index of the chromosome column                                                       |
| loc.start | Required  | Index of the start position column                                                   |
| loc.end   | Required  | Index of the end position column                                                     |
| num.mark  | Required  | Index of a probe or description column                                               |
| seg.mean  | Required  | No description provided (might be under the data tab on [IGV.org](http://igv.org/) ) |

## 4. Expression Data (mRNA / microRNA)

| Field                 | Required?     | Description                                                                    |
| --------------------- | ------------- | ------------------------------------------------------------------------------ |
| Hugo\_Symbol          | Recommended\* | HUGO gene symbol (\*one of Hugo\_Symbol or Entrez\_Gene\_Id required)          |
| Entrez\_Gene\_Id      | Recommended\* | Entrez Gene numeric identifier (preferred; reduces ambiguity)                  |
| \[SAMPLE\_ID columns] | Required      | One column per sample; real-number expression value or NA per gene-sample pair |

## 5. Mutation Data (MAF)

| Field                             | Required?       | Description                                                                                                                                           |
| --------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hugo\_Symbol                      | Required        | A HUGO gene symbol.                                                                                                                                   |
| Entrez\_Gene\_Id                  | Recommended     | A Entrez Gene numeric identifier.                                                                                                                     |
| Center                            | Optional        | The sequencing center.                                                                                                                                |
| NCBI\_Build                       | Required        | Genome Reference Consortium Build used by variant calling software. Must be GRCh37 or GRCh38 for human, GRCm38 for mouse.                             |
| Chromosome                        | Required        | A chromosome number, e.g. '7'.                                                                                                                        |
| Start\_Position                   | Recommended     | Start position of the event. Required for Cancer Hotspots annotations.                                                                                |
| End\_Position                     | Recommended     | End position of the event. Required for Cancer Hotspots annotations.                                                                                  |
| Strand                            | Optional        | Strand of the mutation. Assumed to be reported for the + strand.                                                                                      |
| Variant\_Classification           | Required        | Translational effect of variant allele, e.g. Missense\_Mutation, Nonsense\_Mutation, Silent, Splice\_Site, Frame\_Shift\_Del, etc. (TCGA MAF values). |
| Variant\_Type                     | Optional        | Variant type, e.g. SNP, DNP, INS, DEL, etc.                                                                                                           |
| Reference\_Allele                 | Required        | The plus strand reference allele at this position.                                                                                                    |
| Tumor\_Seq\_Allele1               | Optional        | Primary data genotype (allele 1).                                                                                                                     |
| Tumor\_Seq\_Allele2               | Required        | Primary data genotype (variant allele).                                                                                                               |
| dbSNP\_RS                         | Optional        | Latest dbSNP rs ID for this position.                                                                                                                 |
| dbSNP\_Val\_Status                | Optional        | dbSNP validation status.                                                                                                                              |
| Tumor\_Sample\_Barcode            | Required        | Sample ID — either a TCGA barcode (patient ID extracted automatically) or a literal SAMPLE\_ID from the clinical data file.                           |
| Matched\_Norm\_Sample\_Barcode    | Optional        | Sample ID for the matched normal sample.                                                                                                              |
| Match\_Norm\_Seq\_Allele1         | Optional        | Primary data genotype for matched normal (allele 1).                                                                                                  |
| Match\_Norm\_Seq\_Allele2         | Optional        | Primary data genotype for matched normal (allele 2).                                                                                                  |
| Tumor\_Validation\_Allele1        | Optional        | Secondary data from orthogonal technology (tumor allele 1).                                                                                           |
| Tumor\_Validation\_Allele2        | Optional        | Secondary data from orthogonal technology (tumor allele 2).                                                                                           |
| Match\_Norm\_Validation\_Allele1  | Optional        | Secondary data from orthogonal technology (normal allele 1).                                                                                          |
| Match\_Norm\_Validation\_Allele2  | Optional        | Secondary data from orthogonal technology (normal allele 2).                                                                                          |
| Verification\_Status              | Optional        | Second pass results from independent attempt using same methods. Values: Verified, Unknown, or NA.                                                    |
| Validation\_Status                | Optional        | Second pass results from orthogonal technology. Values: Valid, Invalid, Untested, Inconclusive, Redacted, Unknown, or NA.                             |
| Mutation\_Status                  | Optional        | Somatic or Germline are displayed in the Mutations tab. None, LOH, and Wildtype will not be loaded. Other values displayed as text.                   |
| Sequencing\_Phase                 | Optional        | Indicates current sequencing phase.                                                                                                                   |
| Sequence\_Source                  | Optional        | Molecular assay type used to produce the analytes used for sequencing.                                                                                |
| Validation\_Method                | Optional        | The assay platforms used for the validation call.                                                                                                     |
| Score                             | Optional        | Not used by cBioPortal.                                                                                                                               |
| BAM\_File                         | Optional        | Not used by cBioPortal.                                                                                                                               |
| Sequencer                         | Optional        | Instrument used to produce primary data.                                                                                                              |
| HGVSp\_Short                      | Required        | Amino acid change in HGVS notation, e.g. p.V600E.                                                                                                     |
| t\_alt\_count                     | Optional        | Variant allele count (tumor).                                                                                                                         |
| t\_ref\_count                     | Optional        | Reference allele count (tumor).                                                                                                                       |
| n\_alt\_count                     | Optional        | Variant allele count (normal).                                                                                                                        |
| n\_ref\_count                     | Optional        | Reference allele count (normal).                                                                                                                      |
| cbp\_driver                       | Optional        | Custom driver annotation: Putative\_Driver, Putative\_Passenger, Unknown, NA, or empty.                                                               |
| cbp\_driver\_annotation           | Optional        | Free-text description of the driver annotation (max 80 chars).                                                                                        |
| cbp\_driver\_tiers                | Optional        | Driver tier label, e.g. 'Highly actionable' (max 20 chars).                                                                                           |
| cbp\_driver\_tiers\_annotation    | Optional        | Description of the driver tier value (max 80 chars).                                                                                                  |
| ASCN.ASCN\_METHOD                 | Optional (ASCN) | Method used to obtain allele-specific copy number data, e.g. FACETS.                                                                                  |
| ASCN.CCF\_EXPECTED\_COPIES        | Optional (ASCN) | Cancer-cell fraction if mutation exists on major allele.                                                                                              |
| ASCN.CCF\_EXPECTED\_COPIES\_UPPER | Optional (ASCN) | Upper error bound for cancer-cell fraction estimate.                                                                                                  |
| ASCN.EXPECTED\_ALT\_COPIES        | Optional (ASCN) | Estimated number of copies harboring the mutant allele.                                                                                               |
| ASCN.CLONAL                       | Optional (ASCN) | Clonal status: Clonal, Subclonal, or Indeterminate.                                                                                                   |
| ASCN.TOTAL\_COPY\_NUMBER          | Optional (ASCN) | Total copy number of the gene.                                                                                                                        |
| ASCN.MINOR\_COPY\_NUMBER          | Optional (ASCN) | Copy number of the minor allele.                                                                                                                      |
| ASCN.ASCN\_INTEGER\_COPY\_NUMBER  | Optional (ASCN) | Absolute integer copy-number estimate.                                                                                                                |
| Site2\_Region                     | Recommended     | Region type: 5\_Prime\_UTR, 3\_Prime\_UTR, Promoter, Exon, or Intron                                                                                  |
| Site2\_Chromosome                 | Recommended     | Chromosome of gene 2                                                                                                                                  |
| Site2\_Position                   | Recommended     | Genomic position of breakpoint at gene 2                                                                                                              |
| NCBI\_Build                       | Optional        | Genome reference build: GRCh37 or GRCh38                                                                                                              |
| Class                             | Optional        | Deletion, Duplication, Insertion, Inversion, or Translocation                                                                                         |
| Event\_Info                       | Optional        | Free-text description of the event, e.g. 'TMPRSS2-ERG fusion'                                                                                         |
| Annotation                        | Optional        | Free-text description of the gene/transcript rearrangement                                                                                            |
| Site1\_Ensembl\_Transcript\_Id    | Optional        | Ensembl transcript ID of gene 1 (required for SV tab visualization)                                                                                   |
| Site2\_Ensembl\_Transcript\_Id    | Optional        | Ensembl transcript ID of gene 2 (required for SV tab visualization)                                                                                   |
| DNA\_Support                      | Optional        | Yes or No — fusion detected from DNA data                                                                                                             |
| RNA\_Support                      | Optional        | Yes or No — fusion detected from RNA data                                                                                                             |
| SV\_Length                        | Optional        | Length of the structural variant in bases                                                                                                             |
| Tumor\_Split\_Read\_Count         | Optional        | Number of split reads supporting the call in tumor                                                                                                    |
| Tumor\_Paired\_End\_Read\_Count   | Optional        | Number of paired-end reads supporting the call in tumor                                                                                               |
| Comments                          | Optional        | Any free-text comments                                                                                                                                |

## 6. Methylation Data

| Field                 | Required?  | Description                                                                         |
| --------------------- | ---------- | ----------------------------------------------------------------------------------- |
| Hugo\_Symbol          | Required\* | HUGO gene symbol (\*one of Hugo\_Symbol or Entrez\_Gene\_Id required)               |
| Entrez\_Gene\_Id      | Required\* | Entrez Gene numeric identifier (\*one of Hugo\_Symbol or Entrez\_Gene\_Id required) |
| \[SAMPLE\_ID columns] | Required   | One column per sample; methylation beta-value per gene-sample pair                  |

## 7. Protein Level Data (RPPA / Mass Spectrometry)

Two-dimensional matrix: one row per antibody, one column per sample. Values are log2 protein expression levels or Z-scores.

| Field                 | Required? | Description                                                                                                                           |
| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Composite.Element.REF | Required  | Antibody identifier encoding gene symbol(s)/Entrez ID(s) and antibody ID, e.g. 'BRAF\|B-Raf-M-NA' or 'MAPK1 MAPK3\|MAPK\_PT202\_Y204' |
| \[SAMPLE\_ID columns] | Required  | One column per sample; real-number protein level per antibody-sample pair                                                             |

## 8. Structural Variant Data (SV)

| Field                            | Required?   | Description                                                                                                                    |
| -------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Sample\_Id                       | Required    | Sample identifier as defined in the clinical sample file                                                                       |
| SV\_Status                       | Required    | SOMATIC or GERMLINE                                                                                                            |
| Site1\_Hugo\_Symbol              | Recommended | HUGO gene symbol of gene 1 (left/3' site)                                                                                      |
| Site1\_Ensembl\_Transcript\_Id   | Optional    | Ensembl transcript ID of gene 1 (required for SV tab visualization)                                                            |
| Site1\_Entrez\_Gene\_Id          | Recommended | Entrez Gene identifier of gene 1                                                                                               |
| Site1\_Region\_Number            | Recommended | Region number of Site 1, e.g. exon 2                                                                                           |
| Site1\_Region                    | Recommended | Region type: 5\_Prime\_UTR, 3\_Prime\_UTR, Promoter, Exon, or Intron                                                           |
| Site1\_Chromosome                | Recommended | Chromosome of gene 1                                                                                                           |
| Site1\_Contig                    | Optional    | The contig of Site 1                                                                                                           |
| Site1\_Position                  | Recommended | Genomic position of breakpoint at gene 1                                                                                       |
| Site1\_Description               | Optional    | Description of this event at site 2. This could be the location of the 2nd breakpoint in case of a fusion event.               |
| Site2\_Hugo\_Symbol              | Recommended | HUGO gene symbol of gene 2 (right/5' site)                                                                                     |
| Site2\_Ensembl\_Transcript\_Id   | Optional    | Ensembl transcript ID of gene 2 (required for SV tab visualization)                                                            |
| Site2\_Entrez\_Gene\_Id          | Recommended | Entrez Gene identifier of gene 2                                                                                               |
| Site2\_Region\_Number            | Recommended | Region number of Site 2                                                                                                        |
| Site2\_Region                    | Recommended | Region type: 5\_Prime\_UTR, 3\_Prime\_UTR, Promoter, Exon, or Intron                                                           |
| Site2\_Chromosome                | Recommended | Chromosome of gene 2                                                                                                           |
| Site2\_Contig                    | Optional    | The contig of Site 2                                                                                                           |
| Site2\_Position                  | Recommended | Genomic position of breakpoint at gene 2                                                                                       |
| Site2\_Description               | Optional    | Description of this event at site 1. This could be the location of the 1st breakpoint in case of a fusion event.               |
| Site2\_Effect\_On\_Frame         | Optional    | The effect of frame reading in gene 2. Frame\_shift or InFrame (free text)                                                     |
| NCBI\_Build                      | Optional    | Genome reference build: GRCh37 or GRCh38                                                                                       |
| Class                            | Optional    | Deletion, Duplication, Insertion, Inversion, or Translocation                                                                  |
| Tumor\_Split\_Read\_Count        | Optional    | Number of split reads supporting the call in tumor                                                                             |
| Tumor\_Paired\_End\_Read\_Count  | Optional    | Number of paired-end reads supporting the call in tumor                                                                        |
| Event\_Info                      | Optional    | Free-text description of the event, e.g. 'TMPRSS2-ERG fusion'                                                                  |
| Connection\_Type                 | Optional    | Which direction the connection is made                                                                                         |
| Breakpoint\_Type                 | Optional    | PRECISE or IMPRECISE which explain the resolution. Fill in PRECISE if the breakpoint resolution is known down to the base pair |
| Annotation                       | Optional    | Free-text description of the gene/transcript rearrangement                                                                     |
| DNA\_Support                     | Optional    | Yes or No — fusion detected from DNA data                                                                                      |
| RNA\_Support                     | Optional    | Yes or No — fusion detected from RNA data                                                                                      |
| SV\_Length                       | Optional    | Length of the structural variant in bases                                                                                      |
| Normal\_Read\_Count              | Optional    | The total number of reads of the normal tissue.                                                                                |
| Tumor\_Read\_Count               | Optional    | The total number of reads of the tumor tissue.                                                                                 |
| Normal\_Variant\_Count           | Optional    | The number of reads of the normal tissue that have the variant/allele.                                                         |
| Tumor\_Variant\_Count            | Optional    | The number of reads of the tumor tissue that have the variant/allele.                                                          |
| Normal\_Paired\_End\_Read\_Count | Optional    | The number of paired-end reads of the normal tissue that support the call.                                                     |
| Normal\_Split\_Read\_Count       | Optional    | The number of split reads of the normal tissue that support the call.                                                          |
| Comments                         | Optional    | Any free-text comments                                                                                                         |

## 9. Fusion Data (DEPRECATED — use Structural Variant Data instead)

This format is deprecated. New studies should use the Structural Variant (SV) format above.

| Field                  | Required? | Description                                                       |
| ---------------------- | --------- | ----------------------------------------------------------------- |
| Hugo\_Symbol           | Required  | HUGO gene symbol                                                  |
| Entrez\_Gene\_Id       | Required  | Entrez Gene numeric identifier                                    |
| Center                 | Required  | Sequencing center                                                 |
| Tumor\_Sample\_Barcode | Required  | Sample ID                                                         |
| Fusion                 | Required  | Description of the fusion, e.g. 'TMPRSS2-ERG fusion'              |
| DNA\_support           | Required  | Fusion detected from DNA: yes or no                               |
| RNA\_support           | Required  | Fusion detected from RNA: yes or no                               |
| Method                 | Required  | Algorithm/tool used for fusion detection                          |
| Frame                  | Required  | in-frame or frameshift                                            |
| Fusion\_Status         | Optional  | Assesment of mutation type: SOMATIC, GERMLINE, UNKNOWN, or empty. |

## 10. Timeline Data

| Field                      | Required? | Description                                                                            |
| -------------------------- | --------- | -------------------------------------------------------------------------------------- |
| PATIENT\_ID                | Required  | Patient identifier from the dataset                                                    |
| START\_DATE                | Required  | Days from date of diagnosis (day 0) to event start                                     |
| STOP\_DATE                 | Required  | Days from date of diagnosis to event end (blank if point-in-time event)                |
| EVENT\_TYPE                | Required  | Category of event: TREATMENT, LAB\_TEST, IMAGING, STATUS, SPECIMEN, or any custom type |
| TREATMENT\_TYPE            | Optional  | For TREATMENT events: Medical Therapy or Radiation Therapy                             |
| SUBTYPE                    | Optional  | For TREATMENT events: Chemotherapy, Hormone Therapy, Targeted Therapy, etc.            |
| AGENT                      | Optional  | For TREATMENT events: agent name with number of cycles if applicable                   |
| TEST                       | Optional  | For LAB\_TEST events: type of test performed                                           |
| RESULT                     | Optional  | For LAB\_TEST events: corresponding test result value                                  |
| DIAGNOSTIC\_TYPE           | Optional  | For IMAGING events: diagnostic tool used (MRI, CT scan, etc.)                          |
| STATUS                     | Optional  | For STATUS events: best response or disease progression stage                          |
| SPECIMEN\_SITE             | Optional  | For SPECIMEN events: site from which specimen was collected                            |
| SPECIMEN\_TYPE             | Optional  | For SPECIMEN events: tissue or blood                                                   |
| STYLE\_SHAPE               | Optional  | Render shape for this event: circle, square, triangle, diamond, star, or camera        |
| STYLE\_COLOR               | Optional  | Hexadecimal color value for rendering this event, e.g. #ffffff                         |
| Agent\_Class               | Optional  | Suggested for TREATMENT events to classify agents into groups                          |
| Diagnostic\_Type\_Detailed | Optional  | Suggested for IMAGING events as a detailed description                                 |
| Source                     | Optional  | Appears as a suggested column for IMAGING, STATUS, and SPECIMEN events                 |

## 11. GISTIC 2.0 Data

| Field             | Required? | Description                                                         |
| ----------------- | --------- | ------------------------------------------------------------------- |
| chromosome        | Required  | Chromosome number (without 'chr' prefix)                            |
| peak\_start       | Required  | Start coordinate of the region of maximal amplification or deletion |
| peak\_end         | Required  | End coordinate of the region of maximal amplification or deletion   |
| genes\_in\_region | Required  | Comma-separated list of HUGO gene symbols in the wide peak          |
| amp               | Required  | 1 for amplification, 0 for deletion                                 |
| cytoband          | Required  | Cytogenetic band specification including chromosome (Giemsa stain)  |
| q\_value          | Required  | Q-value (FDR-corrected p-value) of the peak region                  |

## 12. MutSig Data

| Field       | Required? | Description                                                    |
| ----------- | --------- | -------------------------------------------------------------- |
| rank        | Required  | Gene rank by significance                                      |
| gene        | Required  | HUGO gene symbol                                               |
| N (or Nnon) | Required  | Number of bases covered                                        |
| n (or nnon) | Required  | Number of mutations observed                                   |
| p           | Required  | P-value: probability mutations are due to background processes |
| q           | Required  | Q-value: p-value corrected for multiple testing                |

## 13. Gene Panel Data (Gene Panel Matrix)

| Field                 | Required? | Description                                                                                                       |
| --------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| SAMPLE\_ID            | Required  | Sample identifier                                                                                                 |
| \[stable\_id columns] | Required  | One column per genetic profile (e.g. 'mutations', 'gistic'); value is gene panel stable\_id or NA if not profiled |

## 14. Gene Set Data (GSVA Scores and P-values)

| Field                 | Required? | Description                                                                             |
| --------------------- | --------- | --------------------------------------------------------------------------------------- |
| geneset\_id           | Required  | Gene set name (uppercase); must match across score and p-value files                    |
| \[SAMPLE\_ID columns] | Required  | Score file: GSVA score between -1.0 and 1.0, or NA. P-value file: p-value for the score |

## 15. Generic Assay Data (incl. Arm-Level CNA, Mutational Signatures)

| Field                 | Required? | Description                                                                                    |
| --------------------- | --------- | ---------------------------------------------------------------------------------------------- |
| entity\_stable\_id    | Required  | Stable identifier for the assay entity (e.g. '1p', '1q', 'SBS1' for mutational signatures)     |
| Name                  | Required  | A column from generic\_entity\_meta\_properties (using the property name as the column header) |
| Description           | Required  | Another generic\_entity\_meta\_properties column                                               |
| URL                   | Required  | Another generic\_entity\_meta\_properties column                                               |
| \[SAMPLE\_ID columns] | Required  | One column per sample; numeric value per entity-sample pair                                    |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bcbi.brown.edu/codiac-for-health/ursa-ri/datasets/cbioportal-for-cancer-genomics/data-dictionary.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.