% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/DICErClust.R
\name{DICEr}
\alias{DICEr}
\title{DICEr Function for Training and Evaluating a Deep Learning Model}
\usage{
DICEr(args)
}
\arguments{
\item{args}{A list of arguments that configure the model training and evaluation process. The list should include:
\itemize{
\item \code{seed}: An integer value for setting the random seed for reproducibility.
\item \code{input_path}: A character string specifying the path to the input data directory.
\item \code{filename_train}: A character string specifying the filename of the training dataset.
\item \code{filename_test}: A character string specifying the filename of the test dataset.
\item \code{n_input_fea}: An integer specifying the number of input features.
\item \code{n_hidden_fea}: An integer specifying the number of hidden features in the model.
\item \code{lstm_layer}: An integer specifying the number of LSTM layers in the model.
\item \code{lstm_dropout}: A numeric value specifying the dropout rate for the LSTM layers.
\item \code{K_clusters}: An integer specifying the number of clusters for the k-means clustering.
\item \code{n_dummy_demov_fea}: An integer specifying the number of dummy demographic features.
\item \code{cuda}: A logical value indicating whether to use CUDA (GPU acceleration) for model training.
\item \code{lr}: A numeric value specifying the learning rate for the optimizer.
\item \code{init_AE_epoch}: An integer specifying the number of epochs for training the autoencoder.
\item \code{iter}: An integer specifying the number of iterations for the main optimization process.
\item \code{epoch_in_iter}: An integer specifying the number of epochs in each iteration of the main optimization process.
\item \code{lambda_AE}: A numeric value specifying the weight of the autoencoder loss in the overall loss function.
\item \code{lambda_classifier}: A numeric value specifying the weight of the classification loss in the overall loss function.
\item \code{lambda_outcome}: A numeric value specifying the weight of the outcome prediction loss in the overall loss function.
\item \code{lambda_p_value}: A numeric value specifying the weight of the p-value loss in the overall loss function.
}}
}
\value{
Called for its side effects: trains the model and saves results to
disk. Returns \code{NULL} invisibly.
}
\description{
This function orchestrates the training and evaluation of a deep learning model, specifically for autoencoder-based representation learning followed by clustering and classification. It handles data loading, model training, testing, and saving the best model based on performance criteria.
}
\details{
The \code{DICEr} function executes the following steps:
\enumerate{
\item Sets the random seed for reproducibility.
\item Loads and preprocesses the training and test datasets.
\item Initializes the model, optimizer, and loss functions.
\item Trains an autoencoder for representation learning, saving the model and plotting loss curves.
\item Performs k-means clustering on the learned representations and reassigns cluster labels based on outcome ratios.
\item Iteratively trains the model for clustering, classification, and outcome prediction, optimizing the combined loss function.
\item Saves the best model based on the outcome prediction likelihood and checks for p-value significance.
\item Outputs and saves relevant training metrics, including loss curves and model checkpoints.
}
}
\examples{
\donttest{
## Prepare data in DICErClust format (length-3 RDS list)
data_dir <- tempdir()
n <- 100L; p <- 4L; q <- 2L
set.seed(1)
saveRDS(list(matrix(runif(n * p), n, p),                       # data_x
             matrix(as.double(rbinom(n * q, 1, 0.5)), n, q),  # data_v (float)
             rbinom(n, 1, 0.3)),                               # data_y
        file.path(data_dir, "train.rds"))
saveRDS(list(matrix(runif(30L * p), 30L, p),
             matrix(as.double(rbinom(30L * q, 1, 0.5)), 30L, q),
             rbinom(30L, 1, 0.3)),
        file.path(data_dir, "test.rds"))

args <- list(
  seed = 1L, input_path = paste0(data_dir, "/"),
  filename_train = "train.rds", filename_test = "test.rds",
  n_input_fea = p, n_hidden_fea = 2L,
  lstm_layer = 1L, lstm_dropout = 0.0, K_clusters = 2L,
  n_dummy_demov_fea = q, cuda = FALSE, lr = 1e-4,
  init_AE_epoch = 2L, iter = 5L, epoch_in_iter = 1L,
  lambda_AE = 1.0, lambda_classifier = 1.0,
  lambda_outcome = 1.0, lambda_p_value = 1.0
)
old_wd <- setwd(tempdir())
DICEr(args)
setwd(old_wd)
}
}
