MambaSV Docker Usage

MambaSV is a long-read structural variant (SV) caller for PacBio HiFi and Oxford Nanopore R10 sequencing data. The Docker interface supports two workflows:

• germline calling from one sample BAM
• somatic calling from matched normal/tumor BAMs.

Each workflow runs Mamba-based deep learning breakpoint prediction with bundled checkpoints, converts predictions to VCF records, then applies read-evidence post-filtering. Somatic mode adds an additional matched-sample filtering step.

MambaSV v0.1.2 is a GA release intended for research and development use.

Release image:

nvcr.io/nvidia/clara/clara-parabricks-mambasv:v0.1.2

The v0.1.2 image supports Linux amd64 hosts and NVIDIA Ampere, Ada, Hopper, and Blackwell GPUs. Use a host NVIDIA driver that supports CUDA 12.8.

The image includes CUDA 12.8.1, CPython 3.14 ABI, PyTorch 2.11.0+cu128, Triton 3.6.0, mamba-ssm 2.2.6.post3, and causal-conv1d 1.6.2.post1.

Pull the public image without signing in to NGC:

docker pull nvcr.io/nvidia/clara/clara-parabricks-mambasv:v0.1.2

Requirements

• NVIDIA GPU with a CUDA 12.8-compatible driver.
• Linux amd64 host. ARM64 is not included in v0.1.2.
• Docker with NVIDIA Container Toolkit.
• Coordinate-sorted, haplotype-tagged long-read BAM inputs with .bai indexes.
• Reference FASTA with .fai index.
• Matching contig names between the BAM header and reference FASTA, such as chr1 versus 1.
• A writable output directory mounted into the container.
• GPU sorting is not supported in this image; do not pass --gpusort.

Supported read types:

• --read_type pb: PacBio HiFi.
• --read_type ont: Oxford Nanopore R10.

Smoke Test

Run the included small PacBio HiFi example first to confirm that Docker, GPU access, MambaSV, and somatic filtering work on your system. The example contains a normal BAM with reference-like reads and a tumor BAM with deletion-supporting reads, so it produces at least one somatic call. It is a system check, not a biological validation.

mkdir -p mambasv_smoke_output

docker run --rm \
  --gpus device=0 \
  --ipc=host \
  --user "$(id -u):$(id -g)" \
  -v "$PWD/mambasv_smoke_output:/output" \
  nvcr.io/nvidia/clara/clara-parabricks-mambasv:v0.1.2 \
  mambasv somatic \
    --read_type pb \
    --ref /opt/mambasv/examples/smoke_test/small_ref.fa \
    --bam_normal /opt/mambasv/examples/smoke_test/small_normal.bam \
    --bam_tumor /opt/mambasv/examples/smoke_test/small_tumor.bam \
    --output_dir /output/mambasv \
    --chroms chr1 \
    --num_processes 1 \
    --num_dataloader_workers 0 \
    --batch_size 1

Expected final outputs:

mambasv_smoke_output/mambasv/mambasv.germline.vcf
mambasv_smoke_output/mambasv/mambasv.somatic.vcf

This smoke test is only intended to validate the container and runtime setup. Use your own sorted, indexed, haplotype-tagged normal and tumor BAMs for biological analysis.

Input BAM Assumptions

MambaSV expects long-read BAMs that are ready for indexed regional queries:

• BAMs must be coordinate-sorted and indexed. The index may be either sample.bam.bai or sample.bai.
• BAMs must be haplotype-tagged with HP tags.
• PacBio runs should use HiFi reads with --read_type pb.
• ONT runs should use R10 reads with --read_type ont.
• The reference FASTA must be indexed with samtools faidx, producing reference.fa.fai.
• Reference contig names must match BAM contig names exactly.

Default BAM Realignment

mambasv germline runs consensus-guided BAM realignment before inference by default. mambasv somatic uses the input BAMs directly by default.

Refined BAMs are written under _refined_bam/ using the input BAM basename:

/data/a.b.c.d.bam -> /output/mambasv/_refined_bam/a.b.c.d.mambasv_refined.bam

When refinement is enabled, MambaSV automatically uses the refined BAMs for inference and filtering. To use the input BAM directly for germline, pass --skip_bam_refinement or set bam_refinement.skip_bam_refinement = true in the config file. To enable paired refinement for somatic calling, set bam_refinement.skip_bam_refinement = false in a config file.

