robot-data-audit 0.2.0__tar.gz → 0.2.2__tar.gz

{robot_data_audit-0.2.0 → robot_data_audit-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: robot-data-audit
-Version: 0.2.0
+Version: 0.2.2
 Summary: Robot Data Audit (RDA) - Quality auditing tool for robot datasets
 Author-email: Niu Su Tech <dev@niusutech.com>
 License: MIT

{robot_data_audit-0.2.0 → robot_data_audit-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "robot-data-audit"
-version = "0.2.0"
+version = "0.2.2"
 description = "Robot Data Audit (RDA) - Quality auditing tool for robot datasets"
 readme = "README.md"
 license = { text = "MIT" }

{robot_data_audit-0.2.0 → robot_data_audit-0.2.2}/rda/__init__.py

@@ -1,3 +1,3 @@
 """Robot Data Audit (RDA) - Quality auditing tool for robot datasets."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{robot_data_audit-0.2.0 → robot_data_audit-0.2.2}/rda/audit/dataset_audit.py

@@ -6,6 +6,7 @@ from typing import Dict, List, Optional
 
 from rda.audit.episode_audit import EpisodeAuditResult, EpisodeAuditor
 from rda.audit.rules import AuditVerdict
+from rda.calibration.reference import ReferenceProfile
 from rda.io.schema import DatasetInfo
 
 
@@ -37,19 +38,39 @@ class DatasetAuditResult:
 
 
 class DatasetAuditor:
-    """Orchestrates the full audit of a dataset, episode by episode."""
+    """Orchestrates the full audit of a dataset, episode by episode.
+
+    Args:
+        episode_auditor: EpisodeAuditor instance to use for each episode.
+            If None, a default EpisodeAuditor is created.
+        reference: Optional :class:`ReferenceProfile` for behavioral scoring.
+            When provided and no ``episode_auditor`` is given, a
+            :class:`~rda.calibration.BehavioralScorer` is automatically
+            created and passed to the EpisodeAuditor.
+    """
 
     def __init__(
         self,
         episode_auditor: Optional[EpisodeAuditor] = None,
+        reference: Optional[ReferenceProfile] = None,
     ) -> None:
         """Initialize the dataset auditor.
 
         Args:
             episode_auditor: EpisodeAuditor instance to use for each episode.
                 If None, a default EpisodeAuditor with all metrics is created.
+            reference: Optional ReferenceProfile for behavioral scoring.
+                When provided and episode_auditor is None, a BehavioralScorer
+                is automatically created and injected into the EpisodeAuditor.
         """
-        self.episode_auditor = episode_auditor or EpisodeAuditor()
+        if episode_auditor is not None:
+            self.episode_auditor = episode_auditor
+        elif reference is not None:
+            from rda.calibration.scorer import BehavioralScorer
+            scorer = BehavioralScorer(reference)
+            self.episode_auditor = EpisodeAuditor(scorer=scorer)
+        else:
+            self.episode_auditor = EpisodeAuditor()
 
     def audit_dataset(
         self,

{robot_data_audit-0.2.0 → robot_data_audit-0.2.2}/rda/calibration/__init__.py

@@ -22,8 +22,17 @@ Example::
 """
 from __future__ import annotations
 
-from rda.calibration.portable import PORTABLE_METRICS, extract_portable_metrics
-from rda.calibration.reference import MetricStats, ReferenceProfile
+from rda.calibration.portable import (
+    METRIC_DIRECTIONS,
+    PORTABLE_METRICS,
+    extract_portable_metrics,
+)
+from rda.calibration.reference import (
+    MetricStats,
+    ReferenceProfile,
+    load_reference,
+    save_reference,
+)
 from rda.calibration.scorer import BehavioralScore, BehavioralScorer, calibrate
 
 __all__ = [
@@ -33,5 +42,8 @@ __all__ = [
     "BehavioralScorer",
     "calibrate",
     "PORTABLE_METRICS",
+    "METRIC_DIRECTIONS",
     "extract_portable_metrics",
+    "save_reference",
+    "load_reference",
 ]

robot_data_audit-0.2.2/rda/calibration/normalization.py

@@ -0,0 +1,178 @@
+"""MAD-based normalization utilities.
+
+Implements robust z-score normalization using Median Absolute Deviation
+(MAD) instead of standard deviation, which is less sensitive to outliers
+in robot trajectory data.
+"""
+from __future__ import annotations
+
+from typing import Dict, List, Tuple
+
+import numpy as np
+
+
+def mad(values: np.ndarray) -> float:
+    """Compute Median Absolute Deviation of a 1-D array.
+
+    Args:
+        values: 1-D array of numeric values.
+
+    Returns:
+        MAD value. Returns 0.0 for empty arrays.
+    """
+    if values.size == 0:
+        return 0.0
+    med = float(np.median(values))
+    return float(np.median(np.abs(values - med)))
+
+
+def percentile_stats(values: np.ndarray) -> Dict[str, float]:
+    """Compute p05, p25, median, p75, p95 for a 1-D array.
+
+    Args:
+        values: 1-D array of numeric values.
+
+    Returns:
+        Dict with keys ``p05``, ``p25``, ``median``, ``p75``, ``p95``.
+        All zeros for empty input.
+    """
+    if values.size == 0:
+        return {"p05": 0.0, "p25": 0.0, "median": 0.0, "p75": 0.0, "p95": 0.0}
+    pcts = np.percentile(values, [5, 25, 50, 75, 95])
+    return {
+        "p05": float(pcts[0]),
+        "p25": float(pcts[1]),
+        "median": float(pcts[2]),
+        "p75": float(pcts[3]),
+        "p95": float(pcts[4]),
+    }
+
+
+def robust_z_scores(values: np.ndarray) -> np.ndarray:
+    """Compute robust (MAD-based) z-scores for a 1-D array.
+
+    Scaled by 0.6745 so that the result is comparable to standard
+    z-scores for normally distributed data.
+
+    Args:
+        values: 1-D array of raw values.
+
+    Returns:
+        Array of robust z-scores with same shape as input.
+        All zeros if MAD is zero.
+    """
+    if values.size == 0:
+        return np.array([], dtype=np.float64)
+    med = float(np.median(values))
+    m = mad(values)
+    if m == 0.0:
+        return np.zeros_like(values, dtype=np.float64)
+    return 0.6745 * (values - med) / m
+
+
+def bad_z_scores(values: np.ndarray, direction: str) -> np.ndarray:
+    """Compute direction-aware bad z-scores for a 1-D array.
+
+    For "higher_is_worse" metrics, positive z-scores indicate anomalies
+    (higher values = more anomalous), so bad_z = raw_z.
+    For "lower_is_worse" metrics, negative z-scores indicate anomalies
+    (lower values = more anomalous), so bad_z = -raw_z.
+
+    After this transformation, positive bad_z always means "more anomalous"
+    regardless of the original metric direction.
+
+    Args:
+        values: 1-D array of raw values.
+        direction: One of ``"higher_is_worse"`` or ``"lower_is_worse"``.
+
+    Returns:
+        Array of bad z-scores with same shape as input.
+        All zeros if MAD is zero.
+
+    Raises:
+        ValueError: If direction is not a recognized value.
+    """
+    raw_z = robust_z_scores(values)
+    if direction == "higher_is_worse":
+        return raw_z
+    elif direction == "lower_is_worse":
+        return -raw_z
+    else:
+        raise ValueError(
+            f"Unknown direction '{direction}'. "
+            "Must be 'higher_is_worse' or 'lower_is_worse'."
+        )
+
+
+def compute_pca_loadings(
+    z_matrix: np.ndarray,
+    metric_names: List[str],
+) -> Tuple[List[Dict[str, float]], List[float]]:
+    """Compute principal component loadings from a z-score matrix.
+
+    Returns up to min(2, n_features) components for use in behavioral
+    scoring. The first component captures the dominant anomaly direction,
+    while the second captures orthogonal variance.
+
+    Args:
+        z_matrix: Array of shape ``(n_episodes, n_metrics)`` containing
+            robust z-scores (already normalized and direction-adjusted).
+        metric_names: List of metric names in column order.
+
+    Returns:
+        Tuple of ``(components_list, explained_variance_ratios)`` where:
+        - ``components_list`` is a list of dicts, each mapping metric names
+          to their loading weights for that component.
+        - ``explained_variance_ratios`` is a list of floats indicating
+          how much variance each component explains.
+        Returns empty lists if PCA cannot be computed.
+    """
+    n_samples, n_features = z_matrix.shape
+    if n_samples < 2 or n_features < 2:
+        return [], []
+
+    # Use SVD-based PCA on the covariance matrix for numerical stability.
+    # Center the data (z-scores are already roughly centered, but
+    # centering explicitly is correct regardless).
+    X = z_matrix - np.mean(z_matrix, axis=0)
+
+    try:
+        # Full SVD: U (n×n), S (min(n,m)), Vt (m×m)
+        U, S, Vt = np.linalg.svd(X, full_matrices=False)
+    except np.linalg.LinAlgError:
+        return [], []
+
+    if S.size == 0 or S[0] == 0.0:
+        return [], []
+
+    # Explained variance ratio: singular values squared / sum of all
+    total_variance = float(np.sum(S ** 2))
+    if total_variance == 0.0:
+        return [], []
+
+    # Number of components to return: min(2, n_features)
+    n_components = min(2, n_features)
+
+    components_list: List[Dict[str, float]] = []
+    explained_variance_ratios: List[float] = []
+
+    for i in range(n_components):
+        if i >= len(S) or S[i] == 0.0:
+            break
+
+        evr_i = float((S[i] ** 2) / total_variance)
+        explained_variance_ratios.append(evr_i)
+
+        # Loadings = right singular vector Vt[i]
+        loadings = Vt[i].copy()
+        # Normalize sign so the largest absolute loading is positive
+        max_idx = int(np.argmax(np.abs(loadings)))
+        if loadings[max_idx] < 0:
+            loadings = -loadings
+
+        loadings_dict: Dict[str, float] = {}
+        for name, val in zip(metric_names, loadings):
+            loadings_dict[name] = float(val)
+        components_list.append(loadings_dict)
+
+    return components_list, explained_variance_ratios

{robot_data_audit-0.2.0 → robot_data_audit-0.2.2}/rda/calibration/portable.py

@@ -35,6 +35,15 @@ PORTABLE_METRICS: tuple[str, ...] = (
     "effective_motion_ratio",
 )
 
+# Direction of "badness" for each portable metric.
+# "higher_is_worse": higher values = more anomalous (e.g. long duration, many spikes)
+# "lower_is_worse": lower values = more anomalous (e.g. low effective motion)
+METRIC_DIRECTIONS: Dict[str, str] = {
+    "duration_sec": "higher_is_worse",
+    "spike_count": "higher_is_worse",
+    "effective_motion_ratio": "lower_is_worse",
+}
+
 
 def extract_portable_metrics(episode: EpisodeData) -> Dict[str, float]:
     """Extract the three portable Tier-1 metrics from an episode.

robot_data_audit-0.2.2/rda/calibration/reference.py

@@ -0,0 +1,247 @@
+"""Reference profile data classes for behavioral scoring.
+
+A :class:`ReferenceProfile` captures the distribution of portable metrics
+across a calibration population of "normal" episodes. It is used by
+:class:`~rda.calibration.scorer.BehavioralScorer` to compute robust
+deviation scores for incoming episodes.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+@dataclass
+class MetricStats:
+    """Robust distribution statistics for a single portable metric.
+
+    Attributes:
+        median: Population median (50th percentile).
+        mad: Median Absolute Deviation.
+        p05: 5th percentile.
+        p25: 25th percentile.
+        p75: 75th percentile.
+        p95: 95th percentile.
+    """
+
+    median: float
+    mad: float
+    p05: float
+    p25: float
+    p75: float
+    p95: float
+
+    @property
+    def iqr(self) -> float:
+        """Inter-quartile range (p75 - p25)."""
+        return self.p75 - self.p25
+
+    def robust_z(self, value: float) -> float:
+        """Compute the robust (MAD-based) z-score of *value*.
+
+        Uses the standard 0.6745 scaling factor for comparability with
+        standard z-scores under normality.
+        """
+        if self.mad == 0.0:
+            return 0.0
+        return 0.6745 * (value - self.median) / self.mad
+
+    def bad_z(self, value: float, direction: str) -> float:
+        """Compute the direction-aware bad z-score of *value*.
+
+        Positive result always means "more anomalous" regardless of
+        the original metric direction.
+
+        Args:
+            value: The raw metric value.
+            direction: ``"higher_is_worse"`` or ``"lower_is_worse"``.
+
+        Returns:
+            Bad z-score. Positive = more anomalous.
+        """
+        raw_z = self.robust_z(value)
+        if direction == "lower_is_worse":
+            return -raw_z
+        return raw_z
+
+    def to_dict(self) -> Dict[str, float]:
+        """Serialize to a plain dict."""
+        return {
+            "median": self.median,
+            "mad": self.mad,
+            "p05": self.p05,
+            "p25": self.p25,
+            "p75": self.p75,
+            "p95": self.p95,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, float]) -> "MetricStats":
+        """Deserialize from a dict."""
+        return cls(
+            median=data["median"],
+            mad=data["mad"],
+            p05=data["p05"],
+            p25=data["p25"],
+            p75=data["p75"],
+            p95=data["p95"],
+        )
+
+    def percentile_rank(self, value: float) -> float:
+        """Approximate percentile rank of *value* via piecewise linear
+        interpolation across stored percentiles. Returns value in [0, 1]."""
+        anchors = [
+            (0.05, self.p05),
+            (0.25, self.p25),
+            (0.50, self.median),
+            (0.75, self.p75),
+            (0.95, self.p95),
+        ]
+        if value <= anchors[0][1]:
+            return 0.05
+        if value >= anchors[-1][1]:
+            return 0.95
+        for i in range(len(anchors) - 1):
+            p_lo, v_lo = anchors[i]
+            p_hi, v_hi = anchors[i + 1]
+            if v_lo <= value <= v_hi:
+                if v_hi == v_lo:
+                    return p_lo
+                frac = (value - v_lo) / (v_hi - v_lo)
+                return p_lo + frac * (p_hi - p_lo)
+        return 0.5
+
+
+@dataclass
+class ReferenceProfile:
+    """Reference distribution for behavioral scoring.
+
+    Built by :func:`rda.calibration.scorer.calibrate` from a set of
+    calibration episodes.
+    """
+
+    dataset_name: str
+    platform: str
+    n_calibration: int
+    metrics: Dict[str, MetricStats] = field(default_factory=dict)
+    task_scope: Optional[str] = None
+    # New multi-component PCA fields (P0-2)
+    pca_components: List[Dict[str, float]] = field(default_factory=list)
+    pca_explained_variance_ratios: List[float] = field(default_factory=list)
+    pca_n_components: int = 0
+    # Backward compatibility: legacy fields kept for old code
+    pca_loadings: Optional[Dict[str, float]] = None
+    pca_explained_variance: float = 0.0
+
+    def __post_init__(self) -> None:
+        """Sync legacy fields with new multi-component fields."""
+        # If new fields are populated but legacy fields are not, sync them
+        if self.pca_components and self.pca_loadings is None:
+            self.pca_loadings = self.pca_components[0] if self.pca_components else None
+        if self.pca_explained_variance_ratios and self.pca_explained_variance == 0.0:
+            self.pca_explained_variance = self.pca_explained_variance_ratios[0]
+        # If legacy fields are populated but new fields are not, sync them
+        if self.pca_loadings and not self.pca_components:
+            self.pca_components = [self.pca_loadings]
+            self.pca_n_components = 1
+            if self.pca_explained_variance > 0.0 and not self.pca_explained_variance_ratios:
+                self.pca_explained_variance_ratios = [self.pca_explained_variance]
+        if self.pca_components and self.pca_n_components == 0:
+            self.pca_n_components = len(self.pca_components)
+
+    @property
+    def metric_names(self) -> list[str]:
+        """Sorted list of metric names in the profile."""
+        return sorted(self.metrics.keys())
+
+    def has_pca(self) -> bool:
+        """Return True if PCA loadings are available."""
+        return bool(self.pca_components) or (
+            self.pca_loadings is not None and len(self.pca_loadings) > 0
+        )
+
+    def to_dict(self) -> Dict:
+        """Serialize the profile to a JSON-compatible dict."""
+        return {
+            "dataset_name": self.dataset_name,
+            "platform": self.platform,
+            "n_calibration": self.n_calibration,
+            "task_scope": self.task_scope,
+            "metrics": {
+                name: stats.to_dict() for name, stats in self.metrics.items()
+            },
+            "pca_components": self.pca_components,
+            "pca_explained_variance_ratios": self.pca_explained_variance_ratios,
+            "pca_n_components": self.pca_n_components,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> "ReferenceProfile":
+        """Deserialize a profile from a dict (e.g. loaded from JSON)."""
+        metrics = {
+            name: MetricStats.from_dict(stats_data)
+            for name, stats_data in data.get("metrics", {}).items()
+        }
+        return cls(
+            dataset_name=data["dataset_name"],
+            platform=data["platform"],
+            n_calibration=data["n_calibration"],
+            metrics=metrics,
+            task_scope=data.get("task_scope"),
+            pca_components=data.get("pca_components", []),
+            pca_explained_variance_ratios=data.get("pca_explained_variance_ratios", []),
+            pca_n_components=data.get("pca_n_components", 0),
+        )
+
+    def save(self, path: str | Path) -> None:
+        """Save the profile to a JSON file.
+
+        Args:
+            path: Destination file path.
+        """
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(self.to_dict(), f, indent=2, ensure_ascii=False)
+
+    @classmethod
+    def load(cls, path: str | Path) -> "ReferenceProfile":
+        """Load a profile from a JSON file.
+
+        Args:
+            path: Source file path.
+
+        Returns:
+            A :class:`ReferenceProfile` instance.
+        """
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        return cls.from_dict(data)
+
+
+def save_reference(profile: ReferenceProfile, path: str | Path) -> None:
+    """Save a reference profile to a JSON file.
+
+    Convenience function equivalent to ``profile.save(path)``.
+
+    Args:
+        profile: The profile to save.
+        path: Destination file path.
+    """
+    profile.save(path)
+
+
+def load_reference(path: str | Path) -> ReferenceProfile:
+    """Load a reference profile from a JSON file.
+
+    Convenience function equivalent to ``ReferenceProfile.load(path)``.
+
+    Args:
+        path: Source file path.
+
+    Returns:
+        A :class:`ReferenceProfile` instance.
+    """
+    return ReferenceProfile.load(path)