Skip to content

ontocast.link.clusters

Read-time clusters: which stored entities are one, from the resolution graph.

Links only propose: two entities linked to one match node are candidates. A cluster joins candidates in a fixed order (stronger evidence first, then by IRI) and never joins two clusters that a veto separates, so the answer depends on the stored documents and declarations, not on their order.

Vetoes, all declared or structural:

  • both entities are in one document graph (its aggregation kept them apart);
  • their types are declared disjoint;
  • a property the catalog caps at one value has disjoint values on each;
  • a key that applies to both has different complete values.

An object IRI local to one document cannot be compared with another document's, so it never counts as a conflicting value.

Attributes

DEFAULT_MAX_CANDIDATES = 500 module-attribute

Classes

ClusterMember

Bases: BaseModel

One entity of a cluster.

Source code in ontocast/link/clusters.py
class ClusterMember(BaseModel):
    """One entity of a cluster."""

    iri: str
    graph: str = Field(description="The document graph that holds the entity.")
    labels: list[str] = Field(default_factory=list)
    types: list[str] = Field(default_factory=list)
    reason: str = Field(
        description="`self` for the entity asked about, else the strongest kind "
        "of link it shares with the cluster (key, ifp, identifier, label)."
    )
    via: list[str] = Field(
        default_factory=list, description="Match nodes it shares with the cluster."
    )

Attributes

graph = Field(description='The document graph that holds the entity.') class-attribute instance-attribute
iri instance-attribute
labels = Field(default_factory=list) class-attribute instance-attribute
reason = Field(description='`self` for the entity asked about, else the strongest kind of link it shares with the cluster (key, ifp, identifier, label).') class-attribute instance-attribute
types = Field(default_factory=list) class-attribute instance-attribute
via = Field(default_factory=list, description='Match nodes it shares with the cluster.') class-attribute instance-attribute

EntityCluster

Bases: BaseModel

The entities stored as one with iri, and the candidates kept apart.

Source code in ontocast/link/clusters.py
class EntityCluster(BaseModel):
    """The entities stored as one with ``iri``, and the candidates kept apart."""

    iri: str
    members: list[ClusterMember]
    kept_apart: list[KeptApart] = Field(default_factory=list)
    truncated: bool = Field(
        default=False,
        description="The candidate set reached its cap; some candidates were not read.",
    )

Attributes

iri instance-attribute
kept_apart = Field(default_factory=list) class-attribute instance-attribute
members instance-attribute
truncated = Field(default=False, description='The candidate set reached its cap; some candidates were not read.') class-attribute instance-attribute

KeptApart

Bases: BaseModel

A candidate that shares a match node with the cluster but is not in it.

Source code in ontocast/link/clusters.py
class KeptApart(BaseModel):
    """A candidate that shares a match node with the cluster but is not in it."""

    iri: str
    graph: str
    veto: str = Field(description="Why it is not one entity with the cluster.")

Attributes

graph instance-attribute
iri instance-attribute
veto = Field(description='Why it is not one entity with the cluster.') class-attribute instance-attribute

Functions:

cluster_of(store, declarations, iri, *, max_candidates=DEFAULT_MAX_CANDIDATES) async

The cluster of the stored entity iri, or None when no document holds it.

Parameters:

Name Type Description Default
store TripleStoreManager

The triple store holding the documents and their links graphs.

required
declarations IdentityDeclarations

The catalog's identity declarations.

required
iri str

An entity of some document graph.

required
max_candidates int

Stop collecting candidates beyond this many.

DEFAULT_MAX_CANDIDATES
Source code in ontocast/link/clusters.py
async def cluster_of(
    store: TripleStoreManager,
    declarations: IdentityDeclarations,
    iri: str,
    *,
    max_candidates: int = DEFAULT_MAX_CANDIDATES,
) -> EntityCluster | None:
    """The cluster of the stored entity ``iri``, or None when no document holds it.

    Args:
        store: The triple store holding the documents and their links graphs.
        declarations: The catalog's identity declarations.
        iri: An entity of some document graph.
        max_candidates: Stop collecting candidates beyond this many.
    """
    nodes, edges, truncated = await _candidates(store, iri, max_candidates)
    candidates = sorted({iri} | {e for _, members in nodes.items() for e in members})
    entities = await _read_entities(store, candidates)
    if iri not in entities:
        return None
    ordered_edges = _ordered_edges(nodes, edges, entities)
    parent = {e: e for e in entities}
    members_of = {e: [e] for e in entities}

    def find(x: str) -> str:
        while parent[x] != x:
            parent[x] = parent[parent[x]]
            x = parent[x]
        return x

    for _, _, left, right in ordered_edges:
        root_left, root_right = find(left), find(right)
        if root_left == root_right:
            continue
        if any(
            _veto(entities[a], entities[b], declarations)
            for a in members_of[root_left]
            for b in members_of[root_right]
        ):
            continue
        keep, drop = sorted((root_left, root_right))
        parent[drop] = keep
        members_of[keep].extend(members_of.pop(drop))

    root = find(iri)
    cluster = sorted(members_of[root])
    in_cluster = set(cluster)
    shared = _shared_nodes(nodes, edges, in_cluster)
    members = [
        ClusterMember(
            iri=e,
            graph=entities[e].graph,
            labels=sorted(entities[e].labels),
            types=sorted(entities[e].types),
            reason="self" if e == iri else _strongest(shared.get(e, [])),
            via=sorted(node for node, _ in shared.get(e, [])),
        )
        for e in cluster
    ]
    kept_apart = [
        KeptApart(
            iri=e,
            graph=entities[e].graph,
            veto=next(
                (
                    reason
                    for other in cluster
                    if (reason := _veto(entities[e], entities[other], declarations))
                ),
                "joined another cluster",
            ),
        )
        for e in sorted(entities)
        if e not in in_cluster
    ]
    return EntityCluster(
        iri=iri, members=members, kept_apart=kept_apart, truncated=truncated
    )