-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathindex.html
511 lines (470 loc) · 21.5 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="generator" content="pandoc">
<meta name="author" content="James Overton & Becky Tauber">
<title>ROBOT Tutorial</title>
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, minimal-ui">
<link rel="stylesheet" href="resources/css/reveal.css">
<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
</style>
<link rel="stylesheet" href="resources/css/sky.css" id="theme">
<!-- Printing and PDF exports
<script>
var link = document.createElement( 'link' );
link.rel = 'stylesheet';
link.type = 'text/css';
link.href = window.location.search.match( /print-pdf/gi ) ? 'https://raw.githubusercontent.com/hakimel/reveal.js/master/css/print/pdf.css' : 'https://raw.githubusercontent.com/hakimel/reveal.js/master/css/print/paper.css';
document.getElementsByTagName( 'head' )[0].appendChild( link );
</script>
-->
<!--[if lt IE 9]>
<script src="http://lab.hakim.se/reveal-js/lib/js/html5shiv.js"></script>
<![endif]-->
</head>
<body>
<div class="reveal">
<div class="slides">
<section id="title-slide">
<h1 class="title">ROBOT Tutorial</h1>
<p class="author">James Overton & Becky Jackson</p>
</section>
<section><section id="overview" class="title-slide slide level1"><h1>Overview</h1></section><section class="slide level2">
<ol>
<li>Manual editing</li>
<li>Repetitive tasks</li>
<li>Automated workflows</li>
<li>Quality assurance</li>
<li>Modular development</li>
<li>Modular releases</li>
<li>Other commands</li>
</ol>
</section></section>
<section><section id="manual-editing" class="title-slide slide level1"><h1>Manual Editing</h1></section><section id="status-quo" class="slide level2">
<h2>Status Quo</h2>
<ul>
<li>development mainly done in Protégé</li>
<li>requires manual editing and review</li>
</ul>
</section><section id="the-solution" class="slide level2">
<h2>The Solution</h2>
<ul>
<li>ROBOT lets us automate many of those tasks</li>
<li>… and provides better quality assurance!</li>
</ul>
</section><section id="robot-releases" class="slide level2">
<h2>ROBOT Releases</h2>
<p>17 releases:</p>
<ul>
<li>v1.0.0 released Feb 8, 2018 …</li>
<li>v1.8.1 released Jan 27, 2021</li>
</ul>
</section><section id="cite-robot" class="slide level2">
<h2>Cite ROBOT</h2>
R.C. Jackson, J.P. Balhoff, E. Douglass, N.L. Harris, C.J. Mungall, and J.A. Overton.<br>
<a href="https://rdcu.be/bMnHT" target="_blank">ROBOT: A tool for automating ontology workflows</a>.<br>
BMC Bioinformatics, vol. 20, July 2019.
</section><section id="lets-get-started" class="slide level2">
<h2>Let’s get started!</h2>
<ul>
<li>download the <a href="https://github.com/rctauber/robot-tutorial" target="_blank">tutorial repository</a></li>
<li>get the latest ROBOT with Docker:
<ul>
<li><code>sh run.sh robot --version</code></li>
</ul></li>
<li>or install it following <a href="http://robot.obolibrary.org/" target="_blank">the documentation</a></li>
<li>navigate to examples: <code>cd examples</code>
<ul>
<li>if using Docker, start each command with <code>sh ../run.sh</code></li>
</ul></li>
</ul>
</section></section>
<section><section id="robot-for-repetitive-tasks" class="title-slide slide level1"><h1>ROBOT for Repetitive Tasks</h1></section><section class="slide level2">
<h3>
merge
</h3>
<h3>
reason
</h3>
<h3>
annotate
</h3>
<h3>
convert
</h3>
</section><section id="merge" class="slide level2">
<h2>Merge</h2>
<ol type="1">
<li>merge two separate ontologies</li>
<li>merge imports into one ontology</li>
</ol>
</section><section class="slide level2">
<h3 id="merge-separate-ontologies">Merge Separate Ontologies</h3>
<pre><code>robot merge --input edit.owl \
--input foo.owl \
--output results/merged.owl</code></pre>
</section><section class="slide level2">
<h3 id="merge-imports">Merge Imports</h3>
<p><small>ROBOT will automatically merge imports. To <em>not</em> merge imports, include <code>--collapse-import-closure false</code>. This option is not supported in v1.0.0.</small></p>
<pre><code>robot merge --input with-import.owl \
--output results/merged_imports.owl</code></pre>
</section><section id="reason" class="slide level2">
<h2>Reason</h2>
<ol type="1">
<li>logical validation</li>
<li>automatic classification</li>
</ol>
</section><section class="slide level2">
<h3 id="reasoners">Reasoners</h3>
<ul>
<li>ELK: a very fast reasoner, but not as powerful as HermiT</li>
<li>HermiT: optimized to classify complex ontologies</li>
<li>EMR: materializes anonymous expressions</li>
<li>Structural: a simple reasoner</li>
</ul>
</section><section class="slide level2">
<h3 id="logical-validation">Logical Validation</h3>
<p><small>Validates that the ontology contains no unsatisfiable entities and that it is not inconsistent.</small></p>
<pre><code>robot reason --input unsatisfiable.owl</code></pre>
</section><section class="slide level2">
<h3 id="automatic-classification">Automatic Classification</h3>
<pre><code>robot reason --input non-reasoned.owl \
--output results/reasoned.owl</code></pre>
</section><section id="annotate" class="slide level2">
<h2>Annotate</h2>
<ol type="1">
<li>add metadata to an ontology for release</li>
</ol>
</section><section class="slide level2">
<h3 id="add-metadata">Add Metadata</h3>
<pre><code>robot annotate --input edit.owl \
--version-iri \
https://github.com/ontodev/robot/releases/2019-07-31/edit.owl \
--annotation oboInOwl:date "07:31:2019 12:00" \
--output results/annotated.owl</code></pre>
</section><section id="convert" class="slide level2">
<h2>Convert</h2>
<ol type="1">
<li>convert an editor’s file to verbose RDF/XML</li>
<li>convert a released ontology to OBO</li>
</ol>
</section><section class="slide level2">
<h3 id="ontology-formats">Ontology Formats</h3>
<ul>
<li>default format is RDF/XML but…</li>
<li>ontologies are shared in many formats
<ul>
<li>OWL functional</li>
<li>OBO</li>
<li>Turtle</li>
<li>and more…</li>
</ul></li>
</ul>
</section><section class="slide level2">
<h3 id="convert-the-edit-file">Convert the Edit File</h3>
<pre><code>robot convert --input edit.owl \
--format owl \
--output results/release.owl</code></pre>
<p><small><small><strong>NOTE</strong>: OWL functional syntax is defined by the suffix <code>.ofn</code> - if you want to convert to that format, use <code>--format ofn</code> or an output ending in <code>.ofn</code>. The <code>.owl</code> suffix can be used to represent any OWL ontology. Using <code>--format owl</code> or excluding the <code>--format</code> option and specifying an output with <code>.owl</code> will convert to RDF/XML.</small></small></p>
</section><section class="slide level2">
<h3 id="convert-to-obo">Convert to OBO</h3>
<pre><code>robot convert --input edit.owl \
--output results/release.obo</code></pre>
<p><small><small><strong>NOTE</strong>: You do not always need to include the <code>--format</code> if the extension of the <code>--output</code> matches the desired format.</small></small></p>
</section></section>
<section><section id="automated-workflows" class="title-slide slide level1"><h1>Automated Workflows</h1></section><section id="chaining-commands" class="slide level2">
<h2>Chaining Commands</h2>
<p><small>Output ontologies can be used as the input to subsequent commands. Only the first command uses an <code>--input</code>, and only the last command uses an <code>--output</code>.</small></p>
<pre><code>robot merge --input edit.owl --collapse-import-closure true \
reason --reasoner ELK \
annotate --version-iri http://purl.obolibrary.org/obo/robot/2018-08-07/release.owl \
convert --output results/chained_release.ttl</code></pre>
</section><section id="makefiles" class="slide level2">
<h2>Makefiles</h2>
<p><small>A Makefile contains a set of rules to make target objects.<br>Here, we use it to create the release files.</small></p>
<pre><code>make release</code></pre>
<p><small><small><strong>NOTE</strong>: This Makefile will fail on v1.0.0 and v1.1.0 - alternatively, run <code>make build</code>.</small></small></p>
</section></section>
<section><section id="quality-assurance" class="title-slide slide level1"><h1>Quality Assurance</h1></section><section class="slide level2">
<h3>
diff
</h3>
<h3>
query (part 1)
</h3>
<h3>
verify
</h3>
<h3>
report
</h3>
</section><section id="diff" class="slide level2">
<h2>Diff</h2>
<ol type="1">
<li>compare the axioms in two version of an ontology</li>
<li>generate a summary page of changes</li>
</ol>
<p><small><code>diff</code> supports different formats:</p>
<ul>
<li><code>plain</code>: default, shows removed and added axioms</li>
<li><code>pretty</code>: plain, plus entity labels for IRIs</li>
<li><code>html</code>: HTML summary page (easy for humans!)</li>
<li><code>markdown</code>: markdown summary (great for GitHub!)</li>
</ul>
<p></small></p>
</section><section class="slide level2">
<h3 id="compare-axioms-default">Compare Axioms (Default)</h3>
<pre><code>robot diff --left non-reasoned.owl \
--right results/reasoned.owl \
--output results/diff.txt</code></pre>
<p><small><small><strong>NOTE</strong>: If you do not include an <code>--output</code>, the results will be printed to the terminal.</small></small></p>
</section><section class="slide level2">
<h3 id="human-readable-diff">Human-Readable Diff</h3>
<pre><code>robot diff --left non-reasoned.owl \
--right results/reasoned.owl \
--format html \
--output results/diff.html</code></pre>
</section><section id="query" class="slide level2">
<h2>Query</h2>
<ol type="1">
<li>run a SPARQL SELECT query</li>
<li>run a SPARQL ASK query</li>
</ol>
</section><section class="slide level2">
<h3 id="select-query">Select Query</h3>
<p><small>SELECT queries can be useful for statistics on the ontology, and for sharing data. For example, you could get a list of all the terms containing just the IDs and labels.</small></p>
<pre><code>robot query --input edit.owl \
--query select.rq results/select.tsv</code></pre>
</section><section class="slide level2">
<h3 id="ask-query">Ask Query</h3>
<p><small>ASK queries can help determine if something exists in the ontology or not. For example, if you want to make sure that “trunk” is in the “vertebrate core” subset.</small></p>
<pre><code>robot query --input edit.owl \
--query ask.rq results/ask.txt</code></pre>
</section><section id="verify" class="slide level2">
<h2>Verify</h2>
<ol type="1">
<li>perform a successful verification</li>
<li>perform an unsuccessful verification</li>
</ol>
</section><section class="slide level2">
<h3 id="successful-verification">Successful Verification</h3>
<p><small>Sometimes, classes can be accidentally orphaned. This verification ensures that all classes, aside from the top-level “anatomical entity”, have asserted parents. If they do not, the verification fails.</small></p>
<pre><code>robot verify --input edit.owl \
--queries verify.rq \
--output-dir results</code></pre>
</section><section class="slide level2">
<h3 id="unsuccessful-verification">Unsuccessful Verification</h3>
<p><small>This verify query checks that all classes have an equivalent class statement. In our edit ontology, only some of the classes have equivalent classes, so this will fail.</small></p>
<pre><code>robot verify --input edit.owl \
--queries verify_fail.rq \
--output-dir results</code></pre>
</section><section id="report" class="slide level2">
<h2>Report</h2>
<ol type="1">
<li>run a series of SPARQL queries to find common violations</li>
</ol>
</section><section class="slide level2">
<h3 id="violations">Violations</h3>
<ul>
<li>annotation, logical, or metadata violations</li>
<li>three logging levels: ERROR, WARN, and INFO</li>
</ul>
</section><section class="slide level2">
<h3 id="generate-a-report">Generate a Report</h3>
<pre><code>robot report --input edit.owl --output results/report.tsv</code></pre>
</section><section id="continuous-integration" class="slide level2">
<h2>Continuous Integration</h2>
<ul>
<li>Travis CI automatically builds and tests changes pushed to GitHub</li>
<li>Often uses <code>make test</code> from the Makefile</li>
<li>If any part of the test fails, the build will fail</li>
</ul>
</section></section>
<section><section id="modular-development" class="title-slide slide level1"><h1>Modular Development</h1></section><section class="slide level2">
<h3>
extract
</h3>
<h3>
template
</h3>
</section><section id="extract" class="slide level2">
<h2>Extract</h2>
<ol type="1">
<li>create an import module with SLME</li>
<li>create an import module with MIREOT</li>
</ol>
</section><section class="slide level2">
<h3 id="import-modules">Import Modules</h3>
<ul>
<li>many bioontologies use terms from external sources</li>
<li>these sources contain more terms than needed</li>
<li>extract ensures the necessary terms and their dependencies are included in module</li>
</ul>
</section><section class="slide level2">
<h3 id="extract-with-slme">Extract with SLME</h3>
<p><small> STAR: fixpoint-nested<br> BOT: bottom module<br> TOP: top module </small></p>
<pre><code>robot extract \
--input-iri http://purl.obolibrary.org/obo/obi.owl \
--term OBI:0000443 \
--method BOT \
--output results/obi_bot.owl</code></pre>
<p><small><small><strong>NOTE</strong>: You can also include a list of terms to extract in a text file with <code>--term-file</code>.<br> <strong>NOTE 2</strong>: To use a local file, use <code>--input <file></code> instead of <code>--input-iri</code>.</small></small></p>
</section><section class="slide level2">
<h3 id="extract-with-mireot">Extract with MIREOT</h3>
<p><small> Creates a simple hierarchy of terms.<br> Requires lower term(s) and optional upper term(s). </small></p>
<pre><code>robot extract \
--input-iri http://purl.obolibrary.org/obo/obi.owl \
--method MIREOT \
--lower-terms obi_terms.txt \
--output results/obi_mireot.owl</code></pre>
<p><small><small><strong>NOTE</strong>: Without specifiying any <code>--upper-terms</code>, the MIREOT method will include all ancestors up to <code>owl:Thing</code>.<br> <strong>NOTE 2</strong>: To just specify <em>one</em> term to extract, use <code>--lower-term</code></small></small></p>
</section><section id="template" class="slide level2">
<h2>Template</h2>
<ol type="1">
<li>create a module</li>
<li>add a class to an ontology</li>
</ol>
</section><section class="slide level2">
<h3 id="create-a-module">Create a Module</h3>
<p><small>This will create a standalone module that can be included in the edit file with an import statement. To update the module, editors only need to update the spreadsheet and run this command to remake the module.</small></p>
<pre><code>robot template --input edit.owl \
--template module.tsv \
--ontology-iri http://purl.obolibrary.org/obo/robot/module.owl \
--output results/module.owl</code></pre>
<p><small><small><strong>NOTE</strong>: <code>template</code> gets all the entity labels from <code>edit.owl</code> so we are able to use the labels in the spreadsheet, instead of always specifying the ID. If we didn’t include the <code>--input</code>, the labels would not resolve.</small></small></p>
</section><section class="slide level2">
<h3 id="add-a-class-to-an-ontology">Add a Class to an Ontology</h3>
<p><small>For one-time class creation (especially if many classes need to be created), a temporary template can be created and the results immediately merged into the edit ontology.</small></p>
<pre><code>robot template --input edit.owl --merge-before \
--template new_class.tsv \
--output results/new_class.owl</code></pre>
<p><small><small><strong>NOTE</strong>: if your ontology includes imports, use <code>--collapse-import-closure false</code> with any merge option to maintain the closure.</small></small></p>
</section></section>
<section><section id="modular-releases" class="title-slide slide level1"><h1>Modular Releases</h1></section><section class="slide level2">
<h3>
query (part 2)
</h3>
<h3>
remove
</h3>
<h3>
filter
</h3>
</section><section id="querying-with-sparql-construct" class="slide level2">
<h2>Querying with SPARQL CONSTRUCT</h2>
<ul>
<li>CONSTRUCT produces RDF data in Turtle format</li>
<li>allows creation of new sets of triples</li>
</ul>
</section><section class="slide level2">
<h3 id="update-annotations-with-construct">Update Annotations with CONSTRUCT</h3>
<pre><code>robot query --input edit.owl \
--query construct.rq results/construct.ttl \
merge --input results/construct.ttl \
--output results/construct.owl</code></pre>
<p><small>The <code>construct.ttl</code> file isn’t much use on its own; we need to merge it. For <code>query</code>, the output ontology is the <em>unchanged</em> input ontology, so we can chain this with the <code>merge</code> command to merge <code>construct.ttl</code>.</small></p>
</section><section id="querying-with-sparql-update" class="slide level2">
<h2>Querying with SPARQL UPDATE</h2>
<ul>
<li>UPDATE changes the RDF data and outputs an updated ontology</li>
<li>allows deletion and insertion of triples</li>
<li>no need to merge after running the UPDATE</li>
</ul>
</section><section class="slide level2">
<h3 id="update-annotations-with-update">Update Annotations with UPDATE</h3>
<pre><code>robot query --input edit.owl \
--update update.ru \
--output results/updated.owl</code></pre>
<p><small>Here, we replace ‘definition’ (<code>IAO:0000115</code>) with ‘external_definition’ (<code>UBPROP:0000001</code>) for all UBERON terms.</small></p>
</section><section id="remove" class="slide level2">
<h2>Remove</h2>
<ol type="1">
<li>remove a class and its descendants</li>
<li>create a ‘simple’ version of an ontology</li>
</ol>
</section><section class="slide level2">
<h3 id="configuration">Configuration</h3>
<ul>
<li>remove a term (or terms) from an ontology and any related terms</li>
<li>highly configurable <code>--select</code> option to remove related terms</li>
<li>specify types of axioms to remove with <code>--axioms</code></li>
</ul>
</section><section class="slide level2">
<h3 id="remove-a-class-descendants">Remove a Class + Descendants</h3>
<pre><code>robot remove --input edit.owl \
--term UBERON:0000475 \
--select "self descendants" \
--output results/removed.owl</code></pre>
</section><section class="slide level2">
<h3 id="create-a-simple-version">Create a ‘Simple’ Version</h3>
<pre><code>robot remove --input edit.owl \
--axioms equivalent \
remove --select parents --select anonymous --select imports \
--output results/simple.owl</code></pre>
<p><small><small><strong>NOTE</strong>: <code>--select</code> accepts a string of options, or can be passed multiple times. For a string of options (previous example) the selected set is the union of all options (both the input term and all descendants of the term). For passing in multiple select options (as above), the options are processed in order (first the parents are selected, and then only the anonymous parents are selected).</small></small></p>
</section><section id="filter" class="slide level2">
<h2>Filter</h2>
<p>Released with v1.2.0-alpha - previously, <code>filter</code> only filtered for object properties.</p>
<ol type="1">
<li>extract a branch of an ontology</li>
<li>create a subset based on annotations</li>
</ol>
</section><section class="slide level2">
<h3 id="extract-a-branch">Extract a Branch</h3>
<pre><code>robot filter --input edit.owl \
--term UBERON:0000475 \
--select "self descendants annotations" \
--output results/branch.owl</code></pre>
<p><small><small><strong>NOTE</strong>: in order to include annotations on the filtered entities, <code>--select annotations</code> must be included. Otherwise, you muist include <em>all</em> annotation properties in the set of input terms.</small></small></p>
</section><section class="slide level2">
<h3 id="create-a-subset">Create a Subset</h3>
<pre><code>robot filter --input edit.owl \
--select \
"oboInOwl:inSubset=<http://purl.obolibrary.org/obo/uberon/core#uberon_slim>" \
--select annotations \
--output-iri http://purl.obolibrary.org/robot/uberon_slim.owl
--output results/uberon_slim.owl</code></pre>
<p><small><small><strong>NOTE</strong>: selecting for annotations is highly configurable:<br> <code>CURIE=CURIE</code><br> <code>CURIE="literal"^^datatype</code><br> <code>CURIE=<IRI></code><br> <code>CURIE=~"regex pattern"</code></small></small></p>
</section></section>
<section><section id="other-commands" class="title-slide slide level1"><h1>Other Commands</h1></section><section class="slide level2">
<h3>
explain materialize
</h3>
<h3>
mirror reduce
</h3>
<h3>
relax rename repair
</h3>
<h3>
unmerge validate
</h3>
</section></section>
<section><section id="questions" class="title-slide slide level1"><h1>Questions?</h1></section></section>
</div>
</div>
<script src="resources/head.js"></script>
<script src="resources/reveal.js"></script>
<script>
// Full list of configuration options available at:
// https://github.com/hakimel/reveal.js#configuration
Reveal.initialize({
// Push each slide change to the browser history
history: true,
// Optional reveal.js plugins
dependencies: [
{ src: 'http://lab.hakim.se/reveal-js/lib/js/classList.js', condition: function() { return !document.body.classList; } },
{ src: 'http://lab.hakim.se/reveal-js/plugin/zoom-js/zoom.js', async: true },
{ src: 'http://lab.hakim.se/reveal-js/plugin/notes/notes.js', async: true }
]
});
</script>
</body>
</html>