Simple Standard for Sharing Literal Mappings

A simple standard for sharing literal mappings (SSSLM).

This repository implements a data model for literal mappings that supports encoding labels, synonyms, synonym types, internationalization, and other important information for curation, construction of lexica, and population of NER/NEN tools.

SSSLM echos the name of SSSOM, which is a related standard for ontological mappings. SSSLM can be pronounced S-S-S-L-M, sess-lem, or however brings joy to you.

💪 Getting Started

```python import ssslm from ssslm import LiteralMapping from curies import NamedReference

Construct a mapping using Pydantic objects

m1 = LiteralMapping( reference=NamedReference(prefix="NCBITaxon", identifier="9606", name="Homo sapiens"), text="human", )

get a pandas dataframe

df = ssslm.literalmappingsto_df([m1])

Write mappings to TSV

ssslm.writeliteralmappings([m1], "literal_mappings.tsv")

Read mappings from TSV

mappings = ssslm.readliteralmappings("literal_mappings.tsv") ```

Note that references are standardized using the curies package. It's up to you to use a meaningful set of prefixes, so consider adopting the Bioregistry as a standard.

Data Model

The SSSLM data model is defined using Pydantic, and corresponds to the following columns in a TSV file:

1. text the label/synonym text itself
2. curie the compact uniform resource identifier (CURIE) for a biomedical entity or concept
3. name the standard name for the concept
4. predicate the predicate which encodes the synonym scope, written as a CURIE from the OBO in OWL (oboInOWL) or RDFS controlled vocabularies, e.g., one of:
   • rdfs:label
   • oboInOwl:hasExactSynonym
   • oboInOwl:hasNarrowSynonym (i.e., the synonym represents a narrower term)
   • oboInOwl:hasBroadSynonym (i.e., the synonym represents a broader term)
   • oboInOwl:hasRelatedSynonym (use this if the scope is unknown)
5. type the (optional) synonym property type, written as a CURIE from the OBO Metadata Ontology (omo) controlled vocabulary, e.g., one of:
   • OMO:0003000 (abbreviation)
   • OMO:0003001 (ambiguous synonym)
   • OMO:0003002 (dubious synonym)
   • OMO:0003003 (layperson synonym)
   • OMO:0003004 (plural form)
   • ...
6. provenance a comma-delimited list of CURIEs corresponding to publications that use the given synonym (ideally using highly actionable identifiers from semantic spaces like pubmed, pmc, doi)
7. contributor a CURIE with the ORCID identifier of the contributor
8. date the optional date when the row was curated in YYYY-MM-DD format
9. language the (optional) ISO 2-letter language code. If missing, assumed to be American English.
10. comment an optional comment
11. source the source of the synonyms, usually biosynonyms unless imported from elsewhere
12. taxon the optional NCBITaxon CURIE, if the term is taxon-specific, like NCBITaxon:9606 for humans

Here's an example of some rows in the synonyms table (with linkified CURIEs):

| text | curie | predicate | provenance | contributor | language | | --------------- | --------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------- | | alsterpaullone | CHEBI:138488 | rdfs:label | pubmed:30655881 | orcid:0000-0003-4423-4370 | en | | 9-nitropaullone | CHEBI:138488 | oboInOwl:hasExactSynonym | pubmed:11597333, pubmed:10911915 | orcid:0000-0003-4423-4370 | en |

Limitations

• It's hard to know which exact matches between different vocabularies could be used to deduplicate synonyms. Right now, this isn't covered but some partial solutions already exist that could be adopted.
• This doesn't keep track of NER annotations, such as when you want to keep track of the start and end position in a full sentence or paragraph
• This doesn't keep track of transformations done to make mappings. It's more oriented towards curation.

🚀 Installation

The most recent code and data can be installed directly from GitHub with uv:

console $ uv pip install git+https://github.com/cthoyt/ssslm.git

or with pip:

console $ python3 -m pip install git+https://github.com/cthoyt/ssslm.git

👐 Contributing

Contributions, whether filing an issue, making a pull request, or forking, are appreciated. See CONTRIBUTING.md for more information on getting involved.

👋 Attribution

⚖️ License

The code in this package is licensed under the MIT License.

🍪 Cookiecutter

This package was created with @audreyfeldroy's cookiecutter package using @cthoyt's cookiecutter-snekpack template.

🛠️ For Developers

🧑‍💻 For Maintainers