fastobo / fastobo-graphs

OBO Graphs decoder and encoder in Rust.

fastobo

Faultless AST for Open Biomedical Ontologies.

Overview

This library provides a mostly-complete implementation of the OBO flat file format 1.4.

• Data structures - fastobo provides a complete owned AST for the OBO language, with constructors and covenience traits where applicable. There is a plan to provide borrowed data structures as well, to be able to build a view of an OBO document from borrowed data.
• Parsing - The parser is implemented using pest, and is reexported from the fastobo-syntax crate. Most structures implement the FromPair trait which allows to build a data structure from a stream of pest tokens.
• Errors - All functions in that crate that return a Result will always use the Error struct defined in the error module. Errors reported by pest are very meaningful, and can give the exact location of a syntax error encountered by the parser.
• Semantics - This library exports specific methods that can be used to edit an OBO syntax tree with the semantics expected in the format guide: mapping identifiers to URLs, adding default namespaces, or expanding entity frames using treat-xrefs macros.

Warning: this project adheres to Semantic Versioning, but the API is likely to change a lot before the release of a stable 1.0.

Features

All the following features are enabled by default, but can be disabled and cherry-picked using the default-features = false option in the Cargo.toml manifest of your project:

• memchr - Use the memchr library to improve parser speed when searching for a particular character in a buffer.
• threading - Use a multi-threaded parser (additionally depending on crossbeam-channel), which can greatly improve the parser speed if parsing is CPU-bound.
• smartstring - Use the smartstring library to reduce heap allocation for identifiers and string data.

Usage

Add fastobo to the [dependencies] sections of your Cargo.toml manifest:

[dependencies]
fastobo = "0.15.2"

The top-level fastobo module provides several functions to parse an OboDoc. Use fastobo::from_reader to load an OBO document from a BufRead implementor (use std::io::BufReader if needed):

extern crate fastobo;
extern crate ureq;

fn main() {
    let response = ureq::get("http://purl.obolibrary.org/obo/ms.obo").call();
    let mut reader = std::io::BufReader::new(response.unwrap().into_reader());

    match fastobo::from_reader(&mut reader) {
        Ok(doc) => println!("Number of MS entities: {}", doc.entities().len()),
        Err(e) => panic!("Could not parse the Mass-Spec Ontology: {}", e),
    }
}

See also

• fastobo-syntax: Standalone pest parser for the OBO format version 1.4.
• fastobo-graphs: Data model and serde implementation of the OBO graphs specification, with conversion traits from and to OBO.
• fastobo-py: Idiomatic Python bindings to this crate.
• fastobo-validator: Standalone CLI to validate OBO files against the specification.
• horned-functional: Parser for OWL2 Functional Syntax (can be used to parse owl-axioms clauses).

Feedback

Found a bug ? Have an enhancement request ? Head over to the GitHub issue tracker of the project if you need to report or ask something. If you are filling in on a bug, please include as much information as you can about the issue, and try to recreate the same bug in a simple, easily reproducible situation.

About

This project was developed by Martin Larralde as part of a Master's Degree internship in the BBOP team of the Lawrence Berkeley National Laboratory, under the supervision of Chris Mungall. Cite this project as:

Larralde M. Developing Python and Rust libraries to improve the ontology ecosystem [version 1; not peer reviewed]. F1000Research 2019, 8(ISCB Comm J):1500 (poster) (https://doi.org/10.7490/f1000research.1117405.1)

fastobo-graphs's Issues

obojson parser requires optional fields to be present

given:

{
  "graphs": [
    {
      "id": "test",
      "nodes": [
        {
          "id": "GO:0005773",
          "lbl": "vacuole",
          "meta": {
            "definition": {
              "val": "..."
            }
          }
        }
      ]
    }
  ]
}

pronto gives:

  File "/Users/cjm/Library/Caches/pypoetry/virtualenvs/oaklib-OeQZizwE-py3.9/lib/python3.9/site-packages/pronto/parsers/obojson.py", line 19, in parse_from
    doc = fastobo.load_graph(handle).compact_ids()
ValueError: graphs[0].nodes[0].meta.definition: missing field `xrefs` at line 10 column 27

this can be fixed with inclusion of empty dicts and lists

{
  "graphs": [
      {
          
          "id": "test",
          "meta": {},
          "equivalentNodesSets": [],
          "logicalDefinitionAxioms": [],
          "domainRangeAxioms": [],
          "propertyChainAxioms": [],
          "nodes": [
              {
                  "id": "GO:0005773",
                  "lbl": "vacuole",
                  "meta": {
                      "definition": {
                          "val": "...",
                          "xrefs": []
                          
                      }
                  }
              }
          ]
      }
  ]
}

but this imposes a bit of a burden on lightweight producers

Sort OBO graph before serializing

This is actually helpful for geneontology/obographs#47 and INCATools/ontology-development-kit#150 (although none are using fastobo ATM).