eccLib

eccLib is a python high-performance library designed for parsing genomic files and analysing genomic context.

Install

The most reliable way of installing this library is to use pip. You can do this with the following command:

pip install eccLib

If you want to install this library from source, you can do this by cloning the repository and using the makefile.

make install

If for some reason, makefile doesn't work for you, the following sequence of steps should work as well:

1. Initialize third party libraries

   git submodule update --init --remote
   

2. Ensure you have a compiler installed

   You are going to need to have a C/C++ compiler installed on your system. For Linux I recommend gcc and for Windows realistically speaking you don't have a choice and will have to install msvc. In order to compile run the following commands

3. Build the library

   pip install .
   

In order to then uninstall this library do this:

pip uninstall eccLib

Usage

Currently the library supports parsing and processing of GTF and FASTA formats. Your IDE should pick up the .pyi file associated with the library and provide documentation for the functions and classes. Additionally the library is properly typed, so you should be able to use it with type checkers like mypy.

For more detailed notes on usage, please refer to the documentation, you can also build it yourself by running the following command:

make python-doc

Citing

If you use this library in your research, please cite the associated article as follows:

@article{10.1093/bioinformatics/btaf558,
    author = {Chady, Tomasz and Filutowska, Zuzanna Karolina},
    title = {Parsing GTF and FASTA files using the eccLib Library},
    journal = {Bioinformatics},
    volume = {41},
    number = {10},
    pages = {btaf558},
    year = {2025},
    month = {10},
    issn = {1367-4811},
    doi = {10.1093/bioinformatics/btaf558},
    url = {https://doi.org/10.1093/bioinformatics/btaf558},
    eprint = {https://academic.oup.com/bioinformatics/article-pdf/41/10/btaf558/64539454/btaf558.pdf},
}

Development

The source code of the library is stored in the src folder. You can learn about the Python/C API here. The preferred way of building the library for development and debugging is to use the debug target in the makefile. This will build the library with debugging symbols. Be sure to check out the test folder during development, as it contains a lot of useful tests. Also consult with the internal documentation for more information on the C code. You can build the documentation by running the following command:

make internal-doc

If you wish to contribute to the library, please first consult the contributing file.

Third party libraries

• hashmap.h has been utilized as the low level hashmap implementation
• xxHash (BSD 2-Clause) has been used for the hashing function used by the hashmap

Benchmarking

You can find the benchmarking scripts in the bench folder. The README file in that folder contains more detailed information on how to run them.

Wheel building

For building wheels for multiple Python versions, we use cibuildwheel. First install it:

pip install cibuildwheel

then run it:

python -m cibuildwheel --output-dir wheelhouse

License

This library is licensed under GNU GPL v3