Setup

Hardware requirements

Participants should have access to a machine with at least 8 GB of RAM and 8 GB of free disk space. You can either run the tutorial on your personal laptop, or use a remote server that you have access to. Some commands we will run may benefit from a multi-threaded setup, but this is only optional.

Software requirements

We will be using krepp version v0.8.2.

Tool	Version	Purpose
conda / micromamba	any recent	environment management
krepp	0.8.2	distance estimation and placement
gappa	0.9.0	phylogenetic placement visualization and processing
wget / curl	any recent	downloading datasets

We recommend using micromamba, refer to this link for installation.

Create an environment and install krepp

Set up an environment and install krepp (version 0.8.2) via Bioconda, then verify the installation:

micromamba create -n krepp-tutorial -c conda-forge -c bioconda krepp=0.8.2 -ymicromamba activate krepp-tutorialkrepp --help

Expected output:

krepp version: v0.8.2krepp: a tool for k-mer-based search, distance estimation & phylogenetic placement.Usage: krepp [OPTIONS] SUBCOMMANDOptions:--help--verbose,--no-verbose{false}                            Increased verbosity and progress report.--seed UINT                 Random seed for the LSH and other parts that require randomness. [0]--num-threads UINT          Number of threads to use in OpenMP-based parallelism. [1]Subcommands:index                       Build an index from k-mers of reference genomes.place                       Place queries on a tree with respect to an index.dist                        Estimate distances of queries to genomes in an index.inspect                     Display statistics and information for a given index.sketch                      Create a sketch from k-mers in a single FASTA/FASTQ file.seek                        Seek query sequences in a sketch and estimate distances.

Install helper tools into the same environment, and verify:

micromamba install -c conda-forge -c bioconda gappa=0.9.0 wget -ygappa --help

Expected output:

                                            ....      ....                                            '' '||.   .||'                                                ||  ||                                                '|.|'    ...'   ....   ... ...  ... ...   ....        .|'|.    |  ||  '' .||   ||'  ||  ||'  || '' .||      .|'  ||    |''   .|' ||   ||    |  ||    | .|' ||     .|'|.  ||    '....  '|..'|'. ||...'   ||...'  '|..'|.    '||'    ||:.    '....'          ||       ||                ''''     ''''   v0.9.0 (c) 2017-2025                                by Lucas Czech and Pierre BarberaUsage: gappa [OPTIONS] SUBCOMMANDOptions:--help FLAG                 Print this help message and exit.--version FLAG              Print the gappa version and exit.Subcommands:analyze                     Commands for analyzing and comparing placement data, that is, finding differences and patterns.edit                        Commands for editing and manipulating files like jplace, fasta or newick.examine                     Commands for examining, visualizing, and tabulating information in placement data.prepare                     Commands for preparing and preprocessing of phylogenetic and placement data.simulate                    Commands for random generation of phylogenetic and placement data.tools                       Auxiliary commands of gappa.gappa - a toolkit for analyzing and visualizing phylogenetic (placement) data

Download and prepare the tutorial data

git clone https://github.com/bo1929/ismb2026-krepp-tutorial-materials.gitcd ismb2026-krepp-tutorial-materialsbash scripts/setup.sh

Note

setup.sh will download a small (~1.5 GB) microbial index.

Verify the inputs are ready

ls data/

Expected output:

input_map.tsvindex-WoLv1-tiny/profile.tsvprofile_species_accessions.tsvquery_genomes/query_info.tsvquery_taxonomy.tsvquery_mixture.fq.gzreference_genomes/reference_info.tsvreference_taxonomy.tsvreference_tree.nwk

Path	Description
`index-WoLv1-tiny/`	A lightweight Web of Life index for ~10,000 microbial genomes
`reference_genomes/`	A toy reference set, consisting of 31 reference genome assemblies (FASTA, gzip-compressed)
`reference_info.tsv`	Metadata describing reference labels, taxonomic groups and lineages, and accessions
`reference_tree.nwk`	A simple baseline phylogeny for the toy reference set, built from Mash distances
`input_map.tsv`	Two-column TSV mapping reference labels to genome file paths (31 lines)
`query_genomes/`	Genome assemblies for the 20 query organisms (FASTA, gzip-compressed)
`query_info.tsv`	Metadata (taxon and accession) for 20 query taxa selected with controlled novelty
`query_mixture.fq.gz`	100,000 Illumina reads simulated from the query genomes (FASTQ, gzip-compressed)
`profile.tsv`	Taxonomic profile of the mock community across taxa (77 lines)