PELC (Python Eplet Load Calculator)

Overview

PELC is a Python package designed to calculate efficiently the HLA Eplet Load (based on the EpRegistry database) between donors and recipients by loading in a pandas.DataFrame in eplet_comparison.compute_epletic_load the recipients' and donors' typings. See minimal reproducible example for more details.

Getting started

Install from PyPI (recommended)

To use pelc, run pip install pelc in your terminal.

Usage

a. Comparing two alleles

Here is a minimal example of how to use pelc to compare two alleles: ```py from pelc.simplecomparison import simplecomparison

simplecomparison( "A68:01", "A68:02", "output", # file will be saved as output.csv in the current directory verifiedonly=False, # if True, only verified eplets will be considered, otherwise all eplets will be considered interlocus2=True # doesn't matter for class I alleles ) `` In theoutput.csv` file created in the current directory, you will find two rows: "In A*68:02 but not in A*68:01" and "In A*68:01 but not in A*68:02".

b. Batch mode

Here is a minimal example with the file Template.xlsx (click to download): ```py import pandas as pd

from pelc import batchepletcomp, batchepletcompaux, outputtype

if name == "main": input_path: str = "Template.xlsx"

output_path: str = "MyOutput"
input_df: pd.DataFrame = pd.read_excel(
    input_path,
    sheet_name="My Sheet",
    index_col=0,
)

donordf: pd.DataFrame
recipientdf: pd.DataFrame
donordf, recipientdf = batch_eplet_comp_aux.split_dataframe(input_df)

batch_eplet_comp.compute_epletic_load(
    donordf,
    recipientdf,
    output_path,
    output_type.OutputType.DETAILS_AND_COUNT,
    class_i=True,  # Compute class I eplets comparison?
    class_ii=True,  # Compute class II eplets comparison?
    verified_only=False,  # How should the epletic charge be computed? Verified eplets only? Or all eplets?
    exclude=None,  # list of indices to exclude
    interlocus2=True  # whether or not to take into account interlocus eplets for HLA of class II
)

`` Note that if a typing is unknown, one can useA,B, ...,DPB1` as the allele name for *both** recipients and donors. If the allele is unknown for only of the two individuals, it is necessary to use A*, B*, ..., DPB1* for both individuals otherwise the eplet mismatch computation will not be performed for this donor / recipient pair.

Advanced usage:

a. Not taking into account all loci (if they are not typed for example)

If one wants to determine the eplet mismatches between a donor and a recipient but without taking into account a certain locus, one can use A*, B*, ..., DPB1* as the allele name for both recipients and donors on this locus and the eplet mismatch computation will only take into account the loci filled in.

b. Not creating a file but generating a pandas.DataFrame

If one wants to generate a pandas.DataFrame directly, the output_path argument of simple_comparison can be set to None. The pandas.DataFrame will be returned by the function. Same goes for compute_epletic_load.

Exit codes:

- 55: an eplet did not match the regular expression '^\d+' (ABC, DR, DQ or DP) and it also did not match the regular expression '^.[PQR]*(\d+)' (interlocus2) either.

Unit tests

Tested on Python 3.10.6 (pelc0.5.2) & Python 3.11.1 (pelc0.5.2) & Python 3.12.5 (pelc0.5.4.4). ``` platform win32 -- Python 3.10.6, pytest-7.4.0, pluggy-1.2.0 plugins: mypy-0.10.3 collected 39 items

unittestsmypy.py .. [ 5%] unittestssimple.py . [ 7%] pelc_init.py . [ 10%] pelc_inputsanitycheck.py . [ 12%] pelc_openepregistrydatabases.py . [ 15%] pelc_unexpectedalleles.py . [ 17%] pelc\batchepletcomp.py . [ 20%] pelc\batchepletcompaux.py . [ 23%] pelc\outputtype.py . [ 25%] pelc\simplecomparison.py . [ 28%] tests_init_.py . [ 30%] tests\baseloadingfortests.py . [ 33%] tests\testepletmismatches.py ......... [ 56%] tests\testextractkeytorankepletes.py .. [ 61%] tests\testisvalidallele.py .. [ 66%] tests\testonlyonechromosome.py .. [ 71%] tests\testpelc.py .. [ 76%] tests\testsamelocus.py .. [ 82%] tests\testsimplecomparison.py ..... [ 94%] tests\testunexpectedalleles.py .. [100%] ==================================== mypy =====================================

Success: no issues found in 20 source files ============================= 39 passed in 34.42s ============================= ```

