#
# This file is part of bioservices software
#
# Copyright (c) 2013-2014 - EBI-EMBL
#
# File author(s):
# Thomas Cokelaer <cokelaer@ebi.ac.uk>
#
# Distributed under the GPLv3 License.
# See accompanying file LICENSE.txt or copy at
# http://www.gnu.org/licenses/gpl-3.0.html
#
# website: https://github.com/cokelaer/bioservices
# documentation: http://packages.python.org/bioservices
#
##############################################################################
"""Interface to the Reactome webs services
.. topic:: What is Reactome?
:URL: http://www.reactome.org/ReactomeGWT/entrypoint.html
:Citation: http://www.reactome.org/citation.html
:REST: http://reactomews.oicr.on.ca:8080/ReactomeRESTfulAPI/RESTfulWS
.. highlights::
"REACTOME is an open-source, open access, manually curated and peer-reviewed
pathway database. Pathway annotations are authored by expert biologists, in
collaboration with Reactome editorial staff and cross-referenced to many
bioinformatics databases. These include NCBI Entrez Gene, Ensembl and UniProt
databases, the UCSC and HapMap Genome Browsers, the KEGG Compound and ChEBI
small molecule databases, PubMed, and Gene Ontology. ... "
-- from Reactome web site
"""
from bioservices.services import REST
__all__ = ["Reactome"]
[docs]class Reactome:
"""Interface to the `Reactome <https://reactome.org>`_ knowledgebase.
Reactome is an open-source, manually curated and peer-reviewed pathway
database. This class wraps the Reactome ContentService REST API.
.. doctest::
>>> from bioservices import Reactome
>>> r = Reactome()
>>> r.get_species_main()
.. todo:: interactors, orthology, participants, person,
query, references, schema
"""
_url = "https://reactome.org/ContentService"
def __init__(self, verbose=True, cache=False):
"""**Constructor**
:param bool verbose: set to False to prevent informative messages
:param bool cache: set to True to enable HTTP caching
"""
self.services = REST(name="Reactome", url=Reactome._url, verbose="ERROR", cache=False)
self.debugLevel = verbose
@property
def version(self):
return self.services.http_get("data/database/version", frmt="txt")
@property
def name(self):
return self.services.http_get("data/database/name", frmt="txt")
[docs] def get_discover(self, identifier):
"""The schema.org for an Event in Reactome knowledgebase
For each event (reaction or pathway) this method generates a
json file representing the dataset object as defined by
schema.org (http). This is mainly used by search engines in
order to index the data
:param str identifier: a Reactome stable identifier (e.g., ``"R-HSA-446203"``)
:return: schema.org JSON-LD representation of the event
::
r.get_discover("R-HSA-446203")
"""
res = self.services.http_get("data/discover/{}".format(identifier), frmt="json")
return res
[docs] def get_diseases(self):
"""list of diseases objects"""
return self.services.http_get("data/diseases", frmt="json")
[docs] def get_diseases_doid(self):
"""retrieves the list of disease DOIDs annotated in Reactome
:return: dictionary with DOID contained in the values()
"""
res = self.services.http_get("data/diseases/doid", frmt="txt")
res = dict([x.split() for x in res.split("\n")])
return res
[docs] def get_interactors_psicquic_molecule_details(self):
"""Retrieve clustered interaction, sorted by score, of a given accession by resource."""
raise NotImplementedError
[docs] def get_interactors_psicquic_molecule_summary(self):
"""Retrieve a summary of a given accession by resource"""
raise NotImplementedError
[docs] def get_interactors_psicquic_resources(self):
"""Retrieve a list of all Psicquic Registries services"""
raise NotImplementedError
[docs] def get_interactors_static_molecule_details(self):
"""Retrieve a detailed interaction information of a given accession"""
raise NotImplementedError
[docs] def get_interactors_static_molecule_pathways(self):
"""Retrieve a list of lower level pathways where the interacting molecules can be found"""
raise NotImplementedError
[docs] def get_interactors_static_molecule_summary(self):
"""Retrieve a summary of a given accession"""
raise NotImplementedError
[docs] def get_exporter_fireworks(self):
raise NotImplementedError
[docs] def get_exporter_reaction(self):
raise NotImplementedError
[docs] def get_exporter_diagram(
self,
identifier,
ext="png",
quality=5,
diagramProfile="Modern",
analysisProfile="Standard",
filename=None,
):
"""Export a given pathway diagram to raster file
This method accepts identifiers for Event class instances.
When a diagrammed pathway is provided, the diagram is exported
to the specified format. When a subpathway is provided, the
diagram for the parent is exported and the events that are part
of the subpathways are selected. When a reaction is provided,
the diagram containing the reaction is exported and the reaction
is selected.
:param str identifier: event identifier (pathway with diagram, subpathway, or reaction)
:param str ext: file extension / image format — one of ``"png"``, ``"jpeg"``,
``"jpg"``, ``"svg"``, ``"gif"``
:param int quality: result image quality between 1 and 10 (default 5)
:param str diagramProfile: diagram color profile (``"Modern"`` or ``"Standard"``)
:param str analysisProfile: analysis color profile
:param str filename: if given, save the result to this file path
:return: raw image data if *filename* is not set; ``None`` after saving otherwise
"""
if ext not in ["png", "jpg", "jpeg", "svg", "gif"]:
raise ValueError("ext must be one of: png, jpg, jpeg, svg, gif")
if quality not in range(11):
raise ValueError("quality must be between 0 and 10")
if diagramProfile not in ["Modern", "Standard"]:
raise ValueError("diagramProfile must be 'Modern' or 'Standard'")
if analysisProfile not in ["Standard", "Strosobar", "Copper Plus"]:
raise ValueError("analysisProfile must be 'Standard', 'Strosobar', or 'Copper Plus'")
params = {
"diagramProfile": diagramProfile,
"analysisProfile": analysisProfile,
"quality": quality,
}
res = self.services.http_get("exporter/diagram/{}.{}".format(identifier, ext), params=params, frmt=ext)
if filename:
if ext != "svg":
with open(filename, "wb") as fout:
fout.write(res)
else:
with open(filename, "w") as fout:
fout.write(res)
else:
return res
[docs] def get_complex_subunits(self, identifier, excludeStructuresSpecifies=False):
"""A list with the entities contained in a given complex
Retrieves the list of subunits that constitute any given complex.
In case the complex comprises other complexes, this method
recursively traverses the content returning each contained
PhysicalEntity. Contained complexes and entity sets can be
excluded setting the ‘excludeStructures’ optional parameter to ‘true’
:param str identifier: a Reactome stable identifier for the complex
:param bool excludeStructuresSpecifies: if True, exclude contained complexes
and entity sets from the response
::
r.get_complex_subunits("R-HSA-5674003")
"""
params = {"excludeStructuresSpecifies": excludeStructuresSpecifies}
res = self.services.http_get("data/complex/{}/subunits".format(identifier), params=params, frmt="json")
return res
[docs] def get_complexes(self, resources, identifier):
"""A list of complexes containing the pair (identifier, resource)
Retrieves the list of complexes that contain a given (identifier,
resource). The method deconstructs the complexes into all its
participants to do so.
:param str resources: the resource of the identifier (e.g., ``"UniProt"``)
:param str identifier: the identifier for which complexes are requested
::
r.get_complexes(resources, identifier)
r.get_complexes("UniProt", "P43403")
"""
res = self.services.http_get("data/complexes/{}/{}".format(resources, identifier), frmt="json")
return res
[docs] def get_entity_componentOf(self, identifier):
"""A list of larger structures containing the entity
Retrieves the list of structures (Complexes and Sets) that
include the given entity as their component. It should be
mentioned that the list includes only simplified entries
(type, names, ids) and not full information about each item.
::
r.get_entity_componentOf("R-HSA-199420")
"""
res = self.services.http_get("data/entity/{}/componentOf".format(identifier), frmt="json")
return res
[docs] def get_event_ancestors(self, identifier):
"""The ancestors of a given event
The Reactome definition of events includes pathways and reactions.
Although events are organised in a hierarchical structure, a single
event can be in more than one location, i.e. a reaction can take
part in different pathways while, in the same way, a sub-pathway
can take part in many pathways. Therefore, this method retrieves
a list of all possible paths from the requested event to the top
level pathway(s).
:param str identifier: a Reactome stable identifier for the event
::
r.get_event_ancestors("R-HSA-5673001")
"""
res = self.services.http_get("data/event/{}/ancestors".format(identifier), frmt="json")
return res
[docs] def get_eventsHierarchy(self, species):
"""The full event hierarchy for a given species
Events (pathways and reactions) in Reactome are organised in a
hierarchical structure for every species. By following all
‘hasEvent’ relationships, this method retrieves the full event
hierarchy for any given species. The result is a list of tree
structures, one for each TopLevelPathway. Every event in these trees is
represented by a PathwayBrowserNode. The latter contains the stable identifier,
the name, the species, the url, the type, and the diagram of the particular
event.
:param species: taxonomy ID (e.g., ``9606``) or species name (e.g., ``"Homo sapiens"``)
::
r.get_eventsHierarchy(9606)
"""
res = self.services.http_get("data/eventsHierarchy/{}".format(species), frmt="json")
return res
[docs] def get_exporter_sbml(self, identifier):
"""Export given Pathway to SBML
:param str identifier: DbId or StId of the requested pathway
::
r.exporter_sbml("R-HSA-68616")
"""
res = self.services.http_get("exporter/sbml/{}.xml".format(identifier), frmt="xml")
return res
[docs] def get_pathway_containedEvents(self, identifier):
"""All the events contained in the given event
Events are the building blocks used in Reactome to represent
all biological processes, and they include pathways and reactions.
Typically, an event can contain other events. For example, a
pathway can contain smaller pathways and reactions. This method
recursively retrieves all the events contained in any given event.
::
res = r.get_pathway_containedEvents("R-HSA-5673001")
"""
res = self.services.http_get("data/pathway/{}/containedEvents".format(identifier), frmt="json")
return res
[docs] def get_pathway_containedEvents_by_attribute(self, identifier, attribute):
"""A single property for each event contained in the given event
Events are the building blocks used in Reactome to represent all
biological processes, and they include pathways and reactions.
Typically, an event can contain other events. For example, a
pathway can contain smaller pathways (subpathways) and reactions.
This method recursively retrieves a single attribute for each of
the events contained in the given event.
:param identifier: The event for which the contained events are requested
:param str identifier: the event for which the contained events are requested
:param str attribute: attribute to filter (e.g., ``"stId"``)
::
r.get_pathway_containedEvents_by_attribute("R-HSA-5673001", "stId")
"""
res = self.services.http_get(
"data/pathway/{}/containedEvents/{}".format(identifier, attribute),
frmt="txt",
)
try:
res = [x.strip() for x in res[1:-1].split(",")]
except Exception:
pass
return res
[docs] def get_pathways_low_diagram_entity(self, identifier):
"""A list of lower level pathways with diagram containing
a given entity or event
This method traverses the event hierarchy and retrieves the
list of all lower level pathways that have a diagram and
contain the given PhysicalEntity or Event.
:param str identifier: the entity that has to be present in the pathways
::
r.get_pathways_low_diagram_entity("R-HSA-199420")
"""
res = self.services.http_get("data/pathways/low/diagram/entity/{}".format(identifier), frmt="json")
return res
[docs] def get_pathways_low_entity(self, identifier):
"""A list of lower level pathways containing a given entity or event
This method traverses the event hierarchy and retrieves the
list of all lower level pathways that contain the given
PhysicalEntity or Event.
::
r.get_pathways_low_entity("R-HSA-199420")
"""
res = self.services.http_get("data/pathways/low/entity/{}".format(identifier), frmt="json")
return res
[docs] def get_pathways_top(self, species):
"""Retrieve the list of top-level pathways for a given species.
:param species: taxonomy ID (e.g., ``9606``) or species name (e.g., ``"Homo sapiens"``)
:return: list of top-level pathway objects
"""
res = self.services.http_get("data/pathways/top/{}".format(species), frmt="json")
return res
[docs] def get_references(self, identifier):
"""All referenceEntities for a given identifier
Retrieves a list containing all the reference entities for a given
identifier.
::
r.get_references(15377)
"""
res = self.services.http_get("references/mapping/{}".format(identifier), frmt="json")
return res
[docs] def get_mapping_identifier_pathways(self, resource, identifier):
"""Retrieve pathways containing a mapped identifier.
:param str resource: the external resource (e.g., ``"UniProt"``)
:param str identifier: the identifier to map (e.g., ``"P43403"``)
:return: list of pathway objects
"""
res = self.services.http_get("data/mapping/{}/{}/pathways".format(resource, identifier), frmt="json")
return res
[docs] def get_mapping_identifier_reactions(self, resource, identifier):
"""Retrieve reactions containing a mapped identifier.
:param str resource: the external resource (e.g., ``"UniProt"``)
:param str identifier: the identifier to map (e.g., ``"P43403"``)
:return: list of reaction objects
"""
res = self.services.http_get("data/mapping/{}/{}/reactions".format(resource, identifier), frmt="json")
return res
[docs] def search_facet(self):
"""A list of facets corresponding to the whole Reactome search data
This method retrieves faceting information on the whole Reactome search data.
"""
res = self.services.http_get("search/facet", frmt="json")
return res
[docs] def search_facet_query(self, query):
"""A list of facets corresponding to a specific query
This method retrieves faceting information on a specific query
"""
res = self.services.http_get("search/facet_query?query={}".format(query), frmt="json")
return res
[docs] def search_query(self, query):
"""Queries Solr against the Reactome knowledgebase
This method performs a Solr query on the Reactome knowledgebase.
Results can be provided in a paginated format.
"""
res = self.services.http_get("search/query?query={}".format(query), frmt="json")
return res
[docs] def search_spellcheck(self, query):
"""Spell-check suggestions for a given query
This method retrieves a list of spell-check suggestions
for a given search term.
"""
res = self.services.http_get("search/spellcheck?query={}".format(query), frmt="json")
return res
[docs] def search_suggest(self, query):
"""Autosuggestions for a given query.
This method retrieves a list of suggestions for a given search term.
:param str query: search term (e.g., ``"apopt"``)
:return: list of suggestion strings
::
>>> r.search_suggest("apopt")
['apoptosis', 'apoptosome', 'apoptosome-mediated', 'apoptotic']
"""
res = self.services.http_get("search/suggest?query={}".format(query), frmt="json")
return res
[docs] def get_species_all(self):
"""the list of all species in Reactome"""
res = self.services.http_get("data/species/all", frmt="json")
return res
[docs] def get_species_main(self):
"""the list of main species in Reactome
::
r.get_species_main()
"""
res = self.services.http_get("data/species/main", frmt="json")
return res
"""
class ReactomePathway(object):
def __init__(self, entry):
self.raw_data = copy.deepcopy(entry)
# just adding the attributes to make life easier
for k in self.raw_data._keyord:
setattr(self, k, getattr(self.raw_data, k))
def __str__(self):
txt = "id: " + str(self.id)
txt += "\nname: " + str(self.name)
txt += "\nhasComponent:"
if self.hasComponent:
txt += str(len(self.hasComponent))
if self.raw_data.compartment:
txt += "\ncompartment:" + str(len(self.raw_data.compartment))
else:
txt += "\ncompartment: " + str(self.raw_data.compartment)
txt += "\nliteratureReference:"
this = self.raw_data.literatureReference
if this:
for i,x in enumerate(this):
txt += " --- %s: %s %s\n" % (i, x.id, x.name)
txt += "\nspecies:"
this = self.raw_data.species
if this:
txt += " %s (%s)" % (this.scientificName, this.id)
txt += "\nsummation:"
this = self.raw_data.summation
if this:
for x in this:
txt += " - %s \n" % (self.raw_data.id)
txt += "\ngoBiologicalProcess:"
this = self.raw_data.goBiologicalProcess
if this: txt += "\n - %s %s\n" % (this.id, this.name)
txt += "\ninferredFrom:" + str(self.raw_data.inferredFrom)
txt += "\northologousEvent: "
this = self.raw_data.orthologousEvent
if this:
txt += str(len(this))
txt += "\nprecedingEvent: " + str(self.raw_data.precedingEvent)
txt += "\nevidence Type: " + str(self.raw_data.evidenceType) + "\n"
return txt
"""