Library Reference

The Faultless AST for Open Biomedical Ontologies.

Functions

fastobo.dump_graph

fastobo.dump_graph(doc, fh)

Dump an OBO graph into the given writer or file handle, serialized into a compact JSON representation.

Parameters
  • fh (str or file-handle) – The path to a file, or a writable binary stream to write the serialized graph into. A binary stream needs a write(b) method that accepts binary strings.

  • doc (OboDoc) – The OBO document to be converted into an OBO Graph.

Raises
  • TypeError – When the argument have invalid types.

  • ValueError – When the JSON serialization fails.

  • OSError – When an underlying OS error occurs.

Example

Use fastobo to convert an OBO file into an OBO graph:

>>> doc = fastobo.load("tests/data/plana.obo")
>>> fastobo.dump_graph(doc, "tests/data/plana.json")

fastobo.dump_owl

fastobo.dump_owl(doc, fh, format='ofn')

Convert an OBO ontology to OWL and write it to the given handle.

Parameters
  • fh (str or file-handle) – The path to a file, or a writable binary stream to write the serialized graph into. A binary stream needs a write(b) method that accepts bytes.

  • doc (OboDoc) – The OBO document to be converted into an OWL Ontology.

  • format (str) – The OWL format to serialize the converted OWL document into. Supported values are: ofn for Functional-style syntax.

Raises
  • TypeError – When the argument have invalid types.

  • ValueError – When the conversion to OWL fails.

  • OSError – When an underlying OS error occurs.

Example

Use fastobo to convert an OBO file into an OWL file:

>>> doc = fastobo.load("tests/data/ms.obo")
>>> fastobo.dump_owl(doc, "tests/data/ms.ofn", format="ofn")

Caution

This method is experimental. Conversion to OWL is provided on a best-effort basis using a dedicated Rust implementation of the OBO to OWL2-DL mapping. It should produce a document with correct syntax, but might fail to preserve the semantics. In such cases, consider opening an issue directly on the fastobo-owl issue tracker.

Hint

To support serialization to OWL, an OBO document is required to declare an ontology clause in the header. Furthermore, every entity frame must have a namespace clause, otherwise a default-namespace clause must be declared in the header. Failure to do both will result in a ValueError being thrown.

fastobo.iter

fastobo.iter(fh, ordered=True, threads=0)

Iterate over the frames contained in an OBO document.

The header frame can be accessed with the header method of the returned object. Entity frames are yielded one after like any Python iterator. See the Examples section.

Parameters
  • fh (str or file-handle) – The path to an OBO file, or a binary stream that contains a serialized OBO document. A binary stream needs a read(x) method returning x bytes.

  • ordered (bool) – Whether or not to yield the frames in the same order they are declared in the source document.

  • threads (int) – The number of threads to use for parsing. Set to 0 to detect the number of logical cores, 1 to use the single threadeded parser, or to any positive integer value.

Yields

AbstractFrame – The individual frames contained in the OBO document.

Raises
  • TypeError – When the argument is not a str or a binary stream.

  • SyntaxError – When the document is not in valid OBO syntax.

  • OSError – When an underlying OS error occurs.

Example

Use fastobo.iter to load an ontology frame-by-frame, even a larger one:

>>> reader = fastobo.iter('tests/data/ms.obo')
>>> reader.header()
HeaderFrame([...])
>>> next(reader)
TermFrame(PrefixedIdent('MS', '0000000'))
>>> list(reader)
[TermFrame(PrefixedIdent('MS', '1000001')), ...]

fastobo.load

fastobo.load(fh, threads=0)

Load an OBO document from the given path or file handle.

Parameters
  • fh (str or file-handle) – The path to an OBO file, or a binary stream that contains a serialized OBO document. A binary stream needs a read(x) method returning x bytes.

  • ordered (bool) – Whether or not to yield the frames in the same order they are declared in the source document.

  • threads (int) – The number of threads to use for parsing. Set to 0 to detect the number of logical cores, 1 to use the single threadeded parser, or to any positive integer value.

Returns

OboDoc – The OBO document deserialized into an Abstract Syntax Tree.

Raises
  • TypeError – When the argument is not a str or a binary stream.

  • SyntaxError – When the document is not in valid OBO syntax.

  • OSError – When an underlying OS error occurs.

Example

Use urlopen and fastobo.load to parse an ontology downloaded from the OBO Library:

