pu-toolbox 1.0.0__py3-none-any.whl

pu_toolbox/__init__.py

@@ -0,0 +1,56 @@
+"""PU Learning Toolbox -- Positive-Unlabeled Learning in Python."""
+
+__version__ = "1.0.0"
+
+from .advisor import ScoringConfig, recommend_from_profile, recommend_methods
+from .diagnostics import analyze_pu_sensitivity, build_diagnostic_report
+from .estimators.bias_aware.lbe import LBEClassifier
+from .estimators.bias_aware.pusb import PUSBClassifier
+from .estimators.bias_aware.pusb_kernel import PUSBKernelClassifier
+from .estimators.classic.elkan_noto import ElkanNotoClassifier
+from .estimators.classic.llsvm import LLSVMClassifier
+from .estimators.deep.dgpu import DGPUClassifier
+from .estimators.deep.infomax_pu import InfoMaxPUClassifier
+from .estimators.deep.self_pu import SelfPUClassifier
+from .estimators.deep.weighted_contrastive_pu import WeightedContrastivePUClassifier
+from .estimators.risk.dist_pu import DistPUClassifier
+from .estimators.risk.kldce import KLDCEClassifier
+from .estimators.risk.ldce import LDCEClassifier
+from .estimators.risk.nnpu import NonNegativePUClassifier
+from .estimators.risk.pnu import PNUClassifier
+from .estimators.risk.upu import UPUClassifier
+from .preprocessing import make_sar_dataset, profile_pu_data
+from .prior.kernel_mean import KernelMeanPriorEstimator
+from .prior.pen_l1 import ClassPriorEstimator
+from .prior.recpe import ReCPEEstimator
+from .workflows import PipelineReport, PUPipeline
+
+__all__ = [
+    "ClassPriorEstimator",
+    "DGPUClassifier",
+    "DistPUClassifier",
+    "ElkanNotoClassifier",
+    "InfoMaxPUClassifier",
+    "KLDCEClassifier",
+    "KernelMeanPriorEstimator",
+    "LBEClassifier",
+    "LDCEClassifier",
+    "LLSVMClassifier",
+    "NonNegativePUClassifier",
+    "PNUClassifier",
+    "PUSBClassifier",
+    "PUSBKernelClassifier",
+    "PipelineReport",
+    "PUPipeline",
+    "ReCPEEstimator",
+    "ScoringConfig",
+    "SelfPUClassifier",
+    "UPUClassifier",
+    "WeightedContrastivePUClassifier",
+    "analyze_pu_sensitivity",
+    "build_diagnostic_report",
+    "make_sar_dataset",
+    "profile_pu_data",
+    "recommend_from_profile",
+    "recommend_methods",
+]

pu_toolbox/advisor/__init__.py

@@ -0,0 +1,17 @@
+"""Algorithm advisor — data-driven PU method recommendation."""
+
+from ._types import MethodCandidate as MethodCandidate
+from ._types import RecommendationResult as RecommendationResult
+from .recommender import recommend_from_profile as recommend_from_profile
+from .recommender import recommend_methods as recommend_methods
+from .rules import DEFAULT_CONFIG as DEFAULT_CONFIG
+from .rules import ScoringConfig as ScoringConfig
+
+__all__ = [
+    "DEFAULT_CONFIG",
+    "MethodCandidate",
+    "RecommendationResult",
+    "ScoringConfig",
+    "recommend_from_profile",
+    "recommend_methods",
+]

pu_toolbox/advisor/_types.py

