rdf-construct 0.2.0__py3-none-any.whl

rdf_construct/stats/formatters/text.py

@@ -0,0 +1,186 @@
+"""Text output formatter for ontology statistics."""
+
+from typing import Optional
+
+from rdflib import Graph
+
+from rdf_construct.stats.collector import OntologyStats
+from rdf_construct.stats.comparator import ComparisonResult
+
+
+def _format_pct(value: float) -> str:
+    """Format a percentage value for display."""
+    return f"{value * 100:.1f}%"
+
+
+def _shorten_uri(uri: str, graph: Optional[Graph] = None) -> str:
+    """Shorten a URI to CURIE if possible."""
+    if graph:
+        try:
+            qname = graph.namespace_manager.qname(uri)
+            return qname
+        except Exception:
+            pass
+    # Fallback: extract local name
+    if "#" in uri:
+        return uri.split("#")[-1]
+    if "/" in uri:
+        return uri.rsplit("/", 1)[-1]
+    return uri
+
+
+def format_text_stats(stats: OntologyStats, graph: Optional[Graph] = None) -> str:
+    """Format ontology statistics as aligned text.
+
+    Args:
+        stats: The statistics to format.
+        graph: Optional graph for CURIE formatting.
+
+    Returns:
+        Formatted text string.
+    """
+    lines = []
+
+    # Header
+    lines.append(f"Ontology Statistics: {stats.source}")
+    lines.append("=" * 50)
+    lines.append("")
+
+    # Basic counts
+    lines.append("BASIC COUNTS")
+    lines.append(f"  Triples:                  {stats.basic.triples:,}")
+    lines.append(f"  Classes:                  {stats.basic.classes:,}")
+    lines.append(f"  Object Properties:        {stats.basic.object_properties:,}")
+    lines.append(f"  Datatype Properties:      {stats.basic.datatype_properties:,}")
+    lines.append(f"  Annotation Properties:    {stats.basic.annotation_properties:,}")
+    lines.append(f"  Individuals:              {stats.basic.individuals:,}")
+    lines.append("")
+
+    # Hierarchy
+    lines.append("HIERARCHY")
+    lines.append(f"  Root Classes:             {stats.hierarchy.root_classes:,}")
+    lines.append(f"  Leaf Classes:             {stats.hierarchy.leaf_classes:,}")
+    lines.append(f"  Max Depth:                {stats.hierarchy.max_depth}")
+    lines.append(f"  Avg Depth:                {stats.hierarchy.avg_depth:.1f}")
+    lines.append(f"  Avg Branching:            {stats.hierarchy.avg_branching:.1f}")
+    orphan_pct = _format_pct(stats.hierarchy.orphan_rate)
+    lines.append(f"  Orphan Classes:           {stats.hierarchy.orphan_classes} ({orphan_pct})")
+    lines.append("")
+
+    # Properties
+    lines.append("PROPERTIES")
+    dom_pct = _format_pct(stats.properties.domain_coverage)
+    range_pct = _format_pct(stats.properties.range_coverage)
+    lines.append(f"  With Domain:              {stats.properties.with_domain} ({dom_pct})")
+    lines.append(f"  With Range:               {stats.properties.with_range} ({range_pct})")
+    lines.append(f"  Inverse Pairs:            {stats.properties.inverse_pairs}")
+    lines.append(f"  Functional:               {stats.properties.functional}")
+    lines.append(f"  Symmetric:                {stats.properties.symmetric}")
+    lines.append("")
+
+    # Documentation
+    lines.append("DOCUMENTATION")
+    cls_label_pct = _format_pct(stats.documentation.classes_labelled_pct)
+    cls_doc_pct = _format_pct(stats.documentation.classes_documented_pct)
+    prop_label_pct = _format_pct(stats.documentation.properties_labelled_pct)
+    lines.append(f"  Classes Labelled:         {stats.documentation.classes_labelled} ({cls_label_pct})")
+    lines.append(f"  Classes Documented:       {stats.documentation.classes_documented} ({cls_doc_pct})")
+    lines.append(f"  Properties Labelled:      {stats.documentation.properties_labelled} ({prop_label_pct})")
+    lines.append("")
+
+    # Complexity
+    lines.append("COMPLEXITY")
+    lines.append(f"  Avg Props/Class:          {stats.complexity.avg_properties_per_class:.1f}")
+    lines.append(f"  Avg Superclasses:         {stats.complexity.avg_superclasses_per_class:.1f}")
+    lines.append(f"  Multiple Inheritance:     {stats.complexity.multiple_inheritance_count}")
+    lines.append(f"  OWL Restrictions:         {stats.complexity.owl_restriction_count}")
+    lines.append(f"  Equivalent Classes:       {stats.complexity.owl_equivalent_count}")
+    lines.append("")
+
+    # Connectivity
+    lines.append("CONNECTIVITY")
+    if stats.connectivity.most_connected_class:
+        most_connected = _shorten_uri(stats.connectivity.most_connected_class, graph)
+        lines.append(f"  Most Connected:           {most_connected} ({stats.connectivity.most_connected_count} refs)")
+    else:
+        lines.append(f"  Most Connected:           (none)")
+    lines.append(f"  Isolated Classes:         {stats.connectivity.isolated_classes}")
+
+    return "\n".join(lines)
+
+
+def format_text_comparison(
+        comparison: ComparisonResult,
+        graph: Optional[Graph] = None,
+) -> str:
+    """Format comparison results as aligned text.
+
+    Args:
+        comparison: The comparison result to format.
+        graph: Optional graph for CURIE formatting.
+
+    Returns:
+        Formatted text string.
+    """
+    lines = []
+
+    # Header
+    lines.append(f"Comparing: {comparison.old_source} → {comparison.new_source}")
+    lines.append("=" * 60)
+    lines.append("")
+
+    if not comparison.changes:
+        lines.append("No changes detected.")
+        return "\n".join(lines)
+
+    # Table header
+    lines.append(f"{'Metric':<30} {'Old':>10} {'New':>10} {'Change':>15}")
+    lines.append("-" * 65)
+
+    # Group changes by category
+    current_category = None
+    for change in comparison.changes:
+        if change.category != current_category:
+            current_category = change.category
+            lines.append(f"\n{current_category.upper()}")
+
+        # Format the change
+        old_str = _format_value(change.old_value)
+        new_str = _format_value(change.new_value)
+
+        # Format delta with sign
+        if change.delta is not None:
+            if change.pct_change is not None:
+                delta_str = f"{change.delta:+g} ({change.pct_change:+.1f}%)"
+            else:
+                delta_str = f"{change.delta:+g}"
+        else:
+            delta_str = "-"
+
+        # Add indicator
+        if change.improved is True:
+            delta_str += " ✓"
+        elif change.improved is False:
+            delta_str += " ⚠"
+
+        metric_name = change.metric.replace("_", " ").title()
+        lines.append(f"  {metric_name:<28} {old_str:>10} {new_str:>10} {delta_str:>15}")
+
+    lines.append("")
+    lines.append(f"Summary: {comparison.summary}")
+
+    return "\n".join(lines)
+
+
+def _format_value(value: float | int | str | None) -> str:
+    """Format a metric value for display."""
+    if value is None:
+        return "-"
+    if isinstance(value, float):
+        if value < 1:
+            # Probably a percentage/rate
+            return f"{value * 100:.1f}%"
+        return f"{value:.2f}"
+    if isinstance(value, int):
+        return f"{value:,}"
+    return str(value)