Germline Calling

docker run --rm \
  --gpus device=0 \
  --ipc=host \
  --user "$(id -u):$(id -g)" \
  -v /path/to/data:/data:ro \
  -v /path/to/output:/output \
  nvcr.io/nvidia/clara/clara-parabricks-mambasv:v0.1.2 \
  mambasv germline \
    --read_type pb \
    --ref /data/reference.fa \
    --bam /data/sample.bam \
    --output_dir /output/mambasv

Use --read_type ont for ONT R10 data.

Final germline outputs:

/output/mambasv/_refined_bam/sample.mambasv_refined.bam
/output/mambasv/_refined_bam/sample.mambasv_refined.bam.bai
/output/mambasv/mambasv.germline.vcf
/output/mambasv/log.txt
/output/mambasv/inference_args.json

The raw germline VCF is retained at /output/mambasv/_intermediate/germline.vcf.

Somatic Calling

docker run --rm \
  --gpus device=0 \
  --ipc=host \
  --user "$(id -u):$(id -g)" \
  -v /path/to/data:/data:ro \
  -v /path/to/output:/output \
  nvcr.io/nvidia/clara/clara-parabricks-mambasv:v0.1.2 \
  mambasv somatic \
    --read_type pb \
    --ref /data/reference.fa \
    --bam_normal /data/normal.bam \
    --bam_tumor /data/tumor.bam \
    --output_dir /output/mambasv

Use --read_type ont for ONT R10 data.

Final somatic outputs:

/output/mambasv/mambasv.germline.vcf
/output/mambasv/mambasv.somatic.vcf
/output/mambasv/log.txt
/output/mambasv/inference_args.json

Raw and first-pass VCFs are retained under /output/mambasv/_intermediate/.

Final Outputs

Use the mambasv.*.vcf files for downstream analysis.

Every successful MambaSV run also writes:

Intermediate VCFs are moved under _intermediate/ after filtering. Germline runs retain _intermediate/germline.vcf. Somatic runs retain _intermediate/germline.vcf, _intermediate/somatic.vcf, _intermediate/all.vcf, and _intermediate/somatic_filtered.vcf when those files are produced.

Validated BND adjacencies are emitted as reciprocal records linked by MATEID and EVENT. Intrachromosomal BND records use SVLEN=abs(posA-posB); interchromosomal BND records omit SVLEN.

Workflow Status Lines

MambaSV writes lifecycle lines to both stdout and log.txt. Each line identifies a workflow stage and one of STARTED, COMPLETED, SKIPPED, or FAILED.

[MambaSV][stage=workflow][status=STARTED] mode=somatic read_type=pb output_dir=/output/mambasv
[MambaSV][stage=bam_refinement][status=SKIPPED] reason='using input BAMs directly'
[MambaSV][stage=inference][status=STARTED]
[MambaSV][stage=inference][status=COMPLETED] elapsed_seconds=29.400
[MambaSV][stage=finalize][status=COMPLETED] elapsed_seconds=0.002
[MambaSV][stage=workflow][status=COMPLETED] elapsed_seconds=35.100

Somatic workflows also report postfilter and somatic_postfilter; germline workflows report postfilter. A failed stage writes status=FAILED with available diagnostic information. Detailed progress information is available under _logs/.

Input Validation

Before starting BAM refinement or inference, MambaSV validates:

• command-line enums and numeric values,
• TOML syntax, section/key names, value types, ranges, and supported enum values,
• conflicting options and inconsistent GPU rank/device settings,
• readable FASTA/BAM inputs and their required indexes,
• requested contigs against the reference .fai, and
• optional BED and model override paths.

Invalid input exits nonzero with a concise mambasv: error: diagnostic. Configuration typos include a suggestion when a close supported name exists.

mambasv: error: invalid TOML in /input/malformed.toml: Invalid value (at end of document)
mambasv: error: config /input/run.toml: unknown config key inference.batch_szie; did you mean batch_size?
mambasv: error: Missing required input or index: --ref /missing/ref.fa, /missing/ref.fa.fai

