pyplasmode 1.0.0__py3-none-any.whl

pyplasmode/results.py

@@ -0,0 +1,172 @@
+"""Typed aggregate results returned by biomarker evaluators."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(frozen=True, slots=True)
+class RankingAtDepth:
+    """Exact-feature recovery at one leading-list depth."""
+
+    depth: int
+    selected_count: int
+    true_positive_count: int
+    target_count: int
+    recall: float
+    precision: float
+    false_discovery_fraction: float
+
+
+@dataclass(frozen=True, slots=True)
+class RankingEvaluation:
+    """Exact recovery across declared depths."""
+
+    first_relevant_rank: int | None
+    at_depth: tuple[RankingAtDepth, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class GroupAtDepth:
+    """Admissible substitute-group recovery at one depth."""
+
+    depth: int
+    recovered_group_count: int
+    group_count: int
+    group_recall: float
+
+
+@dataclass(frozen=True, slots=True)
+class GroupEvaluation:
+    """Recovery of at least one declared member per substitute group."""
+
+    at_depth: tuple[GroupAtDepth, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ModuleAtDepth:
+    """Absolute-weight coverage of a distributed module at one depth."""
+
+    depth: int
+    recovered_member_count: int
+    member_count: int
+    weighted_coverage: float
+
+
+@dataclass(frozen=True, slots=True)
+class ModuleEvaluation:
+    """Distributed module coverage across declared depths."""
+
+    at_depth: tuple[ModuleAtDepth, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class GraphRegionAtDepth:
+    """Node and induced-edge recovery for a declared graph region."""
+
+    depth: int
+    node_coverage: float
+    edge_coverage: float
+
+
+@dataclass(frozen=True, slots=True)
+class GraphRegionEvaluation:
+    """Graph-region recovery across declared depths."""
+
+    at_depth: tuple[GraphRegionAtDepth, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class SignalReconstructionEvaluation:
+    """Held-out linear reconstruction of a known latent signal."""
+
+    selected_feature_count: int
+    evaluation_count: int
+    r_squared: float
+    root_mean_squared_error: float
+
+
+@dataclass(frozen=True, slots=True)
+class PredictionEvaluation:
+    """One standard prediction metric over supplied outputs."""
+
+    metric: str
+    value: float
+    sample_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class PanelEvaluation:
+    """Prediction retained by a panel relative to supplied reference predictions."""
+
+    metric: str
+    reference_value: float
+    panel_value: float
+    difference: float
+    sample_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class RankStabilityEvaluation:
+    """Pairwise leading-set, full-rank and top-weighted stability."""
+
+    ranking_count: int
+    feature_count: int
+    depth: int
+    mean_leading_jaccard: float
+    mean_leading_intersection: float
+    expected_random_intersection: float
+    excess_leading_intersection: float
+    mean_spearman: float
+    mean_rank_biased_overlap: float
+
+
+@dataclass(frozen=True, slots=True)
+class ReplicateSummary:
+    """Mean, Monte Carlo uncertainty and failure count across replicates."""
+
+    replicate_count: int
+    failure_count: int
+    mean: float
+    standard_deviation: float
+    standard_error: float
+    confidence_interval_low: float
+    confidence_interval_high: float
+
+
+@dataclass(frozen=True, slots=True)
+class FractionalRecovery:
+    """Mechanism-specific recovery for one fractional nomination."""
+
+    estimand: Literal["exact", "group", "module", "interaction"]
+    value: float
+    truth_support: int
+    positive_score_support_size: int
+    requested_depth: int
+    achieved_size: int
+
+
+@dataclass(frozen=True, slots=True)
+class MatchedRecovery:
+    """Observed recovery calibrated against an analytic matched reference."""
+
+    estimand: Literal["exact", "group", "module", "interaction"]
+    method: Literal["analytic"]
+    requested_depth: int
+    achieved_size: int
+    observed_recovery: float
+    expected_recovery: float
+    chance_adjusted_recovery: float
+    admissible_panel_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class OutcomeSpecificity:
+    """Own-truth recovery relative to disjoint foreign truths."""
+
+    estimand: Literal["exact", "group", "module", "interaction"]
+    own_adjusted_recovery: float
+    mean_foreign_adjusted_recovery: float
+    specificity: float
+    foreign_truth_count: int

pyplasmode/structures.py

@@ -0,0 +1,123 @@
+"""Resource-agnostic biomarker sets, graphs and alignment."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from pyplasmode.data import Population
+
+
+@dataclass(frozen=True, slots=True)
+class StructureAlignment:
+    """Explicit alignment of structure identities to a population."""
+
+    mapped: tuple[str, ...]
+    unmapped: tuple[str, ...]
+    excluded: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class FeatureSet:
+    """One named biomarker membership set."""
+
+    name: str
+    members: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        if not self.name or self.name.strip() != self.name:
+            raise ValueError("feature-set name must be a non-empty normalized string")
+        if not self.members or any(not member for member in self.members):
+            raise ValueError("a feature set must contain non-empty identities")
+        if len(set(self.members)) != len(self.members):
+            raise ValueError("feature-set members must be unique")
+
+
+@dataclass(frozen=True, slots=True)
+class FeatureSets:
+    """An ordered collection of named biomarker membership sets."""
+
+    sets: tuple[FeatureSet, ...]
+
+    def __post_init__(self) -> None:
+        if not self.sets:
+            raise ValueError("FeatureSets must contain at least one set")
+        names = tuple(item.name for item in self.sets)
+        if len(set(names)) != len(names):
+            raise ValueError("feature-set names must be unique")
+
+    def get(self, name: str) -> FeatureSet:
+        """Return one named feature set or fail explicitly."""
+        for item in self.sets:
+            if item.name == name:
+                return item
+        raise ValueError(f"unknown feature set: {name}")
+
+    def align(self, population: Population) -> StructureAlignment:
+        """Report mapped, unmapped and population-excluded identities."""
+        declared = {member for item in self.sets for member in item.members}
+        population_ids = set(population.feature_ids)
+        return StructureAlignment(
+            mapped=tuple(identity for identity in population.feature_ids if identity in declared),
+            unmapped=tuple(sorted(declared - population_ids)),
+            excluded=tuple(
+                identity for identity in population.feature_ids if identity not in declared
+            ),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class FeatureEdge:
+    """One finite non-negative undirected biomarker edge."""
+
+    source: str
+    target: str
+    weight: float = 1.0
+
+    def __post_init__(self) -> None:
+        if not self.source or not self.target or self.source == self.target:
+            raise ValueError("edge endpoints must be distinct non-empty identities")
+        if not np.isfinite(self.weight) or self.weight < 0.0:
+            raise ValueError("edge weight must be finite and non-negative")
+
+
+@dataclass(frozen=True, slots=True)
+class FeatureGraph:
+    """A weighted undirected graph over explicit biomarker identities."""
+
+    nodes: tuple[str, ...]
+    edges: tuple[FeatureEdge, ...]
+
+    def __post_init__(self) -> None:
+        if not self.nodes or any(not node for node in self.nodes):
+            raise ValueError("graph nodes must be non-empty identities")
+        if len(set(self.nodes)) != len(self.nodes):
+            raise ValueError("graph nodes must be unique")
+        node_set = set(self.nodes)
+        pairs: set[tuple[str, str]] = set()
+        for edge in self.edges:
+            if edge.source not in node_set or edge.target not in node_set:
+                raise ValueError("every edge endpoint must be declared in graph nodes")
+            pair = (
+                (edge.source, edge.target)
+                if edge.source < edge.target
+                else (edge.target, edge.source)
+            )
+            if pair in pairs:
+                raise ValueError("undirected graph edges must be unique")
+            pairs.add(pair)
+
+    def align(self, population: Population) -> StructureAlignment:
+        """Report mapped, unmapped and population-excluded graph nodes."""
+        graph_nodes = set(self.nodes)
+        population_ids = set(population.feature_ids)
+        return StructureAlignment(
+            mapped=tuple(
+                identity for identity in population.feature_ids if identity in graph_nodes
+            ),
+            unmapped=tuple(sorted(graph_nodes - population_ids)),
+            excluded=tuple(
+                identity for identity in population.feature_ids if identity not in graph_nodes
+            ),
+        )