mehari

Python bindings for the mehari Rust library.

Features

• Single variants: Annotate a single variant using a format string (chr:pos:ref:alt) or keyword arguments.
• Multiple variants (experimental): Evaluate the compound effect of multiple variants.
• DataFrames: Process batches of variants by passing a polars.DataFrame.
• LazyFrames: Support for polars.LazyFrame to process large datasets (like Parquet files) without loading everything into memory.

Usage

Initialize SeqvarsAnnotator with your transcript database (see mehari-data-tx) and a reference genome (FASTA, uncompressed, with index).

from mehari import SeqvarsAnnotator

annotator = SeqvarsAnnotator(
    transcript_db_paths=["path/to/txs.bin.zst"],
    reference_path="path/to/reference.fa"
)

To annotate a single variant either use colon separated format string or keyword arguments:

result1 = annotator.annotate("17:41197701:G:C")
result2 = annotator.annotate(chromosome="3", position=193332511, reference="G", alternative="T")

To annotate multiple phased variants together as a single compound event (Experimental):

Note: Mehari does not infer phasing. When using annotate_multiple, mehari assumes all provided variants are on the same chromosome, exist on the same haplotype, and do not overlap.

result1 = annotator.annotate_multiple(["1:37799635:TA:A", "1:37799639:C:CG"])

result2 = annotator.annotate_multiple([
    {"chromosome": "1", "position": 37799635, "reference": "TA", "alternative": "A"},
    {"chromosome": "1", "position": 37799639, "reference": "C", "alternative": "CG"}
])

To annotate a batch of variants, pass a polars.DataFrame or polars.LazyFrame.

import polars as pl

df = pl.DataFrame(
    {
        "chromosome": ["17", "3"],
        "position": [41197701, 193332511],
        "reference": ["G", "G"],
        "alternative": ["C", "T"],
    },
    schema={
        "chromosome": pl.Categorical, "position": pl.Int32,
        "reference": pl.String, "alternative": pl.String
    }
)

annotated_df = annotator.annotate(df)

Schemas and types

Enums

Mehari exports its internal enums to Python so you can use them for filtering or comparisons:

from mehari import ConsequenceEnum, ImpactEnum

DataFrame Schema

When annotating a DataFrame or LazyFrame, mehari appends an "annotation" column. This column is a polars List(Struct) with the following fields:

• allele: String
• consequences: List(ConsequenceEnum)
• putative_impact: ImpactEnum
• gene_symbol: String
• gene_id: String
• hgnc_id: String
• feature_type: String
• feature_id: String
• feature_biotype: List(String)
• feature_tags: List(String)
• rank: Struct(ord: Int32, total: Int32)
• cdna_pos: Struct(ord: Int32, total: Int32)
• cds_pos: Struct(ord: Int32, total: Int32)
• protein_pos: Struct(ord: Int32, total: Int32)
• hgvs_g: String
• hgvs_n: String
• hgvs_c: String
• hgvs_p: String
• distance: Int32
• strand: Int32
• messages: List(String)

Building a transcript database

To build a transcript database, you can use the build_transcript_db function:

from mehari import build_transcript_db
build_transcript_db(
    assembly="grch38",
    annotation=["grch38.gff.gz"],
    transcript_sequences="grch38.fasta",
    transcript_source="ensembl",
    output="grch38.bin.zst"
)

This may take a while (several minutes for GRCh38 + Ensembl). Most of the time goes into compressing the database at the default compression_level=19. To show a progress bar for each step, pass a tqdm-compatible class as progress, for example progress=tqdm.auto.tqdm. To follow the steps in between, enable logging.

Logging

mehari writes its log messages to Python's logging module, under the logger mehari. By default, Python shows only warnings and errors. To also see progress messages, enable the INFO level:

import logging

logging.basicConfig(level=logging.INFO)

Configure logging before you create a SeqvarsAnnotator or call build_transcript_db. mehari caches the log levels and rereads them only when one of these two starts.