PyMisha
Python interface for misha genomic databases. PyMisha provides full read/write access to misha track databases with C++ streaming backends for genome-scale operations. |
|
Features
- 1D and 2D track support: Dense, sparse, and 2D (rectangle/point) tracks with full CRUD operations.
- C++ streaming backends: Extraction, summary, quantiles, distribution, lookup, segmentation, Wilcoxon tests, correlation, and sampling all stream through C++ for performance.
- Virtual tracks: Computed-on-the-fly track views with filtering, shifting, and 30+ aggregation functions.
- Interval operations: Union, intersection, difference, canonicalization, neighbors, annotation, normalization, random generation, and liftover.
- Sequence analysis: Extraction, k-mer counting, PWM/PSSM scoring, and Markov-chain synthesis (
gsynth). - Database management: Create, link, convert, and manage misha-compatible genomic databases.
- R misha compatibility: Reads and writes the same on-disk formats as R misha (123/145 R exports covered).
Installation
pip install pymisha
Pre-built wheels are available for Linux (x86_64) and macOS (x86_64 and arm64), Python 3.10-3.12.
To install from source (requires a C++17 compiler and numpy):
pip install -e ".[dev]"
Quick start
PyMisha ships with a built-in examples database so you can start exploring immediately -- no external data needed:
import pymisha as pm
# Option 1: one-liner to load the bundled examples database
pm.gdb_init_examples()
# Option 2: equivalent explicit form
pm.gsetroot(pm.gdb_examples_path())
# List available tracks and extract data
print(pm.gtrack_ls())
print(pm.gextract("dense_track", pm.gintervals("chr1", 0, 1000)))
To connect to your own misha database, use gsetroot:
import pymisha as pm
# Initialize the database
pm.gsetroot("/path/to/misha_db")
# Create intervals and extract data
intervals = pm.gintervals_from_strings(["chr1:0-1000", "chr1:2000-2600"])
out = pm.gextract("track1", intervals, iterator=100)
# Filter and summarize
filtered = pm.gscreen("track1 > 0.5", intervals)
stats = pm.gsummary("track1", intervals)
Thread safety
PyMisha inherits R misha's single-threaded design. Keep the following constraints in mind:
- Not thread-safe. All module-level state (
_GROOT,_UROOT,_VTRACKS,CONFIG) is process-global and unsynchronized. Do not call PyMisha from multiple threads concurrently. - One database per process. You cannot have two databases open simultaneously;
gsetroot()replaces the active database globally. CONFIGis global. Changing settings likemax_processesaffects every subsequent operation in the process.- Multiprocessing uses
fork(). The C++ backend parallelizes viafork()with shared memory (mmap) and semaphores. This is transparent to the caller but means PyMisha should not be used inside already-forked worker processes or withfork-unsafe libraries.
Examples
Using the built-in example database:
import pymisha as pm
# Quickest way to get started
pm.gdb_init_examples()
# Or equivalently, using gsetroot with the examples path
pm.gsetroot(pm.gdb_examples_path())
print(pm.gtrack_ls())
print(pm.gextract("dense_track", pm.gintervals("chr1", 0, 1000)))
Creating a genome database
PyMisha ships prebuilt genome databases for common assemblies. Download and set up with a single call:
import pymisha as pm
# Download a prebuilt genome (mm9, mm10, mm39, hg19, hg38)
pm.gdb_create_genome("hg38", path="/data/genomes") # creates /data/genomes/hg38/
pm.gsetroot("/data/genomes/hg38")
pm.gchrom_sizes() # verify it worked
To build a database from your own FASTA files (e.g. a custom assembly):
pm.gdb_create("/data/my_genome", "genome.fa.gz", verbose=True)
pm.gsetroot("/data/my_genome")
See the Creating Genome Databases tutorial for UCSC download workflows and advanced options.
Optional dependencies
pyBigWig: For BigWig import ingtrack_import.pyreadr+Rscript: For loading R-serialized big interval sets.PyYAML: For richergdataset_infometadata parsing.
Using pymisha with an LLM agent
LLM coding agents (Claude Code, Copilot, Cursor) writing pymisha analysis code can pre-load these reference docs into context for fewer hallucinated APIs and more idiomatic recipes:
- agent-guides/pymisha-core.md — concepts, chooser tables, everyday recipes.
- agent-guides/pymisha-advanced.md — 2D/Hi-C, PWM, import/export, new genomes, gsynth.
- agent-guides/pymisha-anti-patterns.md — silent footguns cross-referenced from the above.
- agent-guides/skills/importing-tracks/SKILL.md — full track-import reference.
Drop-in prompt (no clone needed). Paste the block below into your agent at the start of a pymisha task. It points the agent at the raw files on GitHub, so it works without a local checkout:
Before writing any pymisha code, fetch and read:
- https://raw.githubusercontent.com/tanaylab/pymisha/main/agent-guides/pymisha-core.md (mandatory: concepts + everyday recipes)
- https://raw.githubusercontent.com/tanaylab/pymisha/main/agent-guides/pymisha-anti-patterns.md (silent footguns; cross-referenced from core)
- https://raw.githubusercontent.com/tanaylab/pymisha/main/agent-guides/pymisha-advanced.md (consult on demand: 2D/Hi-C, PWM, import/export, new genomes)
Follow the conventions in those files. When you hit a recipe with an
"Avoid:" block, treat it as a hard rule.
Pin to a release tag for stability by replacing main with any tag that contains agent-guides/. The skills/importing-tracks/SKILL.md guide listed above is load-on-demand; pull it in only when the task specifically calls for track import.
The guides mirror the equivalent set in R misha — same section numbering, same recipes, translated to the pymisha API.
Missing features
Compared to R misha, the following are not yet implemented:
- Track Arrays:
gtrack.array.*andgvtrack.array.slice. - Legacy Conversion:
gtrack.convert(for migrating old 2D formats).
License
MIT. See LICENSE for details.
1 maintainer
Release files for pymisha 0.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pymisha-0.12.0.tar.gz | 1.7 MB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| pymisha-0.12.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl | CPython 3.12 | CPython 3.12 | Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 | Details |
| pymisha-0.12.0-cp312-cp312-macosx_11_0_arm64.whl | CPython 3.12 | CPython 3.12 | macOS 11.0+ ARM64 | Details |
| pymisha-0.12.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl | CPython 3.11 | CPython 3.11 | Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 | Details |
| pymisha-0.12.0-cp311-cp311-macosx_11_0_arm64.whl | CPython 3.11 | CPython 3.11 | macOS 11.0+ ARM64 | Details |
| pymisha-0.12.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl | CPython 3.10 | CPython 3.10 | Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 | Details |
Total release size: 41.3 MB
Release files / pymisha-0.12.0.tar.gz
| Download URL | pymisha-0.12.0.tar.gz |
|---|---|
| Size | 1.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3a340e2cbf59bfb4b71c4b9e898b5bfb89febc4f290487d222f13a83a201294b
|
|
BLAKE2b-256 checksum How to use checksums |
250e7c72bab339b19cbf514348e085a2fb0b5deafd5dce91eaebed5b3a005920
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logRelease files / pymisha-0.12.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pymisha-0.12.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 12.2 MB |
| Tags | CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
4505ad44e2ee7ad8118527243f64710878975665a82853bbd9d74e077c3ba552
|
|
BLAKE2b-256 checksum How to use checksums |
93df5a4ed5d9338a08121dbd4ab98b9e81ef728d9934fe8202ef7ae64b327e6d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logRelease files / pymisha-0.12.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | pymisha-0.12.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.5 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
1105becc90a9905bf48fd975896f4a1b4632c3585fc5aeeacba35738ef34392e
|
|
BLAKE2b-256 checksum How to use checksums |
47094b8c86657ea1cd30cc4cc542392b377d9c8208896bde45abdec230f36273
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logRelease files / pymisha-0.12.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pymisha-0.12.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 12.2 MB |
| Tags | CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
1265c33c529ebed7bc041ad2d990e809147dfe4cc99be62698e73fab51baf51d
|
|
BLAKE2b-256 checksum How to use checksums |
83a4de33f5350321978a57a79631ea7c5b0b1ea53b7e0b52e558a2cecac32186
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logRelease files / pymisha-0.12.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | pymisha-0.12.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.5 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
fba50fe40680a8c724dc21487ee6dd971176dbebc7fccfb6e2547325d701f46e
|
|
BLAKE2b-256 checksum How to use checksums |
abb8aa70bce999bc80b06fe7c7a3f7855b9025eef0a0f06e2429653688bb3a7a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logRelease files / pymisha-0.12.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pymisha-0.12.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 12.2 MB |
| Tags | CPython 3.10 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
1487893d037a695b8e001b498e1a21d50e41c8d017992ed02f1b238a6641222a
|
|
BLAKE2b-256 checksum How to use checksums |
468e0cf6a95f474202a8829354e0d526dac1f6f92e0fc8761902e14a22f5e9d7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency log
