Metadata-Version: 2.4
Name: biomappings
Version: 0.5.4
Summary: Curated and predicted mappings between biomedical identifiers in different namespaces
Keywords: snekpack,cookiecutter,biology,chemistry,ontologies,ontology,nlp
Author: Charles Tapley Hoyt
Author-email: Charles Tapley Hoyt <cthoyt@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Framework :: Pytest
Classifier: Framework :: tox
Classifier: Framework :: Sphinx
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Dist: click
Requires-Dist: tqdm
Requires-Dist: curies>=0.13.0
Requires-Dist: bioregistry>=0.13.0
Requires-Dist: sssom-pydantic>=0.5.1
Requires-Dist: sssom-curator[web]>=0.4.0
Requires-Dist: sssom-curator[exports] ; extra == 'exports'
Requires-Dist: sssom-curator[predict-embeddings] ; extra == 'predict-embeddings'
Requires-Dist: sssom-curator[predict-lexical] ; extra == 'predict-lexical'
Requires-Dist: sssom-curator[web] ; extra == 'web'
Maintainer: Charles Tapley Hoyt
Maintainer-email: Charles Tapley Hoyt <cthoyt@gmail.com>
Requires-Python: >=3.10
Project-URL: Bug Tracker, https://github.com/biopragmatics/biomappings/issues
Project-URL: Homepage, https://github.com/biopragmatics/biomappings
Project-URL: Repository, https://github.com/biopragmatics/biomappings.git
Project-URL: Documentation, https://biomappings.readthedocs.io
Project-URL: Funding, https://github.com/sponsors/cthoyt
Provides-Extra: exports
Provides-Extra: predict-embeddings
Provides-Extra: predict-lexical
Provides-Extra: web
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://github.com/biopragmatics/biomappings/raw/main/docs/source/logo.png" height="150">
</p>

<h1 align="center">
  Biomappings
</h1>

<p align="center">
    <a href="https://github.com/biopragmatics/biomappings/actions/workflows/tests.yml">
        <img alt="Tests" src="https://github.com/biopragmatics/biomappings/actions/workflows/tests.yml/badge.svg" /></a>
    <a href="https://pypi.org/project/biomappings">
        <img alt="PyPI" src="https://img.shields.io/pypi/v/biomappings" /></a>
    <a href="https://pypi.org/project/biomappings">
        <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/biomappings" /></a>
    <a href="https://github.com/biopragmatics/biomappings/blob/main/LICENSE">
        <img alt="PyPI - License" src="https://img.shields.io/pypi/l/biomappings" /></a>
    <a href='https://biomappings.readthedocs.io/en/latest/?badge=latest'>
        <img src='https://readthedocs.org/projects/biomappings/badge/?version=latest' alt='Documentation Status' /></a>
    <a href="https://codecov.io/gh/biopragmatics/biomappings/branch/main">
        <img src="https://codecov.io/gh/biopragmatics/biomappings/branch/main/graph/badge.svg" alt="Codecov status" /></a>  
    <a href="https://github.com/cthoyt/cookiecutter-python-package">
        <img alt="Cookiecutter template from @cthoyt" src="https://img.shields.io/badge/Cookiecutter-snekpack-blue" /></a>
    <a href="https://github.com/astral-sh/ruff">
        <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff" style="max-width:100%;"></a>
    <a href="https://github.com/biopragmatics/biomappings/blob/main/.github/CODE_OF_CONDUCT.md">
        <img src="https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg" alt="Contributor Covenant"/></a>
    <a href="https://github.com/biopragmatics/bioregistry">
        <img alt="Powered by the Bioregistry" src="https://img.shields.io/static/v1?label=Powered%20by&message=Bioregistry&color=BA274A&style=flat&logo=image/png;base64,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" /></a>
    <a href="https://zenodo.org/badge/latestdoi/285352907">
        <img src="https://zenodo.org/badge/285352907.svg" alt="DOI"></a>
</p>

Biomappings is a repository of community curated and predicted equivalences and
related mappings between named biological entities that are not available from
primary sources. It's also a place where anyone can contribute curations of
predicted mappings or their own novel mappings. Ultimately, we hope that primary
resources will integrate these mappings and distribute them themselves.

