Skip to content

NG-MAST/NG-STAR Mastery: ngmaster v2.0.0 Unleashed with database overhaul

Choose a tag to compare

View all tags
@himal2007 himal2007 released this 22 May 08:07
· 74 commits to master since this release
v2.0.0
467d216

ngmaster v2.0.0

⚠️ Breaking change: this release is not backward compatible with v1.x due to database schema changes.

Breaking Changes

  • --updatedb now requires authenticated PubMLST access via mlstdb. Run mlstdb connect -d pubmlst once to register your credentials before using --updatedb. Unauthenticated access is still possible but will only provide data up to 2024-12-31 due to PubMLST licensing restrictions.
  • mlst >= 2.25.0 is now required. Older versions of mlst will silently miss alleles in large databases.
  • Output schema change: a new CC (clonal complex) column is now included in all output formats. Scripts parsing ngmaster output by column index will need updating.

Bug Fixes

  • Fixes #37: NG-STAR typing failed when >1 23S alleles were detected. Duplicate 23S alleles are now collapsed before typing.
  • Fixes #38: --updatedb crashed with ConnectionResetError(104, 'Connection reset by peer'). Resolved by migrating to mlstdb for robust, session-managed API access to PubMLST.
  • Fixes missed allele detections in large BLAST databases — requires mlst >= 2.25.0 (upstream fix).

New Features

  • --version now reports both the tool version and the bundled database version.
  • CC (clonal complex) column added to output from the updated NG-STAR scheme.
  • --comments flag includes per-allele NG-STAR annotation comments in output.
  • --threads N (default: 1, recommended: 4) parallelises:
    • Allele fetching during --updatedb (limits simultaneous connections to PubMLST)
    • mlst subprocess execution during typing
  • Default --db path shown in --help for easier debugging of custom database setups.
  • Updated README.md with new features, and database update instructions.

Database

The bundled database is the last freely redistributable snapshot of the PubMLST NG-MAST/NG-STAR schemes (up to 2024-12-31). Per the PubMLST terms and conditions, content after this date cannot be redistributed without appropriate licensing. Use ngmaster --updatedb with authenticated mlstdb credentials to get the latest alleles.

Development

  • Added pixi.toml + pixi.lock for fast, reproducible contributor environments (pixi install sets up the full stack including mlst from bioconda).
  • Removed Pipfile, deploy.sh, and redundant publsh.yml workflow.
  • User-Agent header in PubMLST API requests now identifies as ngmaster v2.0.0.

Upgrade notes

# Install/upgrade
pip install ngmaster==2.0.0   # or: conda install -c bioconda ngmaster=2.0.0

# One-time authentication setup for --updatedb
mlstdb connect -d pubmlst

# Update to latest alleles
ngmaster --updatedb --threads 4

Changelog

Full Changelog: v1.1.1...v2.0.0

Assets 2
Loading