antecedent.query

Query stubs.

View Source

  1"""Typed causal queries for the Python facade."""
  2
  3from __future__ import annotations
  4
  5from dataclasses import dataclass, field
  6from typing import Literal, Sequence
  7
  8
  9@dataclass(frozen=True)
 10class AverageEffect:
 11    """Average treatment effect (static tabular)."""
 12
 13    treatment: str
 14    outcome: str
 15    control_level: float = 0.0
 16    active_level: float = 1.0
 17    target_population: object | None = None
 18    kind: Literal["average"] = "average"
 19
 20
 21@dataclass(frozen=True)
 22class PulseEffect:
 23    """Temporal pulse intervention effect."""
 24
 25    treatment: str
 26    outcome: str
 27    active_level: float = 1.0
 28    treatment_lag: int = 1
 29    horizon_steps: int = 1
 30    kind: Literal["pulse"] = "pulse"
 31
 32
 33@dataclass(frozen=True)
 34class SustainedEffect:
 35    """Temporal sustained intervention effect."""
 36
 37    treatment: str
 38    outcome: str
 39    active_level: float = 1.0
 40    treatment_lag: int = 1
 41    horizon_steps: int = 1
 42    kind: Literal["sustained"] = "sustained"
 43
 44
 45@dataclass(frozen=True)
 46class InterventionalDistribution:
 47    """Interventional distribution query (static)."""
 48
 49    outcome: str
 50    interventions: dict[str, float] = field(default_factory=dict)
 51    conditioning: Sequence[str] = ()
 52    kind: Literal["distribution"] = "distribution"
 53
 54
 55@dataclass(frozen=True)
 56class PathSpecificEffect:
 57    """Path-specific effect query (static)."""
 58
 59    treatment: str
 60    outcome: str
 61    path_nodes: Sequence[str] | None = None
 62    control_level: float = 0.0
 63    active_level: float = 1.0
 64    max_paths: int = 64
 65    max_len: int = 16
 66    kind: Literal["path_specific"] = "path_specific"
 67
 68
 69@dataclass(frozen=True)
 70class ConditionalEffect:
 71    """Conditional / context average effect with a single effect modifier."""
 72
 73    treatment: str
 74    outcome: str
 75    modifier: str
 76    control_level: float = 0.0
 77    active_level: float = 1.0
 78    kind: Literal["conditional"] = "conditional"
 79
 80
 81@dataclass(frozen=True)
 82class MediationEffect:
 83    """Static mediation (treatment → mediator(s) → outcome)."""
 84
 85    treatment: str
 86    outcome: str
 87    mediators: Sequence[str]
 88    contrast: Literal["total", "direct", "mediated"] = "mediated"
 89    control_level: float = 0.0
 90    active_level: float = 1.0
 91    kind: Literal["mediation"] = "mediation"
 92
 93
 94@dataclass(frozen=True)
 95class Counterfactual:
 96    """Unit-level ITE via GCM abduction–action–prediction."""
 97
 98    treatment: str
 99    outcome: str
100    control_level: float = 0.0
101    active_level: float = 1.0
102    kind: Literal["counterfactual"] = "counterfactual"
103
104
105@dataclass(frozen=True)
106class TemporalMediationEffect:
107    """Temporal linear mediation (treatment → mediator → outcome)."""
108
109    treatment: str
110    mediator: str
111    outcome: str
112    contrast: Literal["total", "direct", "mediated"] = "mediated"
113    control_level: float = 0.0
114    active_level: float = 1.0
115    kind: Literal["temporal_mediation"] = "temporal_mediation"
116
117
118__all__ = [
119    "AverageEffect",
120    "ConditionalEffect",
121    "Counterfactual",
122    "InterventionalDistribution",
123    "MediationEffect",
124    "PathSpecificEffect",
125    "PulseEffect",
126    "SustainedEffect",
127    "TemporalMediationEffect",
128]

@dataclass(frozen=True)

class AverageEffect: View Source

10@dataclass(frozen=True)
11class AverageEffect:
12    """Average treatment effect (static tabular)."""
13
14    treatment: str
15    outcome: str
16    control_level: float = 0.0
17    active_level: float = 1.0
18    target_population: object | None = None
19    kind: Literal["average"] = "average"

Average treatment effect (static tabular).

AverageEffect( treatment: str, outcome: str, control_level: float = 0.0, active_level: float = 1.0, target_population: object | None = None, kind: "Literal['average']" = 'average')

treatment: str

outcome: str

control_level: float = 0.0

active_level: float = 1.0

target_population: object | None = None

kind: "Literal['average']" = 'average'

@dataclass(frozen=True)

class ConditionalEffect: View Source

70@dataclass(frozen=True)
71class ConditionalEffect:
72    """Conditional / context average effect with a single effect modifier."""
73
74    treatment: str
75    outcome: str
76    modifier: str
77    control_level: float = 0.0
78    active_level: float = 1.0
79    kind: Literal["conditional"] = "conditional"

Conditional / context average effect with a single effect modifier.

ConditionalEffect( treatment: str, outcome: str, modifier: str, control_level: float = 0.0, active_level: float = 1.0, kind: "Literal['conditional']" = 'conditional')

treatment: str

outcome: str

modifier: str

control_level: float = 0.0

active_level: float = 1.0

kind: "Literal['conditional']" = 'conditional'

@dataclass(frozen=True)

class Counterfactual: View Source

 95@dataclass(frozen=True)
 96class Counterfactual:
 97    """Unit-level ITE via GCM abduction–action–prediction."""
 98
 99    treatment: str
100    outcome: str
101    control_level: float = 0.0
102    active_level: float = 1.0
103    kind: Literal["counterfactual"] = "counterfactual"

