% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/main.R
\name{causal_inference_model}
\alias{causal_inference_model}
\title{Bayesian Mixed Treatment-State Causal Model (MTSCM)}
\usage{
causal_inference_model(
  df,
  y_name,
  continuous_name,
  categorical_name,
  treatment_name,
  previous_status_name,
  subjectID_name,
  num_warmup,
  num_samples,
  model_type,
  thin = 1,
  L = 50,
  alpha = 0.95,
  beta = 1.25,
  leaf_model_scale = 0.3/50,
  cutpoint_grid_size = 100,
  max_depth = 10,
  credible_interval_level = 0.95,
  print_progress = TRUE,
  random_seed = 100,
  calculate_causal_estimand = FALSE,
  previous_status_grid_size = 100
)
}
\arguments{
\item{df}{the input dataframe. The datatype is \code{data.frame}.}

\item{y_name}{the name of the response variable. The datatype is \code{character}.}

\item{continuous_name}{the name of continuous predictors. The datatype is \code{character}.}

\item{categorical_name}{the name of categorical predictors. The datatype is \code{character}.}

\item{treatment_name}{the name of the treatment predictor. The datatype is \code{character}.}

\item{previous_status_name}{the name of variable that represents previous status of a subject. The datatype is \code{character}.}

\item{subjectID_name}{the name of variable that represents subjectID. The datatype is \code{character}.}

\item{num_warmup}{the number of warmup iterations. The datatype is \code{integer}.}

\item{num_samples}{the number of post-warmup iterations. The datatype is \code{integer}.}

\item{model_type}{the type of causal inference models. It must be one of \code{"Tobit-XBART"}, \code{"Tobit-SBART"}, \code{"Tobit-LH"}, \code{"N-XBART"}, \code{"N-SBART"}, or \code{"N-LH"}.}

\item{thin}{the period between saved samples. This should typically be left at its default (no thinning) unless memory is a problem. The datatype is \code{integer}.}

\item{L}{the number of trees. The datatype is \code{integer}.}

\item{alpha}{the tree prior parameters. \code{alpha*(1+depth)^(-beta)} represents the prior probability of splitting at one of the cutpoints. Check equation (4) and related descriptions from "Stochastic Tree Ensembles for Regularized Nonlinear Regression" for more details. The datatype is \code{double}.}

\item{beta}{the tree prior parameters. \code{alpha*(1+depth)^(-beta)} represents the prior probability of splitting at one of the cutpoints. Check equation (4) and related descriptions from "Stochastic Tree Ensembles for Regularized Nonlinear Regression" for more details. The datatype is \code{double}.}

\item{leaf_model_scale}{the prior variance on leaf mean equals to \code{leaf_model_scale/L}. The datatype is \code{double}.}

\item{cutpoint_grid_size}{the number of cutoff points in XBART. The datatype is \code{integer}.}

\item{max_depth}{the maximum depth of tree allowed. The datatype is \code{integer}.}

\item{credible_interval_level}{the nominal level of credible intervals of causal estimand. The datatype is \code{double}.}

\item{print_progress}{whether print progress bar or not. The datatype is \code{boolean}.}

\item{random_seed}{the random seed of the MCMC sampler. The datatype is \code{integer}.}

\item{calculate_causal_estimand}{calculate causal estimand or not. The datatype is \code{boolean}.}

\item{previous_status_grid_size}{the number of cutoff points of previous status for causal estimands. The datatype is \code{integer}.}
}
\value{
a list containing posterior inference of causal estimands.
}
\description{
Fits a Bayesian Mixed Treatment-State Causal Model (MTSCM) tailored for longitudinal settings with irregular visits.
This model is specifically designed for bounded continuous outcomes with mass at both boundaries, such as the proportion of periodontal pockets exceeding 3 mm.
}
\details{
\strong{Outcome Model Description:}
The MTSCM utilizes a double-censored Tobit regression structure with subject-level random effects to capture within-subject correlation.
It uses tree-based ensemble priors (encompassing standard BART and Soft BART) to flexibly model complex, non-linear interactions without parametric restrictions.
Using a latent Gaussian variable \eqn{Z_{i,j+1}}, the data generating process for the outcome \eqn{Y_{i,j+1}} is formulated as:
\deqn{Z_{i,j+1} = f(A_{ij}, Y_{ij}, \mathbf{X}_{ij}) + U_i + \epsilon_{ij}, \quad \epsilon_{ij} \sim N(0, \sigma^2).}
\deqn{Y_{i,j+1} = \begin{cases} 0 & \text{if } Z_{i,j+1} \leq 0, \\ Z_{i,j+1} & \text{if } 0 < Z_{i,j+1} < 1, \\ 1 & \text{if } Z_{i,j+1} \geq 1. \end{cases}}

\strong{Causal Estimand Description:}
The framework estimates causal effects using the G-computation formula to marginalize conditional expectations over the covariate distribution.

\strong{Mixed Average Potential Outcome (MAPO):}
The MAPO represents the expected potential outcome across the population for a given treatment \eqn{a} and previous continuous disease state \eqn{y^{\star}}.
It is defined mathematically as:
\deqn{\theta(a,y^{\star}) = \frac{\sum_{i=1}^{N} \sum_{j=0}^{n_i - 1} \mathbb{E}(Y_{i,j+1} \mid A_{ij} = a, Y_{ij} = y^{\star}, \mathbf{X}_{ij} = \mathbf{x}_{ij})}{\sum_{i=1}^{N} n_{i}}.}

\strong{Mixed Probability of Disease Resolution (MPDR):}
The MPDR estimates the population-level probability of achieving a zero disease burden under a specific treatment \eqn{a} and previous disease state \eqn{y^{\star}}.
It is computed as:
\deqn{\theta^{(0)}(a,y^{\star}) = \frac{\sum_{i=1}^{N} \sum_{j=0}^{n_i - 1} \mathbb{P}(Y_{i,j+1} = 0 \mid A_{ij} = a, Y_{ij} = y^{\star}, \mathbf{X}_{ij} = \mathbf{x}_{ij})}{\sum_{i=1}^{N} n_{i}}.}
}
\examples{
df1 <- data_generation(random_seed = 100,
                       N = 100,
                       sigma = 0.2,
                       sigma_u = 0.1)

inference_output <- causal_inference_model(df = df1,
                                           y_name = "current_value",
                                           continuous_name = c("previous_value",
                                                               "confounder"),
                                           categorical_name = c("treatment"),
                                           treatment_name = "treatment",
                                           previous_status_name = "previous_value",
                                           subjectID_name = "subjectID",
                                           num_warmup = 2,
                                           num_samples = 2,
                                           model_type = "Tobit-XBART",
                                           thin = 1,
                                           L = 5,
                                           alpha = 0.95,
                                           beta = 1.25,
                                           leaf_model_scale = 0.3/5,
                                           cutpoint_grid_size = 100,
                                           max_depth = 10,
                                           credible_interval_level = 0.95,
                                           random_seed = 100,
                                           calculate_causal_estimand = FALSE,
                                           previous_status_grid_size = 2)
}
