Metadata-Version: 2.4
Name: sensityper
Version: 1.0.1
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)
  ```bash
  conda install -c bioconda ariba
  ```
- **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.

> **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, e.g. `conda install -c bioconda ariba`. The `sensitype` and `sensitreat` modules need no external software.

### 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 input for 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

### 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.