rdf_construct/stats/metrics/__init__.py

@@ -0,0 +1,26 @@
+"""Metric collectors for RDF ontology statistics."""
+
+from rdf_construct.stats.metrics.basic import BasicStats, collect_basic_stats
+from rdf_construct.stats.metrics.hierarchy import HierarchyStats, collect_hierarchy_stats
+from rdf_construct.stats.metrics.properties import PropertyStats, collect_property_stats
+from rdf_construct.stats.metrics.documentation import (
+    DocumentationStats,
+    collect_documentation_stats,
+)
+from rdf_construct.stats.metrics.complexity import ComplexityStats, collect_complexity_stats
+from rdf_construct.stats.metrics.connectivity import ConnectivityStats, collect_connectivity_stats
+
+__all__ = [
+    "BasicStats",
+    "collect_basic_stats",
+    "HierarchyStats",
+    "collect_hierarchy_stats",
+    "PropertyStats",
+    "collect_property_stats",
+    "DocumentationStats",
+    "collect_documentation_stats",
+    "ComplexityStats",
+    "collect_complexity_stats",
+    "ConnectivityStats",
+    "collect_connectivity_stats",
+]

rdf_construct/stats/metrics/basic.py

@@ -0,0 +1,147 @@
+"""Basic count metrics for RDF ontologies.
+
+Provides fundamental counts: triples, classes, properties, individuals.
+"""
+
+from dataclasses import dataclass, field
+
+from rdflib import Graph, RDF, RDFS
+from rdflib.namespace import OWL
+
+
+@dataclass
+class BasicStats:
+    """Basic count statistics for an ontology.
+
+    Attributes:
+        triples: Total number of triples in the graph.
+        classes: Number of owl:Class + rdfs:Class entities.
+        object_properties: Number of owl:ObjectProperty entities.
+        datatype_properties: Number of owl:DatatypeProperty entities.
+        annotation_properties: Number of owl:AnnotationProperty entities.
+        individuals: Number of named individuals (non-class, non-property).
+    """
+
+    triples: int = 0
+    classes: int = 0
+    object_properties: int = 0
+    datatype_properties: int = 0
+    annotation_properties: int = 0
+    individuals: int = 0
+
+    @property
+    def total_properties(self) -> int:
+        """Total count of all property types."""
+        return self.object_properties + self.datatype_properties + self.annotation_properties
+
+
+def get_all_classes(graph: Graph) -> set:
+    """Get all classes from the graph (owl:Class + rdfs:Class).
+
+    Args:
+        graph: RDF graph to query.
+
+    Returns:
+        Set of class URIRefs.
+    """
+    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.
+
+    Args:
+        graph: RDF graph to query.
+
+    Returns:
+        Set of property URIRefs (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 get_individuals(graph: Graph) -> set:
+    """Get all named individuals from the graph.
+
+    Individuals are subjects that are typed but not classes or properties.
+
+    Args:
+        graph: RDF graph to query.
+
+    Returns:
+        Set of individual URIRefs.
+    """
+    classes = get_all_classes(graph)
+    properties = get_all_properties(graph)
+
+    # Get all typed subjects
+    all_typed = set()
+    for s in graph.subjects(RDF.type, None):
+        # Skip blank nodes and literal subjects
+        if hasattr(s, "n3"):
+            all_typed.add(s)
+
+    # Exclude classes, properties, and ontology declarations
+    ontologies = set(graph.subjects(RDF.type, OWL.Ontology))
+    individuals = all_typed - classes - properties - ontologies
+
+    # Also exclude property types themselves and OWL constructs
+    owl_constructs = {
+        OWL.Class,
+        OWL.ObjectProperty,
+        OWL.DatatypeProperty,
+        OWL.AnnotationProperty,
+        OWL.Restriction,
+        OWL.Ontology,
+        RDFS.Class,
+        RDF.Property,
+    }
+    individuals = {i for i in individuals if i not in owl_constructs}
+
+    return individuals
+
+
+def collect_basic_stats(graph: Graph) -> BasicStats:
+    """Collect basic count statistics from an RDF graph.
+
+    Args:
+        graph: RDF graph to analyse.
+
+    Returns:
+        BasicStats with all count metrics populated.
+    """
+    # Total triples
+    triples = len(graph)
+
+    # Classes (both owl:Class and rdfs:Class)
+    classes = len(get_all_classes(graph))
+
+    # Object properties
+    obj_props = len(set(graph.subjects(RDF.type, OWL.ObjectProperty)))
+
+    # Datatype properties
+    data_props = len(set(graph.subjects(RDF.type, OWL.DatatypeProperty)))
+
+    # Annotation properties
+    ann_props = len(set(graph.subjects(RDF.type, OWL.AnnotationProperty)))
+
+    # Individuals
+    individuals = len(get_individuals(graph))
+
+    return BasicStats(
+        triples=triples,
+        classes=classes,
+        object_properties=obj_props,
+        datatype_properties=data_props,
+        annotation_properties=ann_props,
+        individuals=individuals,
+    )

rdf_construct/stats/metrics/complexity.py

@@ -0,0 +1,137 @@
+"""Complexity metrics for RDF ontologies.
+
+Analyses structural complexity: multiple inheritance, axioms, restrictions.
+"""
+
+from collections import defaultdict
+from dataclasses import dataclass
+
+from rdflib import Graph, RDF, RDFS
+from rdflib.namespace import OWL
+
+
+@dataclass
+class ComplexityStats:
+    """Complexity statistics for an ontology.
+
+    Attributes:
+        avg_properties_per_class: Average properties referencing each class.
+        avg_superclasses_per_class: Average number of superclasses per class.
+        multiple_inheritance_count: Classes with 2+ direct superclasses.
+        owl_restriction_count: Number of owl:Restriction nodes.
+        owl_equivalent_count: Number of owl:equivalentClass statements.
+    """
+
+    avg_properties_per_class: float = 0.0
+    avg_superclasses_per_class: float = 0.0
+    multiple_inheritance_count: int = 0
+    owl_restriction_count: int = 0
+    owl_equivalent_count: int = 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 _count_properties_per_class(graph: Graph, classes: set) -> dict:
+    """Count how many properties reference each class (via domain/range).
+
+    Args:
+        graph: RDF graph to query.
+        classes: Set of class URIRefs.
+
+    Returns:
+        Dictionary mapping class -> property count.
+    """
+    counts: dict = defaultdict(int)
+
+    # Count domain references
+    for s, p, o in graph.triples((None, RDFS.domain, None)):
+        if o in classes:
+            counts[o] += 1
+
+    # Count range references
+    for s, p, o in graph.triples((None, RDFS.range, None)):
+        if o in classes:
+            counts[o] += 1
+
+    return dict(counts)
+
+
+def _count_superclasses(graph: Graph, classes: set) -> dict:
+    """Count direct superclasses for each class.
+
+    Args:
+        graph: RDF graph to query.
+        classes: Set of class URIRefs.
+
+    Returns:
+        Dictionary mapping class -> superclass count.
+    """
+    counts: dict = {}
+
+    for cls in classes:
+        superclasses = set(graph.objects(cls, RDFS.subClassOf))
+        # Only count named classes, not restrictions or other constructs
+        named_supers = superclasses & classes
+        counts[cls] = len(named_supers)
+
+    return counts
+
+
+def _count_multiple_inheritance(superclass_counts: dict) -> int:
+    """Count classes with multiple inheritance (2+ superclasses).
+
+    Args:
+        superclass_counts: Dictionary mapping class -> superclass count.
+
+    Returns:
+        Number of classes with multiple inheritance.
+    """
+    return sum(1 for count in superclass_counts.values() if count >= 2)
+
+
+def collect_complexity_stats(graph: Graph) -> ComplexityStats:
+    """Collect complexity statistics from an RDF graph.
+
+    Args:
+        graph: RDF graph to analyse.
+
+    Returns:
+        ComplexityStats with all complexity metrics populated.
+    """
+    classes = _get_all_classes(graph)
+    total_classes = len(classes)
+
+    if total_classes == 0:
+        return ComplexityStats()
+
+    # Properties per class
+    prop_counts = _count_properties_per_class(graph, classes)
+    total_prop_refs = sum(prop_counts.values())
+    avg_props = total_prop_refs / total_classes if total_classes else 0.0
+
+    # Superclasses per class
+    super_counts = _count_superclasses(graph, classes)
+    total_supers = sum(super_counts.values())
+    avg_supers = total_supers / total_classes if total_classes else 0.0
+
+    # Multiple inheritance
+    multi_inherit = _count_multiple_inheritance(super_counts)
+
+    # OWL restrictions
+    restrictions = len(set(graph.subjects(RDF.type, OWL.Restriction)))
+
+    # Equivalent class statements
+    equivalents = len(list(graph.triples((None, OWL.equivalentClass, None))))
+
+    return ComplexityStats(
+        avg_properties_per_class=round(avg_props, 2),
+        avg_superclasses_per_class=round(avg_supers, 2),
+        multiple_inheritance_count=multi_inherit,
+        owl_restriction_count=restrictions,
+        owl_equivalent_count=equivalents,
+    )

rdf_construct/stats/metrics/connectivity.py

@@ -0,0 +1,130 @@
+"""Connectivity metrics for RDF ontologies.
+
+Analyses how classes are connected through properties.
+"""
+
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import Optional
+
+from rdflib import Graph, RDF, RDFS, URIRef
+from rdflib.namespace import OWL
+
+
+@dataclass
+class ConnectivityStats:
+    """Connectivity statistics for an ontology.
+
+    Attributes:
+        most_connected_class: URI of the class referenced by most properties.
+        most_connected_count: Number of properties referencing the most connected class.
+        isolated_classes: Classes not referenced by any property domain/range.
+    """
+
+    most_connected_class: Optional[str] = None
+    most_connected_count: int = 0
+    isolated_classes: int = 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 _count_property_references(graph: Graph, classes: set) -> dict:
+    """Count property references to each class (via domain/range).
+
+    A class is "connected" if a property references it in its domain or range.
+
+    Args:
+        graph: RDF graph to query.
+        classes: Set of class URIRefs.
+
+    Returns:
+        Dictionary mapping class -> reference count.
+    """
+    counts: dict = defaultdict(int)
+
+    # Count domain references
+    for s, p, o in graph.triples((None, RDFS.domain, None)):
+        if o in classes:
+            counts[o] += 1
+
+    # Count range references
+    for s, p, o in graph.triples((None, RDFS.range, None)):
+        if o in classes:
+            counts[o] += 1
+
+    return dict(counts)
+
+
+def _find_most_connected(ref_counts: dict) -> tuple[Optional[str], int]:
+    """Find the class with the most property references.
+
+    Args:
+        ref_counts: Dictionary mapping class -> reference count.
+
+    Returns:
+        Tuple of (class URI string, reference count).
+    """
+    if not ref_counts:
+        return None, 0
+
+    most_connected = max(ref_counts.items(), key=lambda x: x[1])
+    uri = str(most_connected[0]) if most_connected[0] else None
+    return uri, most_connected[1]
+
+
+def _count_isolated(classes: set, ref_counts: dict, graph: Graph) -> int:
+    """Count classes not connected to any property.
+
+    A class is isolated if:
+    - No property has it as domain or range
+    - AND it has no subclasses or superclasses (not part of hierarchy)
+
+    Args:
+        classes: Set of class URIRefs.
+        ref_counts: Dictionary mapping class -> reference count.
+        graph: RDF graph to query for hierarchy.
+
+    Returns:
+        Number of isolated classes.
+    """
+    isolated = 0
+    for cls in classes:
+        # Not referenced by properties
+        if ref_counts.get(cls, 0) == 0:
+            # Also check if it's disconnected from hierarchy
+            has_super = any(graph.objects(cls, RDFS.subClassOf))
+            has_sub = any(graph.subjects(RDFS.subClassOf, cls))
+            if not has_super and not has_sub:
+                isolated += 1
+    return isolated
+
+
+def collect_connectivity_stats(graph: Graph) -> ConnectivityStats:
+    """Collect connectivity statistics from an RDF graph.
+
+    Args:
+        graph: RDF graph to analyse.
+
+    Returns:
+        ConnectivityStats with all connectivity metrics populated.
+    """
+    classes = _get_all_classes(graph)
+
+    if not classes:
+        return ConnectivityStats()
+
+    ref_counts = _count_property_references(graph, classes)
+
+    most_uri, most_count = _find_most_connected(ref_counts)
+    isolated = _count_isolated(classes, ref_counts, graph)
+
+    return ConnectivityStats(
+        most_connected_class=most_uri,
+        most_connected_count=most_count,
+        isolated_classes=isolated,
+    )