rdf-construct 0.3.0__py3-none-any.whl

rdf_construct/stats/comparator.py

@@ -0,0 +1,298 @@
+"""Ontology statistics comparison.
+
+Compares statistics between two ontology versions and generates change summaries.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from rdf_construct.stats.collector import OntologyStats
+
+
+@dataclass
+class MetricChange:
+    """A change in a single metric between two versions.
+
+    Attributes:
+        category: The metric category (e.g., "basic", "hierarchy").
+        metric: The metric name (e.g., "classes", "max_depth").
+        old_value: Value in the old/baseline version.
+        new_value: Value in the new version.
+        delta: Numeric difference (new - old).
+        pct_change: Percentage change (may be None for non-numeric).
+        improved: Whether the change is an improvement (context-dependent).
+    """
+
+    category: str
+    metric: str
+    old_value: Any
+    new_value: Any
+    delta: float | int | None = None
+    pct_change: float | None = None
+    improved: bool | None = None
+
+
+@dataclass
+class ComparisonResult:
+    """Result of comparing two ontology versions.
+
+    Attributes:
+        old_source: Path/identifier of the old version.
+        new_source: Path/identifier of the new version.
+        changes: List of metric changes.
+        summary: Human-readable summary of the comparison.
+    """
+
+    old_source: str
+    new_source: str
+    changes: list[MetricChange] = field(default_factory=list)
+    summary: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert comparison to dictionary for JSON serialisation."""
+        return {
+            "old_source": self.old_source,
+            "new_source": self.new_source,
+            "changes": [
+                {
+                    "category": c.category,
+                    "metric": c.metric,
+                    "old_value": c.old_value,
+                    "new_value": c.new_value,
+                    "delta": c.delta,
+                    "pct_change": c.pct_change,
+                    "improved": c.improved,
+                }
+                for c in self.changes
+            ],
+            "summary": self.summary,
+        }
+
+
+def _pct_change(old: float | int, new: float | int) -> float | None:
+    """Calculate percentage change between two values.
+
+    Args:
+        old: Original value.
+        new: New value.
+
+    Returns:
+        Percentage change, or None if old is zero.
+    """
+    if old == 0:
+        return None
+    return round(((new - old) / old) * 100, 1)
+
+
+def _is_improvement(category: str, metric: str, delta: float | int) -> bool | None:
+    """Determine if a metric change is an improvement.
+
+    Some metrics are better when higher (e.g., documentation coverage),
+    others are better when lower (e.g., orphan rate).
+
+    Args:
+        category: The metric category.
+        metric: The metric name.
+        delta: The change in value.
+
+    Returns:
+        True if improved, False if degraded, None if neutral.
+    """
+    # Metrics where higher is better
+    higher_is_better = {
+        ("basic", "classes"),
+        ("basic", "object_properties"),
+        ("basic", "datatype_properties"),
+        ("documentation", "classes_labelled"),
+        ("documentation", "classes_labelled_pct"),
+        ("documentation", "classes_documented"),
+        ("documentation", "classes_documented_pct"),
+        ("documentation", "properties_labelled"),
+        ("documentation", "properties_labelled_pct"),
+        ("properties", "with_domain"),
+        ("properties", "with_range"),
+        ("properties", "domain_coverage"),
+        ("properties", "range_coverage"),
+    }
+
+    # Metrics where lower is better
+    lower_is_better = {
+        ("hierarchy", "orphan_classes"),
+        ("hierarchy", "orphan_rate"),
+        ("connectivity", "isolated_classes"),
+    }
+
+    key = (category, metric)
+    if key in higher_is_better:
+        return delta > 0
+    if key in lower_is_better:
+        return delta < 0
+
+    # Neutral - neither better nor worse
+    return None
+
+
+def _extract_numeric_metrics(stats: OntologyStats) -> dict[tuple[str, str], float | int]:
+    """Extract all numeric metrics from an OntologyStats object.
+
+    Args:
+        stats: The statistics object.
+
+    Returns:
+        Dictionary mapping (category, metric) -> value.
+    """
+    metrics: dict[tuple[str, str], float | int] = {}
+
+    # Basic
+    metrics[("basic", "triples")] = stats.basic.triples
+    metrics[("basic", "classes")] = stats.basic.classes
+    metrics[("basic", "object_properties")] = stats.basic.object_properties
+    metrics[("basic", "datatype_properties")] = stats.basic.datatype_properties
+    metrics[("basic", "annotation_properties")] = stats.basic.annotation_properties
+    metrics[("basic", "individuals")] = stats.basic.individuals
+
+    # Hierarchy
+    metrics[("hierarchy", "root_classes")] = stats.hierarchy.root_classes
+    metrics[("hierarchy", "leaf_classes")] = stats.hierarchy.leaf_classes
+    metrics[("hierarchy", "max_depth")] = stats.hierarchy.max_depth
+    metrics[("hierarchy", "avg_depth")] = stats.hierarchy.avg_depth
+    metrics[("hierarchy", "avg_branching")] = stats.hierarchy.avg_branching
+    metrics[("hierarchy", "orphan_classes")] = stats.hierarchy.orphan_classes
+    metrics[("hierarchy", "orphan_rate")] = stats.hierarchy.orphan_rate
+
+    # Properties
+    metrics[("properties", "with_domain")] = stats.properties.with_domain
+    metrics[("properties", "with_range")] = stats.properties.with_range
+    metrics[("properties", "domain_coverage")] = stats.properties.domain_coverage
+    metrics[("properties", "range_coverage")] = stats.properties.range_coverage
+    metrics[("properties", "inverse_pairs")] = stats.properties.inverse_pairs
+    metrics[("properties", "functional")] = stats.properties.functional
+    metrics[("properties", "symmetric")] = stats.properties.symmetric
+
+    # Documentation
+    metrics[("documentation", "classes_labelled")] = stats.documentation.classes_labelled
+    metrics[("documentation", "classes_labelled_pct")] = stats.documentation.classes_labelled_pct
+    metrics[("documentation", "classes_documented")] = stats.documentation.classes_documented
+    metrics[("documentation", "classes_documented_pct")] = stats.documentation.classes_documented_pct
+    metrics[("documentation", "properties_labelled")] = stats.documentation.properties_labelled
+    metrics[("documentation", "properties_labelled_pct")] = stats.documentation.properties_labelled_pct
+
+    # Complexity
+    metrics[("complexity", "avg_properties_per_class")] = stats.complexity.avg_properties_per_class
+    metrics[("complexity", "avg_superclasses_per_class")] = stats.complexity.avg_superclasses_per_class
+    metrics[("complexity", "multiple_inheritance_count")] = stats.complexity.multiple_inheritance_count
+    metrics[("complexity", "owl_restriction_count")] = stats.complexity.owl_restriction_count
+    metrics[("complexity", "owl_equivalent_count")] = stats.complexity.owl_equivalent_count
+
+    # Connectivity
+    metrics[("connectivity", "most_connected_count")] = stats.connectivity.most_connected_count
+    metrics[("connectivity", "isolated_classes")] = stats.connectivity.isolated_classes
+
+    return metrics
+
+
+def _generate_summary(changes: list[MetricChange]) -> str:
+    """Generate a human-readable summary of changes.
+
+    Args:
+        changes: List of metric changes.
+
+    Returns:
+        Summary string.
+    """
+    if not changes:
+        return "No significant changes detected."
+
+    # Count improvements and degradations
+    improvements = sum(1 for c in changes if c.improved is True)
+    degradations = sum(1 for c in changes if c.improved is False)
+
+    # Find notable changes
+    class_change = next((c for c in changes if c.metric == "classes"), None)
+    doc_change = next((c for c in changes if c.metric == "classes_documented_pct"), None)
+    orphan_change = next((c for c in changes if c.metric == "orphan_classes"), None)
+
+    parts = []
+
+    # Ontology growth/shrinkage
+    if class_change and class_change.delta:
+        if class_change.delta > 0:
+            parts.append(f"Ontology grew (+{class_change.delta} classes)")
+        else:
+            parts.append(f"Ontology shrank ({class_change.delta} classes)")
+
+    # Documentation improvements
+    if doc_change and doc_change.delta and doc_change.delta > 0:
+        parts.append("improved documentation coverage")
+
+    # Orphan changes
+    if orphan_change and orphan_change.delta:
+        if orphan_change.delta < 0:
+            parts.append("fewer orphan classes")
+        elif orphan_change.delta > 0:
+            parts.append("more orphan classes (review needed)")
+
+    if not parts:
+        if improvements > degradations:
+            return "Overall improvement in ontology quality."
+        elif degradations > improvements:
+            return "Some quality metrics have degraded."
+        else:
+            return "Minor changes with mixed impact."
+
+    return ", ".join(parts).capitalize() + "."
+
+
+def compare_stats(
+    old_stats: OntologyStats,
+    new_stats: OntologyStats,
+) -> ComparisonResult:
+    """Compare statistics between two ontology versions.
+
+    Args:
+        old_stats: Statistics from the baseline/old version.
+        new_stats: Statistics from the new version.
+
+    Returns:
+        ComparisonResult with all metric changes.
+    """
+    old_metrics = _extract_numeric_metrics(old_stats)
+    new_metrics = _extract_numeric_metrics(new_stats)
+
+    changes: list[MetricChange] = []
+
+    for key, old_val in old_metrics.items():
+        category, metric = key
+        new_val = new_metrics.get(key, 0)
+
+        # Skip if no change
+        if old_val == new_val:
+            continue
+
+        delta = new_val - old_val
+        pct = _pct_change(old_val, new_val)
+        improved = _is_improvement(category, metric, delta)
+
+        changes.append(
+            MetricChange(
+                category=category,
+                metric=metric,
+                old_value=old_val,
+                new_value=new_val,
+                delta=delta,
+                pct_change=pct,
+                improved=improved,
+            )
+        )
+
+    # Sort by category then metric
+    changes.sort(key=lambda c: (c.category, c.metric))
+
+    summary = _generate_summary(changes)
+
+    return ComparisonResult(
+        old_source=old_stats.source,
+        new_source=new_stats.source,
+        changes=changes,
+        summary=summary,
+    )

