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("plana.obo")
>>> fastobo.dump_graph(doc, "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("ms.obo")
>>> fastobo.dump_owl(doc, "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('ms.obo')
>>> reader.header()
HeaderFrame([...])
>>> next(reader)
TermFrame(PrefixedIdent('MS', '0000000'))
>>> list(reader)
[TermFrame(PrefixedIdent('MS', '1000001')), ...]

fastobo.load

fastobo.load(fh, ordered=True, 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, ordered=True, threads=0)

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 fastobo to parse an ontology graph in JSON format:

>>> graph = fastobo.load_graph("pato.json")
>>> 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

--

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

--

fastobo.header.DataVersionClause

--

fastobo.header.DateClause

--

fastobo.header.SavedByClause

--

fastobo.header.AutoGeneratedByClause

--

fastobo.header.ImportClause

--

fastobo.header.SubsetdefClause

--

fastobo.header.SynonymTypedefClause

--

fastobo.header.DefaultNamespaceClause

--

fastobo.header.IdspaceClause

--

fastobo.header.TreatXrefsAsEquivalentClause

--

fastobo.header.TreatXrefsAsGenusDifferentiaClause

--

fastobo.header.TreatXrefsAsReverseGenusDifferentiaClause

--

fastobo.header.TreatXrefsAsRelationshipClause

--

fastobo.header.TreatXrefsAsIsAClause

--

fastobo.header.TreatXrefsAsHasSubclassClause

--

fastobo.header.PropertyValueClause

--

fastobo.header.RemarkClause

--

fastobo.header.OntologyClause

--

fastobo.header.OwlAxiomsClause

--

fastobo.header.UnreservedClause

--

Term (fastobo.term)

fastobo.term.TermFrame

fastobo.term.BaseTermClause

A term clause, appearing in an OBO term frame.

fastobo.term.AltIdClause

--

fastobo.term.BuiltinClause

--

fastobo.term.CommentClause

--

fastobo.term.ConsiderClause

--

fastobo.term.CreatedByClause

--

fastobo.term.CreationDateClause

--

fastobo.term.DefClause

--

fastobo.term.DisjointFromClause

--

fastobo.term.EquivalentToClause

--

fastobo.term.IntersectionOfClause

--

fastobo.term.IsAClause

--

fastobo.term.IsAnonymousClause

--

fastobo.term.IsObsoleteClause

--

fastobo.term.NameClause

--

fastobo.term.NamespaceClause

--

fastobo.term.PropertyValueClause

--

fastobo.term.RelationshipClause

--

fastobo.term.ReplacedByClause

--

fastobo.term.SubsetClause

--

fastobo.term.SynonymClause

--

fastobo.term.UnionOfClause

--

fastobo.term.XrefClause

--

Typedef (fastobo.typedef)

fastobo.typedef.TypedefFrame

fastobo.typedef.BaseTypedefClause

fastobo.typedef.AltIdClause

--

fastobo.typedef.BuiltinClause

--

fastobo.typedef.CommentClause

--

fastobo.typedef.ConsiderClause

--

fastobo.typedef.CreatedByClause

--

fastobo.typedef.CreationDateClause

--

fastobo.typedef.DefClause

--

fastobo.typedef.DisjointFromClause

--

fastobo.typedef.DisjointOverClause

--

fastobo.typedef.DomainClause

--

fastobo.typedef.EquivalentToChainClause

--

fastobo.typedef.EquivalentToClause

--

fastobo.typedef.ExpandAssertionToClause

--

fastobo.typedef.ExpandExpressionToClause

--

fastobo.typedef.HoldsOverChainClause

--

fastobo.typedef.IntersectionOfClause

--

fastobo.typedef.InverseOfClause

--

fastobo.typedef.IsAClause

--

fastobo.typedef.IsAnonymousClause

--

fastobo.typedef.IsAntiSymmetricClause

--

fastobo.typedef.IsAsymmetricClause

--

fastobo.typedef.IsClassLevelClause

--

fastobo.typedef.IsCyclicClause

--

fastobo.typedef.IsFunctionalClause

--

fastobo.typedef.IsInverseFunctionalClause

--

fastobo.typedef.IsMetadataTagClause

--

fastobo.typedef.IsObsoleteClause

--

fastobo.typedef.IsReflexiveClause

--

fastobo.typedef.IsSymmetricClause

--

fastobo.typedef.IsTransitiveClause

--

fastobo.typedef.NameClause

--

fastobo.typedef.NamespaceClause

--

fastobo.typedef.PropertyValueClause

--

fastobo.typedef.RangeClause

--

fastobo.typedef.RelationshipClause

--

fastobo.typedef.ReplacedByClause

--

fastobo.typedef.SubsetClause

--

fastobo.typedef.SynonymClause

--

fastobo.typedef.TransitiveOverClause

--

fastobo.typedef.UnionOfClause

--

fastobo.typedef.XrefClause

--

Property Value (fastobo.pv)

fastobo.pv.AbstractPropertyValue

fastobo.pv.LiteralPropertyValue

fastobo.pv.ResourcePropertyValue

Synonym (fastobo.syn)

fastobo.syn.Synonym

fastobo.syn.SynonymScope

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.

Threading Errors

fastobo.exceptions.DisconnectedChannelError