Calculated from a parameter vector, from a prior or from a posterior distribution.
Usage
query_model(
model,
queries = NULL,
given = NULL,
using = list("parameters"),
parameters = NULL,
stats = NULL,
n_draws = 4000,
expand_grid = NULL,
case_level = FALSE,
query = NULL,
cred = 95,
labels = NULL
)Arguments
- model
A
causal_model. A model object generated bymake_model.- queries
A vector of strings or list of strings specifying queries on potential outcomes such as "Y[X=1] - Y[X=0]". Queries can also indicate conditioning sets by placing second queries after a colon: "Y[X=1] - Y[X=0] :|: X == 1 & Y == 1". Note a colon, ':|:' is used rather than the traditional conditioning marker '|' to avoid confusion with logical operators.
- given
A character vector specifying given conditions for each query. A 'given' is a quoted expression that evaluates to logical statement.
givenallows the query to be conditioned on either observed or counterfactural distributions. A value of TRUE is interpreted as no conditioning. A given statement can alternatively be provided after a colon in the query statement.- using
A vector or list of strings. Whether to use priors, posteriors or parameters.
- parameters
A vector of real numbers in [0,1]. Values of parameters to specify (optional). By default, parameters is drawn from the parameters dataframe. See
inspect(model, "parameters_df").- stats
Functions to be applied to the query distribution. If NULL, defaults to mean, standard deviation, and 95% confidence interval. Functions should return a single numeric value.
- n_draws
An integer. Number of draws.
- expand_grid
Logical. If
TRUEthen all combinations of provided lists are examined. If not then each list is cycled through separately. Defaults to FALSE.- case_level
Logical. If TRUE estimates the probability of the query for a case.
- query
alias for queries
- cred
size of the credible interval ranging between 0 and 100
- labels
labels for queries: if provided labels should have the length of the combinations of requests
Value
An object of class model_query. A data frame with possible
columns: model, query, given, using, case_level, mean, sd, cred.low, cred.high.
Further columns are generated as specified in stats.
Details
Queries can condition on observed or counterfactual quantities.
Nested or "complex" counterfactual queries of the form
Y[X=1, M[X=0]] are allowed.
Examples
model <- make_model("X -> Y")
query_model(model, "Y[X=1] - Y[X = 0]", using = "priors")
#>
#> Causal queries generated by query_model (all at population level)
#>
#> |label |using | mean| sd| cred.low| cred.high|
#> |:-----------------|:------|------:|----:|--------:|---------:|
#> |Y[X=1] - Y[X = 0] |priors | -0.004| 0.32| -0.653| 0.63|
#>
query_model(model, "Y[X=1] - Y[X = 0] :|: X==1 & Y==1", using = "priors")
#>
#> Causal queries generated by query_model (all at population level)
#>
#> |label |using | mean| sd| cred.low| cred.high|
#> |:-----------------------------------|:------|----:|-----:|--------:|---------:|
#> |Y[X=1] - Y[X = 0] given X==1 & Y==1 |priors | 0.49| 0.288| 0.025| 0.972|
#>
query_model(model,
list("Y[X=1] - Y[X = 0]",
"Y[X=1] - Y[X = 0] :|: X==1 & Y==1"),
using = "priors")
#>
#> Causal queries generated by query_model (all at population level)
#>
#> |label |query |given |using | mean| sd| cred.low| cred.high|
#> |:-----------------------------------|:-----------------|:-----------|:------|-----:|-----:|--------:|---------:|
#> |Y[X=1] - Y[X = 0] |Y[X=1] - Y[X = 0] |- |priors | 0.003| 0.318| -0.641| 0.639|
#> |Y[X=1] - Y[X = 0] given X==1 & Y==1 |Y[X=1] - Y[X = 0] |X==1 & Y==1 |priors | 0.495| 0.291| 0.024| 0.976|
#>
query_model(model, "Y[X=1] > Y[X = 0]", using = "parameters")
#>
#> Causal queries generated by query_model (all at population level)
#>
#> |label |using | mean|
#> |:-----------------|:----------|----:|
#> |Y[X=1] > Y[X = 0] |parameters | 0.25|
#>
query_model(model, "Y[X=1] > Y[X = 0]", using = c("priors", "parameters"))
#>
#> Causal queries generated by query_model (all at population level)
#>
#> |label |using | mean| sd| cred.low| cred.high|
#> |:-----------------|:----------|-----:|-----:|--------:|---------:|
#> |Y[X=1] > Y[X = 0] |priors | 0.249| 0.193| 0.009| 0.708|
#> |Y[X=1] > Y[X = 0] |parameters | 0.250| NA| 0.250| 0.250|
#>
# \donttest{
# `expand_grid= TRUE` requests the Cartesian product of arguments
models <- list(
M1 = make_model("X -> Y"),
M2 = make_model("X -> Y") |>
set_restrictions("Y[X=1] < Y[X=0]")
)
# No expansion: lists should be equal length
query_model(
models,
query = list(ATE = "Y[X=1] - Y[X=0]",
Share_positive = "Y[X=1] > Y[X=0]"),
given = c(TRUE, "Y==1 & X==1"),
using = c("parameters", "priors"),
expand_grid = FALSE)
#>
#> Causal queries generated by query_model (all at population level)
#>
#> |label |model |query |given |using | mean| sd| cred.low| cred.high|
#> |:--------------|:-----|:---------------|:-----------|:----------|-----:|-----:|--------:|---------:|
#> |ATE |M1 |Y[X=1] - Y[X=0] |- |parameters | 0.000| NA| 0.000| 0.000|
#> |Share_positive |M1 |Y[X=1] > Y[X=0] |Y==1 & X==1 |priors | 0.501| 0.290| 0.026| 0.974|
#> |ATE |M2 |Y[X=1] - Y[X=0] |- |parameters | 0.333| NA| 0.333| 0.333|
#> |Share_positive |M2 |Y[X=1] > Y[X=0] |Y==1 & X==1 |priors | 0.504| 0.291| 0.026| 0.979|
#>
# Expansion when query and given arguments coupled
query_model(
models,
query = list(ATE = "Y[X=1] - Y[X=0]",
Share_positive = "Y[X=1] > Y[X=0] :|: Y==1 & X==1"),
using = c("parameters", "priors"),
expand_grid = TRUE)
#>
#> Causal queries generated by query_model (all at population level)
#>
#> |label |model |query |given |using | mean| sd| cred.low| cred.high|
#> |:--------------|:-----|:---------------|:-----------|:----------|------:|-----:|--------:|---------:|
#> |ATE |M1 |Y[X=1] - Y[X=0] |- |parameters | 0.000| NA| 0.000| 0.000|
#> |ATE |M2 |Y[X=1] - Y[X=0] |- |parameters | 0.333| NA| 0.333| 0.333|
#> |ATE |M1 |Y[X=1] - Y[X=0] |- |priors | -0.005| 0.320| -0.643| 0.657|
#> |ATE |M2 |Y[X=1] - Y[X=0] |- |priors | 0.333| 0.236| 0.012| 0.849|
#> |Share_positive |M1 |Y[X=1] > Y[X=0] |Y==1 & X==1 |parameters | 0.500| NA| 0.500| 0.500|
#> |Share_positive |M2 |Y[X=1] > Y[X=0] |Y==1 & X==1 |parameters | 0.500| NA| 0.500| 0.500|
#> |Share_positive |M1 |Y[X=1] > Y[X=0] |Y==1 & X==1 |priors | 0.499| 0.289| 0.027| 0.972|
#> |Share_positive |M2 |Y[X=1] > Y[X=0] |Y==1 & X==1 |priors | 0.501| 0.288| 0.024| 0.974|
#>
# Expands over query and given argument when these are not coupled
query_model(
models,
query = list(ATE = "Y[X=1] - Y[X=0]",
Share_positive = "Y[X=1] > Y[X=0]"),
given = c(TRUE, "Y==1 & X==1"),
using = c("parameters", "priors"),
expand_grid = TRUE)
#>
#> Causal queries generated by query_model (all at population level)
#>
#> |label |model |query |given |using | mean| sd| cred.low| cred.high|
#> |:--------------|:-----|:---------------|:-----------|:----------|-----:|-----:|--------:|---------:|
#> |ATE |M1 |Y[X=1] - Y[X=0] |- |parameters | 0.000| NA| 0.000| 0.000|
#> |ATE |M2 |Y[X=1] - Y[X=0] |- |parameters | 0.333| NA| 0.333| 0.333|
#> |ATE |M1 |Y[X=1] - Y[X=0] |- |priors | 0.001| 0.319| -0.640| 0.627|
#> |ATE |M2 |Y[X=1] - Y[X=0] |- |priors | 0.335| 0.235| 0.014| 0.831|
#> |ATE |M1 |Y[X=1] - Y[X=0] |Y==1 & X==1 |parameters | 0.500| NA| 0.500| 0.500|
#> |ATE |M2 |Y[X=1] - Y[X=0] |Y==1 & X==1 |parameters | 0.500| NA| 0.500| 0.500|
#> |ATE |M1 |Y[X=1] - Y[X=0] |Y==1 & X==1 |priors | 0.497| 0.288| 0.027| 0.971|
#> |ATE |M2 |Y[X=1] - Y[X=0] |Y==1 & X==1 |priors | 0.503| 0.287| 0.026| 0.973|
#> |Share_positive |M1 |Y[X=1] > Y[X=0] |- |parameters | 0.250| NA| 0.250| 0.250|
#> |Share_positive |M2 |Y[X=1] > Y[X=0] |- |parameters | 0.333| NA| 0.333| 0.333|
#> |Share_positive |M1 |Y[X=1] > Y[X=0] |- |priors | 0.248| 0.193| 0.009| 0.705|
#> |Share_positive |M2 |Y[X=1] > Y[X=0] |- |priors | 0.335| 0.235| 0.014| 0.831|
#> |Share_positive |M1 |Y[X=1] > Y[X=0] |Y==1 & X==1 |parameters | 0.500| NA| 0.500| 0.500|
#> |Share_positive |M2 |Y[X=1] > Y[X=0] |Y==1 & X==1 |parameters | 0.500| NA| 0.500| 0.500|
#> |Share_positive |M1 |Y[X=1] > Y[X=0] |Y==1 & X==1 |priors | 0.497| 0.288| 0.027| 0.971|
#> |Share_positive |M2 |Y[X=1] > Y[X=0] |Y==1 & X==1 |priors | 0.503| 0.287| 0.026| 0.973|
#>
# An example of a custom statistic: uncertainty of token causation
f <- function(x) mean(x)*(1-mean(x))
query_model(
model,
using = list( "parameters", "priors"),
query = "Y[X=1] > Y[X=0]",
stats = c(mean = mean, sd = sd, token_variance = f))
#>
#> Causal queries generated by query_model (all at population level)
#>
#> |label |using | mean| sd| token_variance|
#> |:---------------|:----------|-----:|-----:|--------------:|
#> |Y[X=1] > Y[X=0] |parameters | 0.250| NA| 0.188|
#> |Y[X=1] > Y[X=0] |priors | 0.247| 0.194| 0.186|
#>
# }