Library Reference#

The Faultless AST for Open Biomedical Ontologies.

Functions#

fastobo.dump_graph(doc, file)#

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

Parameters:

file (str, os.PathLike 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(doc, file, format='ofn')#

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

Parameters:

file (str, os.PathLike or file-handle) – The path to a file, or a writable binary stream to write the serialized ontology 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, owx for OWL/XML syntax, rdf for RDX/XML 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(file, 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:

file (str, os.PathLike 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(file, 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(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:

TypeError – When the argument is not a str.
SyntaxError – When the document is not in valid OBO syntax.

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(file)#

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:

file (str, os.PathLike 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(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(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`)#

OboDoc

Abstract Base Classes (`fastobo.abc`)#

`AbstractClause`	An abstract clause.
`AbstractEntityClause`	An abstract entity clause.
`AbstractFrame`	An abstract OBO frame, storing a sequence of various clauses.
`AbstractEntityFrame`	An abstract entity frame, which clauses define an entity.

Identifier (`fastobo.id`)#

`BaseIdent`	A sequence of character used to refer to an OBO entity.
`PrefixedIdent`	An identifier with a prefix.
`UnprefixedIdent`	An identifier without a prefix.
`Url`	A URL used as an identifier.

Header (`fastobo.header`)#

Term (`fastobo.term`)#

Typedef (`fastobo.typedef`)#

Property Value (`fastobo.pv`)#

`AbstractPropertyValue`
`LiteralPropertyValue`
`ResourcePropertyValue`

Synonym (`fastobo.syn`)#

Synonym

Xref (`fastobo.xref`)#

`Xref`	A cross-reference to another entity or an external resource.
`XrefList`	A list of cross-references.

Qualifier (`fastobo.qual`)#

`Qualifier`	A qualifier used as a modifier for a clause.
`QualifierList`	A list of qualifiers.

Exceptions#

Cardinality Errors#

`MissingClauseError`	An error indicating a required clause is missing.
`DuplicateClausesError`	An error indicating a unique clause appears more than one.
`SingleClauseError`	An error indicating a clause appears only once when it shouldn't.

Threading Errors#

DisconnectedChannelError

`HeaderFrame`
`BaseHeaderClause`	A header clause, appearing in the OBO header frame.
`FormatVersionClause`
`DataVersionClause`
`DateClause`
`SavedByClause`
`AutoGeneratedByClause`
`ImportClause`
`SubsetdefClause`
`SynonymTypedefClause`
`DefaultNamespaceClause`
`IdspaceClause`
`TreatXrefsAsEquivalentClause`
`TreatXrefsAsGenusDifferentiaClause`
`TreatXrefsAsReverseGenusDifferentiaClause`
`TreatXrefsAsRelationshipClause`
`TreatXrefsAsIsAClause`
`TreatXrefsAsHasSubclassClause`
`PropertyValueClause`
`RemarkClause`
`OntologyClause`
`OwlAxiomsClause`
`UnreservedClause`

`TermFrame`
`BaseTermClause`	A term clause, appearing in an OBO term frame.
`AltIdClause`
`BuiltinClause`
`CommentClause`
`ConsiderClause`
`CreatedByClause`
`CreationDateClause`
`DefClause`
`DisjointFromClause`
`EquivalentToClause`
`IntersectionOfClause`
`IsAClause`
`IsAnonymousClause`
`IsObsoleteClause`
`NameClause`
`NamespaceClause`
`PropertyValueClause`
`RelationshipClause`
`ReplacedByClause`
`SubsetClause`
`SynonymClause`
`UnionOfClause`
`XrefClause`

`TypedefFrame`
`BaseTypedefClause`
`AltIdClause`
`BuiltinClause`
`CommentClause`
`ConsiderClause`
`CreatedByClause`
`CreationDateClause`
`DefClause`
`DisjointFromClause`
`DisjointOverClause`
`DomainClause`
`EquivalentToChainClause`
`EquivalentToClause`
`ExpandAssertionToClause`
`ExpandExpressionToClause`
`HoldsOverChainClause`
`IntersectionOfClause`
`InverseOfClause`
`IsAClause`
`IsAnonymousClause`
`IsAntiSymmetricClause`
`IsAsymmetricClause`
`IsClassLevelClause`
`IsCyclicClause`
`IsFunctionalClause`
`IsInverseFunctionalClause`
`IsMetadataTagClause`
`IsObsoleteClause`
`IsReflexiveClause`
`IsSymmetricClause`
`IsTransitiveClause`
`NameClause`
`NamespaceClause`
`PropertyValueClause`
`RangeClause`
`RelationshipClause`
`ReplacedByClause`
`SubsetClause`
`SynonymClause`
`TransitiveOverClause`
`UnionOfClause`
`XrefClause`

Library Reference#

Functions#

Data structures#

Document (fastobo.doc)#

Abstract Base Classes (fastobo.abc)#

Identifier (fastobo.id)#

Header (fastobo.header)#

Term (fastobo.term)#

Typedef (fastobo.typedef)#

Property Value (fastobo.pv)#

Synonym (fastobo.syn)#

Xref (fastobo.xref)#

Qualifier (fastobo.qual)#

Exceptions#

Cardinality Errors#

Threading Errors#

This Page

Document (`fastobo.doc`)#

Abstract Base Classes (`fastobo.abc`)#

Identifier (`fastobo.id`)#

Header (`fastobo.header`)#

Term (`fastobo.term`)#

Typedef (`fastobo.typedef`)#

Property Value (`fastobo.pv`)#

Synonym (`fastobo.syn`)#

Xref (`fastobo.xref`)#

Qualifier (`fastobo.qual`)#