==========
apybiomart
==========
.. image:: https://img.shields.io/pypi/v/apybiomart.svg
:target: https://pypi.python.org/pypi/apybiomart
.. image:: https://www.repostatus.org/badges/latest/wip.svg
:alt: Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.
:target: https://www.repostatus.org/#wip
.. image:: https://travis-ci.com/robertopreste/apybiomart.svg?branch=master
:target: https://travis-ci.com/robertopreste/apybiomart
:alt: Travis CI build status
.. image:: https://circleci.com/gh/robertopreste/apybiomart.svg?style=svg
:target: https://circleci.com/gh/robertopreste/apybiomart
:alt: CircleCI build status
.. image:: https://codecov.io/gh/robertopreste/apybiomart/branch/master/graph/badge.svg
:target: https://codecov.io/gh/robertopreste/apybiomart
:alt: Codecov status
.. image:: https://readthedocs.org/projects/apybiomart/badge/?version=latest
:target: https://apybiomart.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://pyup.io/repos/github/robertopreste/apybiomart/shield.svg
:target: https://pyup.io/repos/github/robertopreste/apybiomart/
:alt: Updates
.. image:: https://pyup.io/repos/github/robertopreste/apybiomart/python-3-shield.svg
:target: https://pyup.io/repos/github/robertopreste/apybiomart/
:alt: Python 3
.. image:: https://pepy.tech/badge/apybiomart
:target: https://pepy.tech/project/apybiomart
:alt: Downloads
Async pythonic interface to BioMart.
* Free software: MIT license
* Documentation: https://apybiomart.readthedocs.io
* GitHub repo: https://github.com/robertopreste/apybiomart
Features
========
apybiomart is a Python module which provides a simple asynchronous interface to Ensembl BioMart_. Users can exploit the async interface to schedule multiple queries using all the commodities offered by Python's asyncio library.
Depending on specific needs, apybiomart offers different entry points:
* an asynchronous ``aquery()`` function, to schedule multiple queries in the same event loop;
* a synchronous ``query()`` function, which can be used for exploratory queries, executed in real time;
* a set of synchronous ``find_*()`` functions, which can be used to retrieve the list of available
marts (``find_marts()``), datasets for a specific mart (``find_datasets()``), attributes
(``find_attributes()``) and filters (``find_filters()``) for a specific dataset.
- a set of related CLI commands also exists to allow exploration of these data from the command
line; these are, respectively, ``apybiomart marts``, ``apybiomart datasets``,
``apybiomart attributes`` and ``apybiomart filters``. Run ``apybiomart --help`` for further
details.
Please refer to the Usage_ section of the documentation for further information.
Background
----------
apybiomart was originally born as a fork of the great pybiomart_ package.
I was working on a project that employed a series of async calls to several online resources, but
I couldn't manage to perform asynchronous calls to BioMart using that package, so I decided to
modify it to better suit my needs. However, it gradually evolved into a very different thing:
the original implementation was rewritten and the structure of the package changed a bit, in a
way that I found most useful for my purpose.
This said, all the credits go to jrderuiter_, which created the original pybiomart_ package.
Installation
============
**apybiomart only supports Python 3**, and can be installed using pip::
pip install apybiomart
Please refer to the Installation_ section of the documentation for further information.
Credits
=======
This package was created with Cookiecutter_ and the `cc-pypackage`_ project template.
.. _BioMart: https://www.ensembl.org/biomart/martview
.. _Usage: https://apybiomart.readthedocs.io/en/latest/usage.html
.. _pybiomart: https://github.com/jrderuiter/pybiomart
.. _jrderuiter: https://github.com/jrderuiter
.. _Installation: https://apybiomart.readthedocs.io/en/latest/installation.html
.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`cc-pypackage`: https://github.com/robertopreste/cc-pypackage
=======
History
=======
0.1.0 (2019-03-26)
==================
* First development release.
0.1.1 (2019-03-27)
------------------
* Requests are converted to async calls;
* Code style is clean and Python 3 compatible.
0.1.2 (2019-03-27)
------------------
* Add basic tests.
0.2.0 (2019-03-31)
==================
* New version with different organisation of classes and functions;
* Sync ``query`` and async ``aquery`` functions to query Biomart;
* Sync ``list_*`` functions to retrieve available ``marts``, ``datasets``, ``filters`` and ``attributes``.
0.2.1 (2019-04-01)
------------------
* Add tests.
0.2.2 (2019-04-01)
------------------
* Basic functions working and tested;
* Fix documentation;
* Update requirements.
0.2.3 (2019-04-02)
------------------
* Update requirements;
* Fix type hints for query functions;
* Reorganise query classes into a single class;
* Update documentation.
0.2.4 (2019-04-04)
------------------
* Fix type hints;
* Fix docstrings in classes;
* Add docstrings to main entry points.
0.2.5 (2019-04-09)
------------------
* Fix test files with new BioMart versions;
* Add script to create test files automatically.
0.2.6 (2019-04-29)
------------------
* Update test files;
* Fix and update documentation.
0.3.0 (2019-05-05)
==================
* Change ``list_*`` functions names to ``find_*`` for better compliance;
* Update documentation.
0.3.1 (2019-05-11)
------------------
* Fix requirements handling;
* Add function to check internet connection.
0.3.2 (2019-05-29)
------------------
* Correct minor typos;
* Update documentation and testfiles.
0.3.3 (2019-07-29)
------------------
* Fix #37 - issue with the requests module not installed.
0.3.4 (2019-08-23)
------------------
* Better handling of filters arguments for ``query()`` and ``aquery()`` functions;
* Convert docstrings to Google style;
* Fix documentation.
0.3.5 (2019-08-25)
------------------
* Relax requirement versions.
0.4.0 (2020-01-26)
==================
* Add CLI commands for finding marts, datasets, attributes and filters;
* Change output dataframe column names.
0.5.0 (2020-03-22)
==================
* Add CLI and Python module options to save outputs to CSV file.
0.5.1 (2020-04-04)
------------------
* Add option to specify the output CSV filename.
0.5.2 (2020-06-06)
------------------
* Update tests and test files;
* Clean code;
* Add CI module.
0.5.3 (2020-11-30)
------------------
* Remove deprecated ``pd.np`` occurrencies;
* Update test files.