Type: Package
Title: Primary and Secondary Analyses for Micro-Randomized Trials
Version: 0.1.2
Description: Estimates marginal causal excursion effects and moderated causal excursion effects for micro-randomized trial (MRT). Applicable to MRT with binary treatment options and continuous or binary outcomes. The method for MRT with continuous outcomes is the weighted centered least squares (WCLS) by Boruvka et al. (2018) <doi:10.1080/01621459.2017.1305274>. The method for MRT with binary outcomes is the estimator for marginal excursion effect (EMEE) by Qian et al. (2021) <doi:10.1093/biomet/asaa070>.
License: GPL-3
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.2.3
Imports: rootSolve, stats, geepack, sandwich
Depends: R (≥ 4.2)
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2023-07-01 20:59:57 UTC; tqian
Author: Tianchen Qian ORCID iD [aut, cre], Shaolin Xiang [aut], Zhaoxi Cheng [aut], Audrey Boruvka [ctb]
Maintainer: Tianchen Qian <t.qian@uci.edu>
Repository: CRAN
Date/Publication: 2023-07-01 21:20:02 UTC

A synthetic data set of an MRT with binary outcome

Description

A synthetic data set of an MRT with binary outcome

Usage

data_binary

Format

a data frame with 3000 observations and 10 variables

This random sample uses the baseline model: log E(Y_t+1 | A_t = 0, I_t = 1) = alpha_0 + alpha_1 * time / total_T + alpha_2 * 1(time > total_T/2), the treatment effect model: log relative risk = beta_0 + beta_1 * time / total_T, the probability of treatment assignment p_t: 0.3, 0.5, 0.7 with repetition, and exogenous probability of availability: 0.8 at all time points.

userid

individual id number

time

decision point index

time_var1

time-varying covariate 1, the "standardized time in study", defined as the current decision point index divided by the total number of decision points

time_var2

time-varying covariate 2, indicator of "the second half of the study", defined as whether the current decision point index is greater than the total number of decision points divided by 2.

Y

binary proximal outcome

A

treatment assignment, i.e., whether the intervention is randomized to be delivered (=1) or not (=0) at the current decision point

rand_prob

the randomization probability P(A=1) for the current decision point

avail

whether the individual is available (=1) or not (=0) at the current decision point

A synthetic data set that mimics the HeartSteps V1 data structure to illustrate the use of [wcls()] function for continuous outcomes

Description

A synthetic data set that mimics the HeartSteps V1 data structure to illustrate the use of [wcls()] function for continuous outcomes

Usage

data_mimicHeartSteps

Format

a data frame with 7770 observations and 9 variables

userid

individual id number

time

decision point index

day_in_study

day in the study

logstep_30min

proximal outcome: the step count in the 30 minutes following the current decision point (log-transformed)

logstep_30min_lag1

proximal outcome at the previous decision point (lag-1 outcome): the step count in the 30 minutes following the previous decision point (log-transformed)

logstep_pre30min

the step count in the 30 minutes prior to the current decision point (log-transformed); used as a control variable

is_at_home_or_work

whether the individual is at home or work (=1) or at other locations (=0) at the current decision point

intervention

whether the intervention is randomized to be delivered (=1) or not (=0) at the current decision point

rand_prob

the randomization probability P(A=1) for the current decision point

availability

whether the individual is available (=1) or not (=0) at the current decision point

Estimates the causal excursion effect for binary outcome MRT

Description

Returns the estimated causal excursion effect (on log relative risk scale) and the estimated standard error. Small sample correction using the "Hat" matrix in the variance estimate is implemented.

Usage

emee(
  data,
  id,
  outcome,
  treatment,
  rand_prob,
  moderator_formula,
  control_formula,
  availability = NULL,
  numerator_prob = NULL,
  start = NULL,
  verbose = TRUE
)

Arguments

data

A data set in long format.

id

The subject id variable.

outcome

The outcome variable.

treatment

The binary treatment assignment variable.

rand_prob

The randomization probability variable.

moderator_formula

A formula for the moderator variables. This should start with ~ followed by the moderator variables. When set to ~ 1, a fully marginal excursion effect (no moderators) is estimated.

