HCMO — Home-Cage Monitoring Ontology

HCMO is an ontology for home-cage monitoring of laboratory animals. It models monitored enclosures, biological subjects and experimental groups, the environment and its measurements, observations and results, and the sensors, hardware, and software that produce the data. The project ships as a standalone, tool-consumable package: a stable release manifest, modular Turtle sources, generated distributions, SHACL shapes, competency queries, and a JSON-LD context.

At a glance

Ontology IRI	https://w3id.org/hcmo/ontology/hcm
Base namespace	https://w3id.org/hcmo/ontology/hcm#
Module sub-namespaces	…/hcm/bio#, …/hcm/env#, …/hcm/obs#, …/hcm/tech#
Version	0.4.1 (versionIRI …/hcm/0.4.1)
Prefix	hcm
License	CC BY 4.0
Logo	HCMO-logo3.png
Release manifest	hcmo.yaml
Documentation	https://dhuzard.github.io/HCMO/index-en.html

The release manifest hcmo.yaml is the contract that downstream tools (e.g. the hcmo-kgqa-lab sync layer) read. Its shape is treated as an API and kept stable across releases.

See docs/UPPER-LEVEL-VIEW.md for the simple end-user hierarchy and the optional source-faithful ontology-developer view.

Repository layout

hcmo.yaml                      # release manifest (name, version, namespace, modules, dist, shapes, queries, examples)
ontology/
  modules/                     # hand-authored modular sources
    external-upper.ttl         #   five-anchor end-user upper presentation
    hcm-core.ttl               #   core terms + owl:Ontology header (attribution)
    hcm-bio.ttl                #   subjects, experimental groups        (…/hcm/bio#)
    hcm-env.ttl                #   environment & measurements           (…/hcm/env#)
    hcm-obs.ttl                #   observations & results               (…/hcm/obs#)
    hcm-tech.ttl               #   sensors, devices, software & data    (…/hcm/tech#)
    hcm-compat.ttl             #   deprecated 0.0.1 IRIs + replacements
  profiles/
    external-upper-developer.ttl # optional source-faithful BFO/IAO hierarchy
  context.jsonld               # JSON-LD context for app developers
  legacy/                      # previous HCMO 1.0.0 + HCMO/MAPP 0.0.1 sources (not merged)
dist/                          # GENERATED — never hand-edit
  hcmo.ttl                     #   merged graph, canonical/sorted Turtle (reproducible)
  hcmo.owl                     #   merged graph, RDF/XML
  hcmo.json                    #   merged graph, JSON-LD
  profile.json                 #   flat term inventory {iri,label,comment} + counts
shapes/hcm-shapes.ttl          # SHACL constraints
examples/                      # ABox examples (abox-minimal, abox-edge-cases)
queries/                       # competency_questions.yaml + cq-*.rq
tooling/                       # build.py, validate.py, docs.py, requirements.txt
docs/                          # documentation (incl. MISSING-DEFINITIONS.md)
.github/workflows/             # validate.yml (PR gate), release.yml (tag → assets)

Quickstart

pip install -r tooling/requirements.txt

python tooling/build.py      # regenerate dist/ + profile.json (idempotent, reproducible)
python tooling/validate.py   # parse + contract + SHACL + exact-answer CQs (the CI gate)
python tooling/external_vocab.py --verify-network  # recheck pinned source bytes
pip install -r tooling/interoperability-requirements.txt
python tooling/validate_interoperability.py  # independent RO-Crate/ISA evidence gate
python tooling/validate_isa_native_projection.py  # controlled-loss ISA-JSON/ISA-Tab gate

