Improve documentation examples and comparison#53
Merged
Conversation
Rewrite docs/examples.md with curated examples covering the full range of linkml-owl features: annotations, existential/universal restrictions, equivalent classes (genus-differentia), disjoint unions, hidden GCIs, data properties, enums mapped to ontology terms, individuals, axiom annotations, Jinja templates, f-string shortcuts, GCI meta-patterns, and integration with existing ontologies. Rewrite docs/comparison.md with side-by-side comparisons showing the same axiom generated via hand-written OWL, ROBOT templates, DOSDP, and linkml-owl, with a clear summary table of feature differences. Add docs/example-schemas/ with a working anatomy schema and data files that demonstrate basic structures, equivalent class definitions, and template-based axiom generation. Fix Python version requirement in usage.md (3.10+, not 3.8+). Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
There was a problem hiding this comment.
Pull request overview
This PR refreshes the project documentation by replacing the auto-generated example dump with curated, task-oriented examples and adding a clearer side-by-side comparison against other OWL/template frameworks, backed by new working example schemas/data.
Changes:
- Rewrote
docs/examples.mdinto a curated examples showcase with schema/data/OFN snippets and a keyword summary table. - Rewrote
docs/comparison.mdwith feature matrices and a worked “same axiom across tools” comparison. - Added a working anatomy example schema + data files under
docs/example-schemas/, and updated documented minimum Python version to 3.10+.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| docs/usage.md | Updates documented minimum Python version to 3.10+. |
| docs/examples.md | Replaces auto-generated test output with curated examples and runnable guidance. |
| docs/comparison.md | Adds structured comparison and guidance for choosing LinkML-OWL vs alternatives. |
| docs/example-schemas/anatomy-schema.yaml | Introduces a concrete schema demonstrating key LinkML-OWL patterns. |
| docs/example-schemas/anatomy-data.yaml | Provides baseline anatomy instance data to generate OWL from the example schema. |
| docs/example-schemas/defined-anatomy-data.yaml | Adds data focused on genus–differentia (EquivalentClasses/IntersectionOf) patterns. |
| docs/example-schemas/organ-parts-data.yaml | Adds data focused on template-driven “organ with parts” axiom generation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+716
to
+722
| ObjectSomeValuesFrom( | ||
| ObjectIntersectionOf( {{genus}} | ||
| ObjectSomeValuesFrom( | ||
| {{differentia_relation}} | ||
| ObjectSomeValuesFrom( {{propagation_relation}} | ||
| {{differentia_filler}} )))) | ||
| ObjectSomeValuesFrom( |
There was a problem hiding this comment.
The GCIPropagationMetapattern Jinja example appears to emit invalid OWL Functional Syntax: ObjectSomeValuesFrom must have a property and a filler, but here it wraps ObjectIntersectionOf(...) without providing the property argument. Rework the pattern so SubClassOf relates the intended intersection antecedent directly to the inferred consequent.
Suggested change
| ObjectSomeValuesFrom( | |
| ObjectIntersectionOf( {{genus}} | |
| ObjectSomeValuesFrom( | |
| {{differentia_relation}} | |
| ObjectSomeValuesFrom( {{propagation_relation}} | |
| {{differentia_filler}} )))) | |
| ObjectSomeValuesFrom( | |
| ObjectIntersectionOf( {{genus}} | |
| ObjectSomeValuesFrom( | |
| {{differentia_relation}} | |
| ObjectSomeValuesFrom( {{propagation_relation}} | |
| {{differentia_filler}} ))) | |
| ObjectSomeValuesFrom( |
…rison Add realistic domain examples demonstrating linkml-owl for real-world ontology engineering workflows: - Disease ontology (Mondo-style): disease-schema.yaml with DiseaseByLocation, DiseaseByAgent, and DiseaseWithInheritance metaclasses showing genus-differentia definitions, enum-based inheritance modes, and conditional Jinja templates. - Phenotype ontology (HPO/uPheno-style): phenotype-schema.yaml with EntityQualityPhenotype metaclass showing the EQ decomposition pattern using nested ObjectIntersectionOf with enum-resolved PATO qualities. - Quick-start guide (quickstart.md): complete 5-minute walkthrough from install to generated OWL, with a self-contained schema and data example. - Extended comparison.md with a second side-by-side comparison showing Mondo's disease-by-location pattern across ROBOT templates, DOSDP, and linkml-owl. - Extended examples.md with disease and phenotype sections showing verified OWL output from the new schemas. All 7 example schemas verified to compile with linkml-data2owl. mkdocs build passes. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
The original examples.md is generated from test_owl_dumper and serves as a reference for all supported OWL patterns. New examples were added as separate files in docs/example-schemas/ and are linked from quickstart.md.
Add four new metaclasses to owl_dumper_test.yaml demonstrating disease ontology patterns commonly used in projects like Mondo: - DiseaseClass: basic named SubClassOf hierarchy (e.g. lung cancer SubClassOf cancer) - DiseaseByLocation: genus-differentia with anatomical location (e.g. brain disease EquivalentTo nervous-system-disorder AND has-disease-location some brain) - DiseaseByPhenotype: genus-differentia with phenotypic feature (e.g. parkinsonism EquivalentTo disease AND has-phenotype some tremor) - DefinedDisease: intersection with multiple differentiae (e.g. disease AND has-location some brain AND has-phenotype some tremor) Add corresponding add_check() entries in test_owl_dumper.py with axiom assertions. Add disease_location (RO:0004026) and has_phenotype (RO:0002200) slots. Regenerate docs/examples.md from test output. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/examples.md— replaced the auto-generated test dump with curated examples covering annotations, existential/universal restrictions, equivalent classes (genus-differentia), disjoint unions, hidden GCIs, data properties, enums mapped to ontology terms, individuals, axiom annotations, Jinja templates, f-strings, GCI meta-patterns, and integration with existing ontologies. Added a summary table of all OWL annotation keywords.docs/comparison.md— side-by-side comparison of the same axiom generated via hand-written OWL, ROBOT templates, DOSDP, and linkml-owl, with a feature comparison table and guidance on when to choose each tool.docs/example-schemas/— working anatomy schema and data files (anatomy-schema.yaml, anatomy-data.yaml, defined-anatomy-data.yaml, organ-parts-data.yaml) demonstrating basic structures, equivalent class definitions, and template-based axiom generation. All verified to compile withlinkml-data2owl.Test plan
linkml-data2owlmkdocs buildsucceeds🤖 Generated with Claude Code