robot-obo-tool

What this skill does

# 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:

```bash
# 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:

```bash
export ROBOT_JAVA_ARGS="-Xmx8G"
```

Verify installation:

```bash
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

| Command | Description | Key Example |
|---------|-------------|-------------|
| `merge` | Combine multiple ontologies | `robot merge --input a.owl --input b.owl --output merged.owl` |
| `reason` | Run reasoner, assert inferred axioms | `robot reason --reasoner ELK --input edit.owl --output reasoned.owl` |
| `relax` | Convert EquivalentClass to SubClassOf | `robot reason ... relax --output relaxed.owl` |
| `reduce` | Remove redundant SubClassOf axioms | `robot reason ... relax reduce --output reduced.owl` |
| `materialize` | Assert inferred superclass expressions | `robot materialize --reasoner ELK --input edit.owl --output mat.owl` |
| `unmerge` | Remove axioms of one ontology from another | `robot unmerge --input merged.owl --input remove.owl --output result.owl` |

### Extracting and Filtering

| Command | Description | Key Example |
|---------|-------------|-------------|
| `extract` | Extract module from ontology | `robot extract --method BOT --input ont.owl --term GO:0005634 --output module.owl` |
| `filter` | Keep only matching axioms | `robot filter --input ont.owl --term UBERON:0000955 --select "self ancestors" --output filtered.owl` |
| `remove` | Remove matching axioms | `robot remove --input ont.owl --select "imports" --output no-imports.owl` |

### Creating and Editing

| Command | Description | Key Example |
|---------|-------------|-------------|
| `template` | Generate OWL from TSV/CSV templates | `robot template --input ont.owl --template terms.tsv --output new-terms.owl` |
| `annotate` | Add ontology-level metadata | `robot annotate --input ont.owl --ontology-iri "http://purl.obolibrary.org/obo/my.owl" --output annotated.owl` |
| `rename` | Rename entity IRIs | `robot rename --input ont.owl --mappings mappings.tsv --output renamed.owl` |
| `expand` | Expand shortcut macros | `robot expand --input ont.owl --output expanded.owl` |
| `repair` | Fix deprecated class references | `robot repair --input ont.owl --output repaired.owl` |
| `collapse` | Collapse import hierarchy | `robot collapse --input ont.owl --output collapsed.owl` |

### Quality Control

| Command | Description | Key Example |
|---------|-------------|-------------|
| `report` | QC report with built-in checks | `robot report --input ont.owl --output report.tsv` |
| `verify` | Check SPARQL-based rules | `robot verify --input ont.owl --queries rules/*.sparql` |
| `validate-profile` | Validate OWL profile compliance | `robot validate-profile --input ont.owl --profile EL --output violations.tsv` |

### Querying and Exporting

| Command | Description | Key Example |
|---------|-------------|-------------|
| `query` | Run SPARQL queries | `robot query --input ont.owl --query q.sparql results.csv` |
| `export` | Export entities as table | `robot export --input ont.owl --header "ID\|LABEL\|SubClass Of" --export terms.csv` |
| `diff` | Compare two ontologies | `robot diff --left v1.owl --right v2.owl --output changes.md` |
| `measure` | Ontology metrics | `robot measure --input ont.owl --output metrics.tsv` |

### Debugging

| Command | Description | Key Example |
|---------|-------------|-------------|
| `explain` | Explain inferred axioms | `robot explain --input ont.owl --reasoner ELK --axiom "'eye' SubClassOf 'organ'" --explanation result.md` |

### Other

| Command | Description | Key Example |
|---------|-------------|-------------|
| `convert` | Convert between formats | `robot convert --input ont.owl --format obo --output ont.obo` |
| `mirror` | Download imported ontologies | `robot mirror --input ont.owl --directory mirror/ --output catalog.xml` |

## Deep Dive: Reasoning

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

### Reasoner Choice

| Reasoner | Speed | Expressivity | When to Use |
|----------|-------|-------------|-------------|
| **ELK** | Fast | EL++ (no negation/disjunction) | Default for most OBO ontologies |
| **HermiT** | Slow | Full OWL DL | When ELK misses inferences or you need full DL |
| **Whelk** | Fast | EL++ | Alternative to ELK, Scala-based |
| **Structural** | Very fast | None (syntactic only) | Quick checks, no reasoning |

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

### Key Options

```bash
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:

```bash
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:

```bash
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 Stru