Himito

Building Mitochondrial anchor-based graphical genome from long reads. Filter Numts reads, assemble major haplotypes, call homoplasmic and heteroplasmic variants, analyze methylation signals

Documentation

User Guide

Installation

Standard install

Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

System dependencies (needed to compile rust-htslib):

# Debian/Ubuntu
sudo apt-get install -y build-essential cmake pkg-config libssl-dev libclang-dev zlib1g-dev

Build Himito from source:

git clone https://github.com/broadinstitute/Himito.git
cd Himito
cargo build --release

Or download a prebuilt Linux binary from GitHub Releases:

wget https://github.com/broadinstitute/Himito/releases/download/v1.1.2/Himito
chmod +x Himito
./Himito --help

Restricted network environments (incl. China)

If GitHub, Docker Hub, or crates.io are slow or unreachable, use the Zenodo source archive, Cargo/rustup mirrors, or an offline cargo build --offline workflow. See Installation in restricted network environments.

Usage

Quick start (Filter-Build-Asm-Call-Methyl)

./target/release/Himito quick-start -i <lrWGS.bam> \
                                    -o <output_prefix> \
                                    -r <rCRS.fa> \
                                    -s <HG002> \
                                    -d pacbio

If you are analyzing high coverage samples, remember to set --maximal-mt-depth to a reasonable number

Details

build Himito graph

# filter NUMTs-derived reads
./target/release/Himito filter -i <input.bam> -c <chromosome in bam, e.g. "chrM"> -m <mt_output.bam> -n <numts_output.bam>

# construct graph
./target/release/Himito build -i <mt_output.bam> -k <kmer_size> -r <NC_012920.1.fasta> -o <output.gfa>

(Optional) Prune the Himito graph using paired srWGS data

The graph served as the foundation for downstream assembly, variant calling and methylation analysis.

If you have paired short reads data, you can refine the graph by using Himito correct.

Himito correct trims graph paths according to the occurrence counts of path kmers in the paired srWGS data. We recommend to first subset the srWGS BAM file to reads aligned to chrM, then compressed these reads into a msBWT.

msbwt2-build -o sr_msbwt.npy <srWGS.chrM.fasta.gz>
./target/release/Himito correct -g <output.gfa> -b <bwt_file, e.g. sr_msbwt.npy> -o <corrected.gfa> -m <minimal_supporting_sr> -q <query_length, should be less than short read length>

Downstream analysis

# call variants from graph, default for pacbio, change <-d ont> to ont data
./target/release/Himito call -g <output.gfa> -r <NC_012920.1.fasta> -k <kmer_size> -s <sampleid> -o <output.vcf>

# extract major haplotype from graph
./target/release/Himito asm -g <output.gfa>  -o <output.majorhaplotpe.fasta> -s <header string, e.g. "HG002 major haplotype">

# call methylation signals
./target/release/Himito methyl -g <output.annotated.gfa> -p <min_prob> -b <mt_test.bam> -o <methyl.bed>

# enumerate all possible haplotypes within windows
./target/release/Himito minorhap -g <output.gfa> -o <output.allhaplotype.fasta> -s <sample_id>

Jan 20th 2026 Updates: NUMTs Breakpoint Calling (Under-construction)

Himito can identify and call NUMTs (Nuclear Mitochondrial DNA segments) breakpoints from long-read BAM files. NUMTs are segments of mitochondrial DNA that have been inserted into the nuclear genome. The NUMTs calling functionality (callnumts.rs) works by:

1. Identifying NUMT reads: Parses supplementary alignment (SA) tags in BAM files to identify reads that have:

   • Primary alignment to mitochondrial DNA (chrM) and supplementary alignment to nuclear chromosomes, OR
   • Primary alignment to nuclear chromosomes and supplementary alignment to mitochondrial DNA

2. Merging breakpoints: Groups breakpoints by chromosome and merges consecutive breakpoints within a specified gap threshold (max_gap_threshold) to create intervals.

3. Writing BND records: Outputs breakend (BND) structural variant records in VCF format, representing the NUMT breakpoints. Each BND record includes:

   • Breakpoint positions on both the nuclear chromosome and mitochondrial genome
   • Strand orientation information
   • Supporting read counts (allele depth)
   • Properly formatted BND ALT fields based on strand orientations

Usage:

./target/release/Himito call-numts -i sample.bam \
                               -c chrM \
                               -m 10000 \
                               -r hg38.fa \
                               -o numts_breakpoints.vcf \
                               -s HG002 \
                               -a 2

Output format: The output VCF file contains BND (breakend) records in standard VCFv4.3 format. Each record represents a NUMT breakpoint with:

• CHROM: Nuclear chromosome where the breakpoint occurs
• POS: Breakpoint position (1-based)
• ALT: BND format string indicating the connection to mitochondrial DNA
• INFO: Contains SVTYPE=BND
• FORMAT: GT (genotype) and AD (allele depth/supporting read count)

This will identify NUMT breakpoints where reads have alignments spanning both mitochondrial and nuclear genomes, merge breakpoints within 10kb, and output only those with at least 2 supporting reads. If you want to examine all possible NUMTs BND, adjust -a to <=1.

ToDo: may perform local assembly to find sequence resolved NUMTs insertions

July 14th 2026 Updates: Mitochondrial lineage inference (Under-construction)

Himito includes a new function for inferring mitochondrial mutation history from heteroplasmic variants given the Infinite Sites assumption (ISA) that every variant can only mutate once and will exist on the lineage over the lifetime.

Given a Himito read–variant matrix (<prefix>.matrix.csv from call) and the corresponding VCF, the lineage command filters to informative heteroplasmic sites, deduplicates reads into haplotypes, and runs an MCMC search over mutation trees and identify a ML tree (algorithm adapted from SCITE, Kuipers J et al. Single-cell sequencing data reveals widespread recurrence and loss of mutational hits in the life histories of tumorus. Genome Research 2017; 27:1885-1894.). The initial tree is a Neighbor–Joining tree constructed from reads instead of a random tree though. Sequencing errors are modeled with configurable false-positive (defaul 0.001) and false-negative rates (defaul 0.05).

Outputs include a mutation tree, read-level lineage Newick tree, cleaned read–variant matrix, variant co-occurrence tables, and haplotype maps.

./target/release/Himito lineage -m <prefix>.matrix.csv \
                                 -v <output.vcf> \
                                 -o <output_prefix> \
                                 --min-hf 0.01 \
                                 --max-hf 0.95

Key outputs: <output_prefix>.mutation_tree.tsv, <output_prefix>.read_lineage.nwk, <output_prefix>.cleaned_matrix.csv, <output_prefix>.raw_haplotype_map.tsv, <output_prefix>.cleaned_haplotype_map.tsv.

To Do:

1. mutation/error rate in homopolymer regions could be different (higher FP rate).
2. add four gamete test
3. Add posteriors, convergence and confidence metrics