Skip to content

LINcodes

Jump to bottom
Bert Bogaerts edited this page Aug 19, 2026 · 3 revisions

This tutorial describes how to retrieve LIN codes (Life Identification Number codes) with MiST.

Life Identification Numbers (LINs) are hierarchical, multi-position integer codes derived from cgMLST profiles. Each successive position represents a more specific level of genomic relatedness, enabling comparisons between isolates at different taxonomic levels.

For more information on LIN codes in general, see the BIGSdb Institut Pasteur documentation.

LIN codes and your scheme source

mist lincode retrieves the LIN code for the best-matching profile in a mist call JSON output. Where it gets that LIN code from depends on the source of the cgMLST scheme:

Source LIN codes in the profiles file? How MiST retrieves them
BIGSdb (PubMLST.org, BIGSdb Institut Pasteur) Yes, included as metadata Fully offline, from the downloaded profiles.tsv
EnteroBase No An authenticated API call to EnteroBase for the matched cgST
cgMLST.org Does not support LIN codes Does not support LIN codes

mist lincode also determines how many leading LIN code positions can be reliably assigned given the number of matching loci, and masks the other positions.

Notes:

  • MiST does not assign novel LIN numbers, it can only identify the LIN code up to the level supported by similarity to existing profiles in the local database. Submitting your data to the source platform is required to get (and register) complete, up-to-date LIN codes.
  • Downloading and indexing a cgMLST scheme is a time-consuming, one-time step. Querying afterwards is fast (allele calling typically takes one to two minutes), while cgMLST/LIN-code matching itself is near-instantaneous, see Benchmarks below).

Requirements

  • MiST v1.4.0 or later.
  • A local cgMLST scheme and its indexed profile database.
  • EnteroBase schemes only: an EnteroBase API token.
  • BIGSdb schemes: authorized access to PubMLST.org / BIGSdb Institut Pasteur Paris is recommended to download the cgMLST schemes

BIGSdb walkthrough (Klebsiella LIN codes)

This walkthrough shows how to download the Klebsiella cgMLST scheme, build a MiST profile index, and use it to retrieve a LIN code.

The Klebsiella LIN code scheme is based on the scgMLST629_S scheme, hosted on the Institut Pasteur Paris BIGSdb instance.

1. Download the scheme

The first command shows the available BIGSdb databases. The second lists the schemes available in the Klebsiella sequence-definition database.

mist list --downloader bigsdb --host pasteur  # List the available sub-databases on the BIGSdb instance
mist list --downloader bigsdb --host pasteur --db pubmlst_klebsiella_seqdef  # List Klebsiella schemes

In this example, scgMLST629_S corresponds to scheme ID 18.

mist download \
  --downloader bigsdb \
  --url https://bigsdb.pasteur.fr/api/db/pubmlst_klebsiella_seqdef/schemes/18 \
  --output kleb_scgmlst_s \
  --include-profiles

⚠️ Note: Downloading profiles can take a long time due to the large number of entries (a BIGSdb limitation, not MiST).

💡 Tip: The example above downloads without authentication. To obtain the latest version of the scheme, use the bigsdb_auth downloader instead. See Downloading schemes for details.

2. Create the MiST index

mist index \
  --fasta-list kleb_scgmlst_s/fasta_list.txt \
  --profiles kleb_scgmlst_s/profiles.tsv \
  --output kleb_scgmlst_s-index \
  --threads 8 \
  --build-profile-index

Because scgMLST629_S is a full core-genome scheme, --build-profile-index is worth the additional indexing time and substantially speeds up profile matching, see Indexing schemes.

3. Call alleles

Download a test dataset, or use your own assembly.

curl -L -o GCA_048969535.fasta \
  "https://www.ebi.ac.uk/ena/browser/api/fasta/GCA_048969535.1?download=true&gzip=false"
mist call \
  --fasta GCA_048969535.fasta \
  --db kleb_scgmlst_s-index \
  --out-json GCA_048969535.json

The log will display the best-matching scgST(s):

2025-09-26 11:30:24,271 -      mistcaller -    INFO - Matching ST: 4362 (99.21% match)