Unit-level ITE via GCM abduction–action–prediction.

Counterfactual( treatment: str, outcome: str, control_level: float = 0.0, active_level: float = 1.0, kind: "Literal['counterfactual']" = 'counterfactual')

treatment: str

outcome: str

control_level: float = 0.0

active_level: float = 1.0

kind: "Literal['counterfactual']" = 'counterfactual'

@dataclass(frozen=True)

class InterventionalDistribution: View Source

46@dataclass(frozen=True)
47class InterventionalDistribution:
48    """Interventional distribution query (static)."""
49
50    outcome: str
51    interventions: dict[str, float] = field(default_factory=dict)
52    conditioning: Sequence[str] = ()
53    kind: Literal["distribution"] = "distribution"

Interventional distribution query (static).

InterventionalDistribution( outcome: str, interventions: dict[str, float] = <factory>, conditioning: 'Sequence[str]' = (), kind: "Literal['distribution']" = 'distribution')

outcome: str

interventions: dict[str, float]

conditioning: 'Sequence[str]' = ()

kind: "Literal['distribution']" = 'distribution'

@dataclass(frozen=True)

class MediationEffect: View Source

82@dataclass(frozen=True)
83class MediationEffect:
84    """Static mediation (treatment → mediator(s) → outcome)."""
85
86    treatment: str
87    outcome: str
88    mediators: Sequence[str]
89    contrast: Literal["total", "direct", "mediated"] = "mediated"
90    control_level: float = 0.0
91    active_level: float = 1.0
92    kind: Literal["mediation"] = "mediation"

Static mediation (treatment → mediator(s) → outcome).

MediationEffect( treatment: str, outcome: str, mediators: 'Sequence[str]', contrast: "Literal['total', 'direct', 'mediated']" = 'mediated', control_level: float = 0.0, active_level: float = 1.0, kind: "Literal['mediation']" = 'mediation')

treatment: str

outcome: str

mediators: 'Sequence[str]'

contrast: "Literal['total', 'direct', 'mediated']" = 'mediated'

control_level: float = 0.0

active_level: float = 1.0

kind: "Literal['mediation']" = 'mediation'

@dataclass(frozen=True)

class PathSpecificEffect: View Source

56@dataclass(frozen=True)
57class PathSpecificEffect:
58    """Path-specific effect query (static)."""
59
60    treatment: str
61    outcome: str
62    path_nodes: Sequence[str] | None = None
63    control_level: float = 0.0
64    active_level: float = 1.0
65    max_paths: int = 64
66    max_len: int = 16
67    kind: Literal["path_specific"] = "path_specific"

Path-specific effect query (static).

PathSpecificEffect( treatment: str, outcome: str, path_nodes: 'Sequence[str] | None' = None, control_level: float = 0.0, active_level: float = 1.0, max_paths: int = 64, max_len: int = 16, kind: "Literal['path_specific']" = 'path_specific')

treatment: str

outcome: str

path_nodes: 'Sequence[str] | None' = None

control_level: float = 0.0

active_level: float = 1.0

max_paths: int = 64

max_len: int = 16

kind: "Literal['path_specific']" = 'path_specific'

@dataclass(frozen=True)

class PulseEffect: View Source

22@dataclass(frozen=True)
23class PulseEffect:
24    """Temporal pulse intervention effect."""
25
26    treatment: str
27    outcome: str
28    active_level: float = 1.0
29    treatment_lag: int = 1
30    horizon_steps: int = 1
31    kind: Literal["pulse"] = "pulse"

Temporal pulse intervention effect.

PulseEffect( treatment: str, outcome: str, active_level: float = 1.0, treatment_lag: int = 1, horizon_steps: int = 1, kind: "Literal['pulse']" = 'pulse')

treatment: str

outcome: str

active_level: float = 1.0

treatment_lag: int = 1

horizon_steps: int = 1

kind: "Literal['pulse']" = 'pulse'

@dataclass(frozen=True)

class SustainedEffect: View Source

34@dataclass(frozen=True)
35class SustainedEffect:
36    """Temporal sustained intervention effect."""
37
38    treatment: str
39    outcome: str
40    active_level: float = 1.0
41    treatment_lag: int = 1
42    horizon_steps: int = 1
43    kind: Literal["sustained"] = "sustained"

Temporal sustained intervention effect.

SustainedEffect( treatment: str, outcome: str, active_level: float = 1.0, treatment_lag: int = 1, horizon_steps: int = 1, kind: "Literal['sustained']" = 'sustained')

treatment: str

outcome: str

active_level: float = 1.0

treatment_lag: int = 1

horizon_steps: int = 1

kind: "Literal['sustained']" = 'sustained'

@dataclass(frozen=True)

class TemporalMediationEffect: View Source

106@dataclass(frozen=True)
107class TemporalMediationEffect:
108    """Temporal linear mediation (treatment → mediator → outcome)."""
109
110    treatment: str
111    mediator: str
112    outcome: str
113    contrast: Literal["total", "direct", "mediated"] = "mediated"
114    control_level: float = 0.0
115    active_level: float = 1.0
116    kind: Literal["temporal_mediation"] = "temporal_mediation"

Temporal linear mediation (treatment → mediator → outcome).

TemporalMediationEffect( treatment: str, mediator: str, outcome: str, contrast: "Literal['total', 'direct', 'mediated']" = 'mediated', control_level: float = 0.0, active_level: float = 1.0, kind: "Literal['temporal_mediation']" = 'temporal_mediation')

treatment: str

mediator: str

outcome: str

contrast: "Literal['total', 'direct', 'mediated']" = 'mediated'

control_level: float = 0.0

active_level: float = 1.0

kind: "Literal['temporal_mediation']" = 'temporal_mediation'