nanomonsv

Introduction

nanomonsv is a software for detecting somatic structural variations from paired (tumor and matched control) cancer genome sequence data. nanomonsv is presented in the following paper. When you use nanomonsv or any resource of this repository, please kindly cite this paper.

Precise characterization of somatic complex structural variations from tumor/control paired long-read sequencing data with nanomonsv, Shiraishi et al., Nucleic Acids Research, 2023, [link].

Key features:

• Single-nucleotide breakpoint resolution using consensus sequences from long-read alignments.
• LINE1 insertion classification: Distinguishes Solo L1, Partnered L1 (transduction), and Orphan L1 (orphan transduction), and identifies source L1 elements.
• Two detection modules: Canonical SV module for standard SVs with high precision and recall, and Single breakend SV module for complex SVs involving highly-repetitive sequences (centromeres, LINE1, viruses) that can only be identified by long-reads.
• Haplotype-aware (v0.9.0+): Reports per-haplotype supporting read counts (HP1, HP2, unphased) using phasing information from the input BAM file. This enables phasing of SV breakpoints.

Installation

pip install nanomonsv

You can also install via conda (bioconda channel). Occasionally the conda releases lag behind PyPI.

conda create -n nanomonsv -c conda-forge -c bioconda nanomonsv

Dependencies

Python >=3.9, pysam, numpy, parasail

Input requirements

