Metadata-Version: 2.4
Name: sensityper
Version: 1.0.4
Summary: Genomic antimicrobial susceptibility prediction and treatment recommendation for Neisseria gonorrhoeae
Author: Daniel Golparian, Leonor Sánchez-Busó, Magnus Unemo
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/leosanbu/sensityper
Project-URL: Documentation, https://leosanbu.github.io/sensityper/
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: metrics
Requires-Dist: numpy; extra == "metrics"
Requires-Dist: pandas; extra == "metrics"
Requires-Dist: scikit-learn; extra == "metrics"
Requires-Dist: plotly; extra == "metrics"
Dynamic: license-file

# SensiTyper - Genomic Antimicrobial Susceptibility Prediction and Treatment Recommendation for *Neisseria gonorrhoeae*

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-GPL--3.0-blue.svg)](https://github.com/leosanbu/sensityper/blob/main/LICENSE)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-teal.svg)](https://leosanbu.github.io/sensityper/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.866572118.svg)](https://doi.org/10.5281/zenodo.22835140)

> **Full documentation and vignettes:** [https://leosanbu.github.io/sensityper/](https://leosanbu.github.io/sensityper/)

## Overview

SensiTyper is a genomic antimicrobial susceptibility typing pipeline for *Neisseria gonorrhoeae*. It predicts antibiotic resistance profiles from whole-genome sequencing data and provides evidence-based treatment recommendations.

### Key Features

- **Genomic resistance profiling** - Identifies resistance-conferring mutations in 8 antibiotics
- **Treatment recommendations** - Assigns regimens based on current clinical guidelines
- **Interactive HTML reports** - Sortable, searchable tables for easy investigation of results
- **XDR detection** - Flags extensively drug-resistant (XDR) isolates for clinical review
- **Modular workflow** - Run complete pipeline or individual steps

### Supported Antibiotics

- **Ceftriaxone** - First-line injectable cephalosporin
- **Azithromycin** - First-line macrolide (dual therapy)
- **Ciprofloxacin** - Fluoroquinolone (restricted use)
- **Spectinomycin** - Alternative injectable (limited pharyngeal efficacy)
- **Penicillin** - Historical β-lactam
- **Tetracycline** - Historical broad-spectrum
- **Zoliflodacin** - Oral spiropyrimidinetrione
- **Gepotidacin** - Oral triazaacenaphthylene

### Pipeline Overview

SensiTyper reads the summary output obtained from ARIBA containing key determinants of antimicrobial resistance, identifies which antibiotics each strain is susceptible to and makes a treatment recommendation. This can be done by running different modules in SensiTyper:

| Module | Aim |
| --- | --- |
| `ariba` | Run ARIBA as a wrapper script |
| `sensitype` | Identify antibiotics each strain is susceptible to |
| `sensitreat` | Perform a treatment recommendation |
| `pipeline` | Chain different modules, e.g. `ariba,sensitype,sensitreat`, `sensitype,sensitreat`, etc. Note that the order must be `ariba → sensitype → sensitreat`, and `sensitreat` needs the output of sensitype to run |

### Workflow:

![SensiTyper workflow — from raw FASTQ reads to treatment recommendations](https://raw.githubusercontent.com/leosanbu/sensityper/main/docs/images/sensityper_workflow.png)

### Resistance Determinants

The table below lists the genetic markers evaluated by the prediction logic for each antibiotic.

| Antibiotic | Locus | Wild-type position | Known AMR determinant |
|------------|------|--------------------|-------------------|
| **Ceftriaxone** | PenA | A311 | Any |
|  |  | V316 | Any |
|  |  | A501 | A501P |
| **Azithromycin** | 23S rDNA | A2059 | 2059A>G |
|  | | C2611 | 2611C>T |
|  | MtrD | - | Semi- and mosaic structure |
|  | MtrC | - | GC dinucleotide deletion in repeat |
| **Ciprofloxacin** | GyrA | S91 | S91F/T/Y/I |
|  |  | D95 | D95G/N |
|  | ParC | D86 | D86N |
|  |  | S87 | S87A/I/N/R/W |
|  |  | E91 | E91K |
| **Penicillin** | *bla*TEM | - | Presence in pBla plasmid |
|  | PenA | - | insD345 |
|  |  | - | Semi- and mosaic structure |
|  | PonA | L421 | L421P |
| **Tetracycline** | *tetM* | - | Presence in pConjugative plasmid |
|  | RpsJ | V57 | V57M |
| **Spectinomycin** | 16S rDNA | C1192 | 1192C>T |
|  | RpsE | T24 | T24P |
| **Zoliflodacin** | GyrB | D429 | Any |
|  |  | K450 | Any |
| **Gepotidacin** | GyrA | A92 | A92T \* |
|  | ParC | D86 | D86N \* |

\* **Combination rule.** Gepotidacin is excluded only when **both** GyrA A92T *and* ParC D86N are present; either mutation on its own is reported in `gepotidacin_NWT` but does not exclude the drug. Ceftriaxone follows the same pattern: it is excluded by PenA A501P, or by A311 **and** V316 together.

## Installation

### Prerequisites

- **Python 3.8+** — the core pipeline (`ariba`, `sensitype` and `sensitreat` modules) requires no external Python packages
- **[ARIBA](https://github.com/sanger-pathogens/ariba/wiki)** (Antimicrobial Resistance Identification By Assembly) — only needed for the `ariba` module. ARIBA is no longer actively maintained (last release October 2023): its conda package supports Python up to 3.12 and needs setuptools older than 82. See *Install with conda* below for a working command.
- **Sensityping metrics only** — the companion evaluation script (`sensityping-metrics`) additionally requires standard scientific Python, installed with the `metrics` extra:
  ```bash
  pip install 'sensityper[metrics]'
  ```

### Install from PyPI

```bash
pip install sensityper
sensityper --help
```

The databases are bundled with the package. The command `sensityper` is installed on your PATH.

To try SensiTyper with the bundled example data (WHO tutorial data and the `sensityping-metrics` example), run `sensityper examples` in your working directory; it creates an `examples/` folder.

> **Note:** ARIBA is *not* installed by `pip install sensityper`. It is only needed for the `ariba` module (and `pipeline` runs that include it), and must be installed separately (see *Install with conda* below; ARIBA needs Python 3.12 or older and `setuptools<82`). The `sensitype` and `sensitreat` modules need no external software.

### Install with conda

```bash
conda install -c conda-forge -c bioconda sensityper
```

The conda package (from the [Bioconda](https://bioconda.github.io/) channel) installs SensiTyper and the extra libraries needed by `sensityping-metrics`. It does **not** install ARIBA, which is only needed for the `ariba` module (the `sensitype` and `sensitreat` modules work without it).

To use the `ariba` module as well, create an environment that includes ARIBA. ARIBA is no longer actively maintained, so this needs Python 3.12 or older and `setuptools<82`:

```bash
conda create -n sensityper -c conda-forge -c bioconda python=3.12 sensityper ariba "setuptools<82"
conda activate sensityper
sensityper --help
```

### Setup from source

1. **Clone the repository**:
   ```bash
   git clone https://github.com/leosanbu/sensityper.git
   cd sensityper
   pip install -e .
   ```

2. **Verify database files** are present in `src/sensityper/resources/`:
   ```
   resources/
   ├── sensitype.db         # Resistance mutation database
   ├── sensitype.penA.db    # penA mosaic allele database
   ├── ariba_db/            # ARIBA reference database
   └── examples/            # Example data (WHO tutorial and sensityping-metrics)
 
   ```

3. **(Optional) Set environment variables** for custom paths:
   ```bash
   export SENSITYPE_DB=/path/to/sensitype.db
   export SENSITYPE_PENA_DB=/path/to/sensitype.penA.db
   export SENSITYPE_ARIBA_DB=/path/to/ariba_db
   export SENSITYPE_ARIBA_BATCH=/path/to/ariba_batch_v0.2.py
   export SENSITYPE_RULES_PATH=/path/to/sensiscript.py
   ```

   If not set, the bundled files inside the installed package are used. 

## Usage

### Module: `ariba`

Run ARIBA in batch mode on FASTQ directories.

```bash
sensityper ariba \
    --input_dirs /data/run1,/data/run2 \
    --output_dir ariba_results \
    --db_path /path/to/ariba_db \
    --threads 8
```

**Arguments**:
- `--input_dirs` - Comma-separated list of directories containing FASTQ files
- `--output_dir` - Output directory for ARIBA results
- `--db_path`- Path to the ARIBA database, by default the bundled `resources/ariba_db`
- `--threads` - Number of CPU threads (default: 1)

**FASTQ Naming**: Fastq files must follow one of these patterns:
- `{sample}_1.fastq.gz` / `{sample}_2.fastq.gz`
- `{sample}_R1.fastq.gz` / `{sample}_R2.fastq.gz`
- `{sample}_R1_001.fastq.gz` / `{sample}_R2_001.fastq.gz`

### Module: `sensitype`

Generate resistance profiles from ARIBA output.

```bash
sensityper sensitype \
    --input_AMRtable ariba_summary.csv \
    --sensiscript_outfile sensiscript_results.tsv \
    --sensiscript_antibiotics ceftriaxone,azithromycin,ciprofloxacin
```

**Arguments**:
- `--input_AMRtable` - ARIBA summary CSV file (required)
- `--sensiscript_outfile` - Output TSV file path (default: `sensiscript_results.tsv`)
- `--sensiscript_db` - Path to sensitype main database of genetic AMR determinants (default: bundled `resources/sensitype.db`)
- `--sensiscript_pena` - Path to a database of penA mosaics (default: bundled `resources/sensitype.penA.db`)
- `--sensiscript_antibiotics` - Comma-separated antibiotic list (default: ceftriaxone,azithromycin,ciprofloxacin,tetracycline,penicillin,spectinomycin,zoliflodacin,gepotidacin)

**Outputs**:
- `sensiscript_results.tsv` - Resistance mechanisms per isolate
- `sensiscript_results.html` - Interactive table reporting the genetic determinants of AMR and identified wildtype positions found for each isolate

### Module: `sensitreat`

Assign treatment recommendations from resistance profiles.

```bash
sensityper sensitreat \
    --input_file resistance_profiles.tsv \
    --available_antibiotics ceftriaxone,azithromycin,ciprofloxacin,spectinomycin \
    --sensitreat_order ceftriaxone+azithromycin,ceftriaxone,azithromycin+spectinomycin,ciprofloxacin,spectinomycin \
    --alert_output alert_output.tsv \
    --treatment_output treatment_recommendations.tsv \
    
```

**Arguments**:
- `--input_file` - Input resistance TSV from sensitype (required)
- `--available_antibiotics` - Comma-separated list of antibiotics available in a specific setting (default: ceftriaxone,azithromycin,ciprofloxacin,tetracycline,penicillin,spectinomycin,zoliflodacin,gepotidacin)
- `--sensitreat_order` - Regimen priority order (default: ceftriaxone+azithromycin,ceftriaxone,azithromycin+spectinomycin,ciprofloxacin,spectinomycin,zoliflodacin,gepotidacin). **Important:** azithromycin monotherapy is supported but NOT in the default order; include 'azithromycin' explicitly to enable it
- `--alert_output` - Output TSV for isolates tagged as a clinical alert (default `alert_output.tsv`)
- `--treatment_output` - Output treatment TSV path (default: `treatment_output.tsv`)

**Outputs**:
- `alert_output.tsv` - Isolates with XDR/no treatment options
- `treatment_recommendations.tsv` - Recommended treatment regimens per isolate
- `treatment_recommendations.html` - Combined tabbed HTML with:
  - **Alert Banner** (if XDR isolates present)
  - **Tab 1: Treatment Recommendations** (direct output from the sensitreat module with recommended treatment regimes)
  - **Tab 2: Resistance Profile** (output from the sensitype module)

### Module: `pipeline`

Chain multiple modules together in a single command.

```bash
sensityper pipeline \
    --modules sensitype,sensitreat \
    --other_arguments '--input_AMRtable ariba_summary.csv --sensiscript_outfile sensiscript_results.tsv'
```

**Arguments**:
- `--modules`: Comma-separated module names (required) (options: `ariba`, `sensitype`, `sensitreat`)
- `--other_arguments` - All module-specific arguments within quotes

### Module: `rename`

Standardize FASTQ file naming across directories.

```bash
sensityper rename \
    --directories /data/run1,/data/run2 \
    --pre
```

**Arguments**:
- `--directories` - Comma-separated directory list
- `--pre` - Preview mode (dry-run, no actual renaming)

### Complete Pipeline (FASTQ → Treatment Recommendations)

```bash
sensityper pipeline \
    --modules ariba,sensitype,sensitreat \
    --other_arguments '--input_dirs /data/fastqs \
                       --output_dir ariba_outputdir \
                       --sensiscript_outfile sensiscript_results.tsv \
                       --treatment_output treatment_output.tsv \
                       --threads 8'
```

**Outputs**:
- `ariba_output/` - Folder with ARIBA results for each sample
- `ariba_summary.csv` - ARIBA summary table
- `sensiscript_results.tsv` - Resistance and wildtype determinants detected per isolate (direct output from the `sensitype` module)
- `alert_output.tsv` - XDR/untreatable isolates (direct output from the `sensitreat` module)
- `treatment_output.tsv` - Treatment regimens (direct output from the `sensitreat` module)
- `treatment_output.html` - Interactive combined HTML report (direct output from the `sensitreat` module)

---

## Sensityping metrics — Evaluation of predictions against phenotypic outcomes

**Sensityping metrics** is a companion command-line script for evaluating the performance of genomic AMR predictions against phenotypic (gold-standard) treatment outcomes.

It complements the SensiTyper pipeline by providing rigorous, reproducible performance metrics with confidence intervals, sample size diagnostics, and interactive radar visualisations.

### Two evaluation modes

| Mode | Question answered |
|------|------------------|
| `predicted_vs_treatment` | How accurate is each per-antibiotic prediction? |
| `first_line_vs_treatment` | How well does the treatment cascade perform in practice? |

### Quick example

```bash
# Model-centric evaluation (per antibiotic)
sensityping-metrics \
  -i sensiscript_with_phenotypes.tab \
  -o metrics_predicted.tab \
  -d metrics_predicted_dir \
  --analysis_type predicted_vs_treatment \
  --ci_flag --ci_method hybrid --ci_level 0.95 \
  --n_boot 2000 --seed 1 \
  --ssd_flag --ssd_width 0.05 --ssd_mode observed \
  --radar_flag --radar_metrics PPV,sensitivity,specificity,coverage_fraction

# Clinical cascade evaluation (treatment workflow)
sensityping-metrics \
  -i sensiscript_with_phenotypes.tab \
  -o metrics_firstline.tab \
  -d metrics_firstline_dir \
  --analysis_type first_line_vs_treatment \
  --order 'CRO+AZM,CRO,AZM,AZM+SPC,SPC,ZOL' \
  --id_extraction CRO+AZM,CRO,AZM,AZM+SPC,SPC,ZOL \
  --ci_flag --ci_method hybrid --ci_level 0.95 \
  --n_boot 2000 --seed 1 \
  --ssd_flag --ssd_width 0.05 --ssd_mode observed \
  --radar_flag --radar_metrics PPV,one_minus_FDR,coverage_fraction
```

See the **[Sensityping metrics vignette](https://leosanbu.github.io/sensityper/metrics/)** for a full step-by-step tutorial including argument descriptions, expected outputs, and metric interpretation.

## Output Files

### Resistance Profile TSV (`sensiscript_results.tsv`)

Tab-separated file with columns:
- `isolate` - Sample identifier
- `treatment recommendation` - Comma-separated list of suitable antibiotics
- `{antibiotic}_NWT` - Non-wild-type (resistance) markers
- `{antibiotic}_WT` - Wild-type (susceptible) markers

**Example**:

| isolate | treatment recommendation | ceftriaxone_NWT | ceftriaxone_WT | azithromycin_NWT | azithromycin_WT | ciprofloxacin_NWT | ciprofloxacin_WT | tetracycline_NWT | tetracycline_WT | penicillin_NWT | penicillin_WT | spectinomycin_NWT | spectinomycin_WT | zoliflodacin_NWT | zoliflodacin_WT | gepotidacin_NWT | gepotidacin_WT |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| WHO_A | ceftriaxone,<br>azithromycin,<br>ciprofloxacin,<br>tetracycline,<br>penicillin,<br>zoliflodacin,<br>gepotidacin |  | penA.A311_WT<br>penA.A501_WT<br>penA.V316_WT |  | 23S.A2059_WT<br>23S.C2611_WT<br>mtrC.WT<br>mtrD.WT |  | gyrA.D95_WT<br>gyrA.S91_WT<br>parC.D86_WT<br>parC.E91_WT<br>parC.S87_WT |  | rpsJ.V57_WT<br>tetM.not_present |  | blaTEM.not_present<br>penA.insD345_WT<br>ponA.L421_WT | rpsE.T24P | 16S.C1184_WT |  | gyrB.D429_WT<br>gyrB.K450_WT |  | gyrA.A92_WT<br>parC.D86_WT |
| WHO_Q | spectinomycin,<br>zoliflodacin,<br>gepotidacin | penA.60.001<br>penA.A311V<br>penA.V316T | penA.A501_WT | 23S.A2059G[99.9%] | 23S.C2611_WT<br>mtrC.WT<br>mtrD.WT | gyrA.D95_A<br>gyrA.S91F<br>parC.S87R | parC.D86_WT<br>parC.E91_WT | rpsJ.V57M<br>tetM |  | penA.60.001<br>ponA.L421P | blaTEM.not_present<br>penA.insD345_WT |  | 16S.C1184_WT<br>rpsE.T24_WT |  | gyrB.D429_WT<br>gyrB.K450_WT |  | gyrA.A92_WT<br>parC.D86_WT |
| WHO_Z | azithromycin,<br>spectinomycin,<br>zoliflodacin,<br>gepotidacin | penA.64.001<br>penA.A311V<br>penA.V316T | penA.A501_WT |  | 23S.A2059_WT<br>23S.C2611_WT<br>mtrC.WT<br>mtrD.WT | gyrA.D95N<br>gyrA.S91F<br>parC.S87R | parC.D86_WT<br>parC.E91_WT | rpsJ.V57M | tetM.not_present | penA.64.001<br>ponA.L421P | blaTEM.not_present<br>penA.insD345_WT |  | 16S.C1184_WT<br>rpsE.T24_WT |  | gyrB.D429_WT<br>gyrB.K450_WT |  | gyrA.A92_WT<br>parC.D86_WT |

### Treatment Output TSV (`treatment_output.tsv`)

Tab-separated file with columns:
- `isolate` - Sample identifier
- `Predicted Profile` - Susceptibility summary, one entry per antibiotic evaluated by `sensitype` (e.g., "ceftriaxone=YES, azithromycin=YES, ...")
- `Recommended Treatment` - Full regimen with dosing (e.g., "Ceftriaxone 1 g IM + Azithromycin 2 g orally")
- `Comment` - Clinical guidance and warnings

**Example**:

| isolate | recommended_1 | recommended_2 | Predicted Profile | Recommended Treatment | Comment | ceftriaxone+azithromycin | ceftriaxone | azithromycin | azithromycin+spectinomycin | ciprofloxacin | spectinomycin | zoliflodacin | gepotidacin | chosen_regimen |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| WHO_A | ceftriaxone | azithromycin | ceftriaxone=YES,<br>azithromycin=YES,<br>ciprofloxacin=YES,<br>tetracycline=YES,<br>penicillin=YES,<br>spectinomycin=NO,<br>zoliflodacin=YES,<br>gepotidacin=YES | Ceftriaxone 1 g IM + Azithromycin 2 g orally | Acceptable combination therapy | YES | NO | NO | NO | NO | NO | NO | NO | ceftriaxone+azithromycin |
| WHO_Q | spectinomycin | zoliflodacin | ceftriaxone=NO,<br>azithromycin=NO,<br>ciprofloxacin=NO,<br>tetracycline=NO,<br>penicillin=NO,<br>spectinomycin=YES,<br>zoliflodacin=YES,<br>gepotidacin=YES | Spectinomycin 2 g IM | Lower cure rates in oropharyngeal infection; avoid as monotherapy for oropharyngeal infection when possible | NO | NO | NO | NO | NO | YES | NO | NO | spectinomycin |
| WHO_Z | azithromycin | spectinomycin | ceftriaxone=NO,<br>azithromycin=YES,<br>ciprofloxacin=NO,<br>tetracycline=NO,<br>penicillin=NO,<br>spectinomycin=YES,<br>zoliflodacin=YES,<br>gepotidacin=YES | Spectinomycin 2 g IM + Azithromycin 2 g orally | Alternative regimen | NO | NO | NO | YES | NO | NO | NO | NO | azithromycin+spectinomycin |

### Alert Output TSV

Lists isolates requiring clinical review:
- **XDR** - Resistant to ceftriaxone, azithromycin, AND ciprofloxacin
- **None** - No suitable treatment options available

### HTML Report

When running the `sensiscript` alone or `sensityper sensitype` module, results will also be formatted into an HTML file showing the identified resistance and wildtype determinants for each antibiotic under study.

When running `sensityper sensitreat` or the `pipeline` mode including `sensitreat`, a combined HTML report will be produced showing the results of both `sensitype` and `sensitreat` as two tabs:

- **Report header** - Isolate count and the list of antibiotics available for treatment in this setting, as given to `--available_antibiotics`
- **Alert Banner** - Clinical warnings
- **Tab 1: Treatment Recommendations** (direct output from the `sensitreat` module with recommended treatment regimes)
- **Tab 2: Resistance Profile** (outut from the `sensitype` module with detailed resistance and wildtype determinants

## Documentation

- **[*N. gonorrhoeae* WHO reference strains vignette](https://leosanbu.github.io/sensityper/who-vignette/)** - Step-by-step tutorial
  - Complete workflow example using *N. gonorrhoeae* WHO reference strains
  - Result interpretation
  - Common issues and solutions

- **[Sensityping metrics vignette](https://leosanbu.github.io/sensityper/metrics/)** - Evaluation framework tutorial
  - Model-centric and clinical workflow evaluation
  - Confidence intervals, sample size diagnostics, and radar plots

## Clinical Interpretation

### Treatment Recommendation Categories

**Guideline-recommended monotherapy**:
- Ceftriaxone 1 g IM
- Used when azithromycin resistance detected

**Acceptable combination therapy**:
- Ceftriaxone 1 g IM + Azithromycin 2 g orally
- Preferred dual therapy for uncomplicated gonorrhea

**Alternative regimen**:
- Spectinomycin 2 g IM + Azithromycin 2 g orally
- Used when ceftriaxone resistance detected
- **Note**: Lower cure rates for pharyngeal infections

**Newer oral options**:
- Zoliflodacin 3 g orally (single dose)
- Gepotidacin 3 g orally twice (2 doses, 10-12 h apart)
- US FDA-approved for uncomplicated urogenital infection; lower cure rates in oropharyngeal infection

### Important Limitations

- **Genotypic predictions may differ from phenotypic resistance** - Confirmatory culture and antimicrobial susceptibility testing (AST) recommended
- **Spectinomycin** - Avoid for pharyngeal infections when possible
- **Novel mutations** - Flagged with `(WARN:novel_mutation)`, require expert review
- **Clinical context** - Consider patient history, allergies, infection site, and local resistance patterns

## Troubleshooting

### ARIBA Failures

**Symptom**: ARIBA fails for some samples

**Solutions**:
- Check FASTQ file naming (use `rename` module to standardize)
- Increase retry attempts in ariba_batch_v0.2.py (default: 3)
- Run ARIBA with only one thread

### ARIBA Crashes on Start: `No module named 'pkg_resources'`

**Symptom**: `ariba` (and therefore `sensityper ariba`) stops immediately with `ModuleNotFoundError: No module named 'pkg_resources'`

**Cause**: ARIBA 2.14.7 (the current Bioconda build at the time of writing) imports `pkg_resources`, which was removed from **setuptools 82** and later. ARIBA's conda package does not pin setuptools, so a fresh environment can end up with a version that is too new. This is a problem in ARIBA's packaging, not in SensiTyper.

**Solutions**:
- Install an older setuptools in the same environment: `conda install "setuptools<82"` (or `pip install "setuptools<82"`)
- ARIBA is no longer actively maintained, so this will not be fixed upstream: keep the pin in any environment that uses ARIBA

### ARIBA Fails with the Bundled Database (versions 1.0.1 to 1.0.3)

**Symptom**: the `ariba` module (or a `pipeline` run that includes it) stops while ARIBA is building its read index, with errors such as `Unsorted positions on sequence #1`, `building of index for read_store.gz failed` or `No such file or directory: .../report.tsv`

**Cause**: in the packages published to PyPI and Bioconda up to version 1.0.3, the bundled ARIBA database (`resources/ariba_db`) contains Windows line endings, which ARIBA cannot read correctly. The copy of the database in the GitHub repository is not affected. This is fixed in version 1.0.4 and later, so the workaround below is only needed for 1.0.1 to 1.0.3 (or upgrade with `pip install -U sensityper`).

**Solution**: use the database from a clone of the repository by passing its path with `--db_path`:

```bash
git clone --depth 1 https://github.com/leosanbu/sensityper.git
sensityper ariba --input_dirs <FASTQ_DIR> --output_dir <OUTPUT_DIR> \
    --db_path sensityper/src/sensityper/resources/ariba_db
```

In `pipeline` mode, add `--db_path sensityper/src/sensityper/resources/ariba_db` to the `--other_arguments` string. The `sensitype` and `sensitreat` modules are not affected.

### Treatment Shows "None"

**Symptom**: Treatment recommendation is "None" for an isolate

**Cause**: No suitable treatment available from `--available_antibiotics` list

**Solutions**:
- Check `alert_output.tsv` for XDR status
- Review resistance profile TSV to confirm all antibiotics are resistant
- Consider expanding `--available_antibiotics` if clinically appropriate

### HTML Not Generated

**Symptom**: TSV files created but no HTML output

**Solutions**:
- Check if `--suppress-html` flag was used (pipeline mode suppresses standalone HTML)
- Verify TSV file exists and has valid content (not empty)
- Check console for Python exceptions during HTML generation
- Ensure output directory is writable

## Citation

If you use SensiTyper in your research, please cite:

```
Golparian D, Sánchez-Busó L and Unemo M. Genomic Surveillance Meets Clinical Practice: Rule-Based Individualised Treatment Prediction for Gonorrhoea using SensiTyper. Nature Communications (2026, In press).
```

## Contact

For questions, bug reports, or feature requests:
- Open an issue on GitHub
- Contact leonor.sanchez@fisabio.es or daniel.golparian@regionorebrolan.se

---

**Disclaimer**: This tool is for research and surveillance purposes. Clinical treatment decisions should be made by qualified healthcare professionals considering patient-specific factors, local resistance patterns, and current treatment guidelines. Confirmatory phenotypic testing is recommended when possible.
