Declare a dynamic missingness graph (dm-graph)

A dm-graph is a directed acyclic graph over the unrolled within-person process of an experience-sampling study: person-level latent nodes (eta, the person's typical state; zeta, a person-level response propensity), momentary states X_t, response indicators R_t, and optional context (C_t), sensor (S_t) and probe (Z_t) nodes. The structural edges X_{t-1} -> X_t and eta -> X_t are always present. The missingness mechanism is declared as a set of motifs, each of which adds edges into R_t.

Usage

dm_graph(
  motifs = "M0",
  context = c("none", "latent", "observed"),
  context_persistent = FALSE,
  sensor = FALSE,
  probe = FALSE,
  window = 5L
)

Arguments

motifs

Character vector of motif codes. "M0" (no edges into R), "M1" (X_{t-1} -> R_t, lagged-state dependence), "M2" (X_t -> R_t, self-censoring), "M3" (R_{t-1} -> R_t, burden or fatigue), "M4" (zeta -> R_t with zeta associated with eta, person propensity), "M5" (C_t -> X_t and C_t -> R_t, context confounding), "M6" (R_{t-1} -> X_t, reactivity). Motifs may be combined.

context

One of "none", "latent", "observed". Relevant for "M5"; "observed" means the context variable is recorded at every prompt (for example by a phone sensor).

context_persistent

Logical; if TRUE the context process has edges C_{t-1} -> C_t.

sensor

Logical; add an always-observed passive-sensor node S_t with X_t -> S_t.

probe

Logical; add a randomized probe indicator Z_t with Z_t -> R_t (a probe forces a response).

window

Integer number of prompts in the unrolled graph (at least 4).

Value

An object of class "dm_graph": a list with elements

nodes (character vector of node names), edges (two-column character matrix from, to), motifs, context,

context_persistent, sensor, probe, window,

latent (names of the latent nodes) and observed_always

(names of the nodes observed at every prompt). It has print and

plot methods.

See also

recoverability, dsep, plot.dm_graph, simulate_ema (which generates data under the same motifs)

Examples

g <- dm_graph(c("M1", "M4"))
g
#> Dynamic missingness graph (window of 5 prompts)
#>   motifs: M1 + M4 
#>   context: none  
#>   sensor: FALSE   probe: FALSE 
#>   nodes: 13   edges: 20 
recoverability(g)
#> Recoverability report for motifs: M1 + M4 
#> 
#> * transition kernel (Phi, Psi, contemporaneous network)
#>     [recoverable] complete adjacent pairs, within-person (person intercepts)
#>     condition: R_t _||_ X_t | {X_{t-1},eta,zeta} and R_{t-1} _||_ X_t | {X_{t-1},eta,zeta, R_t}
#> * person mean via observed within-person mean
#>     [NOT recoverable] biased
#>     condition: R_t _||_ X_t | {eta,zeta}
#> * person mean via recovered dynamics
#>     [recoverable] mu_i = (I - Phi)^{-1} c_i from the recovered kernel
#>     condition: transition kernel recoverable
#> * between-person law (mu, Sigma_mu), person-weighted
#>     [recoverable] one recovered mean per person (dynamics-recovered means), persons weighted equally; positivity assumed
#>     condition: a person-mean estimator is available and P(R_t = 1 | eta) > 0
#> * between-person law, prompt-weighted (pooling answered prompts)
#>     [NOT recoverable] biased: response rate depends on the person's states
#>     condition: R_t _||_ X_t | {empty set}
#> * silence test (coefficient of R_t in X_{t+1} ~ X_{t-1} + R_t, within person)
#>     null expected (test valid as a test of the recoverable class)
#>     condition: R_t _||_ X_{t+1} | {X_{t-1},eta,zeta,R_{t-1},R_{t+1}}
g2 <- dm_graph(c("M2", "M3"), sensor = TRUE)
recoverability(g2)
#> Recoverability report for motifs: M2 + M3 
#> 
#> * transition kernel (Phi, Psi, contemporaneous network)
#>     [NOT recoverable] sensitivity analysis (tilt profile) or a calibration design is required
#>     condition: R_t and X_t are d-connected given {X_{t-1},eta}
#> * person mean via observed within-person mean
#>     [NOT recoverable] biased
#>     condition: R_t _||_ X_t | {eta}
#> * person mean via recovered dynamics
#>     [NOT recoverable] not available
#>     condition: transition kernel recoverable
#> * between-person law (mu, Sigma_mu), person-weighted
#>     [NOT recoverable] not recoverable
#>     condition: a person-mean estimator is available and P(R_t = 1 | eta) > 0
#> * between-person law, prompt-weighted (pooling answered prompts)
#>     [NOT recoverable] biased: response rate depends on the person's states
#>     condition: R_t _||_ X_t | {empty set}
#> * silence test (coefficient of R_t in X_{t+1} ~ X_{t-1} + R_t, within person)
#>     non-null expected, but the burden collider at R_{t+1} works against the state-dependent signal: low power; prefer the sensor-gap test
#>     condition: R_t _||_ X_{t+1} | {X_{t-1},eta,R_{t-1},R_{t+1}}
#> * sensor-gap test (coefficient of R_t in S_t ~ X_{t-1} + R_t, within person)
#>     non-null expected: delta can be calibrated from the sensor gap
#>     condition: R_t _||_ S_t | {X_{t-1},eta,R_{t-1}}
# an observed context adds M5 and observed context nodes
g5 <- dm_graph("M1", context = "observed", context_persistent = TRUE)
#> 'context' given: motif M5 added to the declaration
g5$edges[g5$edges[, "from"] == "C2", ]
#>      from to  
#> [1,] "C2" "X2"
#> [2,] "C2" "R2"
#> [3,] "C2" "C3"