Installing ChoCallate

Installing ChoCallate

ChoCallate is tested on Linux; macOS and Windows are not currently tested. The recommended installation uses Conda or Mamba. A Docker image is also available.

Requirements

• Linux
• Conda (Miniconda/Anaconda) or Mamba
• Git
• Nextflow >=26.04.6 (installed by environment.yaml)

Nextflow resolves the nf-boost and nf-schema plugins on first use. For an offline Conda installation, install the pinned versions once on a connected machine with nextflow plugin install nf-schema@3.0.0 and nextflow plugin install nf-boost@0.8.0.

Install with Conda

git clone --depth 1 https://github.com/alermol/ChoCallate.git
cd ChoCallate
conda env create -y -f environment.yaml --no-default-packages
conda activate ChoCallate

Optionally build the Cython accelerator for bin/generate_consensus.py. The Docker image builds it automatically; without it, the consensus step falls back to an equivalent pure-pysam implementation.

python bin/build_consensus_accel.py

Verify the installation

The bundled test_run data provides a small end-to-end run:

cd test_run
bash run_test.sh
bash cleanup.sh

For the full test and lint commands, see Testing and CI.

Use the Docker container

The image installs the pipeline under /opt/chocallate, bundles the nf-schema and nf-boost plugins for offline runs, and provides a writable HOME so it works with Docker, Apptainer and Singularity under an arbitrary UID.

1. Install Docker using the official instructions.

2. Pull the latest image:

docker pull alermol/chocallate:latest

3. Prepare a working directory. Paths inside the container must match the config.yaml and samples.tsv entries; the default working directory is /workspace.

input_data
├── reads
│   ├── sample1_F.fq
│   ├── sample1_R.fq
│   ├── sample2_F.fq
│   └── sample2_R.fq
├── samples.tsv
├── config.yaml
├── include.bed
├── exclude.bed
├── genome_assembly.fna
└── genome_assembly.fna.mmi

Example config.yaml paths:

input:
  samples_tsv: /workspace/samples.tsv
  reference_genome: /workspace/genome_assembly.fna
  reference_index_dir: /workspace
  include_bed: /workspace/include.bed
  exclude_bed: /workspace/exclude.bed

mapping:
  mapper: "minimap2"

output:
  directory: /workspace/ChoCallate_output

The example directory contains a Minimap2 .mmi index, so the configuration selects minimap2. For the default bowtie2 mapper, provide the six .bt2 index files instead.

Example samples.tsv (tab-separated):

sample1	/workspace/reads/sample1_F.fq	/workspace/reads/sample1_R.fq
sample2	/workspace/reads/sample2_F.fq	/workspace/reads/sample2_R.fq

4. Run ChoCallate:

docker run --rm \
  -u "$(id -u):$(id -g)" \
  -v "${PWD}/input_data:/workspace" \
  -w /workspace \
  alermol/chocallate:latest \
  -params-file config.yaml

The image bundles its plugins, so --network none can be added for an offline run.

5. Results are written to output.directory (ChoCallate_output by default).

input_data
├── ChoCallate_output
│   ├── consensus.bcf
│   ├── mapping_stats/
│   ├── dropped_samples.txt
│   ├── pipeline_report.html
│   ├── timeline_report.html
│   └── trace.txt
├── reads
├── samples.tsv
├── config.yaml
├── include.bed
├── exclude.bed
├── genome_assembly.fna
└── genome_assembly.fna.mmi

Next steps

• Pipeline overview and inputs and reference.
• Configure the run with the CLI reference.
• See Output structure for output files and annotations.
• See Operations and troubleshooting for resources and common errors.
• See Merge strategies and testing for multi-sample merge details.