rdf-construct 0.3.0__py3-none-any.whl

rdf_construct/stats/metrics/documentation.py

@@ -0,0 +1,128 @@
+"""Documentation metrics for RDF ontologies.
+
+Analyses documentation coverage: labels, comments, definitions.
+"""
+
+from dataclasses import dataclass
+
+from rdflib import Graph, RDF, RDFS, Namespace
+from rdflib.namespace import OWL, DCTERMS
+
+
+# Common documentation namespaces
+SKOS = Namespace("http://www.w3.org/2004/02/skos/core#")
+
+
+@dataclass
+class DocumentationStats:
+    """Documentation statistics for an ontology.
+
+    Attributes:
+        classes_labelled: Classes with rdfs:label or skos:prefLabel.
+        classes_labelled_pct: Proportion of classes with labels (0.0 - 1.0).
+        classes_documented: Classes with rdfs:comment or skos:definition.
+        classes_documented_pct: Proportion of classes with documentation (0.0 - 1.0).
+        properties_labelled: Properties with labels.
+        properties_labelled_pct: Proportion of properties with labels (0.0 - 1.0).
+    """
+
+    classes_labelled: int = 0
+    classes_labelled_pct: float = 0.0
+    classes_documented: int = 0
+    classes_documented_pct: float = 0.0
+    properties_labelled: int = 0
+    properties_labelled_pct: float = 0.0
+
+
+# Predicates considered as labels
+LABEL_PREDICATES = (
+    RDFS.label,
+    SKOS.prefLabel,
+)
+
+# Predicates considered as documentation
+DOC_PREDICATES = (
+    RDFS.comment,
+    SKOS.definition,
+    DCTERMS.description,
+)
+
+
+def _get_all_classes(graph: Graph) -> set:
+    """Get all classes from the graph."""
+    classes = set(graph.subjects(RDF.type, OWL.Class))
+    classes |= set(graph.subjects(RDF.type, RDFS.Class))
+    return classes
+
+
+def _get_all_properties(graph: Graph) -> set:
+    """Get all properties from the graph."""
+    props = set()
+    for prop_type in (
+        OWL.ObjectProperty,
+        OWL.DatatypeProperty,
+        OWL.AnnotationProperty,
+        RDF.Property,
+    ):
+        props |= set(graph.subjects(RDF.type, prop_type))
+    return props
+
+
+def _has_any_predicate(graph: Graph, subject: object, predicates: tuple) -> bool:
+    """Check if subject has any of the given predicates.
+
+    Args:
+        graph: RDF graph to query.
+        subject: Subject to check.
+        predicates: Tuple of predicates to look for.
+
+    Returns:
+        True if subject has at least one of the predicates.
+    """
+    for pred in predicates:
+        if graph.value(subject, pred) is not None:
+            return True
+    return False
+
+
+def collect_documentation_stats(graph: Graph) -> DocumentationStats:
+    """Collect documentation statistics from an RDF graph.
+
+    Args:
+        graph: RDF graph to analyse.
+
+    Returns:
+        DocumentationStats with all documentation metrics populated.
+    """
+    classes = _get_all_classes(graph)
+    properties = _get_all_properties(graph)
+
+    total_classes = len(classes)
+    total_props = len(properties)
+
+    if total_classes == 0 and total_props == 0:
+        return DocumentationStats()
+
+    # Count classes with labels
+    classes_with_label = sum(
+        1 for c in classes if _has_any_predicate(graph, c, LABEL_PREDICATES)
+    )
+
+    # Count classes with documentation
+    classes_with_doc = sum(
+        1 for c in classes if _has_any_predicate(graph, c, DOC_PREDICATES)
+    )
+
+    # Count properties with labels
+    props_with_label = sum(
+        1 for p in properties if _has_any_predicate(graph, p, LABEL_PREDICATES)
+    )
+
+    return DocumentationStats(
+        classes_labelled=classes_with_label,
+        classes_labelled_pct=round(classes_with_label / total_classes, 3) if total_classes else 0.0,
+        classes_documented=classes_with_doc,
+        classes_documented_pct=round(classes_with_doc / total_classes, 3) if total_classes else 0.0,
+        properties_labelled=props_with_label,
+        properties_labelled_pct=round(props_with_label / total_props, 3) if total_props else 0.0,
+    )