control_formula

A formula for the control variables. This should start with ~ followed by the control variables. When set to ~ 1, only an intercept is included as the control variable.

availability

The availability variable. Use the default value (NULL) if your MRT doesn't have availability considerations.

numerator_prob

Either a number between 0 and 1, or a variable name for a column in data. If you are not sure what this is, use the default value (NULL).

start

A vector of the initial value of the estimators used in the numerical solver. If using default value (NULL), a vector of 0 will be used internally. If specifying a non-default value, this needs to be a numeric vector of length (number of moderator variables including the intercept) + (number of control variables including the intercept).

verbose

If default ('TRUE'), additional messages will be printed during data preprocessing.

Value

An object of type "emee_fit"

Examples


## estimating the fully marginal excursion effect by setting
## moderator_formula = ~ 1
emee(
    data = data_binary,
    id = "userid",
    outcome = "Y",
    treatment = "A",
    rand_prob = "rand_prob",
    moderator_formula = ~1,
    control_formula = ~ time_var1 + time_var2,
    availability = "avail"
)

## estimating the causal excursion effect moderated by time_var1
## by setting moderator_formula = ~ time_var1
emee(
    data = data_binary,
    id = "userid",
    outcome = "Y",
    treatment = "A",
    rand_prob = "rand_prob",
    moderator_formula = ~time_var1,
    control_formula = ~ time_var1 + time_var2,
    availability = "avail"
)

Estimates the causal excursion effect for binary outcome MRT

Description

Returns the estimated causal excursion effect (on log relative risk scale) and the estimated standard error. Small sample correction using the "Hat" matrix in the variance estimate is implemented. This is a slightly altered version of emee(), where the treatment assignment indicator is also centered in the residual term. It would have similar (but not exactly the same) numerical output as emee(). This is the estimator based on which the sample size calculator for binary outcome MRT is developed. (See R package MRTSampleSizeBinary.)

Usage

emee2(
  data,
  id,
  outcome,
  treatment,
  rand_prob,
  moderator_formula,
  control_formula,
  availability = NULL,
  numerator_prob = NULL,
  start = NULL,
  verbose = TRUE
)

Arguments

data

A data set in long format.

id

The subject id variable.

outcome

The outcome variable.

treatment

The binary treatment assignment variable.

rand_prob

The randomization probability variable.

moderator_formula

A formula for the moderator variables. This should start with ~ followed by the moderator variables. When set to ~ 1, a fully marginal excursion effect (no moderators) is estimated.

control_formula

A formula for the control variables. This should start with ~ followed by the control variables. When set to ~ 1, only an intercept is included as the control variable.

availability

The availability variable. Use the default value (NULL) if your MRT doesn't have availability considerations.

numerator_prob

Either a number between 0 and 1, or a variable name for a column in data. If you are not sure what this is, use the default value (NULL).

start

A vector of the initial value of the estimators used in the numerical solver. If using default value (NULL), a vector of 0 will be used internally. If specifying a non-default value, this needs to be a numeric vector of length (number of moderator variables including the intercept) + (number of control variables including the intercept).

verbose

If default ('TRUE'), additional messages will be printed during data preprocessing.

Value

An object of type "emee_fit"

Examples

## estimating the fully marginal excursion effect by setting
## moderator_formula = ~ 1
emee2(
    data = data_binary,
    id = "userid",
    outcome = "Y",
    treatment = "A",
    rand_prob = "rand_prob",
    moderator_formula = ~1,
    control_formula = ~ time_var1 + time_var2,
    availability = "avail"
)

## estimating the causal excursion effect moderated by time_var1
## by setting moderator_formula = ~ time_var1
emee2(
    data = data_binary,
    id = "userid",
    outcome = "Y",
    treatment = "A",
    rand_prob = "rand_prob",
    moderator_formula = ~time_var1,
    control_formula = ~ time_var1 + time_var2,
    availability = "avail"
)

Summarize Causal Excursion Effect Fits for MRT with Binary Outcomes

Description

summary method for class "emee_fit".

Usage

## S3 method for class 'emee_fit'
summary(
  object,
  lincomb = NULL,
  conf_level = 0.95,
  show_control_fit = FALSE,
  ...
)