Mappings are stored in TSV files using the
[Simple Standard for Sharing Ontology Mappings (SSSOM)](https://github.com/mapping-commons/sssom)
format that look like this:

![](docs/img/mappings_screenshot.png)

## 💾 Data

The data are available through the following four files on the
[biopragmatics/biomappings](https://github.com/biopragmatics/biomappings) GitHub
repository.

| Curated | Description                                                  | Link                                                                                                                                                       |
| ------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Yes     | Human-curated true mappings                                  | [`src/biomappings/resources/positive.sssom.tsv`](https://github.com/biopragmatics/biomappings/raw/main/src/biomappings/resources/positive.sssom.tsv)       |
| Yes     | Human-curated _non-trivial_ false (i.e., incorrect) mappings | [`src/biomappings/resources/negative.sssom.tsv`](https://github.com/biopragmatics/biomappings/raw/main/src/biomappings/resources/negative.sssom.tsv)       |
| Yes     | Mappings that have been checked but not yet decided          | [`src/biomappings/resources/unsure.sssom.tsv`](https://github.com/biopragmatics/biomappings/raw/main/src/biomappings/resources/unsure.sssom.tsv)           |
| No      | Automatically predicted mappings                             | [`src/biomappings/resources/predictions.sssom.tsv`](https://github.com/biopragmatics/biomappings/raw/main/src/biomappings/resources/predictions.sssom.tsv) |

The primary and derived data in this repository are both available under the
[CC0 1.0 Universal License](https://github.com/biopragmatics/biomappings/blob/master/LICENSE).

Predictions are generated by scripts in the [`scripts/`](scripts) folder. Each
uses the utilities from the `biomappings.resources` module to programmatically
interact with the mappings files, e.g., to add predictions.

### 🥒 Derived

An aggregation of positive, negative, and predicted mappings are collated in the
SSSOM
([here](https://github.com/biopragmatics/biomappings/blob/master/docs/_data/sssom))
and can be referenced by PURL such as
https://w3id.org/biopragmatics/biomappings/sssom/biomappings.sssom.tsv. The
positive mappings are also available as a network through
[NDEx](https://www.ndexbio.org/#/network/402d1fd6-49d6-11eb-9e72-0ac135e8bacf).

Equivalences and related mappings that are available from the OBO Foundry and
other primary sources can be accessed through
[Inspector Javert's Xref Database](https://zenodo.org/record/3757266) on Zenodo
which was described in
[this blog post](https://cthoyt.com/2020/04/19/inspector-javerts-xref-database.html).

### 📊 Summary

Summary statistics of the manually curated mappings and predicted mappings are
automatically generated nightly and deployed as a website with GitHub Actions to
https://biopragmatics.github.io/biomappings.

[![Summary statistics](docs/img/summary.svg)](https://biopragmatics.github.io/biomappings)

## 💪 Getting Started

There are four main functions exposed from `biomappings`. Each loads a list of
[`sssom_pydantic.SemanticMapping`](https://sssom-pydantic.readthedocs.io)
objects.

```python
import biomappings

positive_mappings = biomappings.load_positive_mappings()
negative_mappings = biomappings.load_false_mappings()
predicted_mappings = biomappings.load_predictions()
unsure_mappings = biomappings.load_unsure_mappings()
```

Full documentation can be found on
[ReadTheDocs](https://biomappings.readthedocs.io).

## 🚀 Installation

The most recent release can be installed from
[PyPI](https://pypi.org/project/biomappings/) with uv:

```console
$ uv pip install biomappings
```

or with pip:

```console
$ python3 -m pip install biomappings
```

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

```console
$ uv pip install git+https://github.com/biopragmatics/biomappings.git
```

or with pip:

```console
$ python3 -m pip install git+https://github.com/biopragmatics/biomappings.git
```

## 👐 Contributing

We welcome contributions in the form of curations to any of the four primary TSV
files in this repository via a pull request to the main Biomappings repository
at https://github.com/biopragmatics/biomappings.

Predicted mappings can be curated by moving a row in the `predictions.sssom.tsv`
file into either the positive mappings file (`positive.sssom.tsv`), negative
mappings file (`negative.sssom.tsv`), or the unsure mappings file
(`unsure.sssom.tsv`). Additionally, the `confidence` column should be removed, a
`mapping_justification` column should be added with an appropriate value from
the SEMAPV vocabulary, such as  
the value `semapv:ManualMappingCuration`, and your ORCiD identifier should be
written as a CURIE (e.g., `orcid:0000-0003-1307-2508`) in the `author_id`
column.

Novel mappings can be curated by adding a full row to the positive mappings file
(`positive.sssom.tsv`) following the format of the previous lines.

While Biomappings is generally able to use any predicate written as a
[compact URI (CURIE)](http://www.w3.org/TR/curie), it's preferred to use
predicates from the
[Simple Knowledge Organization System (SKOS)](https://www.w3.org/2004/02/skos/)
to denote hierarchical relationships. The three most common predicates that are
useful for curating mappings are:

| Predicate                                                                             | Description                                     |
| ------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [`skos:exactMatch`](https://www.w3.org/2009/08/skos-reference/skos.html#exactMatch)   | The two terms can be used interchangeably       |
| [`skos:broadMatch`](https://www.w3.org/2009/08/skos-reference/skos.html#broadMatch)   | The object term is a super-class of the subject |
| [`skos:narrowMatch`](https://www.w3.org/2009/08/skos-reference/skos.html#narrowMatch) | The object term is a sub-class of the subject   |

### Online via GitHub Web Interface

GitHub has an interface for editing files directly in the browser. It will take
care of creating a branch for you and creating a pull request. After logging
into GitHub, click one of the following links to be brought to the editing
interface:

- [Positive Mappings](https://github.com/biopragmatics/biomappings/edit/main/src/biomappings/resources/positive.sssom.tsv)
- [Negative Mappings](https://github.com/biopragmatics/biomappings/edit/main/src/biomappings/resources/negative.sssom.tsv)
- [Unsure Mappings](https://github.com/biopragmatics/biomappings/edit/main/src/biomappings/resources/unsure.sssom.tsv)
- [Predicted Mappings](https://github.com/biopragmatics/biomappings/edit/main/src/biomappings/resources/predictions.sssom.tsv)

This has the caveat that you can only edit one file at a time. It's possible to
navigate to your own forked version of the repository after, to the correct
branch (will not be the default one), then edit other files in the web interface
as well. However, if you would like to do this, then it's probably better to see
the following instructions on contributing locally.

### ✍️ Local via a Text Editor

1. Fork the repository at https://github.com/biopragmatics/biomappings, clone
   locally, and make a new branch (see below)
2. Edit one or more of the resource files (`positive.sssom.tsv`,
   `negative.sssom.tsv`, `unsure.sssom.tsv`, `predictions.sssom.tsv`)
3. Commit to your branch, push, and create a pull request back to the upstream
   repository.

### 🌐 Local via the Web Curation Interface

Rather than editing files locally, this repository also comes with a web-based
curation interface. Install the code in development mode with the `web` option
(which installs `flask` and `flask-bootstrap`) using:

```console
$ git clone https://github.com/biopragmatics/biomappings.git
$ cd biomappings
$ git checkout -b your-branch-name
$ python -m pip install -e .[web]
```

The web application can be run with:

```console
$ biomappings web
```

It can be accessed by navigating to http://localhost:5000/ in your browser.
After you do some curations, the web application takes care of interacting with
the git repository from which you installed `biomappings` via the "commit and
push" button.

**Note** if you've installed `biomappings` via
[PyPI](https://pypi.org/project/biomappings/), then running the web curation
interface doesn't make much sense, since it's non-trivial for most users to find
the location of the resources within your Python installation's `site-packages`
folder, and you won't be able to contribute them back.

### Curation Attribution

There are three places where curators of Biomappings are credited:

1. ORCiD identifiers of curators are stored in each mapping
2. The [summary website](https://biopragmatics.github.io/biomappings) groups and
   counts contributions curator
3. A curation leaderboard is under construction at
   [APICURON](https://apicuron.org/database?resource_uri=https:%2F%2Fbiomappings.github.io%2Fbiomappings%2F),
   though note that this is not up-to-date.

## 👋 Attribution

### ⚖️ License

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

### 📖 Citation

> [Prediction and Curation of Missing Biomedical Identifier Mappings with Biomappings](https://doi.org/10.1093/bioinformatics/btad130)
> <br />Hoyt, C. T., Hoyt, A. L., and Gyori, B. M. (2022)
> <br />_Bioinformatics_, btad130.

```bibtex
@article{Hoyt2022,
   title = {{Prediction and Curation of Missing Biomedical Identifier Mappings with Biomappings}},
   author = {Hoyt, Charles Tapley and Hoyt, Amelia L and Gyori, Benjamin M},
   journal = {Bioinformatics},
   year = {2023},
   month = {03},
   issn = {1367-4811},
   doi = {10.1093/bioinformatics/btad130},
   url = {https://doi.org/10.1093/bioinformatics/btad130},
   note = {btad130},
   eprint = {https://academic.oup.com/bioinformatics/advance-article-pdf/doi/10.1093/bioinformatics/btad130/49521613/btad130.pdf},
}
```

### 🎁 Support

Biomappings was developed by the [INDRA Lab](https://indralab.github.io), a part
of the
[Laboratory of Systems Pharmacology](https://hits.harvard.edu/the-program/laboratory-of-systems-pharmacology/about/)
and the
[Harvard Program in Therapeutic Science (HiTS)](https://hits.harvard.edu) at
[Harvard Medical School](https://hms.harvard.edu/).

### 💰 Funding

The development of this project has been funded in part by the DARPA Young
Faculty Award W911NF2010255 (PI: Benjamin M. Gyori).

### 🍪 Cookiecutter

This package was created with
[@audreyfeldroy](https://github.com/audreyfeldroy)'s
[cookiecutter](https://github.com/cookiecutter/cookiecutter) package using
[@cthoyt](https://github.com/cthoyt)'s
[cookiecutter-snekpack](https://github.com/cthoyt/cookiecutter-snekpack)
template.

## 🛠️ For Developers

<details>
  <summary>See developer instructions</summary>

The final section of the README is for if you want to get involved by making a
code contribution.

### Development Installation

To install in development mode, use the following:

```console
$ git clone git+https://github.com/biopragmatics/biomappings.git
$ cd biomappings
$ uv pip install -e .
```

Alternatively, install using pip:

```console
$ python3 -m pip install -e .
```

### 🥼 Testing

After cloning the repository and installing `tox` with
`uv tool install tox --with tox-uv` or `python3 -m pip install tox tox-uv`, the
unit tests in the `tests/` folder can be run reproducibly with:

```console
$ tox -e py
```

Additionally, these tests are automatically re-run with each commit in a
[GitHub Action](https://github.com/biopragmatics/biomappings/actions?query=workflow%3ATests).

### 📖 Building the Documentation

The documentation can be built locally using the following:

```console
$ git clone git+https://github.com/biopragmatics/biomappings.git
$ cd biomappings
$ tox -e docs
$ open docs/build/html/index.html
```

The documentation automatically installs the package as well as the `docs` extra
specified in the [`pyproject.toml`](pyproject.toml). `sphinx` plugins like
`texext` can be added there. Additionally, they need to be added to the
`extensions` list in [`docs/source/conf.py`](docs/source/conf.py).

The documentation can be deployed to [ReadTheDocs](https://readthedocs.io) using
[this guide](https://docs.readthedocs.io/en/stable/intro/import-guide.html). The
[`.readthedocs.yml`](.readthedocs.yml) YAML file contains all the configuration
you'll need. You can also set up continuous integration on GitHub to check not
only that Sphinx can build the documentation in an isolated environment (i.e.,
with `tox -e docs-test`) but also that
[ReadTheDocs can build it too](https://docs.readthedocs.io/en/stable/pull-requests.html).

</details>

## 🧑‍💻 For Maintainers

<details>
  <summary>See maintainer instructions</summary>

### Initial Configuration

#### Configuring ReadTheDocs

[ReadTheDocs](https://readthedocs.org) is an external documentation hosting
service that integrates with GitHub's CI/CD. Do the following for each
repository:

1. Log in to ReadTheDocs with your GitHub account to install the integration at
   https://readthedocs.org/accounts/login/?next=/dashboard/
2. Import your project by navigating to https://readthedocs.org/dashboard/import
   then clicking the plus icon next to your repository
3. You can rename the repository on the next screen using a more stylized name
   (i.e., with spaces and capital letters)
4. Click next, and you're good to go!

#### Configuring Archival on Zenodo

[Zenodo](https://zenodo.org) is a long-term archival system that assigns a DOI
to each release of your package. Do the following for each repository:

1. Log in to Zenodo via GitHub with this link:
   https://zenodo.org/oauth/login/github/?next=%2F. This brings you to a page
   that lists all of your organizations and asks you to approve installing the
   Zenodo app on GitHub. Click "grant" next to any organizations you want to
   enable the integration for, then click the big green "approve" button. This
   step only needs to be done once.
2. Navigate to https://zenodo.org/account/settings/github/, which lists all of
   your GitHub repositories (both in your username and any organizations you
   enabled). Click the on/off toggle for any relevant repositories. When you
   make a new repository, you'll have to come back to this

After these steps, you're ready to go! After you make "release" on GitHub (steps
for this are below), you can navigate to
https://zenodo.org/account/settings/github/repository/biopragmatics/biomappings
to see the DOI for the release and link to the Zenodo record for it.

#### Registering with the Python Package Index (PyPI)

The [Python Package Index (PyPI)](https://pypi.org) hosts packages so they can
be easily installed with `pip`, `uv`, and equivalent tools.

1. Register for an account [here](https://pypi.org/account/register)
2. Navigate to https://pypi.org/manage/account and make sure you have verified
   your email address. A verification email might not have been sent by default,
   so you might have to click the "options" dropdown next to your address to get
   to the "re-send verification email" button
3. 2-Factor authentication is required for PyPI since the end of 2023 (see this
   [blog post from PyPI](https://blog.pypi.org/posts/2023-05-25-securing-pypi-with-2fa/)).
   This means you have to first issue account recovery codes, then set up
   2-factor authentication
4. Issue an API token from https://pypi.org/manage/account/token

This only needs to be done once per developer.

#### Configuring your machine's connection to PyPI

This needs to be done once per machine.

```console
$ uv tool install keyring
$ keyring set https://upload.pypi.org/legacy/ __token__
$ keyring set https://test.pypi.org/legacy/ __token__
```

Note that this deprecates previous workflows using `.pypirc`.

### 📦 Making a Release

#### Uploading to PyPI

After installing the package in development mode and installing `tox` with
`uv tool install tox --with tox-uv` or `python3 -m pip install tox tox-uv`, run
the following from the console:

```console
$ tox -e finish
```

This script does the following:

1. Uses [bump-my-version](https://github.com/callowayproject/bump-my-version) to
   switch the version number in the `pyproject.toml`, `CITATION.cff`,
   `src/biomappings/version.py`, and
   [`docs/source/conf.py`](docs/source/conf.py) to not have the `-dev` suffix
2. Packages the code in both a tar archive and a wheel using
   [`uv build`](https://docs.astral.sh/uv/guides/publish/#building-your-package)
3. Uploads to PyPI using
   [`uv publish`](https://docs.astral.sh/uv/guides/publish/#publishing-your-package).
4. Push to GitHub. You'll need to make a release going with the commit where the
   version was bumped.
5. Bump the version to the next patch. If you made big changes and want to bump
   the version by minor, you can use `tox -e bumpversion -- minor` after.

#### Releasing on GitHub

1. Navigate to https://github.com/biopragmatics/biomappings/releases/new to
   draft a new release
2. Click the "Choose a Tag" dropdown and select the tag corresponding to the
   release you just made
3. Click the "Generate Release Notes" button to get a quick outline of recent
   changes. Modify the title and description as you see fit
4. Click the big green "Publish Release" button

This will trigger Zenodo to assign a DOI to your release as well.

### Updating Package Boilerplate

This project uses `cruft` to keep boilerplate (i.e., configuration, contribution
guidelines, documentation configuration) up-to-date with the upstream
cookiecutter package. Install cruft with either `uv tool install cruft` or
`python3 -m pip install cruft` then run:

```console
$ cruft update
```

More info on Cruft's update command is available
[here](https://github.com/cruft/cruft?tab=readme-ov-file#updating-a-project).

</details>
