Metadata-Version: 2.1
Name: pyhmmer
Version: 0.1.0
Summary: Cython bindings and Python interface to HMMER3.
Home-page: https://github.com/althonos/pyhmmer
Author: Martin Larralde
Author-email: martin.larralde@embl.de
License: MIT
Project-URL: Bug Tracker, https://github.com/althonos/pyhmmer/issues
Project-URL: Changelog, https://github.com/althonos/pyhmmer/blob/master/CHANGELOG.md
Project-URL: Zenodo, https://doi.org/10.5281/zenodo.4270012
Description: # 🐍🟡♦️🟦 pyHMMER [![Stars](https://img.shields.io/github/stars/althonos/pyhmmer.svg?style=social&maxAge=3600&label=Star)](https://github.com/althonos/pyhmmer/stargazers)
        
        *[Cython](https://cython.org/) bindings and Python interface to [HMMER3](http://hmmer.org/).*
        
        [![TravisCI](https://img.shields.io/travis/com/althonos/pyhmmer/master.svg?maxAge=600&style=flat-square)](https://travis-ci.com/althonos/pyhmmer/branches)
        [![Coverage](https://img.shields.io/codecov/c/gh/althonos/pyhmmer?style=flat-square&maxAge=3600)](https://codecov.io/gh/althonos/pyhmmer/)
        [![PyPI](https://img.shields.io/pypi/v/pyhmmer.svg?style=flat-square&maxAge=3600)](https://pypi.org/project/pyhmmer)
        [![Wheel](https://img.shields.io/pypi/wheel/pyhmmer.svg?style=flat-square&maxAge=3600)](https://pypi.org/project/pyhmmer/#files)
        [![Python Versions](https://img.shields.io/pypi/pyversions/pyhmmer.svg?style=flat-square&maxAge=3600)](https://pypi.org/project/pyhmmer/#files)
        [![Python Implementations](https://img.shields.io/pypi/implementation/pyhmmer.svg?style=flat-square&maxAge=3600&label=impl)](https://pypi.org/project/pyhmmer/#files)
        [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square&maxAge=2678400)](https://choosealicense.com/licenses/mit/)
        [![Source](https://img.shields.io/badge/source-GitHub-303030.svg?maxAge=2678400&style=flat-square)](https://github.com/althonos/pyhmmer/)
        [![Mirror](https://img.shields.io/badge/mirror-EMBL-009f4d?style=flat-square&maxAge=2678400)](https://git.embl.de/larralde/pyhmmer/)
        [![GitHub issues](https://img.shields.io/github/issues/althonos/pyhmmer.svg?style=flat-square&maxAge=600)](https://github.com/althonos/pyhmmer/issues)
        [![Docs](https://img.shields.io/readthedocs/pyhmmer/latest?style=flat-square&maxAge=600)](https://pyhmmer.readthedocs.io)
        [![Changelog](https://img.shields.io/badge/keep%20a-changelog-8A0707.svg?maxAge=2678400&style=flat-square)](https://github.com/althonos/pyhmmer/blob/master/CHANGELOG.md)
        [![Downloads](https://img.shields.io/badge/dynamic/json?style=flat-square&color=303f9f&maxAge=86400&label=downloads&query=%24.total_downloads&url=https%3A%2F%2Fapi.pepy.tech%2Fapi%2Fprojects%2Fpyhmmer)](https://pepy.tech/project/pyhmmer)
        [![DOI](https://img.shields.io/badge/doi-10.5281%2Fzenodo.4270012-purple?style=flat-square&maxAge=86400)](https://doi.org/10.5281/zenodo.4270012)
        
        <!-- [![AppVeyor](https://img.shields.io/appveyor/build/althonos/pyhmmer/master.svg?logo=appveyor&maxAge=600&style=flat-square)](https://ci.appveyor.com/project/althonos/pyhmmer/history) -->
        <!-- [![Bioconda](https://img.shields.io/conda/vn/bioconda/pyhmmer?style=flat-square&maxAge=3600)](https://anaconda.org/bioconda/pyhmmer) -->
        
        
        ## 🗺️ Overview
        
        HMMER is a biological sequence analysis tool that uses profile hidden Markov
        models to search for sequence homologs. HMMER3 is maintained by members of the
        the [Eddy/Rivas Laboratory](http://eddylab.org/) at Harvard University.
        
        `pyhmmer` is a Python module, implemented using the [Cython](https://cython.org/)
        language, that provides bindings to HMMER3. It directly interacts with the
        HMMER internals, which has the following advantages over CLI wrappers
        (like [`hmmer-py`](https://pypi.org/project/hmmer/)):
        
        - **single dependency**: If your software or your analysis pipeline is
          distributed as a Python package, you can add `pyhmmer` as a dependency to
          your project, and stop worrying about the HMMER binaries being properly
          setup on the end-user machine.
        - **no intermediate files**: Everything happens in memory, in Python objects
          you have control on, making it easier to format your inputs to pass to
          HMMER without needing to write them to a file. Output retrieval is also
          done in memory, through instances of the `pyhmmer.plan7.TopHits` class.
        - **no input formatting**: The Easel object model is exposed in the `pyhmmer.easel`
          module, and you have the possibility to build a `Sequence` object yourself
          to pass to the HMMER pipeline. This is useful if your sequences are already
          loaded in memory, for instance because you obtained them from another
          Python library (such as [Pyrodigal](https://github.com/althonos/pyrodigal)
          or [Biopython](https://biopython.org/)).
        - **no output formatting**: HMMER3 is notorious for its numerous output files
          and its fixed-width tabular output, which is hard to parse (even
          [`Bio.SearchIO.HmmerIO`](https://biopython.org/docs/dev/api/Bio.SearchIO.HmmerIO.html)
          is struggling on some sequences).
        - **efficient**: Using `pyhmmer` to launch `hmmsearch` on sequences
          and HMMs in disk storage is typically not slower than directly using the
          `hmmsearch` binary (see the [Benchmarks section](#%EF%B8%8F-benchmarks)).
          `pyhmmer.hmmsearch` uses a different parallelisation strategy compared to
          the `hmmsearch` binary from HMMER, which helps getting the most of
          multiple CPUs.
        
        *This library is still a work-in-progress, and in a very experimental stage,
        but it should already pack enough features to run simple biological analyses
        involving `hmmsearch`.*
        
        
        ## 🔧 Installing
        
        `pyhmmer` can be installed from [PyPI](https://pypi.org/project/pyhmmer/),
        which hosts some pre-built CPython wheels for x86-64 Linux, as well as the
        code required to compile from source with Cython:
        ```console
        $ pip install pyhmmer
        ```
        
        Compilation for UNIX PowerPC is not tested in CI, but should work out of the
        box. Other architectures (e.g. Arm) and OSes (e.g. Windows) are not
        supported by HMMER.
        
        *A `bioconda` package is planned when this package exits the alpha status.*
        
        ## 📖 Documentation
        
        A complete [API reference](https://pyhmmer.readthedocs.io/en/stable/api/) can
        be found in the [online documentation](https://pyhmmer.readthedocs.io/), or
        directly from the command line using
        [`pydoc`](https://docs.python.org/3/library/pydoc.html):
        ```console
        $ pydoc pyhmmer.easel
        $ pydoc pyhmmer.plan7
        ```
        
        
        ## 💡 Example
        
        Use `pyhmmer` to run `hmmsearch`, and obtain an iterable over
        [`TopHits`](https://pyhmmer.readthedocs.io/en/latest/api/plan7.html#pyhmmer.plan7.TopHits)
        that can be used for further sorting/querying in Python:
        
        ```python
        import pyhmmer
        
        with pyhmmer.easel.SequenceFile("938293.PRJEB85.HG003687.faa") as file:
            alphabet = file.guess_alphabet()
            sequences = [seq.digitize(alphabet) for seq in file]
        
        with pyhmmer.plan7.HMMFile("Pfam.hmm") as hmms:
            all_hits = list(pyhmmer.hmmsearch(hmms, sequences_file, cpus=4))
        ```
        
        Processing happens in parallel using Python threads, and a ``TopHits``
        object is yielded for every ``HMM`` passed in the input iterable. *Note that
        for optimal performance, you should pass the number of **physical** cores to
        the `cpus` argument of the `pyhmmer.hmmsearch` function, as HMMER requires
        too many SIMD registers to benefit from hyperthreading*.
        
        
        ## 💭 Feedback
        
        ### ⚠️ Issue Tracker
        
        Found a bug ? Have an enhancement request ? Head over to the [GitHub issue
        tracker](https://github.com/althonos/pyhmmer/issues) if you need to report
        or ask something. If you are filing in on a bug, please include as much
        information as you can about the issue, and try to recreate the same bug
        in a simple, easily reproducible situation.
        
        ### 🏗️ Contributing
        
        Contributions are more than welcome! See [`CONTRIBUTING.md`](https://github.com/althonos/pyhmmer/blob/master/CONTRIBUTING.md) for more details.
        
        ## ⏱️ Benchmarks
        
        Benchmarks were run on a i7-8550U CPU running at 1.80GHz, using a FASTA file
        containing 2100 protein sequences
        ([`tests/data/seqs/938293.PRJEB85.HG003687.faa`](https://github.com/althonos/pyhmmer/blob/master/tests/data/seqs/938293.PRJEB85.HG003687.faa))
        and a subset of the [Pfam](https://pfam.xfam.org/) HMM library containing
        2873 domains. Commands were run 20 times.
        
        | Command                       | # CPUs | mean (s) | σ (ms) | min (s) | max (s) | Speedup |
        |-------------------------------|--------|----------|--------|---------|---------|---------|
        | `python -m pyhmmer hmmsearch` |      4 |  20.706  |  316   |  19.960 |  42.457 |   x1.00 |
        | `python -m pyhmmer hmmsearch` |      2 |  24.076  |  842   |  22.289 |  21.118 |   x1.16 |
        | `hmmsearch`                   |      2 |  35.046  |  161   |  34.734 |  35.183 |   x1.69 |
        | `hmmsearch`                   |      4 |  37.721  |   78   |  37.605 |  37.847 |   x1.82 |
        | `python -m pyhmmer hmmsearch` |      1 |  39.022  | 1346   |  36.081 |  40.644 |   x1.88 |
        | `hmmsearch`                   |      1 |  44.360  |  243   |  44.184 |  45.018 |   x2.14 |
        | `hmmscan`                     |      2 | 102.248  |  381   | 101.479 | 102.765 |   x4.93 |
        | `hmmscan`                     |      4 | 106.779  |  375   | 106.197 | 107.482 |   x5.15 |
        | `hmmscan`                     |      1 | 107.945  |  326   | 107.460 | 108.502 |   x5.21 |
        
        
        ## ⚖️ License
        
        This library is provided under the [MIT License](https://choosealicense.com/licenses/mit/).
        The HMMER3 and Easel code is available under the
        [BSD 3-clause](https://choosealicense.com/licenses/bsd-3-clause/) license.
        See `vendor/hmmer/LICENSE` and `vendor/easel/LICENSE` for more information.
        
        *This project is in no way not affiliated, sponsored, or otherwise endorsed by
        the [original HMMER authors](http://hmmer.org/). It was developed by
        [Martin Larralde](https://github.com/althonos/pyhmmer) during his PhD project
        at the [European Molecular Biology Laboratory](https://www.embl.de/) in
        the [Zeller team](https://github.com/zellerlab).*
        
Keywords: bioinformatics,profile,HMM,sequence,pfam
Platform: posix
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: C
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Typing :: Typed
Requires-Python: >=3.5
Description-Content-Type: text/markdown