>>> from urllib.request import urlopen
>>> url = "http://purl.obolibrary.org/obo/po.obo"
>>> doc = fastobo.load(urlopen(url))
>>> doc.header[3]
SubsetdefClause(UnprefixedIdent('Angiosperm'), 'Term for angiosperms')

fastobo.loads

fastobo.loads(document)

Load an OBO document from a string.

Parameters
  • document (str) – A string containing an OBO document.

  • ordered (bool) – Whether or not to yield the frames in the same order they are declared in the source document.

  • threads (int) – The number of threads to use for parsing. Set to 0 to detect the number of logical cores, 1 to use the single threadeded parser, or to any positive integer value.

Returns

OboDoc – The OBO document deserialized into an Abstract Syntax Tree.

Raises

Example

Use fastobo.loads to deserialize a literal OBO frame into the corresponding syntax tree:

>>> doc = fastobo.loads(textwrap.dedent(
...     """
...     [Term]
...     id: TST:001
...     name: test item
...     """
... ))
>>> doc[0].id
PrefixedIdent('TST', '001')
>>> doc[0][0]
NameClause('test item')

fastobo.load_graph

fastobo.load_graph(fh)

Load an OBO graph from the given path or file handle.

Both JSON and YAML formats are supported. Actually, since YAML is a superset of JSON, all graphs are in YAML format.

Parameters

fh (str or file-handle) – The path to an OBO graph file, or a binary stream that contains a serialized OBO document. A binary stream needs a read(x) method returning x bytes.

Returns

OboDoc – The first graph of the OBO graph converted to an OBO document. The schema allows for more than one graph but this is only used when merging imports into the same document.

Raises
  • TypeError – When the argument is not a str or a binary stream.

  • ValueError – When the JSON is not a valid OBO Graph.

  • SyntaxError – When the document contains invalid OBO identifiers.

  • OSError – When an underlying OS error occurs.

Example

Use urllib and fastobo to parse an ontology downloaded from the Berkeley BOP portal:

>>> from urllib.request import urlopen
>>> url = "http://purl.obolibrary.org/obo/pato.json"
>>> graph = fastobo.load_graph(urlopen(url))
>>> terms = [
...     term for term in graph
...     if isinstance(term.id, fastobo.id.PrefixedIdent)
...     and term.id.prefix == "PATO"
... ]
>>> min(terms, key=lambda term: str(term.id))
TermFrame(PrefixedIdent('PATO', '0000000'))

fastobo.id.is_valid

fastobo.id.is_valid(s)

Check whether or not a string is a valid OBO identifier.

Arguments

s (str): the identifier to validate.

Returns

bool – whether or not the string is valid as an OBO identifier.

Example
>>> fastobo.id.is_valid("MS:1000031")
True
>>> fastobo.id.is_valid("https://purl.obolibrary.org/obo/MS_1000031")
True
>>> fastobo.id.is_valid("related_to")
True
>>> fastobo.id.is_valid("definitely not an identifier")
False

fastobo.id.parse

fastobo.id.parse(s)

Parse a string into an OBO identifier.

Parameters

s (str) – the string representation of an OBO identifier

Returns

BaseIdent – the appropriate concrete subclass that can store the given identifier.

Raises

ValueError – when the string could not be parsed as a valid OBO identifier.

Example

>>> fastobo.id.parse("MS:1000031")
PrefixedIdent('MS', '1000031')
>>> fastobo.id.parse("part_of")
UnprefixedIdent('part_of')
>>> fastobo.id.parse("http://purl.obolibrary.org/obo/IAO_0000231")
Url('http://purl.obolibrary.org/obo/IAO_0000231')

Data structures

Document (fastobo.doc)

fastobo.doc.OboDoc

The abstract syntax tree corresponding to an OBO document.

Abstract Base Classes (fastobo.abc)

fastobo.abc.AbstractClause

An abstract clause.

fastobo.abc.AbstractEntityClause

An abstract entity clause.

fastobo.abc.AbstractFrame

An abstract OBO frame, storing a sequence of various clauses.

fastobo.abc.AbstractEntityFrame

An abstract entity frame, which clauses define an entity.

Identifier (fastobo.id)

fastobo.id.BaseIdent

A sequence of character used to refer to an OBO entity.

fastobo.id.PrefixedIdent

An identifier with a prefix.

fastobo.id.UnprefixedIdent

An identifier without a prefix.

fastobo.id.Url

A URL used as an identifier.

