PyBEL |zenodo| |build| |windows_build| |coverage| |documentation|
=================================================================
`PyBEL <http://pybel.readthedocs.io>`_ is a pure Python package for parsing and handling biological networks encoded in
the `Biological Expression Language <https://biological-expression-language.github.io/>`_
(BEL).

It facilitates data interchange between data formats like `NetworkX <http://networkx.github.io/>`_,
Node-Link JSON, `JGIF <https://github.com/jsongraph/json-graph-specification>`_, CSV, SIF,
`Cytoscape <http://www.cytoscape.org/>`_, `CX <http://www.home.ndexbio.org/data-model/>`_,
`INDRA <https://github.com/sorgerlab/indra>`_, and `GraphDati <https://github.com/graphdati/schemas>`_; database systems
like SQL and `Neo4J <https://neo4j.com>`_; and web services like `NDEx <https://github.com/pybel/pybel2cx>`_,
`BioDati Studio <https://biodati.com/>`_, and `BEL Commons <https://bel-commons-dev.scai.fraunhofer.de>`_. It also
provides exports for analytical tools like `HiPathia <http://hipathia.babelomics.org/>`_,
`Drug2ways <https://github.com/drug2ways/>`_ and `SPIA <https://bioconductor.org/packages/release/bioc/html/SPIA.html>`_;
machine learning tools like `PyKEEN <https://github.com/smartdataanalytics/biokeen>`_ and
`OpenBioLink <https://github.com/OpenBioLink/OpenBioLink#biological-expression-language-bel-writer>`_; and others.

Its companion package, `PyBEL Tools <http://pybel-tools.readthedocs.io/>`_, contains a
suite of functions and pipelines for analyzing the resulting biological networks.

We realize that we have a name conflict with the python wrapper for the cheminformatics package, OpenBabel. If you're
looking for their python wrapper, see `here <https://github.com/openbabel/openbabel/tree/master/scripts/python>`_.

Citation
--------
If you find PyBEL useful for your work, please consider citing:

.. [1] Hoyt, C. T., *et al.* (2017). `PyBEL: a Computational Framework for Biological Expression Language
       <https://doi.org/10.1093/bioinformatics/btx660>`_. *Bioinformatics*, 34(December), 1–2.

Installation |pypi_version| |python_versions| |pypi_license|
------------------------------------------------------------
PyBEL can be installed easily from `PyPI <https://pypi.python.org/pypi/pybel>`_ with the following code in
your favorite shell:

.. code-block:: sh

    $ pip install pybel

or from the latest code on `GitHub <https://github.com/pybel/pybel>`_ with:

.. code-block:: sh

    $ pip install git+https://github.com/pybel/pybel.git

See the `installation documentation <https://pybel.readthedocs.io/en/latest/introduction/installation.html>`_ for more advanced
instructions. Also, check the change log at `CHANGELOG.rst <https://github.com/pybel/pybel/blob/master/CHANGELOG.rst>`_.

Note: while PyBEL works on the most recent versions of Python 3.5, it does not work on 3.5.3 or below due to changes
in the ``typing`` module.

Getting Started
---------------
More examples can be found in the `documentation <http://pybel.readthedocs.io>`_ and in the
`PyBEL Notebooks <https://github.com/pybel/pybel-notebooks>`_ repository.

Compiling and Saving a BEL Graph
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This example illustrates how the a BEL document from the `Human Brain Pharmacome
<https://raw.githubusercontent.com/pharmacome/knowledge>`_ project can be loaded from GitHub.

.. code-block:: python

   >>> import pybel
   >>> url = 'https://raw.githubusercontent.com/pharmacome/knowledge/master/hbp_knowledge/proteostasis/kim2013.bel'
   >>> graph = pybel.from_url(url)

PyBEL can handle `BEL 1.0 <https://github.com/OpenBEL/language/raw/master/docs/version_1.0/bel_specification_version_1.0.pdf>`_
and `BEL 2.0+ <https://github.com/OpenBEL/language/raw/master/docs/version_2.0/bel_specification_version_2.0.pdf>`_
simultaneously.

After you have a BEL graph, there are numerous ways to save it. The ``pybel.dump`` function knows
how to output it in many formats based on the file extension you give. For all of the possibilities,
check the `I/O documentation <https://pybel.readthedocs.io/en/latest/reference/io.html>`_.

.. code-block:: python

   >>> import pybel
   >>> graph = ...
   >>> # write as BEL
   >>> pybel.dump(graph, 'my_graph.bel')
   >>> # write as Node-Link JSON for network viewers like D3
   >>> pybel.dump(graph, 'my_graph.bel.nodelink.json')
   >>> # write as GraphDati JSON for BioDati
   >>> pybel.dump(graph, 'my_graph.bel.graphdati.json')
   >>> # write as CX JSON for NDEx
   >>> pybel.dump(graph, 'my_graph.bel.cx.json')