rdf_construct/stats/metrics/hierarchy.py

@@ -0,0 +1,207 @@
+"""Hierarchy metrics for RDF ontologies.
+
+Analyses class hierarchy structure: depth, branching factor, orphan classes.
+"""
+
+from collections import defaultdict
+from dataclasses import dataclass
+
+from rdflib import Graph, RDF, RDFS
+from rdflib.namespace import OWL
+
+
+@dataclass
+class HierarchyStats:
+    """Hierarchy statistics for an ontology.
+
+    Attributes:
+        root_classes: Classes with no superclass (except owl:Thing).
+        leaf_classes: Classes with no subclasses.
+        max_depth: Maximum depth of the class hierarchy.
+        avg_depth: Average depth across all classes.
+        avg_branching: Average number of direct subclasses per class.
+        orphan_classes: Classes not connected to the main hierarchy.
+        orphan_rate: Proportion of orphan classes (0.0 - 1.0).
+    """
+
+    root_classes: int = 0
+    leaf_classes: int = 0
+    max_depth: int = 0
+    avg_depth: float = 0.0
+    avg_branching: float = 0.0
+    orphan_classes: int = 0
+    orphan_rate: float = 0.0
+
+
+def _get_all_classes(graph: Graph) -> set:
+    """Get all classes from the graph."""
+    classes = set(graph.subjects(RDF.type, OWL.Class))
+    classes |= set(graph.subjects(RDF.type, RDFS.Class))
+    return classes
+
+
+def _build_hierarchy(graph: Graph, classes: set) -> tuple[dict, dict]:
+    """Build parent/child adjacency lists from the class hierarchy.
+
+    Args:
+        graph: RDF graph to query.
+        classes: Set of class URIRefs.
+
+    Returns:
+        Tuple of (parents_of, children_of) dictionaries.
+    """
+    parents_of: dict = defaultdict(set)  # child -> {parents}
+    children_of: dict = defaultdict(set)  # parent -> {children}
+
+    for cls in classes:
+        for parent in graph.objects(cls, RDFS.subClassOf):
+            # Only consider class-class relationships
+            if parent in classes:
+                parents_of[cls].add(parent)
+                children_of[parent].add(cls)
+
+    return dict(parents_of), dict(children_of)
+
+
+def _compute_depths(classes: set, parents_of: dict) -> dict:
+    """Compute depth of each class in the hierarchy.
+
+    Depth is the length of the longest path from a root class.
+    Root classes (no parents) have depth 0.
+
+    Args:
+        classes: Set of all class URIRefs.
+        parents_of: Dictionary mapping class -> set of parent classes.
+
+    Returns:
+        Dictionary mapping class -> depth.
+    """
+    depths: dict = {}
+
+    def compute_depth(cls: object, visited: set) -> int:
+        """Recursively compute depth, handling cycles."""
+        if cls in depths:
+            return depths[cls]
+        if cls in visited:
+            # Cycle detected
+            return 0
+
+        visited.add(cls)
+        parents = parents_of.get(cls, set())
+
+        if not parents:
+            # Root class
+            depth = 0
+        else:
+            # Depth is max parent depth + 1
+            depth = max(compute_depth(p, visited) for p in parents) + 1
+
+        depths[cls] = depth
+        return depth
+
+    for cls in classes:
+        if cls not in depths:
+            compute_depth(cls, set())
+
+    return depths
+
+
+def _find_roots(classes: set, parents_of: dict) -> set:
+    """Find root classes (those with no parent in the class set).
+
+    Args:
+        classes: Set of all class URIRefs.
+        parents_of: Dictionary mapping class -> set of parent classes.
+
+    Returns:
+        Set of root class URIRefs.
+    """
+    return {cls for cls in classes if not parents_of.get(cls)}
+
+
+def _find_leaves(classes: set, children_of: dict) -> set:
+    """Find leaf classes (those with no children).
+
+    Args:
+        classes: Set of all class URIRefs.
+        children_of: Dictionary mapping class -> set of child classes.
+
+    Returns:
+        Set of leaf class URIRefs.
+    """
+    return {cls for cls in classes if not children_of.get(cls)}
+
+
+def _find_orphans(classes: set, parents_of: dict, children_of: dict) -> set:
+    """Find orphan classes (not connected to any other class).
+
+    An orphan class has no parents and no children in the hierarchy.
+
+    Args:
+        classes: Set of all class URIRefs.
+        parents_of: Dictionary mapping class -> set of parent classes.
+        children_of: Dictionary mapping class -> set of child classes.
+
+    Returns:
+        Set of orphan class URIRefs.
+    """
+    return {
+        cls for cls in classes
+        if not parents_of.get(cls) and not children_of.get(cls)
+    }
+
+
+def _compute_avg_branching(classes: set, children_of: dict) -> float:
+    """Compute average branching factor (subclasses per class).
+
+    Only considers classes that have at least one subclass.
+
+    Args:
+        classes: Set of all class URIRefs.
+        children_of: Dictionary mapping class -> set of child classes.
+
+    Returns:
+        Average number of subclasses per parent class.
+    """
+    parent_counts = [len(children) for cls, children in children_of.items() if children]
+    if not parent_counts:
+        return 0.0
+    return sum(parent_counts) / len(parent_counts)
+
+
+def collect_hierarchy_stats(graph: Graph) -> HierarchyStats:
+    """Collect hierarchy statistics from an RDF graph.
+
+    Args:
+        graph: RDF graph to analyse.
+
+    Returns:
+        HierarchyStats with all hierarchy metrics populated.
+    """
+    classes = _get_all_classes(graph)
+
+    if not classes:
+        return HierarchyStats()
+
+    parents_of, children_of = _build_hierarchy(graph, classes)
+    depths = _compute_depths(classes, parents_of)
+
+    roots = _find_roots(classes, parents_of)
+    leaves = _find_leaves(classes, children_of)
+    orphans = _find_orphans(classes, parents_of, children_of)
+
+    max_depth = max(depths.values()) if depths else 0
+    avg_depth = sum(depths.values()) / len(depths) if depths else 0.0
+    avg_branching = _compute_avg_branching(classes, children_of)
+
+    orphan_rate = len(orphans) / len(classes) if classes else 0.0
+
+    return HierarchyStats(
+        root_classes=len(roots),
+        leaf_classes=len(leaves),
+        max_depth=max_depth,
+        avg_depth=round(avg_depth, 2),
+        avg_branching=round(avg_branching, 2),
+        orphan_classes=len(orphans),
+        orphan_rate=round(orphan_rate, 3),
+    )