4. Extract the partial LIN code

mist lincode \
  GCA_048969535.json \
  --db kleb_scgmlst_s-index \
  --output GCA_048969535_lincode.json

The log will display the LIN code, masked to the positions that can be reliably assigned given the number of matching loci:

2026-08-10 16:40:00,000 -    mistlincode -    INFO - Extracted LIN code for ST 4362: 0-0-369-0-0-0-*-*-*-*

GCA_048969535_lincode.json contains the full result:

{
  "st": "4362",
  "nb_matches": 624,
  "nb_loci": 629,
  "lincode_full": ["0", "0", "369", "0", "0", "0", "0", "35", "0", "0"],
  "lincode_partial": ["0", "0", "369", "0", "0", "0", null, null, null, null],
  "fields": {
    "...": "any extra LIN-code-linked fields defined for this scheme, e.g. clonal complex/phylogroup"
  }
}

lincode_partial has the same length as lincode_full, with positions beyond what's reliably assignable set to null - not just truncated, so you can always tell how deep the assignment actually goes. fields are read from whichever extra metadata columns the scheme's LIN-code definition links (varies per scheme).

EnteroBase walkthrough (cgMLST)

EnteroBase cgMLST schemes (e.g. Escherichia/Shigella, Salmonella) don't include LIN codes in the profiles file

  • mist lincode retrieves them from EnteroBase's API instead based on the best-matching cgST (see step 4).

1. Download the scheme

mist list -d enterobase
mist download \
  -d enterobase \
  --url https://enterobase.warwick.ac.uk/schemes/Escherichia.cgMLSTv1/ \
  --include-profiles

The FASTA files and profiles file are downloaded to the mist_download directory. See Downloading schemes for more information.

2. Index the scheme

This step is slow for large EnteroBase schemes (see Benchmarks) - --build-profile-index is strongly recommended here, since these schemes can have hundreds of thousands of profiles.

mist index \
  --fasta-list mist_download/fasta_list.txt \
  --profiles mist_download/profiles.tsv \
  --output DB_NAME \
  --threads 8 \
  --build-profile-index

See Indexing schemes for more information.

3. Call alleles

mist call \
  --fasta contigs.fasta \
  --db DB_NAME \
  --out-json mist.json

The best-matching cgST is reported in mist.json under profiles, together with the percentage of matching loci.

4. Retrieve the LIN code from EnteroBase

Since EnteroBase doesn't include LIN codes in the profiles file, this step queries EnteroBase's API for the matched cgST. Pass your API token (see Requirements) via --entero-token, and select the scheme with --entero-preset:

mist lincode \
  mist.json \
  --db DB_NAME \
  --entero-token ~/.enterobase_token \
  --entero-preset ecoli \
  --output lincode.json

⚠️ Note: EnteroBase's API uses different species/scheme identifiers than its download URLs, and there's no reliable way to derive one from the other (E. coli downloads from Escherichia.cgMLSTv1, but the API expects ecoli/cgMLST). The hierCC field the LIN codes were mapped from also differs per species.
mist lincode can read these from the preset you select. It covers the two EnteroBase schemes that carry LIN codes:

--entero-preset API species API scheme hierCC field
ecoli ecoli cgMLST hierCC
salmonella senterica cgMLST_v2 hierCCv0

Any preset value can be overridden individually with --entero-species, --entero-scheme, or --entero-hiercc-field (e.g. when EnteroBase publishes a new scheme version). If you don't select a preset, you must supply at least --entero-species and --entero-scheme yourself.

mist lincode \
  mist.json \
  --db DB_NAME \
  --entero-token ~/.enterobase_token \
  --entero-species ecoli \
  --entero-scheme cgMLST \
  --output lincode.json
2026-08-10 16:40:00,000 -    mistlincode -    INFO - Extracted LIN code for ST 102245: 0-0-3-0-0-0-0-3-3-7-0-*-*

