Skip to content

ontocast.tool.ontology_validation.shape

Model-free measures of an ontology's shape, and a whole-catalog name index.

The shape measures answer one question about a newly minted class: would a second document in the same domain reuse it? Three signals say it would not: a class sitting on a long chain of named superclasses, a family of sibling classes that differ by one word (a value set modelled as subclasses), and a leaf whose label names one document's case (a number, a long noun phrase).

The surface index maps names to catalog IRIs across every catalog ontology, not the snapshot a unit was shown: a unit that re-mints a term the retrieval did not surface can only be caught against the whole catalog.

Attributes

LONG_LABEL_TOKENS = 4 module-attribute

SURFACE_PREDICATES = (RDFS.label, SKOS.prefLabel, SKOS.notation) module-attribute

SpecificLabelReason = Literal['digit', 'long'] module-attribute

__all__ = ['CatalogSurfaceIndex', 'LONG_LABEL_TOKENS', 'SURFACE_PREDICATES', 'ValueSetFamily', 'build_catalog_surface_index', 'first_label', 'has_own_structure', 'is_depth_root', 'label_tokens', 'minted_class_iris', 'name_tokens', 'named_class_depth', 'normalize_surface', 'resolve_unique', 'role_compatible', 'specific_label_reason', 'value_set_families', 'variant_term_pairs'] module-attribute

Classes

CatalogSurfaceIndex

Bases: BaseModel

Names of every catalog term, case-insensitive, by label and local name.

Source code in ontocast/tool/ontology_validation/shape.py
class CatalogSurfaceIndex(BaseModel):
    """Names of every catalog term, case-insensitive, by label and local name."""

    by_label: dict[str, set[str]] = Field(default_factory=dict)
    by_local: dict[str, set[str]] = Field(default_factory=dict)
    #: Every named subject of the catalog.
    terms: set[str] = Field(default_factory=set)
    properties: set[str] = Field(default_factory=set)
    classes: set[str] = Field(default_factory=set)

    def is_empty(self) -> bool:
        """Whether the index holds no term."""
        return not self.terms

Attributes

by_label = Field(default_factory=dict) class-attribute instance-attribute
by_local = Field(default_factory=dict) class-attribute instance-attribute
classes = Field(default_factory=set) class-attribute instance-attribute
properties = Field(default_factory=set) class-attribute instance-attribute
terms = Field(default_factory=set) class-attribute instance-attribute

Methods:

is_empty()

Whether the index holds no term.

Source code in ontocast/tool/ontology_validation/shape.py
def is_empty(self) -> bool:
    """Whether the index holds no term."""
    return not self.terms

ValueSetFamily

Bases: BaseModel

Sibling classes whose labels differ in one token only.

Source code in ontocast/tool/ontology_validation/shape.py
class ValueSetFamily(BaseModel):
    """Sibling classes whose labels differ in one token only."""

    parent: str
    #: The shared label with the varying token as ``*`` (``* engine``).
    template: str
    #: ``(iri, label)`` pairs, sorted by IRI.
    members: list[tuple[str, str]]

Attributes

members instance-attribute
parent instance-attribute
template instance-attribute

Functions:

build_catalog_surface_index(graphs)

Index the labels, notations and local names of every subject.

Source code in ontocast/tool/ontology_validation/shape.py
def build_catalog_surface_index(graphs: Iterable[RDFGraph]) -> CatalogSurfaceIndex:
    """Index the labels, notations and local names of every subject."""
    index = CatalogSurfaceIndex()
    for graph in graphs:
        for subject in graph.subjects():
            if not isinstance(subject, URIRef):
                continue
            iri = str(subject)
            if iri in index.terms:
                continue
            index.terms.add(iri)
            local = _local_name(iri)
            if local and local != iri:
                index.by_local.setdefault(local.casefold(), set()).add(iri)
        for predicate in SURFACE_PREDICATES:
            for subject, value in graph.subject_objects(predicate):
                if not isinstance(subject, URIRef) or not isinstance(value, RDFLiteral):
                    continue
                key = normalize_surface(str(value))
                if key:
                    index.by_label.setdefault(key, set()).add(str(subject))
        properties, classes = _catalog_term_roles(graph)
        index.properties |= properties
        index.classes |= classes
    index.classes -= index.properties & index.classes
    return index

first_label(subject, *graphs)

The first rdfs:label or skos:prefLabel of subject, sorted.