rdf_construct/stats/metrics/properties.py

@@ -0,0 +1,88 @@
+"""Property metrics for RDF ontologies.
+
+Analyses property definitions: domain/range coverage, special characteristics.
+"""
+
+from dataclasses import dataclass
+
+from rdflib import Graph, RDF, RDFS
+from rdflib.namespace import OWL
+
+
+@dataclass
+class PropertyStats:
+    """Property statistics for an ontology.
+
+    Attributes:
+        with_domain: Properties that have rdfs:domain defined.
+        with_range: Properties that have rdfs:range defined.
+        domain_coverage: Proportion of properties with domain (0.0 - 1.0).
+        range_coverage: Proportion of properties with range (0.0 - 1.0).
+        inverse_pairs: Number of owl:inverseOf pairs.
+        functional: Number of owl:FunctionalProperty properties.
+        symmetric: Number of owl:SymmetricProperty properties.
+    """
+
+    with_domain: int = 0
+    with_range: int = 0
+    domain_coverage: float = 0.0
+    range_coverage: float = 0.0
+    inverse_pairs: int = 0
+    functional: int = 0
+    symmetric: int = 0
+
+
+def _get_all_properties(graph: Graph) -> set:
+    """Get all properties from the graph (object + datatype + annotation)."""
+    props = set()
+    for prop_type in (
+        OWL.ObjectProperty,
+        OWL.DatatypeProperty,
+        OWL.AnnotationProperty,
+        RDF.Property,
+    ):
+        props |= set(graph.subjects(RDF.type, prop_type))
+    return props
+
+
+def collect_property_stats(graph: Graph) -> PropertyStats:
+    """Collect property statistics from an RDF graph.
+
+    Args:
+        graph: RDF graph to analyse.
+
+    Returns:
+        PropertyStats with all property metrics populated.
+    """
+    properties = _get_all_properties(graph)
+    total = len(properties)
+
+    if total == 0:
+        return PropertyStats()
+
+    # Count properties with domain
+    with_domain = sum(1 for p in properties if graph.value(p, RDFS.domain) is not None)
+
+    # Count properties with range
+    with_range = sum(1 for p in properties if graph.value(p, RDFS.range) is not None)
+
+    # Count inverse pairs (each owl:inverseOf creates a pair)
+    # Count unique pairs (A inverseOf B = B inverseOf A)
+    inverse_subjects = set(graph.subjects(OWL.inverseOf, None))
+    inverse_pairs = len(inverse_subjects)  # Each subject represents one pair relationship
+
+    # Count functional properties
+    functional = len(set(graph.subjects(RDF.type, OWL.FunctionalProperty)))
+
+    # Count symmetric properties
+    symmetric = len(set(graph.subjects(RDF.type, OWL.SymmetricProperty)))
+
+    return PropertyStats(
+        with_domain=with_domain,
+        with_range=with_range,
+        domain_coverage=round(with_domain / total, 3) if total else 0.0,
+        range_coverage=round(with_range / total, 3) if total else 0.0,
+        inverse_pairs=inverse_pairs,
+        functional=functional,
+        symmetric=symmetric,
+    )

