SCM: R6 Class for structural causal models

In R6causal: R6 Class for Structural Causal Models

R6 Class for structural causal models

Description

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.

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

R6causal documentation built on May 29, 2024, 4:46 a.m.