# R6 Class for structural causal models R6 Class for structural causal models R6 Class for structural causal models ## Details An R6 class for structural causal models (SCM) with latent variables and missing data mechanism. There are methods for defining, printing, plotting, intervening and simulating SCMs. ## Examples ```r ## ------------------------------------------------ ## Method `SCM$new` ## ------------------------------------------------ backdoor <- SCM$new("backdoor", uflist = list( uz = function(n) {return(stats::runif(n))}, ux = function(n) {return(stats::runif(n))}, uy = function(n) {return(stats::runif(n))} ), vflist = list( z = function(uz) { return(as.numeric(uz < 0.4))}, x = function(ux, z) { return(as.numeric(ux < 0.2 + 0.5*z))}, y = function(uy, z, x) { return(as.numeric(uy < 0.1 + 0.4*z + 0.4*x))} ) ) ## ------------------------------------------------ ## Method `SCM$print` ## ------------------------------------------------ backdoor ## ------------------------------------------------ ## Method `SCM$plot` ## ------------------------------------------------ backdoor$plot() backdoor$plot("v") ## ------------------------------------------------ ## Method `SCM$add_variable` ## ------------------------------------------------ backdoor2 <- backdoor$clone() backdoor2$add_variable( vfnew = list( w = function(uw, x) { return(as.numeric(uw < 0.4 + 0.3*x))}), ufnew = list( uw = function(n) {return(stats::runif(n))}) ) ## ------------------------------------------------ ## Method `SCM$remove_variable` ## ------------------------------------------------ backdoor2 <- backdoor$clone() backdoor2$remove_variable(c("uy","y")) #' @include R6causal.R R6causal_examples.R NULL ## ------------------------------------------------ ## Method `SCM$dosearch` ## ------------------------------------------------ backdoor$dosearch(data = "p(x,y,z)", query = "p(y|do(x))") ## ------------------------------------------------ ## Method `SCM$cfid` ## ------------------------------------------------ backdoor$cfid(gamma = cfid::conj(cfid::cf("Y",0), cfid::cf("X",0, c(Z=1))) ) ## ------------------------------------------------ ## Method `SCM$intervene` ## ------------------------------------------------ # A simple intervention backdoor_x1 <- backdoor$clone() # making a copy backdoor_x1$intervene("x",1) # applying the intervention backdoor_x1$plot() # to see that arrows incoming to x are cut # An intervention that redefines a structural equation backdoor_yz <- backdoor$clone() # making a copy backdoor_yz$intervene("y", function(uy, z) {return(as.numeric(uy < 0.1 + 0.8*z ))}) # making y a function of z only backdoor_yz$plot() # to see that arrow x -> y is cut ## ------------------------------------------------ ## Method `SCM$simulate` ## ------------------------------------------------ backdoor$simulate(8, return_simdata = TRUE, store_simdata = FALSE) backdoor$simulate(10) backdoor$simdata ``` ## Active bindings - **`vflist`**: List of the structural functions of observed variables. - **`vnames`**: List of the names of observed variables. - **`vstarnames`**: List of the names of observed variables with NA's. - **`vfsymb`**: List of the arguments of structural functions of observed variables. - **`uflist`**: List of the structural functions of unobserved variables. - **`unames`**: List of the names of unobserved variables. - **`unames_dedicated`**: List of the names of unobserved variables that have only one child. - **`unames_confounder`**: List of the names of unobserved variables that have two or more children. - **`dedicated_u`**: Named list of the names of unobserved variables that have only one child which is the name of the element. - **`is_linear_gaussian`**: Logical, does the SCM have linear functions and Gaussian background variables? - **`rflist`**: List of the structural functions of missingness indicators. - **`rfsymb`**: List of the names of missingness indicators. - **`rprefix`**: Prefix used to mark missingness indicators. - **`starsuffix`**: Suffix used to mark variables with missing data. - **`simdata`**: Data table containing data simulated from the SCM. - **`simdata_obs`**: Data table containing data simulated from the SCM where missing values are indicated by `NA`. - **`igraph`**: The graph of the SCM in the `igraph` form (without the missing data mechanism). - **`igraph_nodedicated`**: The graph of the SCM in the `igraph` form (without the dedicated U variables and the missing data mechanism). - **`igraph_bidirected`**: The graph of the SCM in the `igraph` form where latent variables are presented by bidirected arcs. - **`igraph_md`**: The graph of the SCM in the `igraph` form including the missing data mechanism. - **`toporder`**: A vector giving the topological order of variables. - **`toporderv`**: A vector giving the topological order of observed variables. - **`graphtext`**: A character string that gives the edges of the graph of the SCM (without the missing data mechanism). - **`graphtext_md`**: A character string that gives the edges of the graph of the SCM including the missing data mechanism. - **`name`**: The name of the SCM. ## Methods ### Public methods * [list("SCM$new()")](#method-SCM-new) * [list("SCM$print()")](#method-SCM-print) * [list("SCM$plot()")](#method-SCM-plot) * [list("SCM$tikz()")](#method-SCM-tikz) * [list("SCM$pa()")](#method-SCM-pa) * [list("SCM$ch()")](#method-SCM-ch) * [list("SCM$an()")](#method-SCM-an) * [list("SCM$de()")](#method-SCM-de) * [list("SCM$add_variable()")](#method-SCM-add_variable) * [list("SCM$remove_variable()")](#method-SCM-remove_variable) * [list("SCM$causal.effect()")](#method-SCM-causal.effect) * [list("SCM$dosearch()")](#method-SCM-dosearch) * [list("SCM$cfid()")](#method-SCM-cfid) * [list("SCM$intervene()")](#method-SCM-intervene) * [list("SCM$simulate()")](#method-SCM-simulate) * [list("SCM$clone()")](#method-SCM-clone) ### Method `new()` Create a new SCM object. #### Usage ``` SCM$new( name = "An SCM", uflist = NULL, vflist = NULL, rflist = NULL, rprefix = "R_", starsuffix = "_md" ) ``` #### Arguments - **`name`**: Name. - **`uflist`**: A named list containing the functions for the background variables. - **`vflist`**: A named list containing the functions for the observed variables. - **`rflist`**: A named list containing the functions for missingness indicators. - **`rprefix`**: The prefix of the missingness indicators. - **`starsuffix`**: The suffix for variables with missing data. #### Returns A new `SCM` object. #### Examples ``` backdoor <- SCM$new("backdoor", uflist = list( uz = function(n) {return(stats::runif(n))}, ux = function(n) {return(stats::runif(n))}, uy = function(n) {return(stats::runif(n))} ), vflist = list( z = function(uz) { return(as.numeric(uz < 0.4))}, x = function(ux, z) { return(as.numeric(ux < 0.2 + 0.5*z))}, y = function(uy, z, x) { return(as.numeric(uy < 0.1 + 0.4*z + 0.4*x))} ) ) ``` ### Method `print()` Print a summmary of the SCM object. #### Usage ``` SCM$print() ``` #### Examples ``` backdoor ``` ### Method `plot()` Plot the DAG of the SCM object. #### Usage ``` SCM$plot(subset = "uvr", method = "igraph", ...) ``` #### Arguments - **`subset`**: Variable groups to be plotted: "uvr", "u2vr","vr","uv", "u2v" or "v". - **`method`**: Plotting method: "qgraph" or "igraph". - **`...`**: other parameters passed to the plotting method #### Examples ``` backdoor$plot() backdoor$plot("v") ``` ### Method `tikz()` Return a TikZ code for drawing the DAG of the SCM object in LaTeX. #### Usage ``` SCM$tikz( subset = "uvr", layoutfunction = igraph::layout_with_lgl, labels = NULL, settings = list(force = FALSE, borders = TRUE, shape = "circle", size = 5, scale = 2), ... ) ``` #### Arguments - **`subset`**: Variable groups to be plotted: "uvr","vr","uv", or "v". - **`layoutfunction`**: A layout function from igraph package. - **`labels`**: A named list that gives the names of vertices in TikZ. - **`settings`**: A list with the following elements: - **`...`**: Arguments to be passed to layoutfunction ### Method `pa()` Return the parents of a set of vertices. #### Usage ``` SCM$pa(vnames, includeself = TRUE) ``` #### Arguments - **`vnames`**: A vector of vertex names - **`includeself`**: Logical, should `vnames` to be included in the results (defaults TRUE) ### Method `ch()` Return the children of a set of vertices. #### Usage ``` SCM$ch(vnames, includeself = TRUE) ``` #### Arguments - **`vnames`**: A vector of vertex names - **`includeself`**: Logical, should `vnames` to be included in the results (defaults TRUE) ### Method `an()` Return the ancestors of a set of vertices. #### Usage ``` SCM$an(vnames, includeself = TRUE) ``` #### Arguments - **`vnames`**: A vector of vertex names - **`includeself`**: Logical, should `vnames` to be included in the results (defaults TRUE) ### Method `de()` Return the descendants of a set of vertices. #### Usage ``` SCM$de(vnames, includeself = TRUE) ``` #### Arguments - **`vnames`**: A vector of vertex names - **`includeself`**: Logical, should `vnames` to be included in the results (defaults TRUE) ### Method `add_variable()` Add a new variable to the SCM object. #### Usage ``` SCM$add_variable( vfnew = NULL, ufnew = NULL, rfnew = NULL, rprefixnew = NULL, starsuffixnew = NULL ) ``` #### Arguments - **`vfnew`**: NULL or a named list containing the functions for the new observed variables. - **`ufnew`**: NULL or a named list containing the functions for the new latent variables. - **`rfnew`**: NULL or a named list containing the functions for the new missingness indicators. - **`rprefixnew`**: NULL or the prefix of the missingness indicators. - **`starsuffixnew`**: NULL orthe suffix for variables with missing data. #### Examples ``` backdoor2 <- backdoor$clone() backdoor2$add_variable( vfnew = list( w = function(uw, x) { return(as.numeric(uw < 0.4 + 0.3*x))}), ufnew = list( uw = function(n) {return(stats::runif(n))}) ) ``` ### Method `remove_variable()` Remove variables from the SCM object. #### Usage ``` SCM$remove_variable(variablenames) ``` #### Arguments - **`variablenames`**: Names of the variables to be removed. #### Examples ``` backdoor2 <- backdoor$clone() backdoor2$remove_variable(c("uy","y")) #' @include R6causal.R R6causal_examples.R NULL ``` ### Method `causal.effect()` Is a causal effect identifiable from observational data? Calls the implementation of ID algorithm from package `causaleffect`. See the documentation of `causal.effect` for the details. #### Usage ``` SCM$causal.effect(y, x, ...) ``` #### Arguments - **`y`**: A vector of character strings specifying target variable(s). - **`x`**: A vector of character strings specifying intervention variable(s). - **`...`**: Other parameters passed to `causal.effect`. #### Returns An expression for the joint distribution of the set of variables (y) given the intervention on the set of variables (x) conditional on (z) if the effect is identifiable. Otherwise an error is thrown describing the graphical structure that witnesses non-identifiability. @examples backdoor$causal.effect(y = "y", x = "x") ### Method `dosearch()` Is a causal effect or other query identifiable from given data sources? Calls `dosearch` from the package `dosearch`. See the documentation of `dosearch` for the details. #### Usage ``` SCM$dosearch( data, query, transportability = NULL, selection_bias = NULL, missing_data = NULL, control = list() ) ``` #### Arguments - **`data`**: Character string specifying the data sources. - **`query`**: Character string specifying the query of interest. - **`transportability`**: Other parameters passed to `dosearch()`. - **`selection_bias`**: Other parameters passed to `dosearch()`. - **`missing_data`**: Other parameters passed to `dosearch()`. - **`control`**: List of control parameters passed to `dosearch()`. #### Returns An object of class `dosearch::dosearch`. #### Examples ``` backdoor$dosearch(data = "p(x,y,z)", query = "p(y|do(x))") ``` ### Method `cfid()` Is a counterfactual query identifiable from given data sources? Calls `identifiable` from the package `cfid`. See the documentation of `cfid` for the details. #### Usage ``` SCM$cfid(gamma, ...) ``` #### Arguments - **`gamma`**: An R object that can be coerced into a `cfid::counterfactual_conjunction` object that represents the counterfactual causal query. - **`...`**: Other arguments passed to `cfid::identifiable`. #### Returns An object of class `cfid::query`. #### Examples ``` backdoor$cfid(gamma = cfid::conj(cfid::cf("Y",0), cfid::cf("X",0, c(Z=1))) ) ``` ### Method `intervene()` Apply an intervention to the SCM object. #### Usage ``` SCM$intervene(target, ifunction) ``` #### Arguments - **`target`**: Name(s) of the variables (in vflist, uflist or rflist) to be intervened. - **`ifunction`**: Either numeric value(s) or new structural function(s) for the target variables. #### Examples ``` # A simple intervention backdoor_x1 <- backdoor$clone() # making a copy backdoor_x1$intervene("x",1) # applying the intervention backdoor_x1$plot() # to see that arrows incoming to x are cut # An intervention that redefines a structural equation backdoor_yz <- backdoor$clone() # making a copy backdoor_yz$intervene("y", function(uy, z) {return(as.numeric(uy < 0.1 + 0.8*z ))}) # making y a function of z only backdoor_yz$plot() # to see that arrow x -> y is cut ``` ### Method `simulate()` Simulate data from the SCM object. Returns simulated data as a data.table and/or creates or updates `simdata` in the SCM object. If `no_missing_data = FALSE`, creates or updates also `simdata_obs` #### Usage ``` SCM$simulate( n = 1, no_missing_data = FALSE, seed = NULL, fixedvars = NULL, store_simdata = TRUE, return_simdata = FALSE ) ``` #### Arguments - **`n`**: Number of observations to be generated. - **`no_missing_data`**: Logical, should the generation of missing data skipped? (defaults FALSE). - **`seed`**: NULL or a number for `set.seed`. - **`fixedvars`**: List of variable names that remain unchanged or a data table/frame that contains the values of the fixed variables. - **`store_simdata`**: Logical, should the simulated data to be stored in the SCM object (defaults TRUE) - **`return_simdata`**: Logical, should the simulated data to be returned as the output (defaults FALSE) #### Examples ``` backdoor$simulate(8, return_simdata = TRUE, store_simdata = FALSE) backdoor$simulate(10) backdoor$simdata ``` ### Method `clone()` The objects of this class are cloneable with this method. #### Usage ``` SCM$clone(deep = FALSE) ``` #### Arguments - **`deep`**: Whether to make a deep clone.

SCM function