Source code in ontocast/tool/ontology_validation/shape.py
def first_label(subject: URIRef, *graphs: Graph) -> str | None:
    """The first ``rdfs:label`` or ``skos:prefLabel`` of ``subject``, sorted."""
    for graph in graphs:
        for predicate in (RDFS.label, SKOS.prefLabel):
            values = sorted(
                str(value)
                for value in graph.objects(subject, predicate)
                if isinstance(value, RDFLiteral) and str(value).strip()
            )
            if values:
                return values[0].strip()
    return None

has_own_structure(class_iri, graph)

Whether class_iri carries something a property value could not.

A subclass, a property whose domain it is, a restriction it is a subclass of, or an owl:equivalentClass definition. A sibling with any of these is a modelled kind, not a value in disguise.

Source code in ontocast/tool/ontology_validation/shape.py
def has_own_structure(class_iri: URIRef, graph: Graph) -> bool:
    """Whether ``class_iri`` carries something a property value could not.

    A subclass, a property whose domain it is, a restriction it is a subclass
    of, or an ``owl:equivalentClass`` definition. A sibling with any of these is
    a modelled kind, not a value in disguise.
    """
    if any(True for _ in graph.subjects(RDFS.subClassOf, class_iri)):
        return True
    if properties_with_side(graph, class_iri, "domain"):
        return True
    if any(isinstance(o, BNode) for o in graph.objects(class_iri, RDFS.subClassOf)):
        return True
    return any(True for _ in graph.objects(class_iri, OWL.equivalentClass))

is_depth_root(class_iri, graph)

Whether class_iri ends a named-superclass chain.

owl:Thing, any term of a well-known vocabulary, and a class with no named superclass in graph.

Source code in ontocast/tool/ontology_validation/shape.py
def is_depth_root(class_iri: URIRef, graph: Graph) -> bool:
    """Whether ``class_iri`` ends a named-superclass chain.

    ``owl:Thing``, any term of a well-known vocabulary, and a class with no
    named superclass in ``graph``.
    """
    if class_iri == OWL.Thing or well_known_vocabulary(str(class_iri)) is not None:
        return True
    return not any(
        isinstance(parent, URIRef)
        for parent in graph.objects(class_iri, RDFS.subClassOf)
    )

label_tokens(text)

Lower-case tokens of a label, split on whitespace, _ and /.

Source code in ontocast/tool/ontology_validation/shape.py
def label_tokens(text: str) -> list[str]:
    """Lower-case tokens of a label, split on whitespace, ``_`` and ``/``."""
    return [token for token in _TOKEN_SPLIT_RE.split(text.casefold()) if token]

minted_class_iris(*graphs)

Subjects the graphs declare as classes or place in a hierarchy.

Source code in ontocast/tool/ontology_validation/shape.py
def minted_class_iris(*graphs: Graph) -> set[str]:
    """Subjects the graphs declare as classes or place in a hierarchy."""
    classes: set[str] = set()
    for graph in graphs:
        for class_type in (OWL.Class, RDFS.Class):
            for subject in graph.subjects(RDF.type, class_type):
                if isinstance(subject, URIRef):
                    classes.add(str(subject))
        for subject in graph.subjects(RDFS.subClassOf, None):
            if isinstance(subject, URIRef):
                classes.add(str(subject))
    return classes

name_tokens(iri)

The local name split at case changes and separators, case-folded.

Source code in ontocast/tool/ontology_validation/shape.py
def name_tokens(iri: str) -> tuple[str, ...]:
    """The local name split at case changes and separators, case-folded."""
    return tuple(label_tokens(_CAMEL_RE.sub(" ", _local_name(iri))))

named_class_depth(class_iri, graph, memo=None)

The longest chain of named superclasses from class_iri to a root.