• BAM or CRAM file aligned by minimap2
• For CRAM files, specify --reference_fasta
• S3 paths (e.g., s3://bucket/path.bam) are supported via pip install nanomonsv[s3]. Note that network latency may significantly slow down processing compared to local files.

Quick Start

1. Prepare the reference genome (here, GDC GRCh38 reference genome).

wget https://api.gdc.cancer.gov/data/254f697d-310d-4d7d-a27b-27fbf767a834 -O GRCh38.d1.vd1.fa.tar.gz
tar xvf GRCh38.d1.vd1.fa.tar.gz

2. (Optional but highly recommended) Download a control panel from zenodo. See Control Panel for available panels and how to choose.

wget https://zenodo.org/api/records/11470934/files/1kg-ont-vienna_hg38_no_singleton.tar.gz/content \
    -O 1kg-ont-vienna_hg38_no_singleton.tar.gz
tar xvf 1kg-ont-vienna_hg38_no_singleton.tar.gz

3. (Optional but highly recommended) Download a simple repeat BED file. Pre-built files for GRCh38 and CHM13 are included in this repository under resource/simple_repeats.

4. Parse putative SV supporting reads.

nanomonsv parse tumor.bam output/tumor
nanomonsv parse ctrl.bam output/ctrl

5. Get the final result.

nanomonsv get output/tumor tumor.bam GRCh38.d1.vd1.fa \
    --control_prefix output/ctrl --control_bam ctrl.bam \
    --control_panel_prefix 1kg-ont-vienna_hg38_no_singleton \
    --simple_repeat_bed resource/simple_repeats/human_GRCh38_simpleRepeat.bed.gz

You will find the result file tumor.nanomonsv.result.txt.

Usage

parse

Parses all supporting reads of putative somatic SVs.

nanomonsv parse [-h] [--reference_fasta reference.fa] [--debug]
                [--split_alignment_check_margin SPLIT_ALIGNMENT_CHECK_MARGIN]
                [--minimum_breakpoint_ambiguity MINIMUM_BREAKPOINT_AMBIGUITY]
                alignment_file output_prefix

• alignment_file: Path to input indexed BAM or CRAM file
• output_prefix: Output file prefix
• --reference_fasta: Path to reference genome (recommended for CRAM files)

After successful completion, you will find: {output_prefix}.deletion.sorted.bed.gz, {output_prefix}.insertion.sorted.bed.gz, {output_prefix}.rearrangement.sorted.bedpe.gz, {output_prefix}.bp_info.sorted.bed.gz and their indexes (.tbi files).

get

Gets the SV result from parsed supporting reads.

nanomonsv get [-h] [--control_prefix CONTROL_PREFIX]
              [--control_bam CONTROL_BAM]
              [--control_panel_prefix CONTROL_PANEL_PREFIX]
              [--simple_repeat_bed SIMPLE_REPEAT_BED]
              [--min_tumor_variant_read_num MIN_TUMOR_VARIANT_READ_NUM]
              [--min_tumor_VAF MIN_TUMOR_VAF]
              [--max_control_variant_read_num MAX_CONTROL_VARIANT_READ_NUM]
              [--max_control_VAF MAX_CONTROL_VAF]
              [--cluster_margin_size CLUSTER_MARGIN_SIZE]
              [--median_mapQ_thres MEDIAN_MAPQ_THRES]
              [--max_overhang_size_thres MAX_OVERHANG_SIZE_THRES]
              [--var_read_min_mapq VAR_READ_MIN_MAPQ]
              [--qv10] [--qv15] [--qv20] [--qv25] [--use_mafft]
              [--no_single_bnd] [--processes PROCESSES]
              [--sort_option SORT_OPTION] [--max_memory_minimap2] [--debug]
              tumor_prefix tumor_bam reference.fa

• tumor_prefix: Prefix to the tumor data set in the parse step
• tumor_bam: Path to input indexed BAM file
• reference.fa: Path to reference genome used for the alignment

Recommended options

Quality presets

merge_control

Merges non-matched control panel supporting reads obtained by parse.

nanomonsv merge_control [-h] prefix_list_file output_prefix

• prefix_list_file: List of output_prefix generated at the parse stage
• output_prefix: Prefix to the merged control supporting reads

insert_classify

Classifies long insertions into mobile element insertions (LINE1, Alu, SVA, processed pseudogene).

nanomonsv insert_classify [-h] [--debug] sv_list_file output_file reference.fa gencode.gtf.gz LINE1_db

• sv_list_file: VCF file or nanomonsv get result file (nanomonsv.result.txt)
• output_file: Path to the output file
• reference.fa: Path to the reference genome
• gencode.gtf.gz: Path to gene annotation GTF file. We recommend Gencode basic annotation (e.g., gencode.v49.basic.annotation.gtf.gz)
• LINE1_db: Path to LINE1 database. Use the files in resource/LINE1_db

validate

Validates candidate SVs by alignment of tumor and matched control BAM files. This may be helpful for evaluating SV tools on short-read platforms when pairs of short-read and long-read sequencing data are available.

nanomonsv validate [-h] [--control_bam CONTROL_BAM]
                   [--var_read_min_mapq VAR_READ_MIN_MAPQ] [--debug]
                   sv_list_file tumor_bam output reference.fa

• sv_list_file: SV candidate list file (only Chr_1 to Inserted_Seq columns are necessary)
• output_file: Path to the output file
• reference.fa: Path to the reference genome

Output Format

Canonical SV result ({tumor_prefix}.nanomonsv.result.txt)

A VCF format file ({tumor_prefix}.nanomonsv.result.vcf) is also generated. See the wiki page for details on filtering.

Single breakend result ({tumor_prefix}.nanomonsv.sbnd.result.txt)

Generated by default. Use --no_single_bnd to disable.

A VCF format file ({tumor_prefix}.nanomonsv.sbnd.result.vcf) is also generated, using VCF single breakend notation (e.g., N. or .N in ALT field with SVTYPE=BND).

insert_classify result

Control Panel

We strongly recommend using a control panel for filtering common SVs and sequencing noise. Pre-built control panels are available at zenodo. You can also create your own from your sequencing data using merge_control.

Pre-built control panels

For ONT data, the 1000G ONT Vienna panel (1,019 samples) is recommended for its large sample size. We recommend using a control panel as close as possible in platform and basecall quality. When unsure, a noisier panel (e.g., Guppy v4) tends to be more versatile.

When you use these control panels and publish, please cite:

• Liao et al., Nature, 2023 (doi:10.1038/s41586-023-05896-x) for HPRC panels
• Schloissnig et al., Nature, 2025 (doi:10.1038/s41586-025-09290-7) for 1000G ONT Vienna panels

Example Data

The Oxford Nanopore Sequencing data used in the paper is available through the public sequence repository (BioProject ID: PRJDB10898):

• COLO829: tumor, control
• H2009: tumor, control
• HCC1954: tumor, control

Results of nanomonsv for the above data are available here. Please kindly cite the NAR paper when you use these data.

See the tutorial wiki page for an example workflow on analyzing the COLO829 sample.

Citation

Shiraishi et al., Precise characterization of somatic complex structural variations from tumor/control paired long-read sequencing data with nanomonsv, Nucleic Acids Research, 2023, [link].