mehari 0.41.0__tar.gz

mehari-0.41.0/Cargo.toml

@@ -0,0 +1,24 @@
+[workspace]
+resolver = "3"
+members = ["mehari"]  # do not include mehari-python here to avoid pulling in jemalloc for python bindings
+
+# Compile insta with full optimization.
+[profile.dev.package.insta]
+opt-level = 3
+[profile.dev.package.similar]
+opt-level = 3
+
+[profile.release]
+debug = false
+lto = "fat"
+codegen-units = 1
+
+[profile.dev]
+debug = true
+lto = false
+codegen-units = 128
+opt-level = 3
+
+[profile.profiling]
+inherits = "release"
+debug = true

mehari-0.41.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Till Hartmann, Berlin Institute of Health
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mehari-0.41.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: mehari
+Version: 0.41.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: License :: OSI Approved :: MIT License
+License-File: LICENSE.txt
+Summary: Python bindings for the mehari variant annotator
+Keywords: bioinformatics,genomics,variants,annotation,vcf
+Author-email: Till Hartmann <till.hartmann@bih-charite.de>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://github.com/varfish-org/mehari/tree/main/docs
+Project-URL: Homepage, https://github.com/varfish-org/mehari
+Project-URL: Repository, https://github.com/varfish-org/mehari.git
+
+# mehari
+
+Python bindings for the [`mehari`](https://github.com/varfish-org/mehari) Rust library.
+
+## Features
+
+* **Single variants:** Annotate a single variant using a format string (`chr:pos:ref:alt`) or keyword arguments.
+* **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`](https://github.com/varfish-org/mehari-data-tx/releases)) and a reference genome (FASTA, uncompressed, with index).
+
+```python
+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:
+```python
+result1 = annotator.annotate("17:41197701:G:C")
+result2 = annotator.annotate(chromosome="3", position=193332511, reference="G", alternative="T")
+```
+
+To annotate a batch of variants, pass a `polars.DataFrame` or `polars.LazyFrame`.
+```python
+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:
+```python
+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`
+- `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)`
+

mehari-0.41.0/README.md

@@ -0,0 +1,81 @@
+# mehari
+
+Python bindings for the [`mehari`](https://github.com/varfish-org/mehari) Rust library.
+
+## Features
+
+* **Single variants:** Annotate a single variant using a format string (`chr:pos:ref:alt`) or keyword arguments.
+* **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`](https://github.com/varfish-org/mehari-data-tx/releases)) and a reference genome (FASTA, uncompressed, with index).
+
+```python
+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:
+```python
+result1 = annotator.annotate("17:41197701:G:C")
+result2 = annotator.annotate(chromosome="3", position=193332511, reference="G", alternative="T")
+```
+
+To annotate a batch of variants, pass a `polars.DataFrame` or `polars.LazyFrame`.
+```python
+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:
+```python
+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`
+- `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)`

mehari-0.41.0/mehari/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.41.0](https://github.com/varfish-org/mehari/compare/v0.40.0...v0.41.0) (2026-03-21)
+
+
+### Features
+
+* Add python bindings via pyO3 ([#959](https://github.com/varfish-org/mehari/issues/959)) ([b2450be](https://github.com/varfish-org/mehari/commit/b2450be38bdf65aa0c21c5b77ea6770910bd46a5))

mehari-0.41.0/mehari/Cargo.toml

@@ -0,0 +1,111 @@
+[package]
+name = "mehari"
+version = "0.41.0"
+edition = "2021"
+authors = ["Manuel Holtgrewe <manuel.holtgrewe@bih-charite.de>"]
+description = "Variant effect prediction all in Rust"
+license = "MIT"
+repository = "https://github.com/varfish-org/mehari"
+readme = "README.md"
+rust-version = "1.75.0"
+
+[features]
+default = ["jemalloc"]
+jemalloc = ["dep:tikv-jemallocator", "rocksdb/jemalloc", "annonars/jemalloc"]
+dhat-heap = ["dep:dhat"]  # for heap profiling with dhats
+documentation = []
+
+[package.metadata.docs.rs]
+all-features = true
+
+[lib]
+name = "mehari"
+path = "src/lib.rs"
+
+[[bin]]
+name = "mehari"
+path = "src/main.rs"
+
+[dependencies]
+actix-web = "4.12"
+annonars = { version = "0.44.1", default-features = false }
+anyhow = "1.0"
+async-compression = { version = "0.4", features = ["tokio", "gzip"] }
+bio = "3.0.0"
+biocommons-bioutils = "0.1.5"
+built = { version = "0.8", features = ["chrono", "semver"] }
+byte-unit = "5.2"
+chrono = "0.4"
+clap-verbosity-flag = "3.0"
+clap = { version = "4.6", features = ["derive"] }
+csv = "1.4"
+derivative = "2.2"
+derive_builder = { version = "0.20", features = ["clippy"] }
+derive-new = "0.7.0"
+enumflags2 = { version = "0.7.11", features = ["serde"] }
+env_logger = "0.11"
+flate2 = "1.1"
+futures = "0.3"
+hgvs = "0.20.1"
+indexmap = { version = "2.13", features = ["serde"] }
+itertools = "0.14"
+jsonl = "4.0"
+log = "0.4"
+nom = "8.0"
+nutype = { version = "0.6.2", features = ["serde"] }
+once_cell = "1.21.4"
+parse-display = "0.10"
+pbjson = "0.9"
+percent-encoding = "2.3"
+procfs = "0.18"
+prost = "0.14.3"
+quick_cache = "0.6.18"
+rand = "0.10"
+rayon = "1.11.0"
+rocksdb = { version = "0.24.0", features = ["multi-threaded-cf"] }
+rustc-hash = "2.1.0"
+seqrepo = { version = "0.10.2", features = ["cached"] }
+serde_json = "1.0"
+serde = { version = "1.0", features = ["derive"] }
+serde_with = { version = "3.16", features = ["alloc", "macros", "indexmap_2"], default-features = false }
+serde_yaml = "0.9"
+strum = { version = "0.28", features = ["derive"] }
+tempfile = "3"
+thousands = "0.2"
+tokio = { version = "1.50", features = ["rt-multi-thread", "macros"] }
+tracing-subscriber = "0.3"
+tracing = { version = "0.1", features = ["log"] }
+uuid = { version = "1.22", features = ["fast-rng", "serde"] }
+zstd = "0.13"
+utoipa = { version = "5.4.0", features = ["actix_extras", "chrono", "indexmap", "openapi_extensions", "preserve_order", "yaml"] }
+utoipa-swagger-ui = { version = "9.0.2", features = ["actix-web"] }
+memmap2 = "0.9.10"
+serde-aux = "4.7.0"
+
+[dependencies.noodles]
+version = "0.97.0"
+features = ["async", "bgzf", "core", "vcf", "bcf", "csi", "fasta", "tabix"]
+
+[target.'cfg(not(target_env = "msvc"))'.dependencies]
+tikv-jemallocator = { version = "0.6", optional = true }
+
+[dependencies.dhat]
+version = "0.3.3"
+optional = true
+
+[build-dependencies]
+anyhow = "1.0"
+built = { version = "0.8", features = ["cargo-lock", "dependency-tree", "git2", "chrono", "semver"] }
+pbjson-build = "0.9.0"
+prost-build = "0.14.3"
+
+[dev-dependencies]
+csv = "1.4"
+hxdmp = "0.2"
+insta = { version = "1.46", features = ["yaml"] }
+pretty_assertions = "1.4"
+rstest = "0.26"
+temp_testdir = "0.2"
+tracing-test = "0.2"
+criterion = { version = "0.8.2", features = ["async_tokio"] }
+pprof = { version = "0.15.0", features = ["flamegraph"] }

mehari-0.41.0/mehari/README.md

@@ -0,0 +1,38 @@
+[![Crates.io](https://img.shields.io/crates/d/mehari.svg)](https://crates.io/crates/mehari)
+[![Crates.io](https://img.shields.io/crates/v/mehari.svg)](https://crates.io/crates/mehari)
+[![Crates.io](https://img.shields.io/crates/l/mehari.svg)](https://crates.io/crates/mehari)
+[![CI](https://github.com/varfish-org/mehari/actions/workflows/rust.yml/badge.svg)](https://github.com/varfish-org/mehari/actions/workflows/rust.yml)
+[![codecov](https://codecov.io/gh/varfish-org/mehari/branch/main/graph/badge.svg?token=B1dfb7N2n8)](https://codecov.io/gh/varfish-org/mehari)
+[![DOI](https://zenodo.org/badge/609124150.svg)](https://zenodo.org/badge/latestdoi/609124150)
+
+# Mehari
+
+<img style="float: right" width="200" height="200" src="misc/camel.jpeg" alt="a camel">
+
+Mehari is a software package for annotating VCF files with variant effect/consequence.
+The program uses [hgvs-rs](https://crates.io/crates/hgvs) for projecting genomic variants to transcripts and proteins and thus has high prediction quality.
+
+Other popular tools offering variant effect/consequence prediction include:
+
+- [SnpEff](http://pcingola.github.io/SnpEff/)
+- [VEP (Variant Effect Predictor)](https://www.ensembl.org/info/docs/tools/vep/index.html)
+
+Mehari offers HGVS predictions that aim to mirror VariantValidator, the gold standard for HGVS variant descriptions, and consequence predictions compatible with VEP.
+Further, it is written in the Rust programming language and can be used as a library for users' Rust software.
+
+## Usage
+To annotate variant consequences, gnomAD frequencies and clinVar information for sequence variants:
+```sh
+    mehari annotate seqvars \
+      --transcripts resources/transcript_db \
+      --frequencies resources/gnomad_db \
+      --clinvar resources/clinvar_db \
+      --path-input-vcf input.vcf \
+      --path-output-vcf output.vcf
+```
+The corresponding database builds can be obtained from:
+ - transcripts: [github.com/varfish-org/mehari-data-tx/releases](https://github.com/varfish-org/mehari-data-tx/releases)
+ - gnomAD frequencies: TODO
+ - clinVar: [github.com/varfish-org/annonars-data-clinvar/releases](https://github.com/varfish-org/annonars-data-clinvar/releases)
+
+See [Getting Started](docs/getting_started.md) for more information on usage, and [Development Setup](docs/development.md) for more information on how to build mehari and its databases from scratch.

mehari-0.41.0/mehari/__init__.py

@@ -0,0 +1,96 @@
+import typing
+import polars as pl
+import pyarrow as pa
+from ._mehari import SeqvarsAnnotator as _SeqvarsAnnotator
+from ._mehari import consequence_variants, putative_impact_variants
+
+ConsequenceEnum = pl.Enum(consequence_variants())
+ImpactEnum = pl.Enum(putative_impact_variants())
+
+
+class SeqvarsAnnotator:
+    def __init__(
+        self, transcript_db_paths: str | list[str], reference_path: str | None = None
+    ):
+        if isinstance(transcript_db_paths, str):
+            transcript_db_paths = [transcript_db_paths]
+        self._annotator = _SeqvarsAnnotator(transcript_db_paths, reference_path)
+
+    def _process_dataframe(self, df: pl.DataFrame) -> pl.DataFrame:
+        """Internal helper to stream Arrow RecordBatches to Rust."""
+        pa_table = df.to_arrow()
+        batches = pa_table.to_batches()
+
+        if not batches:
+            batches = [pa.RecordBatch.from_pylist([], schema=pa_table.schema)]
+
+        result_batches = [self._annotator.annotate_batch(b) for b in batches]
+        res_df = pl.from_arrow(pa.Table.from_batches(result_batches))
+        return df.with_columns(
+            res_df.get_column("annotation")
+            .list.eval(
+                pl.element().struct.with_fields(
+                    pl.element().struct.field("putative_impact").cast(ImpactEnum),
+                    pl.element()
+                    .struct.field("consequences")
+                    .cast(pl.List(ConsequenceEnum)),
+                )
+            )
+            .alias("annotation")
+        )
+
+    @typing.overload
+    def annotate(self, data: str) -> dict[str, typing.Any]: ...
+
+    @typing.overload
+    def annotate(self, data: pl.DataFrame) -> pl.DataFrame: ...
+
+    @typing.overload
+    def annotate(self, data: pl.LazyFrame) -> pl.LazyFrame: ...
+
+    @typing.overload
+    def annotate(
+        self, *, chromosome: str, position: int, reference: str, alternative: str
+    ) -> dict[str, typing.Any]: ...
+
+    def annotate(
+        self,
+        data: str | pl.DataFrame | pl.LazyFrame | None = None,
+        *,
+        chromosome: str | None = None,
+        position: int | None = None,
+        reference: str | None = None,
+        alternative: str | None = None,
+    ) -> typing.Any:
+        """
+        Annotates genetic variants.
+        Supports Polars DataFrames/LazyFrames, 'chr:pos:ref:alt' strings, or explicit kwargs.
+        """
+
+        if isinstance(data, pl.DataFrame):
+            return self._process_dataframe(data)
+
+        if isinstance(data, pl.LazyFrame):
+            in_schema = data.collect_schema()
+            empty_df = pl.DataFrame(schema=in_schema)
+            out_schema = self._process_dataframe(empty_df).schema
+            return data.map_batches(self._process_dataframe, schema=out_schema)
+
+        if isinstance(data, str):
+            try:
+                c, p, r, a = data.split(":")
+                return self._annotator.annotate(c, int(p), r, a)
+            except ValueError:
+                raise ValueError(
+                    f"Invalid format '{data}'. Expected 'chr:pos:ref:alt' (e.g., '17:41197701:G:C')"
+                )
+
+        if all(v is not None for v in (chromosome, position, reference, alternative)):
+            return self._annotator.annotate(
+                str(chromosome), int(position), str(reference), str(alternative)
+            )
+
+        raise ValueError(
+            "Invalid input. Provide a Polars DataFrame/LazyFrame, a variant string ('chr:pos:ref:alt'), "
+            "or explicit kwargs (chromosome=..., position=..., reference=..., alternative=...)."
+        )

mehari-0.41.0/mehari/build.rs

@@ -0,0 +1,64 @@
+// The custom build script, used to (1) generate the Rust classes for the
+// protobuf implementation and (2) use pbjson for proto3 JSON serialization.
+
+use std::io::Write;
+use std::{env, path::PathBuf};
+
+fn main() -> Result<(), anyhow::Error> {
+    // Integration of `prost-build` and `pbjson-build`.
+    let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("protos");
+    let proto_files = ["mehari/txs.proto", "mehari/server.proto"]
+        .iter()
+        .map(|f| root.join(f))
+        .collect::<Vec<_>>();
+
+    // Tell cargo to recompile if any of these proto files are changed
+    for proto_file in &proto_files {
+        println!("cargo:rerun-if-changed={}", proto_file.display());
+    }
+
+    let descriptor_path: PathBuf =
+        PathBuf::from(env::var("OUT_DIR").unwrap()).join("proto_descriptor.bin");
+
+    prost_build::Config::new()
+        // Save descriptors to file
+        .file_descriptor_set_path(&descriptor_path)
+        // Override prost-types with pbjson-types
+        .compile_well_known_types()
+        .extern_path(".google.protobuf", "::pbjson_types")
+        // Define the protobuf files to compile.
+        .compile_protos(&proto_files, &[root])?;
+
+    let descriptor_set = std::fs::read(descriptor_path).unwrap();
+    pbjson_build::Builder::new()
+        .register_descriptors(&descriptor_set)?
+        .build(&[".mehari"])?;
+
+    // Integration of `built`. Workaround for python bindings via maturin in mehari-python
+    let src = env::var("CARGO_MANIFEST_DIR").unwrap();
+    let dst = PathBuf::from(env::var("OUT_DIR").unwrap()).join("built.rs");
+    let manifest_path = std::path::Path::new(&src);
+
+    if let Err(e) = built::write_built_file_with_opts(Some(manifest_path), &dst) {
+        println!(
+            "cargo:warning=Failed to write built file with manifest: {}",
+            e
+        );
+        println!("cargo:warning=Falling back to building without manifest (likely Python sdist)");
+
+        built::write_built_file_with_opts(None, &dst)
+            .map_err(|e| anyhow::anyhow!("Failed to write built file: {}", e))?;
+
+        let mut file = std::fs::OpenOptions::new()
+            .append(true)
+            .open(&dst)
+            .expect("Failed to open built.rs for appending");
+        writeln!(
+            file,
+            "pub const DEPENDENCIES: [(&str, &str); 1] = [(\"hgvs\", \"unknown-sdist\")];"
+        )
+        .expect("Failed to append dummy dependencies");
+    }
+
+    Ok(())
+}

mehari-0.41.0/mehari/protos/mehari/server.proto

@@ -0,0 +1,29 @@
+// Protobuf messages for the server.
+
+syntax = "proto3";
+
+package mehari.server;
+
+import "mehari/txs.proto";
+
+// Query for transcripts of a certain gene.
+message GeneTranscriptsQuery {
+    // Gene identifier to query for.
+    optional string hgnc_id = 1;
+    // Genome build to use.
+    optional mehari.txs.GenomeBuild genome_build = 2;
+
+    // The number of entries to return per page.
+    optional int32 page_size = 3;
+    // The token to continue from a previous query.
+    optional string next_page_token = 4;
+}
+
+// Container for a response to `GeneTranscriptsQuery`.
+message GeneTranscriptsResponse {
+    // The transcripts for the gene.
+    repeated mehari.txs.Transcript transcripts = 1;
+
+    // The token to continue from a previous query.
+    optional string next_page_token = 2;
+}