--- title: "Getting Started" output: rmarkdown::html_vignette: md_extensions: [ "-autolink_bare_uris" ] vignette: > %\VignetteIndexEntry{Getting Started} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ``` r library(CausalQueries) library(dplyr) library(knitr) ``` # Make a model **Generating**: To make a model you need to provide a DAG statement to `make_model`. For instance * `"X->Y"` * `"X -> M -> Y <- X"` or * `"Z -> X -> Y <-> X"`. ``` r # examples of models xy_model <- make_model("X -> Y") iv_model <- make_model("Z -> X -> Y <-> X") ``` **Graphing**: Once you have made a model you can inspect the DAG: ``` r plot(xy_model) ``` ![Simple model](a1xymodel-1.png) **Simple summaries:** You can access a simple summary using `summary()` ``` r summary(xy_model) #> #> Causal statement: #> X -> Y #> #> Nodal types: #> $X #> 0 1 #> #> node position display interpretation #> 1 X NA X0 X = 0 #> 2 X NA X1 X = 1 #> #> $Y #> 00 10 01 11 #> #> node position display interpretation #> 1 Y 1 Y[*]* Y | X = 0 #> 2 Y 2 Y*[*] Y | X = 1 #> #> Number of types by node: #> X Y #> 2 4 #> #> Number of causal types: 8 #> #> Note: Model does not contain: posterior_distribution, stan_objects; #> to include these objects use update_model() #> #> Note: To pose causal queries of this model use query_model() ``` or you can examine model details using `inspect()`. **Inspecting**: The model has a set of parameters and a default distribution over these. ``` r xy_model |> inspect("parameters_df") #> #> parameters_df #> Mapping of model parameters to nodal types: #> #> param_names: name of parameter #> node: name of endogeneous node associated #> with the parameter #> gen: partial causal ordering of the #> parameter's node #> param_set: parameter groupings forming a simplex #> given: if model has confounding gives #> conditioning nodal type #> param_value: parameter values #> priors: hyperparameters of the prior #> Dirichlet distribution #> #> param_names node gen param_set nodal_type given param_value priors #> 1 X.0 X 1 X 0 0.50 1 #> 2 X.1 X 1 X 1 0.50 1 #> 3 Y.00 Y 2 Y 00 0.25 1 #> 4 Y.10 Y 2 Y 10 0.25 1 #> 5 Y.01 Y 2 Y 01 0.25 1 #> 6 Y.11 Y 2 Y 11 0.25 1 ``` **Tailoring**: These features can be edited using `set_restrictions`, `set_priors` and `set_parameters`. Here is an example of setting a monotonicity restriction (see `?set_restrictions` for more): ``` r iv_model <- iv_model |> set_restrictions(decreasing('Z', 'X')) ``` Here is an example of setting priors (see `?set_priors` for more): ``` r iv_model <- iv_model |> set_priors(distribution = "jeffreys") #> Altering all parameters. ``` **Simulation**: Data can be drawn from a model like this: ``` r data <- make_data(iv_model, n = 4) data |> kable() ``` | Z| X| Y| |--:|--:|--:| | 0| 0| 0| | 0| 0| 0| | 1| 0| 0| | 1| 1| 0| # Update the model **Updating**: Update using `update_model`. You can pass all `rstan` arguments to `update_model`. ``` r df <- data.frame(X = rbinom(100, 1, .5)) |> mutate(Y = rbinom(100, 1, .25 + X*.5)) xy_model <- xy_model |> update_model(df, refresh = 0) ``` **Inspecting**: You can access the posterior distribution on model parameters directly thus: ``` r xy_model |> grab("posterior_distribution") |> head() |> kable() ``` | X.0| X.1| Y.00| Y.10| Y.01| Y.11| |---------:|---------:|---------:|---------:|---------:|---------:| | 0.5492781| 0.4507219| 0.2012814| 0.0290333| 0.6173449| 0.1523404| | 0.5721205| 0.4278795| 0.1636895| 0.0076445| 0.6178096| 0.2108564| | 0.5293741| 0.4706259| 0.1105087| 0.0618505| 0.6528884| 0.1747524| | 0.5455803| 0.4544197| 0.0507192| 0.0324765| 0.7909186| 0.1258856| | 0.5584022| 0.4415978| 0.0894235| 0.0573218| 0.6744541| 0.1788006| | 0.4334458| 0.5665542| 0.0484166| 0.0208843| 0.6617683| 0.2689309| where each row is a draw of parameters. # Query the model ## Arbitrary queries **Querying**: You ask arbitrary causal queries of the model. Examples of *unconditional* queries: ``` r xy_model |> query_model("Y[X=1] > Y[X=0]", using = c("priors", "posteriors")) #> #> 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.255| 0.196| 0.008| 0.715| #> |Y[X=1] > Y[X=0] |posteriors | 0.652| 0.082| 0.483| 0.793| ``` This query asks the probability that $Y(1)> Y(0)$. Examples of *conditional* queries: ``` r xy_model |> query_model("Y[X=1] > Y[X=0] :|: X == 1 & Y == 1", using = c("priors", "posteriors")) #> #> 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.496| 0.290| 0.025| 0.977| #> |Y[X=1] > Y[X=0] given X == 1 & Y == 1 |posteriors | 0.795| 0.091| 0.616| 0.967| ``` This query asks the probability that $Y(1) > Y(0)$ *given* $X=1$ and $Y=1$; it is a type of "causes of effects" query. Note that ":|:" is used to separate the main query element from the conditional statement to avoid ambiguity, since "|" is reserved for the "or" operator. Queries can even be conditional on counterfactual quantities. Here the probability of a positive effect given *some* effect: ``` r xy_model |> query_model("Y[X=1] > Y[X=0] :|: Y[X=1] != Y[X=0]", using = c("priors", "posteriors")) #> #> 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 Y[X=1] != Y[X=0] |priors | 0.502| 0.286| 0.029| 0.971| #> |Y[X=1] > Y[X=0] given Y[X=1] != Y[X=0] |posteriors | 0.892| 0.063| 0.763| 0.995| ``` Note that we use ":" to separate the base query from the condition rather than "|" to avoid confusion with logical operators. ## Output Query output is ready for printing as tables, but can also be plotted, which is especially useful with batch requests: ``` r batch_queries <- xy_model |> query_model(queries = list(ATE = "Y[X=1] - Y[X=0]", `Positive effect given any effect` = "Y[X=1] > Y[X=0] :|: Y[X=1] != Y[X=0]"), using = c("priors", "posteriors"), expand_grid = TRUE) batch_queries |> kable(digits = 2, caption = "tabular output") ``` Table: tabular output |label |query |given |using |case_level | mean| sd| cred.low| cred.high| |:--------------------------------|:---------------|:----------------|:----------|:----------|----:|----:|--------:|---------:| |ATE |Y[X=1] - Y[X=0] |- |priors |FALSE | 0.01| 0.31| -0.60| 0.63| |ATE |Y[X=1] - Y[X=0] |- |posteriors |FALSE | 0.57| 0.08| 0.40| 0.72| |Positive effect given any effect |Y[X=1] > Y[X=0] |Y[X=1] != Y[X=0] |priors |FALSE | 0.51| 0.29| 0.03| 0.98| |Positive effect given any effect |Y[X=1] > Y[X=0] |Y[X=1] != Y[X=0] |posteriors |FALSE | 0.89| 0.06| 0.76| 0.99| ``` r batch_queries |> plot() ``` ![Simple query](a1batchplot-1.png)