Skip to content

Getting Started with miint

miint is a DuckDB extension for bioinformatics. It lets you read, analyze, and write common bioinformatics file formats using SQL — or from Python, R, and the command line. If you have never used SQL before, don't worry: the beginner tutorial walks you through everything using Python and Jupyter notebooks.

What you'll learn

These tutorials follow a single question through three levels of complexity:

Does my sample contain Escherichia coli, and how confidently can I tell?

Starting from a raw FASTQ file, you will read and explore the sequences, align them against the E. coli K-12 reference genome, and learn how to separate real signal from alignment noise. Each tutorial uses the same public dataset — an amplicon sequencing run from the American Gut Project (McDonald et al., 2018), part of the Earth Microbiome Project (Thompson et al., 2017) — and builds on the ideas introduced in the previous one.

Tutorial Interface You'll learn to...
Beginner Python / Jupyter Read sequences, explore quality, export to Parquet
Intermediate DuckDB CLI Align reads, filter by quality metrics, count taxa
Advanced Bash + SQL Batch-process samples, compute coverage depth, extend miint

Installation

Install DuckDB

DuckDB is available for many languages and platforms — see the DuckDB installation page for the full list. These tutorials use the Python client and the command-line interface; installation instructions for each are below.

Python library (for the beginner tutorial):

pip install duckdb pyarrow pandas matplotlib           # pip
uv pip install duckdb pyarrow pandas matplotlib        # or uv
conda install -c conda-forge python-duckdb pyarrow pandas matplotlib  # or conda

Command-line interface (for the intermediate and advanced tutorials):

pip install duckdb-cli               # pip
uv pip install duckdb-cli            # or uv
conda install -c conda-forge duckdb-cli  # or conda

Install miint

miint is published in the DuckDB Community Extensions repository. No compilation required — DuckDB will download and verify the extension automatically:

INSTALL miint FROM community;
LOAD miint;

For building from source or other installation methods, see the installation guide.

The dataset

All tutorials use the same publicly available FASTQ file from the American Gut Project:

Field Value
Run accession ERR1074767
Project American Gut Project / Earth Microbiome Project
Region 16S rRNA gene, V4 hypervariable region
Read count 20,939
Read length 151 bp
Platform Illumina

The file is hosted by the European Nucleotide Archive and can be read directly over HTTPS — no download step needed.

References and citations

These tutorials rely on several open-source tools and public datasets. Please cite them if you use miint in published work.

  • DuckDB — Raasveldt, M. & Mühleisen, H. (2019). DuckDB: an embeddable analytical database. SIGMOD 2019. duckdb.org

  • minimap2 — Li, H. (2018). Minimap2: pairwise alignment for nucleotide sequences. Bioinformatics, 34(18), 3094–3100. doi:10.1093/bioinformatics/bty191

  • Woltka — Zhu, Q. et al. (2022). Phylogeny-aware analysis of metagenome community ecology based on matched reference genomes while leveraging phylogeny. mSystems, 7(2). doi:10.1128/msystems.00167-22

  • HTSlib — Bonfield, J.K. et al. (2021). HTSlib: C library for reading/writing high-throughput sequencing data. GigaScience, 10(2). doi:10.1093/gigascience/giab007

  • WFA2-lib — Marco-Sola, S. et al. (2023). Optimal gap-affine alignment in O(s) space. Bioinformatics, 39(2). doi:10.1093/bioinformatics/btad074

  • American Gut Project — McDonald, D. et al. (2018). American Gut: an open platform for citizen science microbiome research. mSystems, 3(3). doi:10.1128/mSystems.00031-18

  • Earth Microbiome Project — Thompson, L.R. et al. (2017). A communal catalogue reveals Earth's multiscale microbial diversity. Nature, 551(7681), 457–463. doi:10.1038/nature24621

  • Escherichia coli K-12 MG1655 genome — Blattner, F.R. et al. (1997). The complete genome sequence of Escherichia coli K-12. Science, 277(5331), 1453–1462. doi:10.1126/science.277.5331.1453