Gracefully handle low-coverage runs with explicit failure output (instead of crashing) [fix #109]

[MikeWLloyd]

Summary

This change makes low/no-coverage OptiType runs fail gracefully.

Previously, when no HLA reads were mapped, OptiType could crash with a pandas length-mismatch error while building the hit matrix. Now, low-coverage scenarios are detected explicitly, the run exits with a clear message, and a structured result TSV is still written so downstream workflows can handle the failure consistently / user can understand the failure.

Problem

In low/no-coverage inputs, the pipeline could reach an empty-read state and raise an internal error similar to:

    Mapping with RazerS3 using 4 threads...
    0:00:01.51 Mapping hg38_WES.trimmed.R1.fastq to GEN reference...
    0:05:52.54 Mapping hg38_WES.trimmed.R2.fastq to GEN reference...
    0:11:46.14 Generating binary hit matrix.
    0:11:46.18 Loading out/hg38_WES_1.bam started. Number of HLA reads loaded (updated every thousand):

     0:11:46.18 0 reads loaded. Creating dataframe...
    Error: Length mismatch: Expected axis has 0 elements, new values have 11179 elements

This exposed an implementation detail rather than a user-meaningful outcome.

What Changed

1. Added safe handling for empty alignment DataFrames so empty inputs do not trigger column assignment crashes.
2. Introduced a dedicated low-coverage failure path in the pipeline:
   • Detects cases where typing cannot proceed due to zero/insufficient usable HLA reads.
   • Raises a domain-specific low-coverage error with a clear, actionable message.
3. Writes a structured failure result TSV when typing is not possible:
   • Includes FAILED status, zero reads, and a human-readable message.
   • Preserves an output artifact even on failure.
4. Added regression tests for:
   • Empty alignment parsing behavior.
   • Pipeline low-coverage graceful failure + failure TSV generation.
   • CLI surfacing of low-coverage reason and result TSV path.

User-Facing Behavior

When typing is not possible due to low coverage, users now get:
• A clear low-coverage failure message.
• A written result TSV indicating FAILED status and why typing could not be produced.

Instead of:
• An internal pandas exception with no graceful diagnostic artifact.

Validation

Targeted tests executed and passing:

1. Empty-alignment + low-coverage pipeline tests.
2. CLI low-coverage messaging/path assertion test.

Backward Compatibility

• No API break intended for successful runs.
• Failure behavior is improved and now deterministic/artifact-producing for low-coverage cases.

Notes for Reviewers

Focus areas:

1. Correctness of low-coverage detection thresholds/conditions.
2. Failure TSV schema/content for downstream compatibility.
3. CLI error messaging clarity and consistency.

[MikeWLloyd]

I have an updated dockerfile that goes with this patch. I wasn't sure if you want such a thing here or not. If you would like the updated file, I can push the change.

Here is the updated build file so you can preview it:

#################################################################
# Dockerfile
#
# Version:          1.0
# Software:         OptiType
# Software Version: 1.3
# Description:      Accurate NGS-based 4-digit HLA typing
# Website:          https://github.com/FRED-2/OptiType/
# Tags:             Genomics
# Provides:         OptiType 1.3
#################################################################

# Source Image
FROM python:3.11-slim

################## BEGIN INSTALLATION ###########################

RUN apt-get update && apt-get install -y --no-install-recommends \
        build-essential \
        cmake \
        git \
        coinor-cbc \
        glpk-utils \
        zlib1g-dev \
        libbz2-dev \
        libhdf5-dev \
    && rm -rf /var/lib/apt/lists/*

# Install optitype from local source
WORKDIR /opt/optitype
COPY . .
RUN pip install --no-cache-dir .

# Build razers3; --depth 1 avoids fetching full seqan history
RUN git clone --depth 1 https://github.com/seqan/seqan.git /tmp/seqan-src \
    && cmake -S /tmp/seqan-src -B /tmp/seqan-build -DCMAKE_BUILD_TYPE=Release \
    && cmake --build /tmp/seqan-build --target razers3 \
    && cp /tmp/seqan-build/bin/razers3 /usr/local/bin/ \
    && rm -rf /tmp/seqan-src /tmp/seqan-build

WORKDIR /data/

CMD ["optitype", "--help"]

##################### INSTALLATION END ##########################

LABEL maintainer="Benjamin Schubert <schubert@informatik.uni-tuebingen.de>"