> For the complete documentation index, see [llms.txt](https://help.connected.illumina.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.connected.illumina.com/annotation/data-sources/primate-ai.md). # PrimateAI-3D ### Overview PrimateAI-3D is an AI annotation model developed by the Illumina Artificial Intelligence Lab to predict missense variant pathogenicity. It uses a 3D convolutional neural network with structural and primate variation data to score missense variants. Scores range from `0` to `1`, where lower values suggest more benign variants and higher values suggest more pathogenic variants. It is trained on data from 233 primate species and has enabled the reclassification of approximately 4.4 million variants of unknown significance (VUS) as likely benign, improving the accuracy of variant interpretation. By learning from conserved sequences across primates, PrimateAI‑3D avoids bias tied to any single human ancestry. For more details, refer to: {% hint style="info" %} **Publication** Gao, et al. The landscape of tolerated genetic variation in humans and primates. *Science* (2023). {% endhint %} {% hint style="warning" %} **Professional data source** This data source requires a Professional license. Contact `annotation_support@illumina.com` to request access. {% endhint %} ### Parsing #### TSV File ```scss chr pos non_flipped_ref non_flipped_alt gene_name change_position_1based ref_aa alt_aa score_PAI3D percentile_PAI3D refseq prediction per_gene_percentile_PAI3D hgnc chr1 69094 G A ENST00000335137.4 2 V M 0.6169436463713646 0.5200308441794135 NM_001005484.1 pathogenic 0.699207135777998 OR4F5 chr1 69094 G C ENST00000335137.4 2 V L 0.5557043975591658 0.4271457250214688 NM_001005484.1 benign 0.6053022794846382 OR4F5 chr1 69094 G T ENST00000335137.4 2 V L 0.5557043975591658 0.4271457391722522 NM_001005484.1 benign 0.6053022794846382 OR4F5 chr1 69095 T A ENST00000335137.4 2 V E 0.8063537482917307 0.8032228720356267 NM_001005484.1 pathogenic 0.9202180376610506 OR4F5 chr1 69095 T C ENST00000335137.4 2 V A 0.5795628190040587 0.4631329075815453 NM_001005484.1 benign 0.6442021803766105 OR4F5 chr1 69095 T G ENST00000335137.4 2 V G 0.7922330142557621 0.7834049546930125 NM_001005484.1 pathogenic 0.900396432111001 OR4F5 ``` Illumina Connected Annotations parses all columns from the file: * `chr` * `pos` * `non_flipped_ref` * `non_flipped_alt` * `gene_name` * `change_position_1based` * `ref_aa` * `alt_aa` * `score_PAI3D` * `percentile_PAI3D` * `refseq` * `prediction` * `per_gene_percentile_PAI3D` * `hgnc` The `gene_name` and `refseq` fields provide the Ensembl and RefSeq transcript IDs. These IDs are passed through as-is, so some can be obsolete or unrecognized by current Ensembl or RefSeq releases. {% hint style="info" %} **GRCh37** For GRCh37, a lifted-over file is provided. The file is not sorted, so sort it before use. Some RefSeq transcripts were not mapped during lift-over. {% endhint %} #### Pre-processing Sorting for GRCh37 ```shell gzcat PrimateAI-3D.hg19.txt.gz | sort -t $'\t' -k1,1 -k2,2n | gzip > PrimateAI-3D.hg19_sorted.tsv.gz ``` #### Generate supplementary annotation files This step converts the raw PrimateAI-3D source file into supplementary annotation files using [SAUtils](/annotation/v3.27/utilities/sautils.md) that Illumina Connected Annotations can load during annotation. You only need this step if you are generating the data source manually. If you use prebuilt annotation files, you can skip it. ```shell dotnet SAUtils.dll \ PrimateAi \ --r "${References}/Homo_sapiens.GRCh38.Nirvana.dat" \ --i "${ExternalDataSources}/PrimateAI/3D/PrimateAI-3D.hg38.txt.gz" \ --o "${SaUtilsOutput]" ``` #### Known Issues {% hint style="warning" %} **Known Issues** Some transcript IDs in the source file are obsolete, retired, or updated. Illumina Connected Annotations does not remove or modify them. **Example:** **ENST00000643905.1** transcript is retired according to [Ensembl](https://useast.ensembl.org/Homo_sapiens/Transcript/Idhistory?db=core;t=ENST00000643905) **NM\_182838.2** transcript is removed because it is a pseudo-gene according to [RefSeq](https://www.ncbi.nlm.nih.gov/nuccore/NM_182838.3) {% endhint %} ### JSON output ```json "primateAI-3D": [ { "aminoAcidPosition": 2, "refAminoAcid": "V", "altAminoAcid": "M", "score": 0.616944, "scorePercentile": 0.52, "genePercentile": 0.7, "classification": "pathogenic", "ensemblTranscriptId": "ENST00000335137.4", "refSeqTranscriptId": "NM_001005484.1", "geneSymbol":"OR4F5" } ] ``` | Field | Type | Notes | | ------------------- | :----: | ----------------------------------- | | aminoAcidPosition | int | Amino Acid Position (1-based) | | refAminoAcid | string | Reference Amino Acid | | altAminoAcid | string | Alternate Amino Acid | | ensemblTranscriptId | string | Transcript ID (Ensembl) | | refSeqTranscriptId | string | Transcript ID (RefSeq) | | scorePercentile | float | range: 0 - 1.0 | | genePercentile | float | range: 0 - 1.0 | | score | float | range: 0 - 1.0 | | classification | string | pathogenic or benign classification | | geneSymbol | string | HGNC gene symbol | ### Interpreting scores PrimateAI-3D scores range from `0` to `1`. * Lower scores suggest more benign variants. * Higher scores suggest more pathogenic variants. ### Resources * [PrimateAI-3D GitHub](https://github.com/Illumina/PrimateAI-3D) * [Download URL](https://primad.basespace.illumina.com/) --- # 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://help.connected.illumina.com/annotation/data-sources/primate-ai.md?ask=&goal= ``` `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.