Metadata-Version: 2.4
Name: pyminimap2
Version: 2.30.2
Summary: Python wrapper for minimap2
Home-page: https://github.com/TheFangLab/pyminimap2
Author: Fang Lab
Author-email: fangli9@mail.sysu.edu.cn
License: MIT
Project-URL: Bug Tracker, https://github.com/TheFangLab/pyminimap2/issues
Project-URL: Documentation, https://github.com/TheFangLab/pyminimap2#readme
Project-URL: Source Code, https://github.com/TheFangLab/pyminimap2
Keywords: minimap2,bioinformatics,sequence alignment,genomics,long-read sequencing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

[![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`, using `pyminimap2` incurs significantly lower overhead. 

## Speed comparison
In our benchmark, executing `pyminimap2.main('--help')` is approximately **20× faster** than calling `minimap2 --help` via `subprocess.run`. 

`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

Simply run:  
```bash
pip install pyminimap2
```

Option 2: Clone the repository and install manually

```bash
git clone https://github.com/TheFangLab/pyminimap2.git
cd pyminimap2
pip install .
```

*Note: both options require a C compiler.*

## 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.
