BASALT is a metagenomic workflow for recovering and refining metagenome-assembled genomes (MAGs) across one or more assemblies. It combines multi-binner candidate generation, within- and between-assembly bin selection, contig-level contamination screening, contig retrieval, and reassembly in one checkpointed pipeline.
Important
New: BASALT-Air v1.0.0 is now available. BASALT-Air is the newer Pixi-based implementation for users who need absolute input paths, separate working and output directories, reproducible run manifests, and built-in dependency checks. Its executable is lowercase basalt, and its CLI and checkpoints are not interchangeable with the Conda-based BASALT documented in this repository.
The published evaluation reports improved MAG recovery and downstream genome-resolved analyses relative to the tested workflows and datasets. These results define the evidence boundary: performance depends on community complexity, sequencing depth, assembly quality, read type, and the selected parameters. See the Nature Communications article for the complete experimental design.
BASALT can jointly evaluate sample-specific assemblies and a biologically matched co-assembly. Individual assemblies preserve sample-restricted populations while avoiding some pooling complexity; co-assembly can increase effective depth for shared, low-abundance genomes. Across related samples, concordant coverage changes provide an abundance fingerprint that complements tetranucleotide composition and sequence overlap during bin selection, dereplication, contig screening, retrieval, and reassembly. This design is especially useful for longitudinal, reactor time-series, nearby-site, extraction-method, intervention, growth-stage, and environmental-gradient studies. Validate it in a pilot; it is not a reason to combine unrelated samples. See Study design patterns.
The BASALT guide is the source of truth for installation, inputs, commands, outputs, troubleshooting, and reproducible reporting. Its editable sources are under BASALT_Guide/docs/.
- Installation
- BASALT-Air: the new implementation
- Quick start
- Input formats
- Study design patterns
- Command-line reference
- Tutorial
- Reproducibility and reporting
| Goal | Recommended route | Read first |
|---|---|---|
| Start a new deployment with modern path and environment handling | BASALT-Air v1.0.0 | BASALT-Air overview |
| Reproduce or resume an existing Conda BASALT analysis | This BASALT repository | Installation |
| First successful run | One assembly and one matched paired-end sample | Quick start |
| Compare individual and pooled assemblies | Run a biologically coherent multi-assembly pilot | Study design patterns |
| Recover candidates with lower compute demand | --sensitive quick --refinepara quick |
Command-line reference |
| Expand the candidate pool | --sensitive sensitive or more-sensitive; optionally add a validated binner |
Extra binners |
| Import bins from another workflow | Data feeding, then optional dereplication and refinement | External-binset workflow |
| Resume an interrupted run | BASALT --mode continue in the unchanged run directory |
Resume semantics |
| Capability | BASALT in this repository | BASALT-Air v1.0.0 |
|---|---|---|
| Environment | Conda plus external installation steps | Pixi environment and lock file |
| Command | BASALT |
basalt |
| Input paths | Dedicated run directory and local names recommended | First-class absolute paths |
| Work and output locations | Intermediates in the current directory | Separate --workdir and --outdir |
| Run provenance | Command, logs, and checkpoint files | Adds a structured run manifest and timestamped logs |
| Best suited to | Existing BASALT analyses and checkpoint reproduction | New deployments needing clearer path and environment isolation |
See the BASALT-Air repository for its authoritative installation and command reference.
- Autobinning. BASALT runs MetaBAT 2 and SemiBin 2 across parameter settings. The
sensitiveandmore-sensitivepresets add CONCOCT, andmore-sensitivealso adds MaxBin 2.0. - Bin selection. Candidate bins are compared within each assembly and then across assemblies to reduce redundancy.
- Refinement. A five-model multilayer-perceptron ensemble screens contigs using sequence-composition and coverage-derived features. Read connectivity is then used to retrieve candidate contigs.
- Reassembly. BASALT can reassemble and polish selected bins when the required read types are available.
Optional adapters support MetaBinner (-e m), VAMB (-e v), and LorBin (-e l). Their installation and input requirements are documented separately in the extra-binner guide.
The LorBin adapter is maintained against PKU-EMBL/LorBin-BASALT-Extrabinner, an in-house fork that adapts LorBin to the BASALT Python 3.12 environment and carries BASALT-specific runtime fixes. Record the fork's Git commit for every analysis that uses -e l; the package version alone does not uniquely identify these changes.
| Preset | Candidate generators | Practical trade-off |
|---|---|---|
quick |
MetaBAT 2 and SemiBin 2 | Lower compute demand and fewer candidate sets |
sensitive |
MetaBAT 2, CONCOCT, and SemiBin 2 | Default balance of candidate diversity and runtime |
more-sensitive |
MaxBin 2.0, MetaBAT 2, CONCOCT, and SemiBin 2 | Higher compute and storage demand; not guaranteed to recover more acceptable MAGs |
Every run requires at least one assembly and at least one source of read coverage. BASALT accepts the following designs:
| Design | Assembly | Short reads | ONT or PacBio CLR | PacBio HiFi |
|---|---|---|---|---|
| Short-read only | required | required | no | no |
| Long-read only | required | no | required | no |
| HiFi only | required | no | no | required |
| Short reads + ONT or CLR | required | required | required | no |
| Short reads + HiFi | required | required | no | required |
Input paths are resolved from the working directory. Use filenames or relative paths without shell metacharacters; for the most reliable execution, place or symlink inputs into a dedicated run directory. Paired-end files within a sample are separated by a comma, and multiple short-read samples are separated by /.
For replicate or longitudinal studies, decide the biological strata before assembling or pooling. BASALT can compare sample-specific and matched pooled assemblies, but it cannot infer whether a pool erased a time, treatment, host, or habitat contrast. The study-design guide provides concrete layouts and a minimum design manifest.
- Linux x86-64
- Python 3.12
- 8 CPU threads and 128 GB RAM as a practical starting point
- 32 or more threads and 256 GB RAM for larger or more complex datasets
- Sufficient temporary storage for mapping, binning, and reassembly intermediates
Resource use is dataset-dependent. Run a pilot or request more memory for large assemblies, many samples, or more-sensitive mode.
The Conda-compatible installation below is the maintained route for this repository. Micromamba is recommended for faster dependency solving and parallel package downloads; current Conda with the libmamba solver is also supported. See the installation guide for databases, model weights, mainland-China mirrors, verification, and container execution notes.
git clone --branch V1.2.2 --depth 1 \
https://github.com/PKU-EMBL/BASALT.git BASALT
cd BASALT
micromamba create -n basalt -f basalt_environment.yml \
--strict-channel-priority --yes
micromamba run -n basalt bash install.shThe release tag makes this installation reproducible instead of following a moving master branch. Clone master without --branch V1.2.2 only for development.
Run the installer with bash install.sh; the source file does not need to be executable. The installer assigns mode 0755 only to installed Python and Perl scripts and the generated BASALT launcher. The platform-compatible jgi_summarize_bam_contig_depths executable is supplied by the maintained MetaBAT 2 package and is validated during installation; BASALT no longer ships a stale Linux binary. Do not use sudo, chmod 777, or chmod -R 777 on the repository or environment. If installation reports a permission error, use a user-owned Conda/Micromamba environment and follow the permission troubleshooting guide.
Activate the environment before using the unprefixed commands shown later in this README:
eval "$(micromamba shell hook --shell bash)"
micromamba activate basalt
# Conda alternative: conda activate basaltIf shell activation is undesirable, prefix each command with micromamba run -n basalt, for example micromamba run -n basalt BASALT --help. Conda users can create the environment with CONDA_CHANNEL_PRIORITY=strict conda env create -n basalt -f basalt_environment.yml --solver libmamba --yes and replace micromamba run with conda run. basalt_environment.yml is the sole environment definition. It uses the portable conda-forge and bioconda channel names and resolves the complete base stack in one Conda transaction; it does not hard-code a site mirror.
As an alternative to the manual environment commands above, mainland-China users can run the network-aware installer. It probes TUNA, BFSU, USTC, and upstream endpoints, prefers micromamba, applies matching Conda and PyPI mirrors only to the installation subprocess, and leaves ~/.condarc and pip configuration unchanged:
python3 BASALT_setup_China_mainland.py \
--manager micromamba \
--bootstrap-micromamba \
--mirror auto \
--model-dir /absolute/persistent/path/BASALT_WEIGHTUse --dry-run to inspect all commands first, --mirror tuna|bfsu|ustc|upstream to pin a route, or --update to synchronize an existing environment. When this installer completes the model step successfully, do not download the same weights again; continue with validation and the shell configuration below.
Download the trained BASALT models into a persistent directory and verify them before configuring the shell. The downloader validates all five ensemble descriptors and every checkpoint they reference:
micromamba run -n basalt BASALT_models_download.py \
--source auto \
--path /absolute/persistent/path/BASALT_WEIGHT
find /absolute/persistent/path/BASALT_WEIGHT \
-maxdepth 1 -name '*_ensemble.csv' | wc -lThe expected count is 5. Inspect ~/.bashrc before adding the validated path for future login and batch shells:
grep -n '^export BASALT_WEIGHT=' ~/.bashrc || true
# If no current definition was printed, append one:
printf '%s\n' \
'export BASALT_WEIGHT="/absolute/persistent/path/BASALT_WEIGHT"' \
>> ~/.bashrc
source ~/.bashrc
test -d "$BASALT_WEIGHT"If grep found an existing definition, edit that line instead of appending another one. Keep exactly one authoritative BASALT_WEIGHT export.
Automatic mode performs a bounded reachability check, downloads concurrently from the official PKU-EMBL/BASALT_WEIGHT repository first, and falls back to the legacy Figshare archive when Hugging Face is unreachable. Adjust the check with --hf-timeout SECONDS. A local ZIP, a custom URL, and the documented Baidu Netdisk route are available when either service is unsuitable.
The downloader pins the release model revision by default. If a site-approved Hugging Face-compatible endpoint is required, pass --hf-endpoint URL; record the selected revision and hash the downloaded files for the analysis record.
Set the CheckM2 database path if it is not already configured by your environment:
checkm2 database --download
checkm2 database --currentOnly when automatic discovery is unavailable:
export CHECKM2DB=/absolute/path/to/CheckM2_database/uniref100.KO.1.dmndIf the export is required across logins, keep one validated absolute definition in ~/.bashrc, following the same duplicate-check and scheduler precautions used for BASALT_WEIGHT.
Verify the command and external tools before a production run:
BASALT --help
command -v \
checkm2 metabat2 jgi_summarize_bam_contig_depths SemiBin2 \
bowtie2 samtools spades.pyCreate a clean working directory and link the inputs into it:
mkdir -p basalt_run
cd basalt_run
ln -s /absolute/path/assembly.fasta .
ln -s /absolute/path/sample_R1.fastq .
ln -s /absolute/path/sample_R2.fastq .Run the full short-read workflow:
BASALT \
-a assembly.fasta \
-s sample_R1.fastq,sample_R2.fastq \
-t 32 \
-m 128 \
--mode new \
-o study_basaltThe final MAGs and final CheckM2 report are written under study_basalt/. Intermediate files, BASALT_command.txt, Basalt_log.txt, and Basalt_checkpoint.txt remain in the working directory.
To resume an interrupted run from that same directory:
BASALT --mode continueDo not combine files from different runs in one working directory. --mode new initializes checkpoint state, but it does not provide complete cleanup or provenance isolation.
Short reads across two assemblies and two samples:
BASALT \
-a assembly_1.fasta,assembly_2.fasta \
-s sample_1_R1.fastq,sample_1_R2.fastq/sample_2_R1.fastq,sample_2_R2.fastq \
-t 64 -m 256 --mode new -o study_basaltShort reads plus ONT or PacBio CLR reads:
BASALT \
-a assembly.fasta \
-s sample_R1.fastq,sample_R2.fastq \
-l nanopore.fastq \
-t 64 -m 256 --mode new -o study_basaltPacBio HiFi reads:
BASALT \
-a assembly.fasta \
-hf hifi.fastq \
-t 32 -m 128 --mode new -o study_basaltFaster candidate generation and refinement:
BASALT \
-a assembly.fasta \
-s sample_R1.fastq,sample_R2.fastq \
--sensitive quick --refinepara quick \
-t 32 -m 128 --mode new -o study_basaltSee the command-line reference before using standalone refinement, data feeding, dereplication, or module-specific execution. These routes require intermediate files from a compatible BASALT run.
For the default CheckM2 route, -o NAME produces the final directory NAME/; without -o, the default is Final_binset/. A scientifically complete result should contain non-empty bin FASTA files and a matching quality report, while the working directory should retain BASALT_command.txt, Basalt_log.txt, and Basalt_checkpoint.txt.
Directory names such as BestBinset, refined, or MAGs describe workflow state, not publication-ready quality. Apply explicit completeness, contamination, taxonomy, contiguity, read-support, and dereplication criteria. See Outputs and quality control.
For each analysis, archive:
- the exact BASALT command and BASALT Git commit or release;
- the Conda environment export and versions of external executables;
- CheckM or CheckM2 database identity and quality thresholds;
- input assembly and read checksums;
BASALT_command.txt,Basalt_log.txt, andBasalt_checkpoint.txt;- the final quality report and all exclusions applied after BASALT.
The reporting guide provides a Methods template and a minimum reporting checklist.
If BASALT contributes to an analysis, cite:
Qiu, Z., Yuan, L., Lian, C.-A. et al. BASALT refines binning from metagenomic data and increases resolution of genome-resolved metagenomic analysis. Nature Communications 15, 2179 (2024). https://doi.org/10.1038/s41467-024-46539-7
@article{qiu2024basalt,
author = {Qiu, Zhiguang and Yuan, Li and Lian, Chun-Ang and Lin, Bin and
Chen, Jie and Mu, Rong and Qiao, Xuejiao and Zhang, Liyu and
Xu, Zheng and Fan, Lu and Zhang, Yunzeng and Wang, Shanquan and
Li, Junyi and Cao, Huiluo and Li, Bing and Chen, Baowei and
Song, Chi and Liu, Yongxin and Shi, Lili and Tian, Yonghong and
Ni, Jinren and Zhang, Tong and Zhou, Jizhong and Zhuang, Wei-Qin and
Yu, Ke},
title = {BASALT refines binning from metagenomic data and increases resolution of genome-resolved metagenomic analysis},
journal = {Nature Communications},
volume = {15},
pages = {2179},
year = {2024},
doi = {10.1038/s41467-024-46539-7}
}If an optional binner materially contributes to the reported analysis, cite that software and record its version and parameters.
Report reproducible bugs through GitHub Issues. Include the command, log, checkpoint, software versions, database configuration, and the smallest shareable input that reproduces the problem.
Scientific or collaboration enquiries:
- Ke Yu: yuke.sz@pku.edu.cn
- Zhaorui (Elijah) Jiang: zrjiang25@stu.pku.edu.cn
BASALT is released under the MIT License.