Package: pyobo
Tools for biological identifiers, names, synonyms, xrefs, hierarchies, relations, and properties through the
perspective of OBO.Example UsageNote! PyOBO is no-nonsense. This means that there’s no repetitive
prefixes in identifiers. It also means all identifiers are strings,
no exceptions.Note! The first time you run these, they have to download and cache
all resources. We’re not in the business of redistributing data,
so all scripts should be completely reproducible. There’s some
AWS tools for hosting/downloading pre-compiled versions inpyobo.awsif you don’t have time for that.Note! PyOBO can perform grounding in a limited number of cases, but
it isnota general solution for named entity recognition (NER) or grounding.
It’s suggested to checkGildafor a no-nonsense solution.Mapping Identifiers and CURIEsGet mapping of ChEBI identifiers to names:importpyobochebi_id_to_name=pyobo.get_id_name_mapping('chebi')name=chebi_id_to_name['132964']assertname=='fluazifop-P-butyl'Or, you don’t have time for two lines:importpyoboname=pyobo.get_name('chebi','132964')assertname=='fluazifop-P-butyl'Get reverse mapping of ChEBI names to identifiers:importpyobochebi_name_to_id=pyobo.get_name_id_mapping('chebi')identifier=chebi_name_to_id['fluazifop-P-butyl']assertidentifier=='132964'Maybe you live in CURIE world and just want to normalize something likeCHEBI:132964:importpyoboname=pyobo.get_name_by_curie('CHEBI:132964')assertname=='fluazifop-P-butyl'Sometimes you accidentally got an old CURIE. It can be mapped to the more recent
one using alternative identifiers listed in the underlying OBO with:importpyobo# Look up DNA-binding transcription factor activity (go:0003700)# based on an old idprimary_curie=pyobo.get_primary_curie('go:0001071')assertprimary_curie=='go:0003700'# If it's already the primary, it just gets returnedassert'go:0003700'==pyobo.get_priority_curie('go:0003700')Mapping SpeciesSome resources have species information for their term. Get a mapping of WikiPathway identifiers
to species (as NCBI taxonomy identifiers):importpyobowikipathways_id_to_species=pyobo.get_id_species_mapping('wikipathways')# Apoptosis (Homo sapiens)taxonomy_id=wikipathways_id_to_species['WP254']asserttaxonomy_id=='9606'Or, you don’t have time for two lines:importpyobo# Apoptosis (Homo sapiens)taxonomy_id=pyobo.get_species('wikipathways','WP254')asserttaxonomy_id=='9606'GroundingMaybe you’ve got names/synonyms you want to try and map back to ChEBI synonyms.
Given the brand nameFusilade IIofCHEBI:132964, it should be able to look
it up and its preferred label.importpyoboprefix,identifier,name=pyobo.ground('chebi','Fusilade II')assertprefix=='chebi'assertidentifier=='132964'assertname=='fluazifop-P-butyl'# When failure happens...prefix,identifier,name=pyobo.ground('chebi','Definitely not a real name')assertprefixisNoneassertidentifierisNoneassertnameisNoneIf you’re not really sure which namespace a name might belong to, you
can try a few in a row (prioritize by ones that cover the appropriate
entity type to avoid false positives in case of conflicts):importpyobo# looking for phenotypes/pathwaysprefix,identifier,name=pyobo.ground(['efo','go'],'ERAD')assertprefix=='go'assertidentifier=='0030433'assertname=='ubiquitin-dependent ERAD pathway'Cross-referencingGet xrefs from ChEBI to PubChem:importpyobochebi_id_to_pubchem_compound_id=pyobo.get_filtered_xrefs('chebi','pubchem.compound')pubchem_compound_id=chebi_id_to_pubchem_compound_id['132964']assertpubchem_compound_id=='3033674'If you don’t have time for two lines:importpyobopubchem_compound_id=pyobo.get_xref('chebi','132964','pubchem.compound')assertpubchem_compound_id=='3033674'Get xrefs from Entrez to HGNC, but they’re only available through HGNC
so you need to flip them:importpyobohgnc_id_to_ncbigene_id=pyobo.get_filtered_xrefs('hgnc','ncbigene')ncbigene_id_to_hgnc_id={ncbigene_id:hgnc_idforhgnc_id,ncbigene_idinhgnc_id_to_ncbigene_id.items()}mapt_hgnc=ncbigene_id_to_hgnc_id['4137']assertmapt_hgnc=='6893'Since this is a common pattern, there’s a keyword argumentflipthat does this for you:importpyoboncbigene_id_to_hgnc_id=pyobo.get_filtered_xrefs('hgnc','ncbigene',flip=True)mapt_hgnc_id=ncbigene_id_to_hgnc_id['4137']assertmapt_hgnc_id=='6893'If you don’t have time for two lines (I admit this one is a bit confusing) and
need to flip it:importpyobohgnc_id=pyobo.get_xref('hgnc','4137','ncbigene',flip=True)asserthgnc_id=='6893'Remap a CURIE based on pre-defined priority list andInspector Javert’s Xref
Database:importpyobo# Map to the best source possiblemapt_ncbigene=pyobo.get_priority_curie('hgnc:6893')assertmapt_ncbigene=='ncbigene:4137'# Sometimes you know you're the best. Own it.assert'ncbigene:4137'==pyobo.get_priority_curie('ncbigene:4137')Find all CURIEs mapped to a given one using Inspector Javert’s Xref Database:importpyobo# Get a set of all CURIEs mapped to MAPTmapt_curies=pyobo.get_equivalent('hgnc:6893')assert'ncbigene:4137'inmapt_curiesassert'ensembl:ENSG00000186868'inmapt_curiesIf you don’t want to wait to build the database locally for thepyobo.get_priority_curieandpyobo.get_equivalent, you can use the following code to download a release fromZenodo:importpyobo.resource_utilspyobo.resource_utils.ensure_inspector_javert()PropertiesGet properties, like SMILES. The semantics of these are defined on an OBO-OBO basis.importpyobo# I don't make the rules. I wouldn't have chosen this as the key for this property. It could be any stringchebi_smiles_property='http://purl.obolibrary.org/obo/chebi/smiles'chebi_id_to_smiles=pyobo.get_filtered_properties_mapping('chebi',chebi_smiles_property)smiles=chebi_id_to_smiles['132964']assertsmiles=='C1(=CC=C(N=C1)OC2=CC=C(C=C2)O[C@@H](C(OCCCC)=O)C)C(F)(F)F'If you don’t have time for two lines:importpyobosmiles=pyobo.get_property('chebi','132964','http://purl.obolibrary.org/obo/chebi/smiles')assertsmiles=='C1(=CC=C(N=C1)OC2=CC=C(C=C2)O[C@@H](C(OCCCC)=O)C)C(F)(F)F'HierarchyCheck if an entity is in the hierarchy:importnetworkxasnximportpyobo# check that go:0008219 ! cell death is an ancestor of go:0006915 ! apoptotic processassert'go:0008219'inpyobo.get_ancestors('go','0006915')# check that go:0070246 ! natural killer cell apoptotic process is a# descendant of go:0006915 ! apoptotic processapopototic_process_descendants=pyobo.get_descendants('go','0006915')assert'go:0070246'inapopototic_process_descendantsGet the subhierarchy below a given node:# get the descendant graph of go:0006915 ! apoptotic processapopototic_process_subhierarchy=pyobo.get_subhierarchy('go','0006915')# check that go:0070246 ! natural killer cell apoptotic process is a# descendant of go:0006915 ! apoptotic process through the subhierarchyassert'go:0070246'inapopototic_process_subhierarchyGet a hierarchy with properties pre-loaded in the node data dictionaries:importpyoboprop='http://purl.obolibrary.org/obo/chebi/smiles'chebi_hierarchy=pyobo.get_hierarchy('chebi',properties=[prop])assert'chebi:132964'inchebi_hierarchyassertpropinchebi_hierarchy.nodes['chebi:132964']assertchebi_hierarchy.nodes['chebi:132964'][prop]=='C1(=CC=C(N=C1)OC2=CC=C(C=C2)O[C@@H](C(OCCCC)=O)C)C(F)(F)F'RelationsGet all orthologies (ro:HOM0000017) between HGNC and MGI (note: this is one way)>>>importpyobo>>>human_mapt_hgnc_id='6893'>>>mouse_mapt_mgi_id='97180'>>>hgnc_mgi_orthology_mapping=pyobo.get_relation_mapping('hgnc','ro:HOM0000017','mgi')>>>assertmouse_mapt_mgi_id==hgnc_mgi_orthology_mapping[human_mapt_hgnc_id]If you want to do it in one line, use:>>>importpyobo>>>human_mapt_hgnc_id='6893'>>>mouse_mapt_mgi_id='97180'>>>assertmouse_mapt_mgi_id==pyobo.get_relation('hgnc','ro:HOM0000017','mgi',human_mapt_hgnc_id)Writings Tests that Use PyOBOIf you’re writing your own code that relies on PyOBO, and unit
testing it (as you should) in a continuous integration setting,
you’ve probably realized that loading all of the resources on each
build is not so fast. In those scenarios, you can use some of the
pre-build patches like in the following:importunittestimportpyobofrompyobo.mocksimportget_mock_id_name_mappingmock_id_name_mapping=get_mock_id_name_mapping({'chebi':{'132964':'fluazifop-P-butyl',},})classMyTestCase(unittest.TestCase):defmy_test(self):withmock_id_name_mapping:# use functions directly, or use your functions that wrap thempyobo.get_name('chebi','1234')InstallationPyOBO can be installed fromPyPIwith:$pipinstallpyoboIt can be installed in development mode fromGitHubwith:$gitclonehttps://github.com/pyobo/pyobo.git$cdpyobo$pipinstall-e.Curation of the BioregistryIn order to normalize references and identify resources, PyOBO uses theBioregistry. It used to be a part of PyOBO, but has since
been externalized for more general reuse.Atsrc/pyobo/registries/metaregistry.jsonis the curated “metaregistry”. This is a source of information that contains
all sorts of fixes for missing/wrong information in MIRIAM, OLS, and OBO Foundry; entries that don’t appear in
any of them; additional synonym information for each namespace/prefix; rules for normalizing xrefs and CURIEs, etc.Other entries in the metaregistry:The"remappings"->"full"entry is a dictionary from strings that might followxref:in a given OBO file that need to be completely replaced, due to incorrect formattingThe"remappings"->"prefix"entry contains a dictionary of prefixes for xrefs that need
to be remapped. Several rules, for example, remove superfluous spaces that occur inside
CURIEs or and others address instances of the GOGO issue.The"blacklists"entry contains rules for throwing out malformed xrefs based on
full string, just prefix, or just suffix.TroubleshootingThe OBO Foundry seems to be pretty unstable with respect to the URLs to OBO resources. If you get an error like:pyobo.getters.MissingOboBuild: OBO Foundry is missing a build for: mondoThen you should check the corresponding page on the OBO Foundry (in this case,http://www.obofoundry.org/ontology/mondo.html)
and make update to theurlentry for that namespace in the Bioregistry.