Arguments

object

An object of class "emee_fit".

lincomb

A vector of length p (p is the number of moderators including intercept) or a matrix with p columns. When not set to 'NULL', the summary will include the specified linear combinations of the causal excursion effect coefficients and the corresponding confidence interval, standard error, and p-value.

conf_level

A numeric value indicating the confidence level for confidence intervals. Default to 0.95.

show_control_fit

A logical value of whether the fitted coefficients for the control variables will be printed in the summary. Default to FALSE. (Interpreting the fitted coefficients for control variables is not recommended.)

...

Further arguments passed to or from other methods.

Value

the original function call and the estimated causal excursion effect coefficients, confidence interval with conf_level, standard error, t-statistic value, degrees of freedom, and p-value.

Examples

fit <- emee(
    data = data_binary,
    id = "userid",
    outcome = "Y",
    treatment = "A",
    rand_prob = "rand_prob",
    moderator_formula = ~time_var1,
    control_formula = ~ time_var1 + time_var2,
    availability = "avail",
    numerator_prob = 0.5,
    start = NULL
)
summary(fit)

Summarize Causal Excursion Effect Fits for MRT with Continuous Outcomes

Description

summary method for class "wcls_fit".

Usage

## S3 method for class 'wcls_fit'
summary(
  object,
  lincomb = NULL,
  conf_level = 0.95,
  show_control_fit = FALSE,
  ...
)

Arguments

object

An object of class "wcls_fit".

lincomb

A vector of length p (p is the number of moderators including intercept) or a matrix with p columns. When not set to 'NULL', the summary will include the specified linear combinations of the causal excursion effect coefficients and the corresponding confidence interval, standard error, and p-value.

conf_level

A numeric value indicating the confidence level for confidence intervals. Default to 0.95.

show_control_fit

A logical value of whether the fitted coefficients for the control variables will be printed in the summary. Default to FALSE. (Interpreting the fitted coefficients for control variables is not recommended.)

...

Further arguments passed to or from other methods.

Value

the original function call and the estimated causal excursion effect coefficients, 95 value or Wald-statistic value (depending on whether sample size is < 50), degrees of freedom, and p-value.

Examples

fit <- wcls(
    data = data_mimicHeartSteps,
    id = "userid",
    outcome = "logstep_30min",
    treatment = "intervention",
    rand_prob = 0.6,
    moderator_formula = ~1,
    control_formula = ~logstep_pre30min,
    availability = "avail",
    numerator_prob = 0.6
)
summary(fit)

Estimates the causal excursion effect for continuous outcome MRT

Description

Returns the estimated causal excursion effect (on additive scale) and the estimated standard error. Small sample correction using the "Hat" matrix in the variance estimate is implemented.

Usage

wcls(
  data,
  id,
  outcome,
  treatment,
  rand_prob,
  moderator_formula,
  control_formula,
  availability = NULL,
  numerator_prob = NULL,
  verbose = TRUE
)

Arguments

data

A data set in long format.

id

The subject id variable.

outcome

The outcome variable.

treatment

The binary treatment assignment variable.

rand_prob

The randomization probability variable.

moderator_formula

A formula for the moderator variables. This should start with ~ followed by the moderator variables. When set to ~ 1, a fully marginal excursion effect (no moderators) is estimated.

control_formula

A formula for the control variables. This should start with ~ followed by the control variables. When set to ~ 1, only an intercept is included as the control variable.

availability

The availability variable. Use the default value (NULL) if your MRT doesn't have availability considerations.

numerator_prob

Either a number between 0 and 1, or a variable name for a column in data. If you are not sure what this is, use the default value (NULL).

verbose

If default ('TRUE'), additional messages will be printed during data preprocessing.

Value

An object of type "wcls_fit"

Examples

wcls(
    data = data_mimicHeartSteps,
    id = "userid",
    outcome = "logstep_30min",
    treatment = "intervention",
    rand_prob = 0.6,
    moderator_formula = ~1,
    control_formula = ~logstep_pre30min,
    availability = "avail",
    numerator_prob = 0.6
)