ROBOT Guide

Overview

ROBOT (ROBOT is an OBO Tool) is the standard command-line tool for OBO ontology development. It handles reasoning, quality control, format conversion, module extraction, template-based term generation, and release automation. Almost every OBO Foundry ontology uses ROBOT in its build pipeline.

ROBOT is a Java application distributed as a JAR with a shell wrapper script.

Home page: <https://robot.obolibrary.org/>

When to Use

Use ROBOT when you need to:

• Reason over an ontology - classify, check consistency, find unsatisfiable classes
• Generate terms from templates - create OWL from TSV/CSV spreadsheets
• Run quality control - check for missing labels, definitions, bad xrefs
• Convert formats - between OWL, OBO, Turtle, OFN, Manchester, JSON
• Extract modules - pull subsets from large ontologies
• Diff ontologies - compare two versions at the OWL level (consider OAK for higher level diffs)
• Query with SPARQL - run SELECT/CONSTRUCT/ASK queries
• Build release pipelines - chain commands for automated releases

Do NOT use ROBOT when:

• You want to search external ontologies interactively - use OAK or OLS MCP instead
• You want to edit individual OBO stanzas by hand - use obo-grep/obo-checkout tools instead
• You need programmatic ontology access from Python - use oaklib instead

Installation & Setup

ROBOT requires Java 8+. Install via:

# Download latest
curl -L https://github.com/ontodev/robot/releases/latest/download/robot.jar -o robot.jar
curl -L https://raw.githubusercontent.com/ontodev/robot/master/bin/robot -o robot
chmod +x robot

For large ontologies, increase Java memory:

export ROBOT_JAVA_ARGS="-Xmx8G"

Verify installation:

robot --version

Command Quick Reference

Every ROBOT command with a one-line description and key example. For full details on any command, read the corresponding file in docs/ within this skill directory.

Core Ontology Operations

Extracting and Filtering

Creating and Editing

Quality Control

Querying and Exporting

Debugging

Other

Deep Dive: Reasoning

Reasoning is the most critical ROBOT operation. It validates logical consistency and infers new axioms from existing definitions.

Reasoner Choice

Most OBO ontologies use ELK. Only use HermiT when you specifically need full OWL DL reasoning.

Key Options

robot reason \
  --reasoner ELK \
  --equivalent-classes-allowed asserted-only \
  --exclude-tautologies structural \
  --input edit.owl \
  --output reasoned.owl

• --equivalent-classes-allowed asserted-only - Fail if reasoning produces unexpected equivalent class pairs (catches modeling errors)
• --exclude-tautologies structural - Skip trivially true axioms
• --annotate-inferred-axioms true - Mark inferred axioms with is_inferred true annotation
• --exclude-duplicate-axioms true - Skip axioms already in imports
• --create-new-ontology true - Put inferences in a separate ontology

Debugging Unsatisfiable Classes with explain

When reasoning finds unsatisfiable classes (classes that cannot have any instances), use explain to generate human-readable markdown explanations:

robot merge --input ont.owl \
  explain \
    --reasoner ELK \
    -M unsatisfiability \
    --unsatisfiable all \
    --explanation unsats.md

This generates a markdown file showing the chain of axioms that leads to each unsatisfiability. This is invaluable for debugging.

You can also explain specific entailments:

robot explain --input ont.owl \
  --reasoner ELK \
  --axiom "'retina' SubClassOf 'part of' some 'eye'" \
  --explanation explanation.md

The --axiom uses Manchester OWL syntax. Use single quotes around class/property names that contain spaces.

Deep Dive: Templates

ROBOT templates let you create OWL ontology content from TSV/CSV spreadsheets. This is the preferred way to manage large sets of terms that follow regular patterns, because domain experts can edit spreadsheets without learning OWL.

Template File Structure

A ROBOT template is a TSV (or CSV) file with:

• Row 1: Human-readable column headers
• Row 2: ROBOT template strings (tell ROBOT how to convert each column to OWL)
• Row 3+: Data rows (one per term)

Template String Reference

#### Identity and Type

#### Annotations

#### Class Axioms

#### Modifiers

Real-World Template Example (OBI-style)

Here is a simplified template for defining assay types, based on patterns from the OBI ontology:

assays.tsv:

ontology ID	label	definition	parent class	has part	evaluant	associated axiom
ID	LABEL	AL definition@en	SC %	SC 'has part' some % SPLIT=|	SC ('has specified input' some (% and 'has role' some 'evaluant role'))	C %
OBI:0000070	assay	A planned process with the objective to produce information about a material entity.	OBI:0000011
OBI:0000716	ChIP-seq assay	An assay using chromatin immunoprecipitation followed by sequencing.	OBI:0000070	OBI:0000626
OBI:0000087	fluorescence microscopy assay	A light microscopy assay using specimen fluorescence.	OBI:0000070		'material entity' and ('has characteristic' some fluorescence)

Key patterns to notice:

• SC % for simple parent class
• SC 'has part' some % SPLIT=| for multiple parts separated by |
• SC ('has specified input' some (% and 'has role' some 'evaluant role')) for complex restrictions using Manchester syntax
• C % combined with CLASS_TYPE for flexible subclass/equivalent declarations
• Empty cells are skipped (no axiom generated)

Template Build Integration

Templates are typically processed in a Makefile:

# Generate OWL module from template
src/ontology/modules/%.owl: src/ontology/templates/%.tsv
	$(ROBOT) merge --input src/ontology/edit.owl \
	template --template $< \
	annotate --ontology-iri "http://purl.obolibrary.org/obo/ont/modules/$(notdir $@)" \
	--output $@