rdf_construct/stats/formatters/__init__.py

@@ -0,0 +1,83 @@
+"""Output formatters 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
+from rdf_construct.stats.formatters.text import format_text_stats, format_text_comparison
+from rdf_construct.stats.formatters.json import format_json_stats, format_json_comparison
+from rdf_construct.stats.formatters.markdown import format_markdown_stats, format_markdown_comparison
+
+
+def format_stats(
+    stats: OntologyStats,
+    format_name: str = "text",
+    graph: Optional[Graph] = None,
+) -> str:
+    """Format ontology statistics for output.
+
+    Args:
+        stats: The statistics to format.
+        format_name: Output format ("text", "json", "markdown", "md").
+        graph: Optional graph for CURIE formatting.
+
+    Returns:
+        Formatted string representation.
+
+    Raises:
+        ValueError: If format_name is not recognised.
+    """
+    formatters = {
+        "text": format_text_stats,
+        "json": format_json_stats,
+        "markdown": format_markdown_stats,
+        "md": format_markdown_stats,
+    }
+
+    formatter = formatters.get(format_name.lower())
+    if not formatter:
+        valid = ", ".join(sorted(formatters.keys()))
+        raise ValueError(f"Unknown format '{format_name}'. Valid formats: {valid}")
+
+    return formatter(stats, graph)
+
+
+def format_comparison(
+    comparison: ComparisonResult,
+    format_name: str = "text",
+    graph: Optional[Graph] = None,
+) -> str:
+    """Format comparison results for output.
+
+    Args:
+        comparison: The comparison result to format.
+        format_name: Output format ("text", "json", "markdown", "md").
+        graph: Optional graph for CURIE formatting.
+
+    Returns:
+        Formatted string representation.
+
+    Raises:
+        ValueError: If format_name is not recognised.
+    """
+    formatters = {
+        "text": format_text_comparison,
+        "json": format_json_comparison,
+        "markdown": format_markdown_comparison,
+        "md": format_markdown_comparison,
+    }
+
+    formatter = formatters.get(format_name.lower())
+    if not formatter:
+        valid = ", ".join(sorted(formatters.keys()))
+        raise ValueError(f"Unknown format '{format_name}'. Valid formats: {valid}")
+
+    return formatter(comparison, graph)
+
+
+__all__ = [
+    "format_stats",
+    "format_comparison",
+]

rdf_construct/stats/formatters/json.py

@@ -0,0 +1,38 @@
+"""JSON output formatter for ontology statistics."""
+
+import json
+from typing import Optional
+
+from rdflib import Graph
+
+from rdf_construct.stats.collector import OntologyStats
+from rdf_construct.stats.comparator import ComparisonResult
+
+
+def format_json_stats(stats: OntologyStats, graph: Optional[Graph] = None) -> str:
+    """Format ontology statistics as JSON.
+
+    Args:
+        stats: The statistics to format.
+        graph: Optional graph (not used for JSON format).
+
+    Returns:
+        JSON string representation.
+    """
+    return json.dumps(stats.to_dict(), indent=2)
+
+
+def format_json_comparison(
+    comparison: ComparisonResult,
+    graph: Optional[Graph] = None,
+) -> str:
+    """Format comparison results as JSON.
+
+    Args:
+        comparison: The comparison result to format.
+        graph: Optional graph (not used for JSON format).
+
+    Returns:
+        JSON string representation.
+    """
+    return json.dumps(comparison.to_dict(), indent=2)

rdf_construct/stats/formatters/markdown.py

@@ -0,0 +1,153 @@
+"""Markdown 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 format_markdown_stats(stats: OntologyStats, graph: Optional[Graph] = None) -> str:
+    """Format ontology statistics as Markdown table.
+
+    Designed for embedding in README files or documentation.
+
+    Args:
+        stats: The statistics to format.
+        graph: Optional graph for CURIE formatting.
+
+    Returns:
+        Markdown string representation.
+    """
+    lines = []
+
+    lines.append(f"## Ontology Statistics")
+    lines.append("")
+    lines.append(f"**Source:** `{stats.source}`")
+    lines.append("")
+
+    # Summary table
+    lines.append("| Metric | Value |")
+    lines.append("|--------|-------|")
+    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"| Max Hierarchy Depth | {stats.hierarchy.max_depth} |")
+    lines.append(f"| Documentation Coverage | {_format_pct(stats.documentation.classes_documented_pct)} |")
+    lines.append("")
+
+    # Detailed sections
+    lines.append("### Structure")
+    lines.append("")
+    lines.append("| Metric | Value |")
+    lines.append("|--------|-------|")
+    lines.append(f"| Total Triples | {stats.basic.triples:,} |")
+    lines.append(f"| Root Classes | {stats.hierarchy.root_classes} |")
+    lines.append(f"| Leaf Classes | {stats.hierarchy.leaf_classes} |")
+    lines.append(f"| Avg Branching Factor | {stats.hierarchy.avg_branching:.1f} |")
+    lines.append(f"| Orphan Classes | {stats.hierarchy.orphan_classes} ({_format_pct(stats.hierarchy.orphan_rate)}) |")
+    lines.append("")
+
+    lines.append("### Properties")
+    lines.append("")
+    lines.append("| Metric | Value |")
+    lines.append("|--------|-------|")
+    lines.append(f"| With Domain | {stats.properties.with_domain} ({_format_pct(stats.properties.domain_coverage)}) |")
+    lines.append(f"| With Range | {stats.properties.with_range} ({_format_pct(stats.properties.range_coverage)}) |")
+    lines.append(f"| Functional | {stats.properties.functional} |")
+    lines.append(f"| Symmetric | {stats.properties.symmetric} |")
+    lines.append("")
+
+    lines.append("### Documentation")
+    lines.append("")
+    lines.append("| Metric | Value |")
+    lines.append("|--------|-------|")
+    lines.append(f"| Classes Labelled | {stats.documentation.classes_labelled} ({_format_pct(stats.documentation.classes_labelled_pct)}) |")
+    lines.append(f"| Classes Documented | {stats.documentation.classes_documented} ({_format_pct(stats.documentation.classes_documented_pct)}) |")
+    lines.append(f"| Properties Labelled | {stats.documentation.properties_labelled} ({_format_pct(stats.documentation.properties_labelled_pct)}) |")
+    lines.append("")
+
+    lines.append("*Generated by rdf-construct stats*")
+
+    return "\n".join(lines)
+
+
+def format_markdown_comparison(
+    comparison: ComparisonResult,
+    graph: Optional[Graph] = None,
+) -> str:
+    """Format comparison results as Markdown.
+
+    Args:
+        comparison: The comparison result to format.
+        graph: Optional graph for CURIE formatting.
+
+    Returns:
+        Markdown string representation.
+    """
+    lines = []
+
+    lines.append(f"## Ontology Comparison")
+    lines.append("")
+    lines.append(f"**Old:** `{comparison.old_source}`")
+    lines.append(f"**New:** `{comparison.new_source}`")
+    lines.append("")
+
+    if not comparison.changes:
+        lines.append("No changes detected.")
+        return "\n".join(lines)
+
+    # Summary
+    lines.append(f"> {comparison.summary}")
+    lines.append("")
+
+    # Changes table
+    lines.append("| Category | Metric | Old | New | Change |")
+    lines.append("|----------|--------|-----|-----|--------|")
+
+    for change in comparison.changes:
+        category = change.category.title()
+        metric = change.metric.replace("_", " ").title()
+        old_val = _format_value(change.old_value)
+        new_val = _format_value(change.new_value)
+
+        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 += " ⚠"
+
+        lines.append(f"| {category} | {metric} | {old_val} | {new_val} | {delta_str} |")
+
+    lines.append("")
+    lines.append("*Generated by rdf-construct stats --compare*")
+
+    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)