Transport

Implement of surrogate outcomes and transportability from [tikka2018].

class TransportQuery(target_interventions: set[Variable], target_outcomes: set[Variable], graphs: dict[Variable, NxMixedGraph], domains: set[Variable], surrogate_interventions: dict[Variable, set[Variable]], target_experiments: set[Variable])[source]

A query used as output for surrogate_to_transport.

identify_target_outcomes(graph: NxMixedGraph, *, target_outcomes: set[Variable], target_interventions: set[Variable], surrogate_outcomes: dict[Variable, set[Variable]], surrogate_interventions: dict[Variable, set[Variable]]) → Expression | None[source]

Get the estimand for the target outcome givne the surrogate outcomes.

See also

Originally described in https://arxiv.org/abs/1806.07172.

Parameters:

  • target_outcomes – A set of target variables for causal effects.

  • target_interventions – A set of interventions for the target domain.

  • graph – The graph of the target domain.

  • surrogate_outcomes – A dictionary of outcomes in other populations

  • surrogate_interventions – A dictionary of interventions in other populations

Returns:

An Expression evaluating the given query, or None

Raises:

ValueError – If the target outcomes and target interventions intersect

The example from figure 8 of the original paper can be executed with the following code:

from y0.algorithm.transport import identify_target_outcome
from y0.dsl import X1, X2, Y1, Y2, Pi1, Pi2
from y0.examples import tikka_trso_figure_8_graph

estimand = identify_target_outcome(
    graph=tikka_trso_figure_8_graph,
    target_outcomes={Y1, Y2},
    target_interventions={X1, X2},
    surrogate_outcomes={Pi1: {Y1}, Pi2: {Y2}},
    surrogate_interventions={Pi1: {X1}, Pi2: {X2}},
)

This returns the following estimand: \(\sum_{W, Z} P(W, Z) \frac{P_{X_1}^{π_1}(W, Y_1, Z)}{P_{X_1}(W, Z)} \frac{P_{X_2}^{π_2}(W, X_1, Y_2, Z)}{P_{X_2}(W, X_1, Z)}\)

trso(query: TRSOQuery) → Expression | None[source]

Run the TRSO algorithm to evaluate a transport problem.

Parameters:

query – A TRSO query, which contains 8 instance variables needed for TRSO

Returns:

An Expression evaluating the given query, or None

Raises:

RuntimeError – when an impossible condition is met

Counterfactual Transport

Implementation of counterfactual transportability.

class CFTDomain(graph: NxMixedGraph, population: PopulationProbability, policy_variables: Collection[Variable] = <factory>, ordering: list[Variable] | None = None)[source]

Represents a counterfactual transport domain.

Each CFTDomain class contains a selection diagram for that domain, an expression denoting the probability distribution \(P^{k}(\mathbf{V};\sigma_{\mathbf{Z}\_{j}})|{\mathbf{Z}_{j}} \in \mathcal{Z}^{i}\), a set of policy variables corresponding to \(\sigma_{\mathbf{Z}_{k}}\), and a topologically sorted list of all the vertices in the corresponding graph that are not transportability nodes. (Nodes that have no parents come first in such lists.) The selection diagram contains a transportability node for every vertex that is distributed differently in the domain in question than in the target domain (e.g., Vertex Z in Figure 3(a) in [correa22a]), and it is a causal diagram such that its edges represent the state of the graph after a regime corresponding to domain \(k\) has been applied (e.g., policy \(\sigma_{X}\) in Figure 4 of [correa22a]).

graph: NxMixedGraph = <dataclasses._MISSING_TYPE object>

The domain graph (a selection diagram, containing transportability nodes)

population: PopulationProbability = <dataclasses._MISSING_TYPE object>

An expression for the joint probability of the vertices in the domain graph, which may be a conditional probability with vertices not in the graph to the right of the conditioning bar (i.e., we may be getting a subgraph of something larger). Can also directly give a Variable, in which case, the population probability is inferred to be the joint population probability over all non-transport nodes in the graph

policy_variables: Collection[Variable] = <dataclasses._MISSING_TYPE object>

The variables in the domain receiving an intervention, which may be stochastic (i.e., intervening on the variable does not necessarily break all incoming edges and may even add some edges)

ordering: list[Variable] | None = None

Topological ordering of the vertices in the domain graph (optional)

class ConditionalCFTResult(expression: Expression, event: list[tuple[Variable, Intervention]] | None)[source]

Represents the result of a conditional counterfactual transportability query.

Create new instance of ConditionalCFTResult(expression, event)

expression: Expression

Alias for field number 0

event: list[tuple[Variable, Intervention]] | None

Alias for field number 1

display() → None[source]

Display this result.

class UnconditionalCFTResult(expression: Expression, event: list[tuple[Variable, Intervention | None]] | None)[source]

Represents the result from an unconditional counterfactual transportability query.

Create new instance of UnconditionalCFTResult(expression, event)

expression: Expression

Alias for field number 0

event: list[tuple[Variable, Intervention | None]] | None

Alias for field number 1

display() → None[source]

Display this result.

conditional_cft(*, outcomes: Variable | list[Variable], conditions: Variable | list[Variable], target_domain_graph: NxMixedGraph, domains: list[CFTDomain]) → ConditionalCFTResult | None[source]

Run a conditional counterfactual transportability query (Algorithm 3 from [correa22a]).