@@ -0,0 +1,130 @@
+"""Data types for algorithm recommendations."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from ..registry.metadata import AlgorithmMetadata
+
+__all__ = [
+    "MethodCandidate",
+    "RecommendationResult",
+]
+
+
+@dataclass(frozen=True)
+class MethodCandidate:
+    """A single recommended method with score and rationale."""
+
+    name: str
+    score: float
+    rank: int
+    reasons: tuple[str, ...]
+    warnings: tuple[str, ...]
+    metadata: AlgorithmMetadata
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "score": round(self.score, 1),
+            "rank": self.rank,
+            "reasons": list(self.reasons),
+            "warnings": list(self.warnings),
+            "family": str(self.metadata.family.value),
+            "backend": str(self.metadata.backend.value),
+            "maturity": str(self.metadata.maturity.value),
+        }
+
+
+@dataclass(frozen=True)
+class RecommendationResult:
+    """Ranked algorithm recommendations with filters and warnings."""
+
+    candidates: tuple[MethodCandidate, ...]
+    filters_applied: dict[str, Any]
+    global_warnings: tuple[str, ...]
+    provenance: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": "1.0",
+            "candidates": [c.to_dict() for c in self.candidates],
+            "filters_applied": self.filters_applied,
+            "global_warnings": list(self.global_warnings),
+            "provenance": self.provenance,
+        }
+
+    def to_json(self, *, indent: int = 2) -> str:
+        return json.dumps(
+            self.to_dict(),
+            ensure_ascii=False,
+            indent=indent,
+            allow_nan=False,
+        )
+
+    def to_markdown(self) -> str:
+        lines = [
+            "# PU Method Recommendations",
+            "",
+        ]
+        if self.global_warnings:
+            lines.append("## Warnings")
+            lines.append("")
+            for w in self.global_warnings:
+                lines.append(f"- {w}")
+            lines.append("")
+        lines.extend(
+            [
+                "## Recommended Methods",
+                "",
+                "| Rank | Method | Score | Family | Backend | Maturity |",
+                "|---:|---|---:|---|---|---|",
+            ]
+        )
+        for c in self.candidates:
+            lines.append(
+                f"| {c.rank} | {c.name} | {c.score:.1f} "
+                f"| {c.metadata.family.value} | {c.metadata.backend.value} "
+                f"| {c.metadata.maturity.value} |"
+            )
+        lines.append("")
+        for c in self.candidates:
+            lines.append(f"### {c.rank}. {c.name}")
+            lines.append("")
+            if c.reasons:
+                for r in c.reasons:
+                    lines.append(f"- {r}")
+            if c.warnings:
+                lines.append("")
+                for w in c.warnings:
+                    lines.append(f"- **Warning**: {w}")
+            lines.append("")
+        return "\n".join(lines)
+
+    def save(
+        self,
+        path: str | Path,
+        *,
+        format: Literal["json", "markdown"] | None = None,
+    ) -> Path:
+        destination = Path(path)
+        fmt = format
+        if fmt is None:
+            suffix = destination.suffix.lower()
+            if suffix == ".json":
+                fmt = "json"
+            elif suffix in {".md", ".markdown"}:
+                fmt = "markdown"
+            else:
+                raise ValueError(
+                    "Cannot infer report format. Use a .json/.md suffix or pass format=."
+                )
+        if fmt not in {"json", "markdown"}:
+            raise ValueError(f"Unknown format {fmt!r}; expected 'json' or 'markdown'.")
+        content = self.to_markdown() if fmt == "markdown" else self.to_json() + "\n"
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_text(content, encoding="utf-8")
+        return destination

pu_toolbox/advisor/recommender.py

@@ -0,0 +1,195 @@
+# ruff: noqa: N803
+
+"""Algorithm recommender — match data profiles to registered PU methods."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+import numpy as np
+
+from ..core.tags import Assumption, Maturity, Scenario
+from ..preprocessing import PUDataProfile, profile_pu_data
+from ..registry.registry import list_algorithms
+from ._types import MethodCandidate, RecommendationResult
+from .rules import DEFAULT_CONFIG, ScoringConfig, global_warnings, method_warnings, score_method
+
+__all__ = [
+    "recommend_from_profile",
+    "recommend_methods",
+]
+
+
+def recommend_methods(
+    X: Any,
+    y_pu: np.ndarray,
+    *,
+    scenario: Scenario | str | None = None,
+    assumption: Assumption | str | None = None,
+    class_prior: float | None = None,
+    has_gpu: bool = False,
+    top_k: int = 5,
+    random_state: int | None = 42,
+    config: ScoringConfig | None = None,
+) -> RecommendationResult:
+    """Recommend PU methods by profiling data and matching against the registry.
+
+    Parameters
+    ----------
+    X : array-like of shape (n_samples, n_features)
+    y_pu : array-like of shape (n_samples,)
+        PU labels (1 = labeled positive, 0 = unlabeled).
+    scenario : Scenario or str, optional
+        Data collection scenario constraint.
+    assumption : Assumption or str, optional
+        Labeling mechanism assumption constraint.
+    class_prior : float, optional
+        Known class prior P(Y=1). Methods requiring it are excluded when None.
+    has_gpu : bool
+        Whether GPU is available.
+    top_k : int
+        Maximum number of candidates to return.
+    random_state : int, optional
+        Seed for the data profiler.
+    config : ScoringConfig, optional
+        Custom scoring weights. Uses ``DEFAULT_CONFIG`` when not provided.
+
+    Returns
+    -------
+    RecommendationResult
+    """
+    profile = profile_pu_data(X, y_pu, class_prior=class_prior, random_state=random_state)
+    return recommend_from_profile(
+        profile,
+        scenario=scenario,
+        assumption=assumption,
+        class_prior=class_prior,
+        has_gpu=has_gpu,
+        top_k=top_k,
+        config=config,
+    )
+
+
+def recommend_from_profile(
+    profile: PUDataProfile,
+    *,
+    scenario: Scenario | str | None = None,
+    assumption: Assumption | str | None = None,
+    class_prior: float | None = None,
+    class_prior_source: str | None = None,
+    has_gpu: bool = False,
+    top_k: int = 5,
+    config: ScoringConfig | None = None,
+) -> RecommendationResult:
+    """Recommend PU methods from an existing data profile.
+
+    Skips data profiling when a ``PUDataProfile`` is already available.
+    See :func:`recommend_methods` for parameter descriptions.
+
+    .. note::
+
+       ``class_prior`` controls hard filtering (excluding methods that
+       require π when it is unavailable).  It must be consistent with
+       the value used to build *profile*; passing a different value
+       produces contradictory results.
+
+    ``class_prior_source`` records where *class_prior* came from
+    ("user" / "estimated" / ...); it only affects the global-warning
+    wording, never filtering or scoring.
+    """
+    if top_k < 1:
+        raise ValueError(f"top_k must be >= 1, got {top_k}")
+
+    cfg = config or DEFAULT_CONFIG
+
+    # register_all_builtin_methods is idempotent (registry-level dedup),
+    # so calling it per recommendation is safe and never goes stale.
+    from ..registry.builtin_methods import register_all_builtin_methods
+
+    register_all_builtin_methods()
+
+    scenario_enum = _resolve_enum(scenario, Scenario) if scenario is not None else None
+    assumption_enum = _resolve_enum(assumption, Assumption) if assumption is not None else None
+
+    all_methods = list_algorithms(trainable_only=True)
+
+    filters_applied: dict[str, Any] = {}
+    filtered = [m for m in all_methods if m.maturity != Maturity.DEPRECATED]
+    if len(filtered) != len(all_methods):
+        filters_applied["maturity"] = "excluded deprecated"
+
+    if scenario_enum is not None:
+        filtered = [m for m in filtered if scenario_enum in m.scenario]
+        filters_applied["scenario"] = scenario_enum.value
+
+    if profile.summary.get("is_sparse", False):
+        filtered = [m for m in filtered if m.supports_sparse]
+        filters_applied["sparse_support"] = True
+
+    if class_prior is None:
+        filtered = [m for m in filtered if not m.requires_class_prior]
+        filters_applied["class_prior_required"] = "excluded (not provided)"
+
+    if assumption_enum is not None:
+        filtered = [m for m in filtered if assumption_enum in m.assumption]
+        filters_applied["assumption"] = assumption_enum.value
+
+    scored = []
+    for meta in filtered:
+        sc, reasons = score_method(meta, profile, assumption_enum, has_gpu, cfg)
+        warns = method_warnings(meta, profile, assumption_enum)
+        scored.append((meta, sc, reasons, warns))
+
+    scored.sort(key=lambda t: t[1], reverse=True)
+    scored = scored[:top_k]
+
+    candidates = tuple(
+        MethodCandidate(
+            name=meta.name,
+            score=sc,
+            rank=i + 1,
+            reasons=tuple(reasons),
+            warnings=tuple(warns),
+            metadata=meta,
+        )
+        for i, (meta, sc, reasons, warns) in enumerate(scored)
+    )
+
+    gw = list(global_warnings(profile, class_prior, class_prior_source))
+    if profile.summary.get("is_sparse", False) and not filtered:
+        # No registered method accepts sparse input; say so instead of
+        # silently returning zero candidates.
+        gw.append(
+            "Sparse data: no registered method supports sparse input. "
+            "Densify the matrix (e.g. X.toarray()) or profile dense data."
+        )
+
+    provenance = {
+        "n_samples": profile.summary.get("n_samples"),
+        "n_features": profile.summary.get("n_features"),
+        "n_candidates_before_filter": len(all_methods),
+        "n_candidates_after_filter": len(filtered),
+        "top_k": top_k,
+        "has_gpu": has_gpu,
+    }
+
+    return RecommendationResult(
+        candidates=candidates,
+        filters_applied=filters_applied,
+        global_warnings=tuple(gw),
+        provenance=provenance,
+    )
+
+
+def _resolve_enum(value: str | Any, enum_cls: type) -> Any:
+    if isinstance(value, enum_cls):
+        return value
+    if isinstance(value, Enum):
+        raise ValueError(f"Expected {enum_cls.__name__}, got {type(value).__name__}: {value!r}")
+    for member in enum_cls:
+        if member.value.lower() == str(value).lower():
+            return member
+        if member.name.lower() == str(value).lower():
+            return member
+    raise ValueError(f"Unknown {enum_cls.__name__} value: {value!r}")