pysec2pri 0.0.6

Secondary to primary identifier mapping

pySec2Pri

Create and use mapping files for secondary (retired/withdrawn) biological database identifiers and symbols to primary (current) identifiers and symbols.

Outputs mappings in SSSOM format by default. Subjects are secondary, objects are primary.

Installation

uv pip install pysec2pri

Or install from source:

uv pip install git+https://github.com/jmillanacosta/pysec2pri.git

Quick Start

Generating mapping sets

To obtain the secondary to primary identifier SSSOM mapping set for ChEBI:

pysec2pri chebi

This will automatically download the latest ChEBI release and generate an SSSOM mapping file in your current directory.

To process locally and specify the output:

pysec2pri chebi ChEBI_complete_3star.sdf --output my_mappings.sssom.tsv

For more options and help on any command:

pysec2pri --help
pysec2pri chebi --help

The default output is in SSSOM (Simple Standard for Sharing Ontology Mappings) TSV format.

Updating IDs and symbols

A generated mapping set can be used to update IDs and symbols in Python:

from pysec2pri import generate_chebi_synonyms, resolve_symbols
cs = generate_chebi_synonyms()
resolve_symbols(["Glucose", "ATP", "Guanine"], cs)

Or from the command line, given a TSV file gene_ex.tsv:

gene	data
HGNC:131	3.5

Resolve the gene column to primary HGNC IDs (a new _primary column is added):

pysec2pri update-ids gene_ex.tsv hgnc --at gene -o gene_ex_primary.tsv
# gene        data    gene_primary
# HGNC:131    3.5     HGNC:145

The same pattern works for symbols with update-symbols, and multiple columns can be resolved by repeating --at:

pysec2pri update-ids data.tsv hgnc --at gene_id --at related_gene_id

To skip regenerating the mapping set, pass a pre-built mapping file:

pysec2pri hgnc ids  # outputs hgnc_{version}_sssom.tsv
pysec2pri update-ids gene_ex.tsv hgnc --at gene --mapping hgnc_{version}_sssom.tsv

Ambiguous mappings (where a deprecated ID or symbol serves as a recommended for another entity) are not resolved, but flagged for users to solve them manually.

A subset with ambiguous mappings only can be generated like:

pysec2pri ambiguous hgnc-symbols

Mapping types

Deprecations (IDs)

When an identifier is deprecated it is usually mapped to a single primary identifier. Sometimes the deprecated ID appears to recommend multiple targets, which introduces ambiguity.

flowchart LR
    D[Deprecated ID]
    P[Primary ID]
    A[Alternate primary]
    D -->|IAO:0100001 term replaced by| P
    D -. oboInOwl:consider .-> A

Symbols

Symbols can be reused over time. A symbol might resolve unambiguously to a single primary entity, or map ambiguously to several candidates.

flowchart LR
    S[Symbol]
    P1[Primary 1]
    P2[Primary 2]
    S -->|IAO:0100001 term replaced by| P1
    S -. oboInOwl:consider .-> P2

Aliases and synonyms

Aliases/synonyms are alternate names for the same primary entity and are typically many-to-one mappings (multiple synonyms -> one primary).

flowchart LR
    Syn1[object_label: glucose]
    Syn2[subject_label: D-glucose]
    Syn1 -->|oboInOwl:hasExactSynonym| Syn2
    Syn2 -->|oboInOwl:hasExactSynonym| Syn1

Documentation

Full documentation: https://pysec2pri.readthedocs.io/

Supported Databases

Datasource	license	citation
ChEBI	CC BY 4.0.	Hastings J, Owen G, Dekker A, et al. ChEBI in 2016: Improved services and an expanding collection of metabolites. Nucleic Acids Research. 2016 Jan;44(D1):D1214-9. DOI: 10.1093/nar/gkv1031. PMID: 26467479; PMCID: PMC4702775.
HMDB	CC0	Wishart DS, Guo A, Oler E, Wang F, Anjum A, Peters H, Dizon R, Sayeeda Z, Tian S, Lee BL, Berjanskii M, Mah R, Yamamoto M, Jovel J, Torres-Calzada C, Hiebert-Giesbrecht M, Lui VW, Varshavi D, Varshavi D, Allen D, Arndt D, Khetarpal N, Sivakumaran A, Harford K, Sanford S, Yee K, Cao X, Budinski Z, Liigand J, Zhang L, Zheng J, Mandal R, Karu N, Dambrova M, Schiöth HB, Greiner R, Gautam V. HMDB 5.0: the Human Metabolome Database for 2022. Nucleic Acids Res. 2022 Jan 7;50(D1):D622-D631. doi: 10.1093/nar/gkab1062. PMID: 34986597; PMCID: PMC8728138.
HGNC	link	Seal RL, Braschi B, Gray K, Jones TEM, Tweedie S, Haim-Vilmovsky L, Bruford EA. Genenames.org: the HGNC resources in 2023. Nucleic Acids Res. 2023 Jan 6;51(D1):D1003-D1009. doi: 10.1093/nar/gkac888. PMID: 36243972; PMCID: PMC9825485.
NCBI	link	Sayers EW, Bolton EE, Brister JR, Canese K, Chan J, Comeau DC, Connor R, Funk K, Kelly C, Kim S, Madej T, Marchler-Bauer A, Lanczycki C, Lathrop S, Lu Z, Thibaud-Nissen F, Murphy T, Phan L, Skripchenko Y, Tse T, Wang J, Williams R, Trawick BW, Pruitt KD, Sherry ST. Database resources of the national center for biotechnology information. Nucleic Acids Res. 2022 Jan 7;50(D1):D20-D26. doi: 10.1093/nar/gkab1112. PMID: 34850941; PMCID: PMC8728269.
UniProt	CC BY 4.0	UniProt Consortium. UniProt: the universal protein knowledgebase in 2021. Nucleic Acids Res. 2021 Jan 8;49(D1):D480-D489. doi: 10.1093/nar/gkaa1100. PMID: 33237286; PMCID: PMC7778908.
Wikidata		Vrandecic, D., Krotzsch, M. Wikidata: a free collaborative knowledgebase. Communications of the ACM. 2014. doi: 10.1145/2629489.

License

MIT License. See LICENSE for details.