CausalTables.jl Full API

AllOrderStatistics <: NetworkSummary

A NetworkSummary which computes all ordered values of the target variable among each unit's connected neighbors in the adjacency matrix.

Fields

• target::Symbol: A key denoting the target variable to be summarized in the DataGeneratingProcess of the StructuralCausalModel; or, alternatively, the target variable to be summarized in the data attribute of a CausalTable.
• matrix::Symbol: A key denoting the adjacency matrix over which summary is computed in the DataGeneratingProcess of the StructuralCausalModel; or, alternatively, the key of the adjacency matrix in the arrays attribute of a CausalTable.
• weights::Union{Symbol, Nothing}: An optional variable by which each unit may be weighted in the summary.

mutable struct DataGeneratingProcess

A struct representing a data generating process.

Fields

• names: An array of symbols representing the names of the variables.
• types: An array of symbols representing the types of the variables.
• funcs: An array of functions representing the generating functions for each variable.

mutable struct Friends <: NetworkSummary

A NetworkSummary counting the number of connected individuals in an adjacency matrix, also known as the number of "friends".

Fields

• matrix::Symbol: A key denoting the adjacency matrix over which summary is computed in the DataGeneratingProcess of the StructuralCausalModel; or, alternatively, the key of the adjacency matrix in the arrays attribute of a CausalTable.

KOrderStatistics <: NetworkSummary

A NetworkSummary which computes the top K ordered values of the target variable among each unit's connected neighbors in the adjacency matrix.

Fields

• target::Symbol: A key denoting the target variable to be summarized in the DataGeneratingProcess of the StructuralCausalModel; or, alternatively, the target variable to be summarized in the data attribute of a CausalTable.
• matrix::Symbol: A key denoting the adjacency matrix over which summary is computed in the DataGeneratingProcess of the StructuralCausalModel; or, alternatively, the key of the adjacency matrix in the arrays attribute of a CausalTable.
• weights::Union{Symbol, Nothing}: An optional variable by which each unit may be weighted in the summary.

Mean <: NetworkSummary

A NetworkSummary which computes the mean of the target variable among each unit connected in the adjacency matrix.

Fields

• target::Symbol: A key denoting the target variable to be summarized in the DataGeneratingProcess of the StructuralCausalModel; or, alternatively, the target variable to be summarized in the data attribute of a CausalTable.
• matrix::Symbol: A key denoting the adjacency matrix over which summary is computed in the DataGeneratingProcess of the StructuralCausalModel; or, alternatively, the key of the adjacency matrix in the arrays attribute of a CausalTable.
• weights::Union{Symbol, Nothing}: An optional variable by which each unit may be weighted in the summary.

abstract type NetworkSummary

Abstract type representing a summary of a network.

struct StructuralCausalModel

A struct representing a structural causal model (SCM). This includes a DataGeneratingProcess

Arguments

• dgp::DataGeneratingProcess: The data generating process from which random data will be drawn.
• treatment::Vector{Symbol}: The variables representing the treatment.
• response::Vector{Symbol}: The variables representing the response.
• confounders::Vector{Symbol}: The variables representing the confounders.
• arraynames: Names of auxiliary variables used in the DataGeneratingProcess that are not included as "tabular" variables. Most commonly used to denote names of adjacency matrices used to compute summary functions of previous steps.

Sum <: NetworkSummary

A NetworkSummary which sums the values of the target variable for each unit connected in the adjacency matrix of a StructuralCausalModel or CausalTable

Fields

• target::Symbol: A key denoting the target variable to be summarized in the DataGeneratingProcess of the StructuralCausalModel; or, alternatively, the target variable to be summarized in the data attribute of a CausalTable.
• matrix::Symbol: A key denoting the adjacency matrix over which summary is computed in the DataGeneratingProcess of the StructuralCausalModel; or, alternatively, the key of the adjacency matrix in the arrays attribute of a CausalTable.
• weights::Union{Symbol, Nothing}: An optional variable by which each unit may be weighted in the summary.

rand(scm::StructuralCausalModel, n::Int)

Generate random data from a Structural Causal Model (SCM) using the specified number of samples.

