pyminimap2 2.30.3
Python wrapper for minimap2 with stdout/stderr capture
License: MIT
Requires Python: >=3.9
Keywords: minimap2, bioinformatics, sequence alignment, genomics

[![PyPI version](https://img.shields.io/pypi/v/pyminimap2.svg)](https://pypi.org/project/pyminimap2/)


# pyminimap2: a Python wrapper for minimap2

`pyminimap2` is a Python wrapper for [minimap2](https://github.com/lh3/minimap2) (developed by Heng Li). `pyminimap2` generates **exactly the same** output as `minimap2` as it simply pass the command-line arguments to the main function in `main.c` of `minimap2`. 

Compared to invoking `minimap2` through `subprocess.run` or `os.system()`, using `pyminimap2` incurs significantly lower overhead. 

In our benchmark, running `pyminimap2.main('--version')` is approximately **20–30 times faster** than invoking `minimap2 --version` using `subprocess.run`, and about **40 times faster** than calling it via `os.system()`.

`pyminimap2` is a good choice for applications requiring frequent or high-throughput invocations of `minimap2` from within Python.

## How to install

**Option 1: Install via pip (Recommended)**

We provide pre-compiled binaries for Linux and Python versions 3.9 to 3.13. Simply run the following command:

```bash
pip install pyminimap2
```

Option 2: Clone and compile from source

```bash
git clone https://github.com/TheFangLab/pyminimap2.git
cd pyminimap2
pip install .
```
Choose this option if you are using Python 3.13 or a later version. You need to have a C compiler (e.g. GCC). 


## How to use

Assuming your orignal command for executing minimap2 is 

```bash
minimap2 -x map-ont ref.fa read.fq.gz
```

You can use `pyminimap2` as follows:

```python
import pyminimap2 as pymm2
out, err = pymm2.main("-x map-ont ref.fa read.fq.gz")
```

This would generate the exact same output as `minimap2 -x map-ont ref.fa read.fq.gz`.

If you want to save the output to a file, you can use the `-o` option (same as the `-o` option of minimap2):

```python
out, err = pymm2.main("-x map-ont ref.fa read.fq.gz -o output.paf")
```

This would generate a `output.paf` file. 

In summary, if you use `-o` to specify the output file, `pyminimap2` will generate the same output file as `minimap2`. If `-o` is not specified, `pymm2.main()` returns a tuple (out, err) where `out` contains the stdout and `err` contains the stderr.

You can find explainations of the command-line arguments of `minimap2` at 

1. https://github.com/lh3/minimap2
2. https://lh3.github.io/minimap2/minimap2.html

## Difference from `mappy`

### 1. Access to the Full Command-Line Interface (CLI).

`pyminimap2` accepts exactly the same command-line arguments as `minimap2`. Everything `minimap2` can do via CLI is available.

### 2. Identical Output

`pyminimap2` generates exact the same output as `minimap2`. If you are running existing pipelines that rely on parsing standard PAF or SAM files generated by the CLI tool, `pyminimap2` creates strictly identical text output (stdout) or files. 

`mappy` requires a deeper understanding of the Python API (such as `mappy.Aligner` and `mappy.Alignment`).

### 3. Low Migration Friction

If you have existing scripts using `subprocess.run` or `os.system()` to call `minimap2`, migrating to `pyminimap2` is almost trivial. You just pass the specific string of arguments you were already using.


## About version

You can use the following code to print the version number of `minimap2` bound in `pyminimap2`:

```python
import pyminimap2 as pymm2
print(pymm2.main('--version')[0])
```

## License

`pyminimap2` is released under the MIT license.