Only named rdfs:subClassOf objects are steps: a restriction or an owl:equivalentClass definition constrains a class without placing it deeper. A class already on the current path ends the walk, so a cycle terminates (reporting it is the subclass-cycle rule's job).

Parameters:

Name Type Description Default
class_iri URIRef

The class to measure.

required
graph Graph

Snapshot plus delta.

required
memo dict[URIRef, tuple[int, list[URIRef]]] | None

Shared across calls on the same graph to make a batch linear.

None

Returns:

Type Description
tuple[int, list[URIRef]]

The number of steps (a root is 0) and the chain, class_iri first.

Source code in ontocast/tool/ontology_validation/shape.py
def named_class_depth(
    class_iri: URIRef,
    graph: Graph,
    memo: dict[URIRef, tuple[int, list[URIRef]]] | None = None,
) -> tuple[int, list[URIRef]]:
    """The longest chain of named superclasses from ``class_iri`` to a root.

    Only named ``rdfs:subClassOf`` objects are steps: a restriction or an
    ``owl:equivalentClass`` definition constrains a class without placing it
    deeper. A class already on the current path ends the walk, so a cycle
    terminates (reporting it is the subclass-cycle rule's job).

    Args:
        class_iri: The class to measure.
        graph: Snapshot plus delta.
        memo: Shared across calls on the same graph to make a batch linear.

    Returns:
        The number of steps (a root is 0) and the chain, ``class_iri`` first.
    """
    cache = memo if memo is not None else {}

    def walk(node: URIRef, path: frozenset[URIRef]) -> tuple[int, list[URIRef]]:
        cached = cache.get(node)
        if cached is not None:
            return cached
        if is_depth_root(node, graph):
            result = (0, [node])
            cache[node] = result
            return result
        best: tuple[int, list[URIRef]] = (0, [node])
        cyclic = False
        for parent in sorted(
            (p for p in graph.objects(node, RDFS.subClassOf) if isinstance(p, URIRef)),
            key=str,
        ):
            if parent in path or parent == node:
                cyclic = True
                continue
            depth, chain = walk(parent, path | {node})
            if depth + 1 > best[0]:
                best = (depth + 1, [node, *chain])
        if not cyclic:
            # A result reached through a cut cycle depends on where the walk
            # entered it; memoising it would leak that order into other calls.
            cache[node] = best
        return best

    return walk(class_iri, frozenset())

normalize_surface(text)

Case-folded, whitespace-collapsed form of a name.

Source code in ontocast/tool/ontology_validation/shape.py
def normalize_surface(text: str) -> str:
    """Case-folded, whitespace-collapsed form of a name."""
    return " ".join(text.casefold().split())

resolve_unique(index, *, label=None, local=None)

The single catalog IRI a label, else a local name, names.

The label key is tried first. A name claimed by more than one IRI is refused: an ambiguous name is not a duplicate of any one term.

Returns:

Type Description
tuple[str, Literal['label', 'local_name']] | None

The IRI and the key that matched, or None.

Source code in ontocast/tool/ontology_validation/shape.py
def resolve_unique(
    index: CatalogSurfaceIndex,
    *,
    label: str | None = None,
    local: str | None = None,
) -> tuple[str, Literal["label", "local_name"]] | None:
    """The single catalog IRI a label, else a local name, names.

    The label key is tried first. A name claimed by more than one IRI is
    refused: an ambiguous name is not a duplicate of any one term.

    Returns:
        The IRI and the key that matched, or ``None``.
    """
    if label:
        candidates = index.by_label.get(normalize_surface(label), set())
        if len(candidates) == 1:
            return next(iter(candidates)), "label"
    if local:
        candidates = index.by_local.get(local.casefold(), set())
        if len(candidates) == 1:
            return next(iter(candidates)), "local_name"
    return None

role_compatible(minted_role, catalog_iri, index)

True when matching would not cross the class/property divide.

The catalog says which side a catalog term is on; a well-known term the catalog does not hold is judged by :func:well_known_role, so a property is never matched to schema:Property (a class) nor a class to a datatype.

Source code in ontocast/tool/ontology_validation/shape.py
def role_compatible(
    minted_role: str, catalog_iri: str, index: CatalogSurfaceIndex
) -> bool:
    """True when matching would not cross the class/property divide.

    The catalog says which side a catalog term is on; a well-known term the
    catalog does not hold is judged by :func:`well_known_role`, so a property
    is never matched to ``schema:Property`` (a class) nor a class to a datatype.
    """
    is_property = catalog_iri in index.properties
    is_class = catalog_iri in index.classes
    if is_property or is_class:
        if minted_role == "property":
            return is_property
        if minted_role == "class":
            return is_class
        return False
    known = well_known_role(catalog_iri)
    if minted_role in ("property", "class"):
        return known is None or known == minted_role
    return known is None

specific_label_reason(label)

Why label names one document's case rather than a reusable kind.

digit: it carries a number (Unit 3). long: four or more tokens.

Source code in ontocast/tool/ontology_validation/shape.py
def specific_label_reason(label: str) -> SpecificLabelReason | None:
    """Why ``label`` names one document's case rather than a reusable kind.

    ``digit``: it carries a number (``Unit 3``). ``long``: four or more tokens.
    """
    if any(character.isdigit() for character in label):
        return "digit"
    if len(label_tokens(label)) >= LONG_LABEL_TOKENS:
        return "long"
    return None

value_set_families(parent_to_children, min_size=3)

Groups of at least min_size siblings one token apart.

Each child is matched against every template obtained by replacing one of its tokens with *; siblings sharing a template form a family. A child belongs to at most one family: the largest is taken first, ties broken by template text, so the result does not depend on input order.

Parameters:

Name Type Description Default
parent_to_children Mapping[str, Sequence[tuple[str, str]]]

Parent IRI to its (child iri, label) pairs.

required
min_size int

Smallest family reported.

3
Source code in ontocast/tool/ontology_validation/shape.py
def value_set_families(
    parent_to_children: Mapping[str, Sequence[tuple[str, str]]],
    min_size: int = 3,
) -> list[ValueSetFamily]:
    """Groups of at least ``min_size`` siblings one token apart.

    Each child is matched against every template obtained by replacing one of
    its tokens with ``*``; siblings sharing a template form a family. A child
    belongs to at most one family: the largest is taken first, ties broken by
    template text, so the result does not depend on input order.

    Args:
        parent_to_children: Parent IRI to its ``(child iri, label)`` pairs.
        min_size: Smallest family reported.
    """
    families: list[ValueSetFamily] = []
    for parent in sorted(parent_to_children):
        children = sorted(set(parent_to_children[parent]))
        groups: dict[tuple[str, ...], set[tuple[str, str]]] = defaultdict(set)
        for iri, label in children:
            tokens = label_tokens(label)
            if len(tokens) < 2:
                continue
            for position in range(len(tokens)):
                template = (*tokens[:position], "*", *tokens[position + 1 :])
                groups[template].add((iri, label))
        taken: set[str] = set()
        ranked = sorted(groups.items(), key=lambda item: (-len(item[1]), item[0]))
        for template, members in ranked:
            free = sorted((iri, label) for iri, label in members if iri not in taken)
            if len(free) < min_size:
                continue
            taken.update(iri for iri, _ in free)
            families.append(
                ValueSetFamily(parent=parent, template=" ".join(template), members=free)
            )
    return families

variant_term_pairs(terms, pool)

(broader, narrower) pairs of near-identical names, narrower in terms.

Two terms of the same role (class / property) pair when their names have the same tokens (then in IRI order), or when the narrower adds one modifier to the broader (hasOpticalCavity -> hasOpticalMicrocavity, hasPhase -> hasInitialPhase).

Parameters:

Name Type Description Default
terms Mapping[str, str]

Candidate narrower terms, IRI to role.

required
pool Mapping[str, str]

Every term a narrower one may vary, IRI to role; terms are included by the caller when pairs among them count.

required
Source code in ontocast/tool/ontology_validation/shape.py
def variant_term_pairs(
    terms: Mapping[str, str], pool: Mapping[str, str]
) -> list[tuple[str, str]]:
    """``(broader, narrower)`` pairs of near-identical names, ``narrower`` in ``terms``.

    Two terms of the same role (``class`` / ``property``) pair when their names
    have the same tokens (then in IRI order), or when the narrower adds one
    modifier to the broader (``hasOpticalCavity`` -> ``hasOpticalMicrocavity``,
    ``hasPhase`` -> ``hasInitialPhase``).

    Args:
        terms: Candidate narrower terms, IRI to role.
        pool: Every term a narrower one may vary, IRI to role; ``terms`` are
            included by the caller when pairs among them count.
    """
    tokens = {iri: name_tokens(iri) for iri in {*terms, *pool}}
    pairs: set[tuple[str, str]] = set()
    for narrow in sorted(terms):
        role = terms[narrow]
        for broad in sorted(pool):
            if broad == narrow or pool[broad] != role or not tokens[broad]:
                continue
            if tokens[broad] == tokens[narrow]:
                pairs.add((min(broad, narrow), max(broad, narrow)))
            elif _narrows(tokens[broad], tokens[narrow]):
                pairs.add((broad, narrow))
    return sorted(pairs)