Metadata-Version: 2.4
Name: py-hla-match
Version: 0.0.1
Summary: Py-HLA-Match open-source research software for HLA matching.
License: Apache-2.0
License-File: LICENSE
Keywords: HLA,histocompatibility,transplantation,matching,bioinformatics
Author: Tim Adams
Author-email: tim.adams@scai.fraunhofer.de
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Dist: openpyxl (>=3.1.0,<4)
Requires-Dist: pandas (>=2.2.2,<3)
Requires-Dist: py-ard (>=1.5.5,<2)
Requires-Dist: requests (>=2.32.4,<3)
Project-URL: Documentation, https://github.com/fraunhofer-izi/py-hla-match#readme
Project-URL: Homepage, https://github.com/fraunhofer-izi/py-hla-match
Project-URL: Issue Tracker, https://github.com/fraunhofer-izi/py-hla-match/issues
Project-URL: Repository, https://github.com/fraunhofer-izi/py-hla-match
Project-URL: Regulatory Notice, https://github.com/fraunhofer-izi/py-hla-match/blob/main/SOFTWARE_CARD.md
Project-URL: Third-Party Licenses, https://github.com/fraunhofer-izi/py-hla-match/blob/main/THIRD_PARTY_LICENSES.md
Description-Content-Type: text/markdown

# Py-HLA-Match

![tests](https://github.com/fraunhofer-izi/py-hla-match/actions/workflows/tests.yaml/badge.svg)
![docs](https://github.com/fraunhofer-izi/py-hla-match/actions/workflows/docs.yaml/badge.svg)
![version](https://img.shields.io/pypi/v/py-hla-match)
![license](https://img.shields.io/badge/license-Apache%202.0-blue)

## About

Py-HLA-Match is a Python library for standardised, rule-based HLA (Human Leukocyte Antigen) matching in retrospective analyses, method development, benchmarking, and in-silico studies in immunogenetics and related fields.

## Regulatory Notice

Py-HLA-Match is **not** certified or conformity assessed as a medical device software or in-vitro medical device software and is intended for **research use only**. It must therefore not be used for diagnosis or therapy of patients.

For more details on intended use, scope, and limitations, see the [Software Card](SOFTWARE_CARD.md).

## Installation

Install from PyPI:

```bash
pip install py-hla-match
```

## Quickstart

This quickstart uses the artificial CSVs bundled under the `demo` folder and avoids any real or sensitive data.

### Run a basic pairwise match

Use the synthetic patient and donor CSVs and write results to a new file:

```python
from py_hla_match.parser import HLADataSource
from py_hla_match.export import PairwiseMatch

data_path = "py_hla_match/demo/data/random_data/synthetic_patients.csv"
donor_path = "py_hla_match/demo/data/random_data/synthetic_donors.csv"
output_path = "py_hla_match/demo/data/random_data/match_results.csv"

src = HLADataSource(
    data_path,
    col_idx_start=1,
    col_idx_stop=13,
    row_idx_start=1,
)

tgt = HLADataSource(
    donor_path,
    col_idx_start=1,
    col_idx_stop=13,
    row_idx_start=1,
)

matcher = PairwiseMatch(
    source=src,
    target=tgt,
    storage_filename=output_path,
    resolution="high",
)

matcher.run()
```

### Inspect raw allele-level results

Convert raw match levels to a DataFrame and write to CSV:

```python
raw_output_path = "py_hla_match/demo/data/random_data/match_results_raw.csv"
matcher.raw_to_df().to_csv(raw_output_path, index=False)
```

## Terminology

Py-HLA-Match uses domain terms such as *patient*, *donor*, and *score* to mirror the structure of typical transplant research datasets (e.g. HSCT retrospective cohorts). These terms refer exclusively to roles and fields in research data and do **not** imply that Py-HLA-Match implements, recommends, or automates any clinical donor-selection or patient-management workflow.

All match levels and related outputs produced by the library are research metrics derived from HLA nomenclature semantics. They are **not** clinical risk scores or decision criteria.

## Development

### Prerequisites

Install [Poetry](https://python-poetry.org/docs/#installation):

```bash
curl -sSL https://install.python-poetry.org | python3 -
```

On Windows (PowerShell):

```powershell
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
```

### Setup

```bash
git clone https://github.com/fraunhofer-izi/py-hla-match.git
cd py-hla-match
poetry install
```

### Running tests

```bash
poetry run pytest
```

## License

Copyright 2025 Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V.

Licensed under the Apache License, Version 2.0. You may obtain a copy of the License in the [`LICENSE`](LICENSE) file or at <http://www.apache.org/licenses/LICENSE-2.0>.