Grounding the Graph
~~~~~~~~~~~~~~~~~~~
Not all BEL graphs contain both the name and identifier for each entity. Some even use non-standard prefixes
(also called **namespaces** in BEL). Usually, BEL graphs are validated against controlled vocabularies,
so the following demo shows how to add the corresponding identifiers to all nodes.

.. code-block:: python

    from urllib.request import urlretrieve

    url = 'https://github.com/cthoyt/selventa-knowledge/blob/master/selventa_knowledge/large_corpus.bel.nodelink.json.gz'
    urlretrieve(url, 'large_corpus.bel.nodelink.json.gz')

    import pybel
    graph = pybel.load('large_corpus.bel.nodelink.json.gz')

    import pybel.grounding
    grounded_graph = pybel.grounding.ground(graph)

Note: you have to install ``pyobo`` for this to work and be running Python 3.7+.

Displaying a BEL Graph in Jupyter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After installing ``jinja2`` and ``ipython``, BEL graphs can be displayed in Jupyter notebooks.

.. code-block:: python

   >>> from pybel.examples import sialic_acid_graph
   >>> from pybel.io.jupyter import to_jupyter
   >>> to_jupyter(sialic_acid_graph)

Using the CLI
~~~~~~~~~~~~~
PyBEL also installs a command line interface with the command :code:`pybel` for simple utilities such as data
conversion. In this example, a BEL document is compiled then exported to `GraphML <http://graphml.graphdrawing.org/>`_
for viewing in Cytoscape.

.. code-block:: sh

    $ pybel compile ~/Desktop/example.bel
    $ pybel serialize ~/Desktop/example.bel --graphml ~/Desktop/example.graphml

In Cytoscape, open with :code:`Import > Network > From File`.

Contributing
------------
Contributions, whether filing an issue, making a pull request, or forking, are appreciated. See
`CONTRIBUTING.rst <https://github.com/pybel/pybel/blob/master/CONTRIBUTING.rst>`_ for more information on getting
involved.

Acknowledgements
----------------
Funding
~~~~~~~
The development of PyBEL has been funded by several projects/organizations:

- `Enveda Therapeutics <https://envedatherapeutics.com/>`_
- `University of Bonn <https://www.uni-bonn.de>`_
- `Fraunhofer Center for Machine Learning <https://www.cit.fraunhofer.de/de/zentren/maschinelles-lernen.html>`_
- `The Cytoscape Consortium <https://cytoscape.org/>`_
- The `European Union <https://europa.eu>`_, `European Federation of Pharmaceutical Industries and Associations
  (EFPIA) <https://www.efpia.eu/>`_, and `Innovative Medicines Initiative <https://www.imi.europa.eu>`_ Joint
  Undertaking under `AETIONOMY <https://www.aetionomy.eu/>`_ [grant number 115568], resources of which
  are composed of financial contribution from the European Union's Seventh Framework Programme (FP7/2007-2013) and
  EFPIA companies in kind contribution.
- `Fraunhofer Institute for Algorithms and Scientific Computing (SCAI) <https://www.scai.fraunhofer.de>`_

Logo
~~~~
The PyBEL `logo <https://github.com/pybel/pybel-art>`_ was designed by `Scott Colby <https://github.com/scolby33>`_.

.. |build| image:: https://travis-ci.com/pybel/pybel.svg?branch=develop
    :target: https://travis-ci.com/pybel/pybel
    :alt: Development Build Status

.. |windows_build| image:: https://ci.appveyor.com/api/projects/status/v22l3ymg3bdq525d/branch/develop?svg=true
    :target: https://ci.appveyor.com/project/cthoyt/pybel
    :alt: Development Windows Build Status

.. |coverage| image:: https://codecov.io/gh/pybel/pybel/coverage.svg?branch=develop
    :target: https://codecov.io/gh/pybel/pybel/branch/develop
    :alt: Development Coverage Status

.. |documentation| image:: https://readthedocs.org/projects/pybel/badge/?version=latest
    :target: http://pybel.readthedocs.io/en/latest/
    :alt: Development Documentation Status

.. |climate| image:: https://codeclimate.com/github/pybel/pybel/badges/gpa.svg
    :target: https://codeclimate.com/github/pybel/pybel
    :alt: Code Climate

.. |python_versions| image:: https://img.shields.io/pypi/pyversions/PyBEL.svg
    :target: https://pypi.python.org/pypi/pybel
    :alt: Stable Supported Python Versions

.. |pypi_version| image:: https://img.shields.io/pypi/v/PyBEL.svg
    :target: https://pypi.python.org/pypi/pybel
    :alt: Current version on PyPI

.. |pypi_license| image:: https://img.shields.io/pypi/l/PyBEL.svg
    :target: https://github.com/pybel/pybel/blob/master/LICENSE
    :alt: MIT License

.. |zenodo| image:: https://zenodo.org/badge/68376693.svg
    :target: https://zenodo.org/badge/latestdoi/68376693
