HLACat

HLACat is an HLA typing webserver that integrates Sanger, NGS, and long-read typing workflows behind a unified Flask backend. It wraps OptiType, SpecHLA, T1K, and a rewritten Python SOAPTyping runtime, normalizes their outputs into shared typing-call summaries, and generates browser-viewable evidence reports where supported.

This public repository contains the HLACat-owned web application, wrappers, tests, documentation, and the Python SOAPTyping runtime source. It does not vendor third-party typing tools, command-line bioinformatics tools, IPD-IMGT/HLA database snapshots, generated reference databases, uploaded user data, or task result artifacts.

HLACat-owned source code and documentation in this repository are released under the MIT License. Third-party tools and databases keep their own licenses and must be installed or rebuilt separately.

What Is Included

• src/hla_backend/: Flask backend, server-rendered HTML templates, local CSS/JavaScript assets, upload validation, task orchestration, setup agent routes, retention cleanup, database update commands, and combined IGV generation code.
• packages/soaptyping_runtime/: HLACat-maintained Python runtime for SOAPTyping-compatible Sanger AB1 typing.
• tests/: public-safe backend and SOAPTyping runtime tests.
• docs/: architecture, setup, database update, combined IGV, public repository boundary, and SOAPTyping runtime documentation.
• ops/: optional maintenance scripts for scheduled IPD-IMGT/HLA database checks.
• scripts/check_release_workspace.py: repository and runtime-path checker.

What Is Not Included

HLACat uses the following external projects or data sources, but they are intentionally not bundled in this public repository:

External component	HLACat usage	Public repository handling
OptiType	Wrapped NGS typing provider	Install from upstream; configure HLACAT_OPTITYPE_ROOT or HLACAT_VENDOR_ROOT.
SpecHLA	Wrapped NGS and long-read typing provider	Install from upstream; configure HLACAT_SPECHLA_ROOT or HLACAT_VENDOR_ROOT.
T1K	Wrapped NGS typing provider	Install from upstream; configure HLACAT_T1K_ROOT or HLACAT_VENDOR_ROOT.
Original SOAPTyping	Reference implementation and database shape for Sanger typing	Not vendored because the original project is GPLv3; HLACat publishes its own Python runtime source instead.
IPD-IMGT/HLA / IMGTHLA	Source reference database for HLA allele data	Rebuild locally through update scripts; generated snapshots are not committed.
BWA, samtools, bcftools, FreeBayes, Bowtie2, bedtools	Alignment, BAM/VCF handling, variant calling, and helper workflows	Install externally and expose through HLACAT_TOOL_ENV_BIN or PATH.
igv-reports / igv.js	Standalone browser evidence reports	Installed as Python/runtime dependencies; upstream licenses remain unchanged.

See THIRD_PARTY_LICENSES.md for license notes and source links.

Python SOAPTyping Runtime

The Sanger lane is not a direct copy of the original SOAPTyping application. HLACat includes a backend-oriented Python runtime under packages/soaptyping_runtime/ that reproduces the required SOAPTyping-compatible workflow for web tasks:

• AB1 parsing, trace extraction, quality handling, and forward/reverse orientation.
• SOAPTyping-style filename parsing for sample, locus, exon, direction, and run fields.
• Consensus alignment against SQLite-backed reference data.
• Forward/reverse read merging into sample-level exon patterns.
• Candidate allele-pair scoring and ranking.
• Structured JSON outputs for HLACat task summaries.
• Static Sanger evidence image generation for browser display.
• IMGT-derived database rebuild/update helpers for the SOAPTyping database shape.

The original SOAPTyping source tree and database assets are not included in this MIT-licensed public repository. For details, see docs/soaptyping_runtime.md.

Quick Start

cd HLACat
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'
python scripts/check_release_workspace.py --public
python -m pytest tests/backend tests/soaptyping_runtime

Start a local development server:

HLACAT_VENDOR_ROOT=/path/to/hlacat-third-party-tools \
HLACAT_TOOL_ENV_BIN=/path/to/hlacat-tool-env/bin \
python -m hla_backend.cli serve --host 127.0.0.1 --port 8013

The web interface can render without full provider tool installation, but end-to-end typing tasks require the corresponding external tools and databases.

Runtime Configuration

Common runtime variables:

• HLACAT_VENDOR_ROOT: root containing external provider tools.
• HLACAT_OPTITYPE_ROOT: OptiType installation path.
• HLACAT_SPECHLA_ROOT: SpecHLA installation path.
• HLACAT_T1K_ROOT: T1K installation path.
• HLACAT_SOAPTYPING_ROOT: optional local original SOAPTyping-compatible reference/runtime path, if maintained separately.
• HLACAT_TOOL_ENV_BIN: directory containing external CLI tools such as BWA, samtools, bcftools, FreeBayes, Bowtie2, and bedtools.

Optional setup-agent variables:

• DASHSCOPE_API_KEY
• DASHSCOPE_BASE_URL
• DASHSCOPE_MODEL

Do not commit secrets, uploaded task data, generated reports, runtime logs, local virtual environments, tool binaries, or generated database releases.

Documentation

• Setup guide
• Architecture
• Python SOAPTyping runtime
• Combined IGV report pipeline
• Database update workflow
• Public repository scope
• Third-party licenses and source links

License

HLACat-owned source code and documentation in this repository are licensed under MIT. This license does not apply to external tools, third-party databases, generated reference assets, uploaded data, task artifacts, or independently installed runtime components.