Header (fastobo.header)

fastobo.header.HeaderFrame

fastobo.header.BaseHeaderClause

A header clause, appearing in the OBO header frame.

fastobo.header.FormatVersionClause

A header clause indicating the format version of the OBO document.

fastobo.header.DataVersionClause

A header clause indicating the version of the data in the OBO document.

fastobo.header.DateClause

A header clause indicating the date the document was last modified.

fastobo.header.SavedByClause

A header clause containing the name of the person who saved the document.

fastobo.header.AutoGeneratedByClause

A header clause indicating the software that generated the document.

fastobo.header.ImportClause

A clause with a URL or ontology ID referencing another OBO document.

fastobo.header.SubsetdefClause

A header clause declaring a subset in the OBO document.

fastobo.header.SynonymTypedefClause

A header clause declaring a synonym type in the OBO document.

fastobo.header.DefaultNamespaceClause

A clause declaring the default namespace for the rest of the document.

fastobo.header.IdspaceClause

A clause giving the mapping between a “local” and a “global” ID space.

fastobo.header.TreatXrefsAsEquivalentClause

A macro to treats xrefs coming from an ID space as equivalence statements.

fastobo.header.TreatXrefsAsGenusDifferentiaClause

A macro to treats xrefs from an ID space as genus-differentia definitions.

fastobo.header.TreatXrefsAsReverseGenusDifferentiaClause

A macro to treats xrefs from an ID space as reverse genus-differentia definitions.

fastobo.header.TreatXrefsAsRelationshipClause

A macro to treats xrefs from an ID space as being relationships.

fastobo.header.TreatXrefsAsIsAClause

A macro to treats xrefs from an ID space as being subclassing relations.

fastobo.header.TreatXrefsAsHasSubclassClause

A macro to treats xrefs from an ID space as being superclassing relations.

fastobo.header.PropertyValueClause

A clause that binds a property to a value in the OBO document.

fastobo.header.RemarkClause

A header clause storing general comments for the current OBO file.

fastobo.header.OntologyClause

The ontology ID of the current OBO file.

fastobo.header.OwlAxiomsClause

A header clause containing untranslatable OWL axioms.

fastobo.header.UnreservedClause

A tag/value pair not reserved in the OBO specification.

Term (fastobo.term)

fastobo.term.TermFrame

fastobo.term.BaseTermClause

A term clause, appearing in an OBO term frame.

fastobo.term.AltIdClause

A clause defines an alternate id for this term.

fastobo.term.BuiltinClause

A clause declaring whether or not this term is built-in to the OBO format.

fastobo.term.CommentClause

A clause storing a comment for this term.

fastobo.term.ConsiderClause

A clause giving a potential substitute for an obsolete term.

fastobo.term.CreatedByClause

A term clause stating the name of the creator of this term.

fastobo.term.CreationDateClause

A clause declaring the date (and optionally time) a term was created.

fastobo.term.DefClause

A clause giving a human-readable definition of the term.

fastobo.term.DisjointFromClause

A clause stating this term has no instances in common with another term.

fastobo.term.EquivalentToClause

A clause indicating the term is exactly equivalent to another term.

fastobo.term.IntersectionOfClause

A clause stating this term is equivalent to the intersection of other terms.

fastobo.term.IsAClause

A clause declaring this term is a subclass of another term.

fastobo.term.IsAnonymousClause

A clause declaring whether or not the current term has an anonymous id.

fastobo.term.IsObsoleteClause

A clause indicating whether or not this term is obsolete.

fastobo.term.NameClause

A term clause declaring the human-readable name of this term.

fastobo.term.NamespaceClause

A term clause declaring the namespace of this term.

fastobo.term.PropertyValueClause

A clause that binds a property to a value in the term.

fastobo.term.RelationshipClause

A clause describing a typed relationship between this term and another term.

fastobo.term.ReplacedByClause

A clause giving a term which replaces this obsolete term.

fastobo.term.SubsetClause

A clause declaring a subset to which this term belongs.

fastobo.term.SynonymClause

A clause giving a synonym for this term, with some cross-references.

fastobo.term.UnionOfClause

A clause indicating the term represents the union of several other terms.

fastobo.term.XrefClause

A cross-reference that describes an analogous term in another vocabulary.

Typedef (fastobo.typedef)

fastobo.typedef.TypedefFrame

fastobo.typedef.BaseTypedefClause

fastobo.typedef.AltIdClause

