ngmaster

In silico multi-antigen sequence typing for Neisseria gonorrhoeae (NG-MAST) and Neisseria gonorrhoeae sequence typing for antimicrobial resistance (NG-STAR).

Synopsis

% ngmaster gona.fa
FILE     SCHEME      NG-MAST/NG-STAR  porB_NG-MAST  tbpB  penA  mtrR  porB_NG-STAR  ponA  gyrA  parC  23S  CC
gono.fa  ngmaSTar    4186/231         2569           241   23    42    100           100   10    2     100  231

Installation

Conda/Mamba

conda install -c bioconda ngmaster

PiPy

conda install -c bioconda mlst mlst mlstdb
pip install ngmaster

pixi (fast reproducible environment)

# Install pixi if not already installed
curl -fsSL https://pixi.sh/install.sh | bash

# Clone the repo and set up the environment
git clone https://github.com/MDU-PHL/ngmaster
cd ngmaster
pixi install
pixi run pip install -e .

Test

% ngmaster --test

Running ngmaster on test example (NG-MAST 4186 / NG-STAR 231) ...
FILE    SCHEME  NG-MAST/NG-STAR porB_NG-MAST    tbpB    penA    mtrR    porB_NG-STAR    ponA    gyrA    parC 23S      CC
test.fa     ngmaSTar        4186/231     2569     241     23      42      100     100     10      2       100     231
... Test successful.

Usage

ngmaster -h

usage:
  ngmaster [OPTIONS] <fasta1> <fasta2> <fasta3> ... <fastaN>

In silico multi-antigen sequence typing for Neisseria gonorrhoeae (NG-MAST)
and Neisseria gonorrhoeae Sequence Typing for Antimicrobial Resistance (NG-STAR)

Please cite as:
  Kwong JC, Goncalves da Silva A, Howden BP and Seemann T.
  NGMASTER: in silico multi-antigen sequence typing for Neisseria gonorrhoeae (NG-MAST)
  GitHub: https://github.com/MDU-PHL/ngmaster

positional arguments:
  FASTA            input FASTA files eg. fasta1, fasta2, fasta3 ... fastaN