Arguments

• scm::StructuralCausalModel: The Structural Causal Model from which to generate data.
• n::Int: The number of samples to generate.

Returns

A CausalTable object containing the generated data.

additive_mtp(δ)

Constructs a function that adds a constant (or constant vector) δ to the treatment variable(s) in a CausalTable object. This function is intended to be used as an argument to ape.

Arguments

• δ: The "additive shift" to be applied to the treatment variable of a CausalTable.

Returns

• A function that takes a CausalTable object as input and returns a column table of treatments that have been shifted by δ units.

Example

using Distributions
dgp = @dgp(
    L ~ Beta(2, 4),
    A ~ @.(Normal(L)),
    Y ~ @.(Normal(A + 2 * L + 1))
)
scm = StructuralCausalModel(dgp, [:A], [:Y], [:L])
ape(scm, additive_mtp(0.5))

adjacency_matrix(o::CausalTable)

Generate the adjacency matrix induced by the summaries and arrays attributes of a CausalTable object. This matrix denotes which units are causally dependent upon one another: an entry of 1 in cell (i,j) indicates that some variable in unit i exhibits a causal relationship to some variable in unit j.

Arguments

• o::CausalTable: The CausalTable object for which the adjacency matrix is to be generated.

Returns

A boolean matrix representing the adjacency relationships in the CausalTable.

ape(scm::StructuralCausalModel, intervention::Function; samples = 10^6)

Approximate the average policy effect for a given structural causal model (SCM), along with its efficiency bound. This is also known as the causal effect of a modified treatment policy, and is approximated using Monte Carlo sampling. Note that unless intervention is piecewise smooth invertible, the estimated statistical quantity may not have a causal interpretation; see Haneuse and Rotnizky (2013). Mathematically, this is

