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

Full documentation and vignettes: 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:

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	blaTEM	-	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 (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:

  pip install 'sensityper[metrics]'
  

Install from PyPI

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

conda install -c conda-forge -c bioconda sensityper

The conda package (from the Bioconda 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:

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:

   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:

   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.

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.

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.

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.

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.

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)

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

# 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 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, azithromycin, ciprofloxacin, tetracycline, penicillin, zoliflodacin, gepotidacin		penA.A311_WT penA.A501_WT penA.V316_WT		23S.A2059_WT 23S.C2611_WT mtrC.WT mtrD.WT		gyrA.D95_WT gyrA.S91_WT parC.D86_WT parC.E91_WT parC.S87_WT		rpsJ.V57_WT tetM.not_present		blaTEM.not_present penA.insD345_WT ponA.L421_WT	rpsE.T24P	16S.C1184_WT		gyrB.D429_WT gyrB.K450_WT		gyrA.A92_WT parC.D86_WT
WHO_Q	spectinomycin, zoliflodacin, gepotidacin	penA.60.001 penA.A311V penA.V316T	penA.A501_WT	23S.A2059G[99.9%]	23S.C2611_WT mtrC.WT mtrD.WT	gyrA.D95_A gyrA.S91F parC.S87R	parC.D86_WT parC.E91_WT	rpsJ.V57M tetM		penA.60.001 ponA.L421P	blaTEM.not_present penA.insD345_WT		16S.C1184_WT rpsE.T24_WT		gyrB.D429_WT gyrB.K450_WT		gyrA.A92_WT parC.D86_WT
WHO_Z	azithromycin, spectinomycin, zoliflodacin, gepotidacin	penA.64.001 penA.A311V penA.V316T	penA.A501_WT		23S.A2059_WT 23S.C2611_WT mtrC.WT mtrD.WT	gyrA.D95N gyrA.S91F parC.S87R	parC.D86_WT parC.E91_WT	rpsJ.V57M	tetM.not_present	penA.64.001 ponA.L421P	blaTEM.not_present penA.insD345_WT		16S.C1184_WT rpsE.T24_WT		gyrB.D429_WT gyrB.K450_WT		gyrA.A92_WT 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, azithromycin=YES, ciprofloxacin=YES, tetracycline=YES, penicillin=YES, spectinomycin=NO, zoliflodacin=YES, 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, azithromycin=NO, ciprofloxacin=NO, tetracycline=NO, penicillin=NO, spectinomycin=YES, zoliflodacin=YES, 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, azithromycin=YES, ciprofloxacin=NO, tetracycline=NO, penicillin=NO, spectinomycin=YES, zoliflodacin=YES, 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 - Step-by-step tutorial

  • Complete workflow example using N. gonorrhoeae WHO reference strains
  • Result interpretation
  • Common issues and solutions

• Sensityping metrics vignette - 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:

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.