R: R6 Class for structural causal models

SCM {R6causal}

R Documentation

R6 Class for structural causal models

Description

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.

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

SCM$new()
SCM$print()
SCM$plot()
SCM$tikz()
SCM$pa()
SCM$ch()
SCM$an()
SCM$de()
SCM$add_variable()
SCM$remove_variable()
SCM$causal.effect()
SCM$dosearch()
SCM$cfid()
SCM$intervene()
SCM$simulate()
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.

Examples


## ------------------------------------------------
## 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

[Package R6causal version 0.8.3 Index]

R6 Class for structural causal models

Description

Details

Active bindings

Methods

Public methods

Method new()

Usage

Arguments

Returns

Examples

Method print()

Usage

Examples

Method plot()

Usage

Arguments

Examples

Method tikz()

Usage

Arguments

Method pa()

Usage

Arguments

Method ch()

Usage

Arguments

Method an()

Usage

Arguments

Method de()

Usage

Arguments

Method add_variable()

Usage

Arguments

Examples

Method remove_variable()

Usage

Arguments

Examples

Method causal.effect()

Usage

Arguments

Returns

Method dosearch()

Usage

Arguments

Returns

Examples

Method cfid()

Usage

Arguments

Returns

Examples

Method intervene()

Usage

Arguments

Examples

Method simulate()

Usage

Arguments

Examples

Method clone()

Usage

Arguments

Examples

Method `new()`

Method `print()`

Method `plot()`

Method `tikz()`

Method `pa()`

Method `ch()`

Method `an()`

Method `de()`

Method `add_variable()`

Method `remove_variable()`

Method `causal.effect()`

Method `dosearch()`

Method `cfid()`

Method `intervene()`

Method `simulate()`

Method `clone()`