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
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:¶
ValueSetFamily
¶
Bases: BaseModel
Sibling classes whose labels differ in one token only.
Source code in ontocast/tool/ontology_validation/shape.py
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
first_label(subject, *graphs)
¶
The first rdfs:label or skos:prefLabel of subject, sorted.
Source code in ontocast/tool/ontology_validation/shape.py
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
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
label_tokens(text)
¶
Lower-case tokens of a label, split on whitespace, _ and /.
minted_class_iris(*graphs)
¶
Subjects the graphs declare as classes or place in a hierarchy.
Source code in ontocast/tool/ontology_validation/shape.py
name_tokens(iri)
¶
The local name split at case changes and separators, case-folded.
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, |
Source code in ontocast/tool/ontology_validation/shape.py
normalize_surface(text)
¶
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 |
Source code in ontocast/tool/ontology_validation/shape.py
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
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
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 |
required |
min_size
|
int
|
Smallest family reported. |
3
|
Source code in ontocast/tool/ontology_validation/shape.py
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; |
required |