Introduction

This site contains:

• A guide to using the GA4GH Phenotools
• An API reference generated from Rustdoc

Getting Started

Add this crate to your project:

[dependencies]
your-crate = "0.1"

**`book/src/api.md`:**
```markdown
# API Reference

The full Rust API documentation is available here:

👉 [API Documentation](./api/your_crate/index.html)

phenotype.hpoa output

The phenotype.hpoa file is is the core download of disease annotation data for the HPO project. Internally, the HPO project uses one so-called "small file" for each disease; information from these files is processed to make the phenotype.hpoa project, which is offered for download. The small files are not offered for download at this time.

GA4GH phenotools has functionality to export a cohort of phenopackets to small file format. For convenience, we explain this format here and explain the assumptions to code makes to generate the files.

Format

Note that this file has one line that specifies the frequency of each HPO term in the cohort of individuals described in the PMID. It is thus possible to have multiple likes for the same HPO with data from different PMIDs.

Legacy template

The pypheools project was our first attempt to curate GA4GH Phenopackets at scale (2021-2024). For this, we designed an Excel template for curation. GA4GH phenotools contains code that enables us to import daa from these excel files and then serialize the contents to the new JSON format. We plan to update the entire phenopacket store to use the new JSON serialization format and delete the legacy Excel files. At this point, we will remove the legacy-related code from the current library as well. We present information about the structure of the Excel files here in order to help with this process.

A format for cohort descriptions in excel

The schema of the template consists in two rows that specify the nature of the data. There is a fixed set of columns that capture basic demographic data together with the disease, the source publication, and the variants. The second half of the template should be used to record information about HPO terms curated from the publications.

Note that the format specifier "CURIE" means "Compact uniform resource identifier", which means the entry should have a prefix (e.g., PMID, a colon, and the identifier, e.g., 3021034, altogether "PMID:3021034"). "str" refers to an arbitrary text (string). "optional" means the cell can be left empty.

Fixed columns

The first (leftmost) 11 or 12 columns specify basic demographic data together with the disease, the source publication, and the variants. The first two rows are used to specify the datatypes and should not be changed. The following tables show the first two rows together with one example row with data extracted from a publication (We show two tables for better legibility)

1. PMID (CURIE: The PubMed identifier of the publication being curated.
2. title (str): The title of the publication being curated.
3. individual_id (str): The identifier of the individual being described in the original publication. This field is required. Please add ‘individual’ if the original article does not provide an identifier (if needed, individual 1, individual 2,...).
4. comment (str): This field is provided to record additional information that will not be used for creating phenopackets but may be helpful for future reference. It can be left empty.
5. disease_id (CURIE). The disease identifer (e.g., OMIM:154700 or MONDO:0007947).
6. disease_label (str). The name of the disease (e.g. Marfan syndrome).

7. HGNC_id (CURIE): Identifier of the HUGO Gene Nomenclature Committee{target="_blank"}.
8. gene_symbol (str):: Gene symbol, e.g., SOCS1.
9. transcript (str): The identifier of the transcript. NCBI RefSeq or ENSEMBL identifiers are preferred.
10. allele_1 (str): A string representing the first pathogenic allele (variant) according to HGVS nomenclature.
11. allele_2 (str): This field should not be used for monoallelic diseases (e.g. autosomal dominant, XLR). The column can eigther be omitted or can be filled with "na" to denote "not applicable". It the column is present and is left empty, this will be flagged as an error. For biallelic diseases (autosomal recessive), specific the second allele (which will be the same as the first for homozygous genotypes).
12. variant.comment (str): This field is provided to record additional information that will not be used for creating phenopackets but may be helpful for future reference.

11. age_of_onset: The age of onset of disease, recorded using iso8601 convention or an HPO Onset{:target="_blank"} term.
12. sex (M:F:U:O): one of M (male), female (F), other(O), or unknown (U)
13. HPO (str): The column marks the end of the data columns and should contain "na".

HPO Term Columns

All of the following columns denote HPO terms. The first row has the HPO term label. Be sure to use the same label as is shown on the HPO webpage and do not chance the capitalization. The second row has the corresponding HPO id. The following table shows several examples, whereby the individual_id column from above is shown for ease of exposition.

Each table cell can contain either

1. observed: The phenotypic abnormality denoted by the HPO term was present
2. excluded: The phenotypic abnormality denoted by the HPO term was investigated and ruled out.
3. An iso8601 string denoting the age of onset.
4. na or empty (blank): Information not available or phenotypic feature not measured.

In this example, individual A was observed to have hepatitis (but age of onset is unknown or not available), pancreatitis was ruled out, no information is available about lymphadenopathy, and splenomegaly was first observed at age 4 years and 2 months.

Individual B was found to have hepatitis first observed at age 3 years, no information was available about pancreatitis, lymphadenopathy was observed (but age of onset is unknown or not available), and splenomegaly was ruled out.

The file should contain at least the following information; see explanations below.

row_type

Each row must begin with one of the words "header1", "header2" or "individual". There should be one row for each individual in the cohort.

id

This is an cohort-specific identifier that must be anonymized.

age

This is the age of the individual at the time of the medical encounter at which the phenotypic features were recorded. The format of the column is recorded in the header1 line. Valid options are ISO8601 for strings such as "P4Y" (four years of age) and "P71Y6M2D" for 71 years, 6 months, and 2 days; Years for 5 (5 years of age) or 7.5 (7 years and 6 months).

sex

Use male, female, other, or unknown.

HPO columns

The remaining columns contain information about HPO terms observed in the individuals. There are three types of column.

The top row contains the label of the term. The header1 row contains the word "simple". The header2 row contains the HPO id; in the example table, we see Tall stature; HP:0000098. If the feature is observed in an indivual, use "+"; if the feature was explicitly excluded, use "-". If the feature was not measured or no information is available, use "n/a".

Demo

Example program

To run the example program (whose code is available at bin/main.rs), enter

cargo run --bin rpt -- --rpt /.../.../phenopacket-store/notebooks/CD28/input/CD28_IMD123_individuals.xlsx --json /.../.../hp.json 

Adjust the paths to an Excel legacy template and the hp.json file as needed.

For faster performance, enter

cargo run --features="cli"  --release --bin rpt -- --template ./../phenopacket-store/notebooks/CD28/input/CD28_IMD123_individuals.xlsx --json ./../../data/hpo/hp.json 

To build the binary demo (with clap)

cargo build --release --features cli

(the binary is then in ./target/release/rpt) to run it

cargo run --features cli --bin rpt

To see private features in documentation

cargo doc --document-private-items --open

API Reference