``` platform win32 -- Python 3.11.1, pytest-7.2.2, pluggy-1.0.0 plugins: anyio-3.6.2, mypy-0.10.3 collected 39 items

unittestsmypy.py .. [ 5%] unittestssimple.py . [ 7%] pelc_init.py . [ 10%] pelc_inputsanitycheck.py . [ 12%] pelc_openepregistrydatabases.py . [ 15%] pelc_unexpectedalleles.py . [ 17%] pelc\batchepletcomp.py . [ 20%] pelc\batchepletcompaux.py . [ 23%] pelc\outputtype.py . [ 25%] pelc\simplecomparison.py . [ 28%] tests_init_.py . [ 30%] tests\baseloadingfortests.py . [ 33%] tests\testepletmismatches.py ......... [ 56%] tests\testextractkeytorankepletes.py .. [ 61%] tests\testisvalidallele.py .. [ 66%] tests\testonlyonechromosome.py .. [ 71%] tests\testpelc.py .. [ 76%] tests\testsamelocus.py .. [ 82%] tests\testsimplecomparison.py ..... [ 94%] tests\testunexpectedalleles.py .. [100%] ==================================== mypy =====================================

Success: no issues found in 20 source files ============================= 39 passed in 32.56s ============================= ```

``` ============================= test session starts ============================= platform win32 -- Python 3.12.5, pytest-8.3.4, pluggy-1.5.0 plugins: mypy-0.10.3 collected 50 items

pelc_init.py .. [ 4%] pelc_inputsanitycheck.py . [ 6%] pelc_openepregistrydatabases.py . [ 8%] pelc_unexpectedalleles.py . [ 10%] pelc\batchepletcomp.py . [ 12%] pelc\batchepletcompaux.py . [ 14%] pelc\outputtype.py . [ 16%] pelc\simplecomparison.py . [ 18%] tests_init_.py . [ 20%] tests\baseloadingfortests.py . [ 22%] tests\testconverttoeplets.py ... [ 28%] tests\testepletmismatches.py ............ [ 52%] tests\testextractkeytorankepletes.py .. [ 56%] tests\testisvalidallele.py .. [ 60%] tests\testnullallele.py ... [ 66%] tests\testonlyonechromosome.py .. [ 70%] tests\testpelc.py .. [ 74%] tests\testsamelocus.py .. [ 78%] tests\testsimplecomparison.py ....... [ 92%] tests\testunexpectedalleles.py .. [ 96%] unittestsmypy.py . [ 98%] unittests_simple.py . [100%] ===================================== mypy ====================================

Success: no issues found in 22 source files ============================ 50 passed in 21.88s ============================== ```

About the source code

• Follows PEP8 Style Guidelines.
• All functions are unit-tested with pytest.
• All variables are correctly type-hinted, reviewed with static type checker mypy.
• All functions are documented with docstrings.

Useful links:

• Corresponding GitHub repository
• Corresponding PyPI page

Citation

If you use this software, please cite it as below.

• APA: ``` If you use this software, please cite it as below.

Lhotte, R., Clichet, V., Usureau, C. & Taupin, J. (2022). Python Eplet Load Calculator (PELC) package (Version 0.5.4.4) [Computer software]. https://doi.org/10.5281/zenodo.7254809 ```

• BibTeX: @software{lhotte_romain_2022_7526198, author = {Lhotte, Romain and Clichet, Valentin and Usureau, Cédric and Taupin, Jean-Luc}, title = {Python Eplet Load Calculator}, month = oct, year = 2022, publisher = {Zenodo}, version = {0.5.4.4}, doi = {10.5281/zenodo.7526198}, }