optional arguments:
  -h, --help       show this help message and exit
  --db DB          specify custom directory containing allele databases
                   directory must contain database sequence files (.tfa) and allele profile files (ngmast.txt / ngstar.txt)
                   in mlst format (see <https://github.com/tseemann/mlst#adding-a-new-scheme>)
                   overrides $NGMASTER_DB if both are set
                   default: $NGMASTER_DB if set, otherwise <path/to/ngmaster/package/db>
  --csv            output comma-separated format (CSV) rather than tab-separated
  --printseq FILE  specify filename to save novel allele sequences to
                   (only alleles marked ~n are written; no file created if all alleles are exact matches)
  --minid MINID    DNA percent identity of full allele to consider 'similar' [~] (default: 95, range: 0-100)
  --mincov MINCOV  DNA percent coverage to report partial allele at [?] (default: 50, range: 0-100)
  --updatedb       update NG-MAST and NG-STAR allele databases from <https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef>
  --assumeyes      assume you are certain you wish to update db
  --test           run test example
  --comments       include NG-STAR comments for each allele in output
  --version        show program's version number and exit

Quick start

To perform in silico NG-MAST and NG-STAR typing on FASTA files:

$ ngmaster <fasta1> <fasta2> <fasta3> ... <fastaN>

The NG-MAST and NG-STAR results and allele numbers are printed in tab-separated format to stdout.

• ngmaster reports alleles according to the same rules that are implemented in mlst.
• mlst's arguments --minid and --mincov are available directly in ngmaster (defaults: --minid 95, --mincov 50; valid range: 0–100)
• For each allele n:

Symbol	Meaning	Length	Identity
n	exact intact allele	100%	100%
~n	novel full length allele similar to n	100%	≥ --minid
n?	partial match to known allele	≥ --mincov	≥ --minid
-	allele missing	< --mincov	< --minid
n,m	multiple alleles

To save results to a tab-separated text file, redirect stdout:

$ ngmaster <fasta1> <fasta2> <fasta3> ... <fastaN> > results.txt

To display results in comma-separated format, use the --csv option:

$ ngmaster --csv <fasta1> <fasta2> <fasta3> ... <fastaN>

To save novel allele sequences to a file (eg. for uploading to PubMLST):

$ ngmaster --printseq [filename] <fasta1> <fasta2> <fasta3> ... <fastaN>

Only alleles marked ~n (novel) are saved. No file is created if all alleles are exact matches. This will create two files:

1. NGMAST__filename
2. NGSTAR__filename

Database management

Updating the allele databases

The bundled database is the last freely redistributable snapshot of the PubMLST NG-MAST and NG-STAR schemes. The PubMLST terms and conditions do not permit redistribution of database content after 2024-12-31 without appropriate licensing.

To update to the latest alleles, you need an authenticated PubMLST account and API credentials via mlstdb:

# Register and connect to PubMLST (one-time setup)
mlstdb connect -d pubmlst --api-key

# Update the bundled database
ngmaster --updatedb

# Or update into a custom directory
ngmaster --updatedb --db path/to/custom/db

Warning: --updatedb overwrites existing database files. Back up your current db/ directory first if needed.

Check version and database version:

ngmaster --version

Shared database (HPC / team use)

Set the $NGMASTER_DB environment variable to point to a shared database directory. ngmaster will use it automatically without requiring --db on every call:

export NGMASTER_DB=/shared/path/to/ngmaster_db
ngmaster <fasta1> <fasta2> ...

--db on the command line takes precedence over $NGMASTER_DB. If neither is set, the bundled database is used.

Creating a custom allele database

To create a custom allele database please follow the instructions for creating a custom mlst database described here. Usually, this should not be necessary, simply run ngmaster --update to update to the latest NG-MAST and NG-STAR schemes from PubMLST.

Changes from version 1 to version 2

• Version and database version info: ngmaster --version now reports both the tool version and the bundled database version. Note: unauthenticated database automatically means database pre-dating 2025.
• Clonal complex (CC): output now includes a CC column from the updated NG-STAR database.
• Duplicate 23S alleles: multiple identical 23S alleles detected in a sample are now collapsed into a single call.
• Large database and decimal allele fix: requires mlst >= 2.34.0 with pubMLST database using NG-STAR style decimal allele numbers (eg. 2.002).
• Database licensing notice: the bundled database reflects the last freely redistributable snapshot of PubMLST. The PubMLST database after 2024-12-31 is subject to PubMLST terms and conditions and cannot be redistributed without appropriate licensing. Use --updatedb (with authenticated access) to get the latest data. For authenticated access, ensure you are registered with PubMLST and have an API key to access the database update endpoint: mlstdb connect -d pubmlst --api-key.

Dependencies

• Python >= 3.7
• BioPython
• mlst >= 2.34.0
• mlstdb — for authenticated database updates

Citation

Kwong JC, Gonçalves da Silva A, Dyet K, Williamson DA, Stinear TP, Howden BP Seemann T.
NGMASTER: in silico multi-antigen sequence typing for Neisseria gonorrhoeae Microbial Genomics 2016 Aug 25;2(8):e000076. PMID:28348871 DOI:10.1099/mgen.0.000076

Feedback

Please submit via the GitHub issues page.

Software Licence

GPLv2

References

• Martin et al. J Infect Dis, 2004 Apr 15; 189(8): 1497-1505.
• Demczuk et al. J Clin Microbiol, 2017 May; 55(5): 1454-1468
• See also PubMLST.

Authors

• Jason Kwong (@kwongjc)
• Anders Gonçalves da Silva (@drandersgs)
• Mark Schultz (@schultzm)
• Torsten Seemann (@torstenseemann)
• Himal Shrestha (@himals2007)
• Andreas Stroehlein (@stroehleina)

Development

When incrementing version (i.e., minor patch), run the following:

bumpversion --verbose --dry-run --new-version <major.minor.patch> patch
bumpversion --new-version <new.version.number> patch

The same can be done for minor and major numbers.

This will automatically commit and tag the commit with the new version number. It will also update the necessary location in the file.