str_sim_scorer 0.1.1

No project description provided

STR Similarity Scorer

This repository contains a single Python module to compute the Tanabe score ("non-empty markers" mode) for pairs of records in an input data frame.

Usage

import pandas as pd
import str_sim_scorer

df = pd.DataFrame(
    [
        {
            "id": "sample1",
            "csf1po": "11, 13",
            "d13s317": "11, 12",
            "d16s539": "9, 12",
            "d18s51": "11, 19",
            "d21s11": "29, 31.2",
            "d3s1358": "17",
            "d5s818": "13",
            "d7s820": "10",
            "d8s1179": "12, 13",
            "fga": "24",
            "penta_d": "9, 12",
            "penta_e": "7, 13",
            "th01": "6, 8",
            "tpox": "11",
        },
        {
            "id": "sample2",
            "csf1po": "12",
            "d13s317": "11, 12",
            "d16s539": "8, 12",
            "d18s51": "17, 18",
            "d21s11": "28, 33.2",
            "d3s1358": "16",
            "d5s818": "11",
            "d7s820": "8, 13",
            "d8s1179": "9, 10",
            "fga": "21, 25",
            "penta_d": "9, 12",
            "penta_e": "7",
            "th01": "7, 9.3",
            "tpox": "8",
        },
        {
            "id": "sample3",
            "csf1po": "11, 12",
            "d13s317": "8",
            "d16s539": "11",
            "d18s51": "18",
            "d21s11": pd.NA,
            "d3s1358": "16",
            "d5s818": "10, 11",
            "d7s820": "12",
            "d8s1179": "11",
            "fga": "26",
            "penta_d": pd.NA,
            "penta_e": "13.1, 12.1",
            "th01": "6, 9.3",
            "tpox": "12",
        },
    ]
)

tanabe_scores = str_sim_scorer.compare(
    df,
    id_col_name="id",
    locus_col_names=[
        "csf1po",
        "d13s317",
        "d16s539",
        "d18s51",
        "d21s11",
        "d3s1358",
        "d5s818",
        "d7s820",
        "d8s1179",
        "fga",
        "penta_d",
        "penta_e",
        "th01",
        "tpox",
    ],
    output="df",
)

Using output="df" returns a data frame for distinct pairs of IDs:

>>> print(tanabe_scores)
       id1      id2  n_shared_alleles  n_common_markers    tanabe
0  sample1  sample2                 6                46  0.260870
1  sample1  sample3                 2                35  0.114286
2  sample2  sample3                 5                35  0.285714

Using output="symmetric_df" returns the same data frame with (id1, id2) rows repeated as (id2, id1):

>>> print(tanabe_scores)
       id1      id2  n_shared_alleles  n_common_markers    tanabe
0  sample1  sample2                 6                46  0.260870
1  sample1  sample3                 2                35  0.114286
2  sample2  sample3                 5                35  0.285714
3  sample2  sample1                 6                46  0.260870
4  sample3  sample1                 2                35  0.114286
5  sample3  sample2                 5                35  0.285714

Finally, output="array" returns a tuple: a symmetric numpy array of just the similarity scores and a list of row/col labels:

>>> print(tanabe_scores)
(array([[1.        , 0.26086957, 0.11428571],
       [0.26086957, 1.        , 0.28571429],
       [0.11428571, 0.28571429, 1.        ]]), ['sample1', 'sample2', 'sample3'])

This package computes the number of shared alleles and common markers largely through matrix algebra, so it is fast enough to be run on thousands of records (millions of pairs).

Development

Installation

1. Install the required system dependencies:

   • pyenv
   • Poetry
   • pre-commit

2. Install the required Python version (3.9.18):

   pyenv install "$(cat .python-version)"
   

3. Confirm that python maps to the correct version:

   python --version
   

4. Set the Poetry interpreter and install the Python dependencies:

   poetry env use "$(pyenv which python)"
   poetry install
   

Run pre-commit run --all-files to automatically format your code with Ruff and check static types with Pyright.

Whenever possible, function/method arguments and return values should be validated with Pydantic/Pandera.

Testing

poetry run pytest