--dry_run validates the effective configuration and command relationships while allowing the main FASTA/BAM paths to remain unavailable. A normal run additionally validates those input files, indexes, and requested contigs before creating the output directory or starting compute.

Common Options

• --skip_bam_refinement: use the input BAMs directly instead of running BAM realignment. This is already the default for somatic calls.
• --gpusort: not supported in v0.1.2. Use the default sorting behavior.
• --chroms chr1,chr2,chr3: limit the run to selected chromosomes.
• --nproc_per_node 2: run inference with two GPU ranks inside the container.
• --cuda_visible_devices 0,1: set CUDA-visible device ordinals inside the container.
• --num_processes 32: override CPU workers for conversion/filtering steps.
• --batch_size 8: override inference batch size when GPU memory is constrained.
• --bnd_validation_min_support 3: set the minimum inference-time BND/INV support required to emit a validated call.

Example multi-GPU run:

docker run --rm \
  --gpus '"device=0,1"' \
  --ipc=host \
  --user "$(id -u):$(id -g)" \
  -v /path/to/data:/data:ro \
  -v /path/to/output:/output \
  nvcr.io/nvidia/clara/clara-parabricks-mambasv:v0.1.2 \
  mambasv germline \
    --read_type pb \
    --ref /data/reference.fa \
    --bam /data/sample.bam \
    --output_dir /output/mambasv \
    --nproc_per_node 2 \
    --cuda_visible_devices 0,1

Config File

MambaSV provides its supported user-configurable settings in a TOML template.

Use a config file when you need to tune resources, restrict regions, override bundled checkpoints, control BAM realignment, or have fine-grained control of model behavior. Common examples include GPU/CPU worker counts, BAM realignment threads, batch size, chromosome lists, BED target regions, max reads per window, read-evidence thresholds, and somatic filtering thresholds.

Set postfilter.debug = true only when you need per-SV post-filter diagnostics such as polished tandem-duplication span messages; normal runs keep those lines off to keep log.txt readable.

To generate the editable template:

docker run --rm nvcr.io/nvidia/clara/clara-parabricks-mambasv:v0.1.2 mambasv config-template > mambasv_defaults.toml

Edit mambasv_defaults.toml, then mount and pass it:

docker run --rm \
  --gpus device=0 \
  --ipc=host \
  --user "$(id -u):$(id -g)" \
  -v /path/to/data:/data:ro \
  -v /path/to/output:/output \
  -v "$PWD/mambasv_defaults.toml:/config/mambasv_defaults.toml:ro" \
  nvcr.io/nvidia/clara/clara-parabricks-mambasv:v0.1.2 \
  mambasv germline \
    --config /config/mambasv_defaults.toml \
    --read_type pb \
    --ref /data/reference.fa \
    --bam /data/sample.bam \
    --output_dir /output/mambasv

Explicit CLI options override values in the config file. The generated template includes comments for each visible setting; leave fields unchanged unless you have a reason to tune that part of the workflow. The final effective settings for each run are saved to inference_args.json in the output directory.

Troubleshooting

• Missing reference index: create /data/reference.fa.fai with samtools faidx reference.fa.
• Missing BAM index: create /data/sample.bam.bai with samtools index sample.bam.
• Permission errors: make sure the mounted output directory is writable by the container user, or run Docker with an appropriate --user value.
• Port conflicts: pass a different --master_port.
• Failed or incomplete runs: start with top-level log.txt, then inspect _logs/inference_status.txt and _logs/inference_progress.tsv for inference-stage details. If a run fails before final output organization, partial VCFs may still be in the output root.
• GPU selection: Docker maps selected host GPUs to container ordinals. With --gpus device=1, the visible GPU inside the container is usually ordinal 0.

Get Help

For questions, bug reports, or other MambaSV support requests, please use the Parabricks developer forum.

License/Terms of Use

By pulling and using the Parabricks MambaSV container, you accept the governing terms: The software and materials are governed by the NVIDIA Software License Agreement (found at https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-software-license-agreement/) and the Product-Specific Terms for NVIDIA AI Products (found at https://www.nvidia.com/en-us/agreements/enterprise-software/product-specific-terms-for-ai-products/); except for the model which is governed by the NVIDIA Models Community License Agreement(found at NVIDIA Community Model License). ADDITIONAL INFORMATION: Apache 2.0.