\[E(Y(d(a) - Y(a))\]

where $d(a)$ represents the intervention on the treatment variable(s) $A$, $Y(d(a))$ represents the counterfactual $Y$ under treatment $d(a)$, and $Y(a)$ represents the counterfactual outcome under the naturally observed value of treatment. This statistical quantity is approximated using Monte Carlo sampling.

Convenience functions for generating intervention functions include additive_mtp and multiplicative_mtp, which construct functions that respectively add or multiply a constant (or constant vector) to the treatment variable(s). One can also implement their own intervention function; this function must take as input a CausalTable object and return a NamedTuple object with each key indexing a treatment variable that has been modified according to the intervention. Also see cast_matrix_to_table_function for a convenience function for constructing interventions.

Arguments

• scm::StructuralCausalModel: The SCM from which data is to be simulated.
• intervention::Function: The intervention function to apply to the SCM.
• samples: The number of samples to draw from scm for Monte Carlo approximation (default is 10^6). This controls the precision of the approximation.

Returns

A named tuple containing:

• μ: The ATU approximation.
• eff_bound: The variance of the difference between the natural and counterfactual responses, which is equal to the efficiency bound for IID data. If observations are correlated, this may not have a meaningful interpretation.

Example

using Distributions
dgp = CausalTables.@dgp(
    L ~ Beta(2, 4),
    A ~ @.(Normal(L)),
    Y ~ @.(Normal(A + 2 * L + 1))
)
scm = CausalTables.StructuralCausalModel(dgp, [:A], [:Y], [:L])
ape(scm, additive_mtp(0.5))
ape(scm, multiplicative_mtp(2.0))

# example of a custom intervention function
custom_intervention = cast_matrix_to_table_function(x -> exp.(x))
ape(scm, custom_intervention)

ate(scm::StructuralCausalModel; samples = 10^6)

Approximate the average treatment effect (ATE) for a given structural causal model (SCM), along with its efficiency bound, for a univariate binary treatment. Mathematically, this is

\[E(Y(1) - Y(0))\]

where $Y(a)$ represents the counterfactual $Y$ had the treatment $A$ been set to $a$. This statistical quantity is approximated using Monte Carlo sampling.

Arguments

• scm::StructuralCausalModel: The SCM from which data is to be simulated.
• samples: The number of samples to draw from scm for Monte Carlo approximation (default is 10^6). This controls the precision of the approximation.

Returns

A named tuple containing:

• μ: The ATE approximation.
• eff_bound: The variance of the counterfactual response, which is equal to the efficiency bound for IID data. If observations are correlated, this may not have a meaningful interpretation.

Example

using Distributions
dgp = @dgp(
    L ~ Beta(2, 4),
    A ~ @.(Bernoulli(L)),
    Y ~ @.(Normal(A + L))
)
scm = StructuralCausalModel(dgp, :A, :Y, [:L])
ate(scm)

att(scm::StructuralCausalModel; samples = 10^6)

Approximate the average treatment effect among the treated (ATT) for a given structural causal model (SCM), along with its efficiency bound, for a univariate binary treatment. Mathematically, this is

\[E(Y(1) - Y(0) \mid A = 1)\]

where $Y(a)$ represents the counterfactual $Y$ had the treatment $A$ been set to $a$. This statistical quantity is approximated using Monte Carlo sampling.

Arguments

• scm::StructuralCausalModel: The SCM from which data is to be simulated.
• samples: The number of samples to draw from scm for Monte Carlo approximation (default is 10^6). This controls the precision of the approximation.

Returns

A named tuple containing:

• μ: The ATT approximation.
• eff_bound: The variance of the counterfactual response, which is equal to the efficiency bound for IID data. If observations are correlated, this may not have a meaningful interpretation.

Example

using Distributions
dgp = @dgp(
    L ~ Beta(2, 4),
    A ~ @.(Bernoulli(L)),
    Y ~ @.(Normal(A + L))
)
scm = StructuralCausalModel(dgp, :A, :Y, [:L])
att(scm, treat_all, treat_none)

atu(scm::StructuralCausalModel; samples = 10^6)

Approximate the average treatment effect among the untreated (ATU) for a given structural causal model (SCM), along with its efficiency bound, for a univariate binary treatment. Mathematically, this is

\[E(Y(1) - Y(0) \mid A = 0)\]

where $Y(a)$ represents the counterfactual $Y$ had the treatment $A$ been set to $a$. This statistical quantity is approximated using Monte Carlo sampling.

Arguments

• scm::StructuralCausalModel: The SCM from which data is to be simulated.
• samples: The number of samples to draw from scm for Monte Carlo approximation (default is 10^6). This controls the precision of the approximation.

Returns

A named tuple containing:

• μ: The ATU approximation.
• eff_bound: The variance of the counterfactual response, which is equal to the efficiency bound for IID data. If observations are correlated, this may not have a meaningful interpretation.

Example

using Distributions
dgp = @dgp(
    L ~ Beta(2, 4),
    A ~ @.(Bernoulli(L)),
    Y ~ @.(Normal(A + L))
)
scm = StructuralCausalModel(dgp, :A, :Y, [:L])
atu(scm, treat_all, treat_none)

cast_matrix_to_table_function(func::Function)

Wraps a given function func that operates on a matrix and returns a new function that operates on a CausalTable object. The returned function converts the CausalTable's treatment matrix to a table, applies func to this matrix, and then converts the result back to a column table with the same header as the original treatment matrix.

Arguments

• func::Function: A function that takes a matrix as input and returns a matrix.

Returns

• A function that takes a CausalTable object as input and returns a column table.

Example

custom_intervention = cast_matrix_to_table_function(x -> exp.(x))

cfdiff(scm::StructuralCausalModel, intervention1::Function, intervention2::Function; samples = 10^6)

Approximate the difference between two counterfactual response means – that under intervention1 having been applied to the treatment, and that under intervention2 – for a given structural causal model (SCM), along with its efficiency bound. Mathematically, this is

\[E(Y(d_1(a)) - Y(d_2(a)))\]

where $d_1$ and $d_2$ represent intervention1 and intervention2 being applied on the treatment variable(s) $A$. This statistical quantity is approximated using Monte Carlo sampling.

Arguments

• scm::StructuralCausalModel: The SCM from which data is to be simulated.
• intervention1::Function: The first intervention function to be contrasted.
• intervention2::Function: The second intervention function to be contrasted.
• samples: The number of samples to draw from scm for Monte Carlo approximation (default is 10^6). This controls the precision of the approximation.

Returns

A named tuple containing:

• μ: The mean difference in counterfactual outcomes.
• eff_bound: The variance of the difference in counterfactual responses, which is equal to the efficiency bound for IID data. If observations are correlated, this may not have a meaningful interpretation.

Example

using Distributions
dgp = @dgp(
    L ~ Beta(2, 4),
    A ~ @.(Bernoulli(L)),
    Y ~ @.(Normal(A + L))
)
scm = StructuralCausalModel(dgp, :A, :Y, [:L])
cfdiff(scm, treat_all, treat_none)

cfmean(scm::StructuralCausalModel, intervention::Function; samples = 10^6)

Approximate the counterfactual mean of the response had intervention been applied to the treatment, along with its efficiency bound, for a given structural causal model (SCM). Mathematically, this estimand is

\[E(Y(d(a)))\]

where $d(a)$ represents an intervention on the treatment variable(s) $A$. This statistical quantity is approximated using Monte Carlo sampling.

Arguments

• scm::StructuralCausalModel: The SCM from which data is to be simulated.
• intervention::Function: The intervention function to apply to the SCM.
• samples: The number of samples to draw from scm for Monte Carlo approximation (default is 10^6). This controls the precision of the approximation.

Returns

A named tuple containing:

• μ: The mean of the counterfactual outcomes.
• eff_bound: The variance of the counterfactual response, which is equal to the efficiency bound for IID data. If observations are correlated, this may not have a meaningful interpretation.

Example

using Distributions
dgp = @dgp(
    L ~ Beta(2, 4),
    A ~ @.(Bernoulli(L)),
    Y ~ @.(Normal(A + L))
)
scm = StructuralCausalModel(dgp, :A, :Y, [:L])
cfmean(scm, treat_all)
cfmean(scm, treat_none)

condensity(scm::StructuralCausalModel, ct::CausalTable, name::Symbol)

Compute the conditional density of variable name in CausalTable ct that has been drawn from StructuralCausalModel scm.

Arguments

• scm::StructuralCausalModel: The StructuralCausalModel representing the data generating process.
• ct::CausalTable: The CausalTable containing the observed data.
• name::Symbol: The variable for which to compute the conditional density.

Returns

The conditional density of the variable var given the observed data.

confounders(o::CausalTable)

Selects and returns the confounders from a CausalTable object.

Arguments

• o::CausalTable: The CausalTable object from which to select confounders.

Returns

A new CausalTable containing only the confounders.

confoundersmatrix(o::CausalTable)

Outputs the confounders from the given CausalTable object as a matrix.

Arguments

• o::CausalTable: The CausalTable object from which to select the confounders.

Returns

A matrix containing only the confounders.

conmean(scm::StructuralCausalModel, ct::CausalTable, name::Symbol)

Compute the conditional mean of variable name in CausalTable ct that has been drawn from StructuralCausalModel scm.

Arguments

• scm::StructuralCausalModel: The StructuralCausalModel object representing the data generating process.
• ct::CausalTable: The CausalTable object representing the data.
• name::Symbol: The variable for which to compute the conditional mean.

Returns

An array of conditional means for the specified variable.

convar(scm::StructuralCausalModel, ct::CausalTable, name::Symbol)

Compute the conditional variance of variable name in CausalTable ct that has been drawn from StructuralCausalModel scm.

Arguments

• scm::StructuralCausalModel: The StructuralCausalModel object representing the data generating process.
• ct::CausalTable: The CausalTable object representing the data.
• name::Symbol: The variable for which to compute the conditional mean.

Returns

An array of conditional variances for the specified variable.

data(o::CausalTable)

Retrieve the data stored in a CausalTable object.

Arguments

• o::CausalTable: The CausalTable from which to retrieve the data.

Returns

The data stored in the CausalTable object.

dependency_matrix(o::CausalTable)

Generate the dependency matrix induced by the summaries and arrays attributes of a CausalTable object. This matrix stores which units are statistically dependent upon one another: an entry of 1 in cell (i,j) indicates that the data of unit i is correlated with the data in unit j. Two units are correlated if they either are causally dependent (neighbors in the adjacency matrix) or share a common cause (share a neighbor in the adjacency matrix).

Arguments

• o::CausalTable: The CausalTable object for which the dependency matrix is to be generated.

Returns

A boolean matrix representing the relationships in the CausalTable.

draw_counterfactual(scm::StructuralCausalModel, parents::CausalTable, intervention::Function) -> Vector

Generate counterfactual responses based on a given structural causal model (SCM), a table of response parents, and an intervention function. That is, sample the responses that would have occurred had some intervention been applied to the treatment specified by the structural causal model.

Arguments

• scm::StructuralCausalModel: The structural causal model used to generate counterfactual outcomes.
• parents::CausalTable: A table containing the variables causally preceding the response variable.
• intervention::Function: A function that defines the intervention to be applied to the parent variables. Use cast_matrix_to_table_function to convert a function acting on a treatment vector or matrix to a function that acts on a CausalTable.

Returns

A vector of counterfactual responses.

getscm(o::CausalTable)

Get the structural causal model (SCM) of a CausalTable object.

This function merges the column table of the CausalTable object with its arrays.

Arguments

• o::CausalTable: The CausalTable object.

Returns

• A merged table containing the column table and arrays of the CausalTable object.

intervene(ct::CausalTable, intervention::Function)

Applies intervention to the treatment vector(s) within a CausalTable, and outputs a new CausalTable with the intervened treatment.

Arguments

• ct::CausalTable: The data on which treatment should be intervened
• intervention::Function: A function that defines the intervention to be applied to the parent variables. Use cast_matrix_to_table_function to convert a function acting on a treatment vector or matrix to a function that acts on a CausalTable.

Returns

A CausalTable containing the same data as ct, but with the treatment variable(s) modified accoding to intervention

Example

using Distributions
dgp = @dgp(
    L ~ Beta(2, 4),
    A ~ @.(Bernoulli(L)),
    Y ~ @.(Normal(A + L))
)
scm = StructuralCausalModel(dgp, :A, :Y, [:L])
ct = rand(scm, 100)
intervene(ct, treat_all)

multiplicative_mtp(δ)

Constructs a function that scales the treatment variable(s) in a CausalTable object by a constant δ. This function is intended to be used as an argument to ape.

Arguments

• δ: The "multiplicative shift" to be applied to the treatment variable of a CausalTable.

Returns

• A function that takes a CausalTable object as input and returns a column table of treatments that have been scaled by δ units.

Example

using Distributions
dgp = CausalTables.@dgp(
    L ~ Beta(2, 4),
    A ~ @.(Normal(L)),
    Y ~ @.(Normal(A + 2 * L + 1))
)
scm = CausalTables.StructuralCausalModel(dgp, [:A], [:Y], [:L])
ape(scm, multiplicative_mtp(2.0))

parents(o::CausalTable, symbol)

Selects the variables that precede symbol causally from the CausalTable o. For instance, if symbol is in o.response, this function will return a CausalTable containing the symbols in o.treatment and o.confounders.

Warning: If symbol is in o.confounders, then this function will return a CausalTable containing an empty data attribute.

Arguments

• o::CausalTable: The CausalTable object from which to extract the parent variables of symbol.
• symbol: The variable for which to extract the parent variables.

Returns

A new CausalTable containing only the parents of symbol

propensity(scm::StructuralCausalModel, ct::CausalTable, name::Symbol)

Compute the (generalized) propensity score of variable name in CausalTable ct that has been drawn from StructuralCausalModel scm.

Arguments

• scm::StructuralCausalModel: The StructuralCausalModel object representing the data generating process.
• ct::CausalTable: The CausalTable object representing the data.
• name::Symbol: The variable for which to compute the conditional mean.

Returns

An array of conditional probabilities for the specified variable (or densities, if the specified variable is continuous).

reject(o::CausalTable, symbols)

Removes the columns specified by symbols from the CausalTable object o.

Arguments

• o::CausalTable: The CausalTable object from which symbols will be rejected.
• symbols: A collection of symbols to be rejected from the CausalTable.

Returns

A new CausalTable object with the specified symbols removed from its data.

replace(o::CausalTable; kwargs...)

Replace the fields of a CausalTable object with the provided keyword arguments.

Arguments

• o::CausalTable: The CausalTable object to be replaced.
• kwargs...: Keyword arguments specifying the new values for the fields.

Returns

A new CausalTable object with the specified fields replaced.

response(o::CausalTable)

Selects the response column(s) from the given CausalTable object.

Arguments

• o::CausalTable: The CausalTable object from which to select the response column(s).

Returns

A new CausalTable containing only the response column(s).

responsematrix(o::CausalTable)

Outputs the response column(s) from the given CausalTable object as a matrix.

Arguments

• o::CausalTable: The CausalTable object from which to select the response column(s).

Returns

A matrix containing only the response column(s)

responseparents(o::CausalTable)

Selects all variables besides those in o.response from the given CausalTable object.

Arguments

• o::CausalTable: The CausalTable object from which to extract the parent variables of the response.

Returns

A new CausalTable containing only the confounders and treatment.

select(o::CausalTable, symbols)

Selects specified columns from a CausalTable object.

Arguments

• o::CausalTable: The CausalTable object from which columns are to be selected.
• symbols: A list of symbols representing the columns to be selected.

Returns

• A new CausalTable object with only the selected columns.

summarize(o::CausalTable)

Summarizes the data in a CausalTable object according to the NetworkSummary objects stored in its summaries attribute.

Arguments

• o::CausalTable: The CausalTable object to be summarized.

Returns

• A new CausalTable object with the original data merged with the summarized data.

treat_all(ct::CausalTable)

Intervenes on a CausalTable object by setting all treatment variables to 1.

Arguments

• ct::CausalTable: A CausalTable object with a univariate binary treatment.

Returns

A NamedTuple object with the same header as the treatment matrix in ct, where each treatment variable is set to 1.

Example

using Distributions
dgp = @dgp(
    L ~ Beta(2, 4),
    A ~ @.(Bernoulli(L)),
    Y ~ @.(Normal(A + L))
)
scm = StructuralCausalModel(dgp, :A, :Y, [:L])
data = rand(scm, 100)
treat_all(data)

treat_all(ct::CausalTable)

Intervenes on a CausalTable object by setting all treatment variables to 0.

Arguments

• ct::CausalTable: A CausalTable object with a univariate binary treatment.

Returns

A NamedTuple object with the same header as the treatment matrix in ct, where each treatment variable is set to 0.

Example

using Distributions
dgp = @dgp(
    L ~ Beta(2, 4),
    A ~ @.(Bernoulli(L)),
    Y ~ @.(Normal(A + L))
)
scm = StructuralCausalModel(dgp, :A, :Y, [:L])
data = rand(scm, 100)
treat_none(data)

treatment(o::CausalTable)

Selects the treatment column(s) from the given CausalTable object.

Arguments

• o::CausalTable: The CausalTable object from which to select the treatment column(s).

Returns

A new CausalTable containing only the treatment column(s)

treatmentmatrix(o::CausalTable)

Outputs the treatment column(s) from the given CausalTable object as a matrix.

Arguments

• o::CausalTable: The CausalTable object from which to select the treatment column(s).

Returns

A matrix containing only the treatment column(s)

treatmentparents(o::CausalTable)

Selects all variables besides those in o.treatment and o.response from the given CausalTable object.

Arguments

• o::CausalTable: The CausalTable object from which to extract the parent variables of the treatment.

Returns

A new CausalTable containing only the confounders.

Distributions.convolve(ds::Vector{T}) where {T <: UnivariateDistribution}

Overload the convolve function to work on a vector of UnivariateDistribution.

Arguments

• ds::Vector{T}: A vector of UnivariateDistribution objects.

Returns

• output: The result of convolving all the distributions in ds. If ds is empty, will return Binomial(0, 0.5) denoting a point mass at 0.