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:
- 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 acceptsbytes
.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 anamespace
clause, otherwise adefault-namespace
clause must be declared in the header. Failure to do both will result in aValueError
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 returningx
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 returningx
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
andfastobo.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:
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
¶
- 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 returningx
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
)¶
-- |
Abstract Base Classes (fastobo.abc
)¶
An abstract clause. |
|
An abstract entity clause. |
|
An abstract OBO frame, storing a sequence of various clauses. |
|
An abstract entity frame, which clauses define an entity. |
Identifier (fastobo.id
)¶
A sequence of character used to refer to an OBO entity. |
|
An identifier with a prefix. |
|
An identifier without a prefix. |
|
A URL used as an identifier. |
Header (fastobo.header
)¶
A header clause, appearing in the OBO header frame. |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
Term (fastobo.term
)¶
A term clause, appearing in an OBO term frame. |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
Typedef (fastobo.typedef
)¶
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
|
-- |
Property Value (fastobo.pv
)¶
Synonym (fastobo.syn
)¶
Xref (fastobo.xref
)¶
A cross-reference to another entity or an external resource. |
|
A list of cross-references. |
Exceptions¶
Cardinality Errors¶
An error indicating a required clause is missing. |
|
An error indicating a unique clause appears more than one. |
|
An error indicating a clause appears only once when it shouldn't. |