Best practises guide

This page details the way in which we would advise that you should use and run PopPUNK, if possible.

Flowchart for choosing how to use PopPUNK

Use an online interface

If available, you may want to use one of the browser-based interfaces to PopPUNK. These include PopPUNK-web and (S. pneumoniae only). See the PopPUNK-web page for full details.

Using these interfaces requires nothing to be installed or set up, doesn’t require any genome data to be shared with us, and will return interactive visualisations. If your species isn’t available, or you have large batches of genomes to cluster you will likely want to use the command line interface instead.

Use the command line interface

Installation and version

Install via conda if possible. Please use at least version v2.3.0 of PopPUNK and v1.5.1 of pp-sketchlib.

Use query assignment mode

If a database is available for your species (see we would strongly recommend downloading it to use to cluster your genomes. This has many advantages:

  • No need to run through the potentially complex model fitting.
  • Assured model performance.
  • Considerable faster run times.
  • Use existing cluster definitions.
  • Use the context of large, high quality reference populations to interpret your genomes’ clusters.

See Query assignment for instructions on how to use this mode.

You can think of this as being similar to using an existing MLST/cgMLST/wgMLST scheme to define your sample’s strains.

Fit your own model

If a database isn’t available for your species, you can fit your own. Details on how to do this can be found on Fitting new models.

After getting a good fit, you may want to share it with others so that they can use it to assign queries. See Distributing PopPUNK models for advice. We would also be interested to hear from you if you’d like to add your new model to the pre-fit databases above – please contact

Create visualisations

A number of plots are created by default. You can also create files for further visualisation in microreact, cytoscape, grapetree and phandango. We have found that looking at the appearance of clusters on a tree is always very helpful, and would recommend this for any fit.

Older versions of PopPUNK mandated this be chosen as part of the main analysis, and then with --generate-viz mode. This is now run separately, after the main analysis, with poppunk_visualise.

See Creating visualisations for details on options.