🧬🧰 PyNCBItk

(Unofficial) Cython bindings and Python interface to the NCBI C++ Toolkit.

⚠️ This package is a work-in-progress and in a very experimental state. Expect segmentation faults, compilation issues, missing features, incomplete documentation.

🗺️ Overview

The NCBI C++ Toolkit is a framework of C++ libraries to work with biological sequence data developed at the National Center for Biotechnology Information. It features a flexible object model for representing sequences of various origin, including composite or virtual sequences; a resource manager to easily manipulate heterogeneous data sources; and a comprehensive API to the various BLAST algorithms[1] developed at the NBCI.

PyNCBItk is a Python library that provides bindings to the NCBI C++ Toolkit data model and BLAST+ interface using Cython. It exposes the internals of the C++ Toolkit, allowing BLAST queries to be run directly from the Python interpreter without external I/O.

📋 Roadmap

The package is in a very experimental state, and only a few core features are supported at the moment:

• Loading sequences from a FASTA file.
• Creating basic sequences through the Python API.
• Running BLAST searches with default parameters.
• Thorough BLAST configuration.
• Error and warning management.
• Support for all kinds of sequence storage.
• Multi-threading for database searches using Python threads.
• Advanced interface for the object manager.
• Interface for all sequence and alignment types.

🔧 Installing

PyNCBItk is available for all modern Python (3.7+). Compilation is done through CMake using Scikit-build-core.

To install an alpha release, use pip with the --pre flag:

$ pip install pyncbitk --pre

The pyncbitk package requires additional runtime libraries that are distributed in the pyncbitk-runtime package. These libraries should be available in a pre-compiled wheel for Linux and MacOS platforms. Otherwise, they can be compiled on setup with the Conan C/C++ package manager to handle compilation of the NCBI C++ Toolkit. The project will take ages to compile the first time, but afterwards only the Cython code will have to be recompiled.

💡 Example

from pyncbitk.objects.seqset import BioSeqSet
from pyncbitk.objtools import DatabaseReader, FastaReader
from pyncbitk.algo.blast import BlastN

# read the sequences from FASTA-formatted files
queries = BioSeqSet(FastaReader("queries.fna", split=False))
subjects = BioSeqSet(FastaReader("subjects.fna", split=False))

# run `blastn` with default parameters
blastn = BlastN()
results = blastn.run(queries, subjects)

The result is a SearchResultsSet which contains one SearchResults object per query/subject pair. The SearchResults object summarizes the result and contains the hit alignments in a SeqAlignSet.

See the Examples section in the online documentation for more information.

💭 Feedback

⚠️ Issue Tracker

Found a bug ? Have an enhancement request ? Head over to the GitHub issue tracker 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 for more details.

📋 Changelog

This project adheres to Semantic Versioning and provides a changelog in the Keep a Changelog format.

⚖️ License

This library is provided under the MIT License. The NCBI C++ Toolkit is a "United States Government Work" and therefore lies in the public domain, but may be subject to copyright by the U.S. in foreign countries. Some restrictions apply, see the NCBI C++ Toolkit license.

This project is in no way not affiliated, sponsored, or otherwise endorsed by the NCBI or any associated entity. It was developed by Martin Larralde during his PhD at the Leiden University Medical Center in the Zeller team.

📚 References

• [1] Altschul, S. F., Gish, W., Miller, W., Myers, E. W., & Lipman, D. J. (1990). Basic local alignment search tool. Journal of molecular biology, 215(3), 403–410. doi:10.1016/S0022-2836(05)80360-2