{
  "st": "102245",
  "nb_matches": 3000,
  "nb_loci": 3002,
  "lincode_full": ["0", "0", "3", "0", "0", "0", "0", "3", "3", "7", "0", "0", "0"],
  "lincode_partial": ["0", "0", "3", "0", "0", "0", "0", "3", "3", "7", "0", null, null]
}

The reliably assignable depth is derived from EnteroBase's hierCC (hierarchical clustering) distances for that ST, which use the same mismatch thresholds as the LIN code itself.

Implementation notes

MiST's original profile-matching approach loaded all profiles into memory as string-keyed objects and checked them one by one, counting matching loci. While this works well for classic 7-gene MLST schemes, it becomes too slow and memory-intensive for cgMLST schemes with hundreds of thousands of profiles and thousands of loci.

The optional profile index (--build-profile-index, see Indexing schemes) addresses these limitations:

  • Compact allele encoding: Alleles are encoded as compact integers, including support for wildcards and missing alleles, instead of strings.
  • Inverted index: A locus + allele → matching profiles index is built, so a query only considers profiles that share at least one detected allele rather than scanning every profile.
  • Disk-backed storage: The index is stored in on-disk NumPy arrays using memory mapping rather than being held entirely in memory. A multithreaded, vectorized scatter step makes construction of large indexes practical.
  • Vectorized matching: Matching profile counts are accumulated using a single vectorized operation rather than one Python operation per match. This is particularly beneficial for schemes with thousands of profiles sharing common alleles, such as wildcard alleles.

Profile indexing is opt-in (--build-profile-index). Regular MLST and smaller cgMLST schemes are typically fast enough with the standard scan, while building the index introduces a one-time computational cost (at the database indexing stage).

Benchmarks

The indexing times below include both database construction and profile-index construction (--build-profile-index). Benchmarks were performed in August 2026 using 4 threads for indexing. Downloading the scheme and profiles with mist download took between 3 and 12 minutes, depending on the external resource.

Species Scheme Source Nb. loci Nb. profiles Indexing Querying
Escherichia coli cgMLST EnteroBase 2,513 418,129 2h 38min 0–3 min
Klebsiella spp. scgMLST629_S BIGSdb Institut Pasteur 629 78,427 9 min 51s <1 min
Listeria spp. cgMLST BIGSdb Institut Pasteur 1,748 77,124 19 min 30s <2 min
Neisseria spp. cgMLST PubMLST.org 1,329 88,374 59 min 21s <1 min
Salmonella spp. cgMLST v2 EnteroBase 3,002 720,475 3h 13min 2–5 min

The following commands were used to download, index, query, and retrieve LIN codes for the benchmark schemes:

mist list  # Retrieve scheme URLs for mist download

# BIGSdb
mist download \
    --url https://bigsdb.pasteur.fr/api/db/pubmlst_listeria_seqdef/schemes/15 \
    --downloader bigsdb_auth \
    --output download/listeria \
    --include-profiles \
    --dir-tokens {PATH_TO_API_KEYS} \
    --key-name Pasteur \
    --site Pasteur

# EnteroBase
mist download \
    --url https://enterobase.warwick.ac.uk/schemes/Salmonella.cgMLSTv2/ \
    --downloader enterobase \
    --output download/salmonella \
    --include-profiles

mist index \
    --fasta-list download/salmonella/fasta_list.txt \
    --profiles download/salmonella/profiles.tsv \
    --output index/salmonella \
    --threads 4 \
    --build-profile-index

mist call \
    --fasta {PATH_TO_FASTA} \
    --db index/salmonella \
    --out-json calls/salmonella.json \
    --threads 4 \
    -m longest

# EnteroBase
mist lincode \
    calls/salmonella.json \
    --db index/salmonella \
    --output calls/salmonella_lincode.json \
    --entero-token {PATH_TO_ENTEROBASE_KEY} \
    --entero-preset salmonella

# BIGSdb
mist lincode \
    calls/listeria.json \
    --db index/listeria \
    --output calls/listeria_lincodes.json

Disclaimer

When using LIN codes, please cite the original publication and database.

Getting started

Creating databases

Running & output

Example use cases

Clone this wiki locally