A clause defines an alternate id for this relationship.

fastobo.typedef.BuiltinClause

A clause declaring whether this relation is built-in to the OBO format.

fastobo.typedef.CommentClause

A clause storing a comment for this relationship.

fastobo.typedef.ConsiderClause

A clause giving a potential substitute for an obsolete typedef.

fastobo.typedef.CreatedByClause

A term clause stating the name of the creator of this relationship.

fastobo.typedef.CreationDateClause

A clause declaring the date (and optionally time) a typedef was created.

fastobo.typedef.DefClause

A clause giving a human-readable definition of the relationship.

fastobo.typedef.DisjointFromClause

A clause stating is disjoint from another relationship.

fastobo.typedef.DisjointOverClause

A clause declaring a relationship this relationship is disjoint over.

fastobo.typedef.DomainClause

A clause declaring the domain of the relationship, if any.

fastobo.typedef.EquivalentToChainClause

A clause declaring a property chain this relationship is equivalent to.

fastobo.typedef.EquivalentToClause

A clause indicating the relation is exactly equivalent to another relation.

fastobo.typedef.ExpandAssertionToClause

An OWL macro that adds an IAO:0000425 annotation to this relation.

fastobo.typedef.ExpandExpressionToClause

An OWL macro that adds an IAO:0000424 annotation to this relation.

fastobo.typedef.HoldsOverChainClause

An extension of the transitive_over tag for property chains.

fastobo.typedef.IntersectionOfClause

Declares this relation is equivalent to the intersection of other relations.

fastobo.typedef.InverseOfClause

A clause declaring the inverse of this relationship type.

fastobo.typedef.IsAClause

A clause declaring this relation is a subproperty of another relation.

fastobo.typedef.IsAnonymousClause

A clause declaring whether or not the relationship has an anonymous id.

fastobo.typedef.IsAntiSymmetricClause

A clause declaring whether the relationship if anti-symmetric or not.

fastobo.typedef.IsAsymmetricClause

A clause declaring whether the relationship is asymmetric or not.

fastobo.typedef.IsClassLevelClause

A clause declaring wether this relationship is class level or not.

fastobo.typedef.IsCyclicClause

A clause declaring whether the relationship if cyclic or not.

fastobo.typedef.IsFunctionalClause

A clause declaring whether the relationship if functional or not.

fastobo.typedef.IsInverseFunctionalClause

A clause declaring whether the relationship if inverse-functional or not.

fastobo.typedef.IsMetadataTagClause

A clause declaring whether this relationship is a metadata tag or not.

fastobo.typedef.IsObsoleteClause

A clause indicating whether or not this relationship is obsolete.

fastobo.typedef.IsReflexiveClause

A clause declaring whether the relationship if reflexive or not.

fastobo.typedef.IsSymmetricClause

A clause declaring whether the relationship if symmetric or not.

fastobo.typedef.IsTransitiveClause

A clause declaring whether the relationship if transitive or not.

fastobo.typedef.NameClause

A clause declaring the human-readable name of this relationship.

fastobo.typedef.NamespaceClause

A term clause declaring the namespace of this relationship.

fastobo.typedef.PropertyValueClause

A clause that binds a property to a value in the relationship.

fastobo.typedef.RangeClause

A clause declaring the range of the relationship, if any.

fastobo.typedef.RelationshipClause

A clause declaring a relationship this relation has to another relation.

fastobo.typedef.ReplacedByClause

A clause giving a relation which replaces this obsolete relation.

fastobo.typedef.SubsetClause

A clause declaring a subset to which this relationship belongs.

fastobo.typedef.SynonymClause

A clause giving a synonym for this relation, with some cross-references.

fastobo.typedef.TransitiveOverClause

A clause declaring another relation that this relation is transitive over.

fastobo.typedef.UnionOfClause

Declares the relation represents the union of several other relations.

fastobo.typedef.XrefClause

A cross-reference describing an analogous relation in another vocabulary.

Xref (fastobo.xref)

fastobo.xref.Xref

A cross-reference to another entity or an external resource.

fastobo.xref.XrefList

A list of cross-references.

Exceptions

Cardinality Errors

fastobo.exceptions.MissingClauseError

An error indicating a required clause is missing.

fastobo.exceptions.DuplicateClausesError

An error indicating a unique clause appears more than one.

fastobo.exceptions.SingleClauseError

An error indicating a clause appears only once when it shouldn’t.