Parameters:

  • outcomes – “Y_*, a set of counterfactual variables in V and y_* a set of values for Y_*.” We encode the counterfactual variables as CounterfactualVariable objects, and the values as Intervention objects.

  • conditions – “X_*, a set of counterfactual variables in V and x_* a set of values for X_*.” We encode the counterfactual variables as CounterfactualVariable objects, and the values as Intervention objects.

  • target_domain_graph – a graph for the target domain.

  • domains – A set of \(K\) CFTDomain classes, one for each of the \(K\) domains. See the documentation for CFTDomain for more details.

Returns:

The result of the query as a ConditionalCFTResult object.

transport_conditional_counterfactual_query(*, outcomes: list[tuple[Variable, Intervention]], conditions: list[tuple[Variable, Intervention]], target_domain_graph: NxMixedGraph, domain_graphs: list[tuple[NxMixedGraph, list[Variable]]], domain_data: list[tuple[Collection[Variable], PopulationProbability]]) → ConditionalCFTResult | None[source]

Implement the ctfTR algorithm from [correa22a] (Algorithm 3).

Parameters:

  • outcomes – “Y_*, a set of counterfactual variables in V and y_* a set of values for Y_*.” We encode the counterfactual variables as CounterfactualVariable objects, and the values as Intervention objects.

  • conditions – “X_*, a set of counterfactual variables in V and x_* a set of values for X_*.” We encode the counterfactual variables as CounterfactualVariable objects, and the values as Intervention objects.

  • domain_graphs – A set of \(K\) tuples, one for each of the \(K\) domains. Each tuple contains a selection diagram for that domain and a topologically sorted list of all the vertices in the corresponding graph that are not transportability nodes. (Nodes that have no parents come first in such lists.) The selection diagram contains a transportability node for every vertex that is distributed differently in the domain in question than in the target domain (e.g., Vertex Z in Figure 3(a) in [correa22a]), and it is a causal diagram such that its edges represent the state of the graph after a regime corresponding to domain \(k\) has been applied (e.g., policy \(\sigma_{X}\) in Figure 4 of [correa22a]).

  • target_domain_graph – a graph for the target domain.

  • domain_data – Corresponding to \(\mathcal{Z}\) in [correa22a], this is a set of \(K\) tuples, one for each of the \(K\) domains except for the target domain. Each tuple contains a set of variables corresponding to \(\sigma_{\mathbf{Z}_{k}}\) and an expression denoting the probability distribution \(P^{k}(\mathbf{V};\sigma_{\mathbf{Z}\_{j}})|{\mathbf{Z}_{j}} \in \mathcal{Z}^{i}\).

Returns:

FAIL (None) if the algorithm fails, or a probabilistic expression for \(P^{\ast}(\mathbf{Y_{\ast}}=\mathbf{y_{\ast}} | \mathbf{X_{\ast}}=\mathbf{x_{\ast}}\) along a mapping of variables to values used to evaluate that expression. If that expression evaluated to 0 because input values of some counterfactual variables were not consistent, then the algorithm returns Zero (a DSL Expression type) and no mapping.

transport_unconditional_counterfactual_query(*, event: list[tuple[Variable, Intervention | None]], target_domain_graph: NxMixedGraph, domain_graphs: list[tuple[NxMixedGraph, list[Variable]]], domain_data: list[tuple[Collection[Variable], PopulationProbability]]) → UnconditionalCFTResult | None[source]

Implement the ctfTRu algorithm from [correa22a] (Algorithm 2).

Parameters:

  • event – “Y_*, a set of counterfactual variables in V and y_* a set of values for Y_*.” We encode the counterfactual variables as CounterfactualVariable objects, and the values as Intervention objects.

  • target_domain_graph – a graph for the target domain.

  • domain_graphs – A set of \(K\) tuples, one for each of the \(K\) domains. Each tuple contains a selection diagram for that domain and a topologically sorted list of all the vertices in the corresponding graph that are not transportability nodes. (Nodes that have no parents come first in such lists.) The selection diagram contains a transportability node for every vertex that is distributed differently in the domain in question than in the target domain (e.g., Vertex Z in Figure 3(a) in [correa22a]), and it is a causal diagram such that its edges represent the state of the graph after a regime corresponding to domain \(k\) has been applied (e.g., policy \(\sigma_{X}\) in Figure 4 of [correa22a]).

  • domain_data – Corresponding to \(\mathcal{Z}\) in [correa22a], this is a set of \(K\) tuples, one for each of the \(K\) domains except for the target domain. Each tuple contains a set of variables corresponding to \(\sigma_{\mathbf{Z}_{k}}\) and an expression denoting the probability distribution \(P^{k}(\mathbf{V};\sigma_{\mathbf{Z}\_{j}})|{\mathbf{Z}_{j}} \in \mathcal{Z}^{i}\).

Returns:

an expression for \(P^{\ast}(\mathbf{Y_{\ast}}=\mathbf{y_{\ast}})\)

unconditional_cft(*, event: Variable | list[Variable], target_domain_graph: NxMixedGraph, domains: list[CFTDomain]) → UnconditionalCFTResult | None[source]

Run an unconditional counterfactual transportability query (Algorithm 2 from [correa22a]).

Parameters:

  • event – “Y_*, a set of counterfactual variables in V and y_* a set of values for Y_*.” We encode the counterfactual variables as CounterfactualVariable objects, and the values as Intervention objects.

  • target_domain_graph – a graph for the target domain.

  • domains – A set of \(K\) CFTDomain classes, one for each of the \(K\) domains. See the documentation for CFTDomain for more details.

Returns:

The result of the query as an UnconditionalCFTResult object.