rdf_construct/uml/__init__.py

@@ -0,0 +1,22 @@
+"""UML diagram generation from RDF ontologies.
+
+This module provides functionality to generate PlantUML class diagrams
+from RDF/OWL ontologies based on YAML-defined contexts.
+"""
+
+from .context import UMLConfig, UMLContext, load_uml_config
+from .mapper import collect_diagram_entities
+from .renderer import render_plantuml
+from .odm_renderer import ODMRenderer, render_odm_plantuml
+
+__all__ = [
+    "UMLConfig",
+    "UMLContext",
+    "load_uml_config",
+    "collect_diagram_entities",
+    "render_plantuml",
+    "uml_layout",
+    "uml_style",
+    "ODMRenderer",
+    "render_odm_plantuml",
+]

rdf_construct/uml/context.py

@@ -0,0 +1,194 @@
+"""UML context configuration for selecting RDF subsets to diagram.
+
+A context defines what classes, properties, and individuals to include
+in a PlantUML diagram, along with filtering and inclusion rules.
+"""
+
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+
+
+class UMLContext:
+    """Represents a UML diagramming context from YAML configuration.
+
+    A context specifies which RDF entities to include in a PlantUML diagram,
+    how to traverse hierarchies, and which relationships to show.
+
+    Attributes:
+        name: Context identifier
+        description: Human-readable description
+        mode: Selection mode ('default' or 'explicit')
+        root_classes: List of root class CURIEs to start from (default mode)
+        focus_classes: Explicit list of classes to include (default mode)
+        include_descendants: Whether to include subclasses (default mode)
+        max_depth: Maximum depth when traversing hierarchies (default mode)
+        properties: Property inclusion configuration
+        include_instances: Whether to include individuals
+        selector: Selector key for bulk selection (default mode)
+        explicit_classes: Explicit class list (explicit mode)
+        explicit_object_properties: Explicit object property list (explicit mode)
+        explicit_datatype_properties: Explicit datatype property list (explicit mode)
+        explicit_annotation_properties: Explicit annotation property list (explicit mode)
+        explicit_instances: Explicit instance list (explicit mode)
+    """
+
+    def __init__(self, name: str, config: dict[str, Any]):
+        """Initialize a UML context from configuration.
+
+        Args:
+            name: Context identifier
+            config: Context configuration dictionary from YAML
+        """
+        self.name = name
+        self.description = config.get("description", "")
+
+        # Determine mode (default vs explicit)
+        self.mode = config.get("mode", "default")
+
+        if self.mode == "explicit":
+            # Explicit mode: directly specify all entities
+            self.explicit_classes = config.get("classes", [])
+            self.explicit_object_properties = config.get("object_properties", [])
+            self.explicit_datatype_properties = config.get("datatype_properties", [])
+            self.explicit_annotation_properties = config.get("annotation_properties", [])
+            self.explicit_instances = config.get("instances", [])
+
+            # These are not used in explicit mode but set defaults for compatibility
+            self.root_classes = []
+            self.focus_classes = []
+            self.selector = None
+            self.include_descendants = False
+            self.max_depth = None
+            self.property_mode = "explicit"
+            self.property_include = []
+            self.property_exclude = []
+            self.include_instances = bool(self.explicit_instances)
+
+        else:
+            # Default mode: existing strategies
+            # Class selection strategies
+            self.root_classes = config.get("root_classes", [])
+            self.focus_classes = config.get("focus_classes", [])
+            self.selector = config.get("selector")  # e.g., "classes"
+
+            # Traversal settings
+            self.include_descendants = config.get("include_descendants", False)
+            self.max_depth = config.get("max_depth")
+
+            # Property configuration
+            prop_config = config.get("properties", {})
+            if isinstance(prop_config, dict):
+                self.property_mode = prop_config.get("mode", "domain_based")
+                self.property_include = prop_config.get("include", [])
+                self.property_exclude = prop_config.get("exclude", [])
+            else:
+                # Simple boolean for backward compatibility
+                self.property_mode = "all" if prop_config else "none"
+                self.property_include = []
+                self.property_exclude = []
+
+            # Instances
+            self.include_instances = config.get("include_instances", False)
+
+            # Explicit mode attributes not used but set for compatibility
+            self.explicit_classes = []
+            self.explicit_object_properties = []
+            self.explicit_datatype_properties = []
+            self.explicit_annotation_properties = []
+            self.explicit_instances = []
+
+        # Style reference (will be used later)
+        self.style = config.get("style", "default")
+
+    def has_class_selection(self) -> bool:
+        """Check if context has any class selection criteria."""
+        if self.mode == "explicit":
+            return bool(self.explicit_classes)
+        return bool(
+            self.root_classes or self.focus_classes or self.selector
+        )
+
+    def __repr__(self) -> str:
+        if self.mode == "explicit":
+            return (
+                f"UMLContext(name={self.name!r}, mode='explicit', "
+                f"classes={len(self.explicit_classes)})"
+            )
+        return (
+            f"UMLContext(name={self.name!r}, mode='default', "
+            f"roots={len(self.root_classes)}, "
+            f"focus={len(self.focus_classes)})"
+        )
+
+
+class UMLConfig:
+    """Configuration for UML diagram generation.
+
+    Loads and manages YAML-based UML context specifications with support
+    for multiple contexts, default settings, and shared configuration via
+    YAML anchors.
+
+    Attributes:
+        defaults: Default settings applied across contexts
+        contexts: Dictionary of available UML contexts
+    """
+
+    def __init__(self, yaml_path: Path | str):
+        """Load UML configuration from a YAML file.
+
+        Args:
+            yaml_path: Path to YAML configuration file
+        """
+        yaml_path = Path(yaml_path)
+        self.config = yaml.safe_load(yaml_path.read_text(encoding="utf-8"))
+
+        self.defaults = self.config.get("defaults", {}) or {}
+
+        # Load contexts
+        self.contexts = {}
+        for ctx_name, ctx_config in (self.config.get("contexts", {}) or {}).items():
+            self.contexts[ctx_name] = UMLContext(ctx_name, ctx_config)
+
+    def get_context(self, name: str) -> UMLContext:
+        """Get a context by name.
+
+        Args:
+            name: Context identifier
+
+        Returns:
+            UMLContext instance
+
+        Raises:
+            KeyError: If context name not found
+        """
+        if name not in self.contexts:
+            raise KeyError(
+                f"Context '{name}' not found. Available contexts: "
+                f"{', '.join(self.contexts.keys())}"
+            )
+        return self.contexts[name]
+
+    def list_contexts(self) -> list[str]:
+        """Get list of available context names.
+
+        Returns:
+            List of context identifier strings
+        """
+        return list(self.contexts.keys())
+
+    def __repr__(self) -> str:
+        return f"UMLConfig(contexts={list(self.contexts.keys())})"
+
+
+def load_uml_config(path: Path | str) -> UMLConfig:
+    """Load UML configuration from a YAML file.
+
+    Args:
+        path: Path to YAML configuration file
+
+    Returns:
+        UMLConfig instance
+    """
+    return UMLConfig(path)