The merge --input before template is critical: it provides the base ontology so that CURIEs in the template can be resolved.

Merging Strategies

• No merge (default): Template result is a standalone ontology
• --merge-before: Merge template result into the input ontology immediately
• --merge-after: Keep template result separate, merge for subsequent chained commands

Template Tips

• Use SPLIT=| when a cell needs multiple values (e.g., multiple synonyms, multiple parents)
• Manchester syntax in template cells must use single quotes around names with spaces: 'has part' some 'protein complex'
• Use --force true during development to continue past errors
• Use --errors errors.tsv to capture template errors to a file
• The >A, >AT, >AL, >AI templates add axiom annotations to the preceding logical axiom

Common Pipelines

Release Pipeline

The standard OBO ontology release workflow:

robot merge --input src/ontology/edit.owl \
  reason --reasoner ELK \
    --equivalent-classes-allowed asserted-only \
    --exclude-tautologies structural \
  relax \
  reduce \
  annotate \
    --ontology-iri "http://purl.obolibrary.org/obo/ONT.owl" \
    --version-iri "http://purl.obolibrary.org/obo/ONT/releases/2024-01-01/ONT.owl" \
    --annotation owl:versionInfo "2024-01-01" \
  convert --format obo \
  --output ONT.obo

Template Pipeline

Generate terms and merge into the ontology:

robot merge --input edit.owl \
  template --template new-terms.tsv \
  --merge-before \
  annotate --ontology-iri "http://example.org/ont.owl" \
  --output result.owl

QC Pipeline

Run quality control before release:

robot report --input edit.owl \
  --fail-on ERROR \
  --output qc-report.tsv

Or with custom rules:

robot verify --input edit.owl \
  --queries src/sparql/qc-*.sparql \
  --output-dir reports/

Module Extraction

Extract a focused module around specific terms:

robot extract --method BOT \
  --input large-ont.owl \
  --term-file my-terms.txt \
  --output module.owl

Extraction methods:

• BOT (most common): Includes superclasses and related axioms
• TOP: Includes subclasses
• STAR: Minimal module (seed + inter-relations)
• MIREOT: Preserves hierarchy, requires upper/lower terms
• subset: Just seed terms + relations between them

Common Pitfalls

Java Memory

Large ontologies (Uberon, GO, ChEBI) need more memory:

export ROBOT_JAVA_ARGS="-Xmx8G"    # 8 GB
export ROBOT_JAVA_ARGS="-Xmx16G"   # 16 GB for very large ontologies

Symptom: java.lang.OutOfMemoryError: Java heap space

Reasoner Timeouts

If ELK is too slow, check for:

• Circular definitions
• Complex nested class expressions
• Large numbers of disjointness axioms

If HermiT hangs, try ELK (it handles most OBO use cases).

OBO Format Conversion Issues

robot convert --format obo may fail with --check true (default). Common causes:

• Classes with multiple labels
• Untranslatable OWL axioms (GCIs, complex restrictions)

Fix with --check false or use --clean-obo options:

robot convert --format obo \
  --clean-obo drop-extra-labels drop-untranslatable-axioms \
  --output ont.obo

Template Quoting

In TSV templates, be careful with:

• Tab characters (use actual tabs, not spaces)
• Manchester syntax quoting: use single quotes for names with spaces
• CURIE resolution: ensure all prefixes are defined (via --prefix or input ontology)

Unsatisfiable Classes

If reason reports unsatisfiable classes:

1. First, generate explanations: robot explain -M unsatisfiability --unsatisfiable all --explanation unsats.md
2. Read the markdown - it shows the axiom chain causing each unsatisfiability
3. Common causes: incorrect disjointness axioms, wrong domain/range restrictions, conflicting definitions
4. Fix the source ontology and re-run reasoning

Import Resolution

If ROBOT cannot find imported ontologies:

robot --catalog catalog-v001.xml merge --input edit.owl ...

The catalog XML maps import IRIs to local files.

Chaining Commands

ROBOT's most powerful feature is command chaining. Instead of writing intermediate files:

# Without chaining (slow, creates temp files)
robot merge --input a.owl --input b.owl --output merged.owl
robot reason --input merged.owl --output reasoned.owl
robot convert --input reasoned.owl --format obo --output result.obo

Chain commands (fast, no intermediate files):

robot merge --input a.owl --input b.owl \
  reason --reasoner ELK \
  convert --format obo \
  --output result.obo

Only the first command needs --input and only the last needs --output. Each command passes its result to the next.

Global Options

These apply to all commands:

# Custom prefixes
robot --prefix "MYONT: http://example.org/myont/" merge ...

# Import catalog
robot --catalog catalog-v001.xml merge ...

# Verbosity
robot -v merge ...     # WARN level
robot -vv merge ...    # INFO level
robot -vvv merge ...   # DEBUG level with stack traces

# Strict mode (fail on unparsed triples)
robot --strict merge ...

Reference

For detailed documentation on every command option, read the files in the docs/ subdirectory of this skill:

• docs/reason.md - Full reasoning documentation
• docs/template.md - Full template documentation
• docs/explain.md - Full explain documentation
• docs/extract.md - Module extraction methods
• docs/report.md - QC report configuration
• docs/query.md - SPARQL query execution
• docs/chaining.md - Command chaining details
• docs/global.md - Global options (prefixes, catalogs, Java)
• docs/examples/ - Example ontology files, templates, and SPARQL queries
• docs/report_queries/ - Built-in QC report query definitions