• tooling/build.py merges ontology/modules/*.ttl into dist/ using a canonicalized, sorted serialization, so re-running produces byte-identical output (clean diffs). Everything in dist/ is generated — edit the modules, not the artifacts.
• tooling/validate.py parses every TTL, runs the SHACL shapes against the examples, validates the dedicated acyclic ISA/STATO evidence slice and the lossless extended-crate round trip, checks mapping/loss contracts, and checks exact competency-query answers; it exits non-zero on failure.
• tooling/validate_isa_native_projection.py executes the native ISA overlap through ISA-JSON → ISA-Tab → ISA-JSON: one animal Source generates one real tissue Sample. It tests identity preservation without fabricating an animal Sample proxy; all non-native HCMO/STATO losses remain explicit. The reproducible ISA-API outputs and the Figure 3 modeling decisions are under examples/isa-roundtrip/native-isa/; pass --write to regenerate them.

Consuming the ontology

• Merged graph: import dist/hcmo.ttl (or dist/hcmo.owl) into your triple store or reasoner.
• Programmatic inventory: read dist/profile.json for the flat list of classes / object properties / datatype properties with labels, comments, and counts — ideal for sync layers and UIs.
• JSON-LD apps: apply ontology/context.jsonld when exchanging data.
• Validation: use shapes/hcm-shapes.ttl to validate payloads during ingestion; shapes/isa-hcmo-evidence-shapes.ttl covers the pinned ISA/STATO bridge, while shapes/isa-hcmo-roundtrip-shapes.ttl covers the generated 2 × 2 extended ISA RO-Crate. See examples/ for conformant, intentionally-invalid, and controlled-loss fixtures. The examples/isa-roundtrip/README.md artifact map links the raw matrix, STATO-annotated result matrix, RDF/RO-Crate serializations, native ISA files, loss manifests, and exact-answer queries.
• External source contract: read external-vocabularies.yaml for pinned versions, canonical term namespaces, used-term allowlists, and checksums.
• Everything is discoverable from hcmo.yaml — resolve module, dist, shapes, queries, and example paths from there rather than hard-coding them.

SPARQL endpoint

A public, read-only SPARQL endpoint serves the reference graph at https://sparql.hcmo.metadatapp.net/ (Apache Jena Fuseki, data loaded at image build time, packaged in deploy/fuseki/). Its permanent address, https://w3id.org/hcmo/sparql, works once the w3id rule is merged (perma-id/w3id.org#7018). The same image runs locally with docker compose -f deploy/fuseki/docker-compose.yml up --build.

• /hcmo: the reference evaluation graph of the twelve competency questions (ontology, three positive examples, six SKOS vocabularies, union default graph).
• /hcmo-0.4.1: the same data under a version-qualified, citable name (the release the image was built from).
• /hcm-systems: exploration dataset with the HCM systems catalogue.
• Web UI: https://sparql.hcmo.metadatapp.net/#/dataset/hcmo/query.
• SPARQL endpoint: https://sparql.hcmo.metadatapp.net/hcmo/sparql (query service only, no update).

python tooling/run_cqs.py --endpoint https://sparql.hcmo.metadatapp.net/hcmo/sparql

Documentation

📖 Published docs: https://dhuzard.github.io/HCMO/index-en.html

Human-readable HTML documentation is generated from the merged graph with WIDOCO (overview, term cross-reference, namespace declarations, a WebVOWL diagram, and provenance).

python tooling/build.py      # ensure dist/ is current
python tooling/docs.py       # render docs/widoco/ (needs a Java 11+ runtime)
# then open docs/widoco/index.html

tooling/docs.py downloads a pinned WIDOCO release into tooling/.widoco/ on first run (override with --jar PATH or WIDOCO_JAR). The generated site under docs/widoco/ is not committed — it is published to GitHub Pages by .github/workflows/docs.yml on every push to main. Term descriptions are sourced from the owl:Ontology header and rdfs:comment; terms still missing definitions (see docs/MISSING-DEFINITIONS.md) render with empty descriptions.

To serve the published site, enable Pages once in Settings → Pages → Source: "GitHub Actions".

Status & known issues

HCMO 0.4.1 is the current published, citable modular release of the early Chowlk-derived term set. Its ontology metadata retains mod:status "draft" as the model-maturity label; this does not negate publication of the immutable versioned release. Active classes and properties have labels, textual definitions, explicit upper/domain anchors, and property domain/range axioms. Invalid UNKNOWN: and bare-namespace artifacts are retained only in the archived 0.0.1 source; valid published 0.0.1 HCMO IRIs remain available as deprecated mapped terms.

The remaining modeling decisions are tracked in docs/MISSING-DEFINITIONS.md. Quantity-bearing dimensions, sampling rates, environmental specifications, and observation results use the pinned QUDT 3.4.0 quantity-value pattern; extensions to additional quantity roles remain subject to semantic review.

Contribution form

The published contribution form under docs/hcm-systems/contribute/ exports current-model Turtle and triple CSV. The former Node.js authoring/blueprint app (webapp/) is no longer part of this repository; it is archived, with its history, at dhuzard/hcmo-webapp.

Conceptual provenance

HCMO is an independently authored formal ontology informed by the Home Cage Monitoring Definition Olog developed by COST Action TEATIME (CA20135). We gratefully acknowledge the Olog's authors and the TEATIME community: the Olog established an important conceptual foundation and domain vocabulary; HCMO independently formalises and substantially extends the domain using OWL, established external ontologies, SHACL constraints, competency questions, and reproducible validation. The deposited Olog source is archived on Zenodo as version DOI 10.5281/zenodo.22646369 with concept DOI 10.5281/zenodo.22646368; the corresponding repository source is available from its v1.0.0 release.

Contributors

• Cyril Gilbert — LIRMM, Université de Montpellier, CNRS, Montpellier, France · 0009-0008-2489-8106 · @cyrilbonus
• Gaoussou Sanou — IMGT®, IGH, Université de Montpellier, CNRS, Montpellier, France · 0000-0003-2204-2466 · @gsanou
• Serge Sonfack Sounchio — Robert Bosch Sp. z o. o., Jutrzenki 105, Poland · 0000-0002-6085-6818 · @sonfack
• Antoine Toffano — LIRMM, Université de Montpellier, CNRS, Montpellier, France · 0009-0008-0575-8490
• Pierre Larmande — DIADE, Université de Montpellier, IRD, CIRAD, Montpellier, France · 0000-0002-2923-9790 · @pierrelarmande
• Benoît Girard — Department of Basic Neurosciences, University of Geneva, Switzerland · 0000-0002-3914-6483 · @BenoitJT-GIRARD
• Philippe Rocca-Serra — Oxford e-Research Centre, Department of Engineering Science, University of Oxford, Oxford OX1 3QG, United Kingdom · 0000-0001-9853-5668
• Konstantin Todorov — LIRMM, Université de Montpellier, CNRS, Montpellier, France · 0000-0002-9116-6692
• Damien Huzard — Neuronautix, Montpellier, France · 0000-0003-4820-7951 · @dhuzard

Attribution is also recorded on the owl:Ontology header (dcterms:creator, using ORCID IRIs where known); ORCIDs and affiliations are recorded in CITATION.cff. The project's historical development and the evidential limits around the auxiliary field-tier inventory are documented in docs/PROVENANCE.md.

Citation

If you use HCMO, please cite it via CITATION.cff (GitHub's "Cite this repository") or the concept DOI 10.5281/zenodo.18925284, which always resolves to the latest version. Each release also has its own version DOI on Zenodo (0.4.1: 10.5281/zenodo.23315766; 0.3.0: 10.5281/zenodo.22208202). Version 0.4.0 (10.5281/zenodo.23315451) was published from the wrong commit and is superseded by 0.4.1; do not cite it.

License

Released under CC BY 4.0.