% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sg-vpop-est.R
\name{sg_vpop_est}
\alias{sg_vpop_est}
\title{Perform generation of synthetic datasets for an empirical distribution}
\usage{
sg_vpop_est(
  data_i,
  nobj = NA,
  id_col = NULL,
  minnumlev = 3,
  npop = 1,
  excl_col = NULL,
  seed = NA,
  seed_umap = 123,
  palette = NULL,
  diag_plots = FALSE,
  remove_duplicates = TRUE,
  noise_level = 0.1,
  nds = 1,
  tg_corrdif = 0.1
)
}
\arguments{
\item{data_i}{data frame. Input data frame containing the original dataset to be synthesized (required)}

\item{nobj}{integer. Specify the exact number of rows to generate in the synthetic dataset. When provided, overrides \code{npop} (optional, default: \code{NA})}

\item{id_col}{Character string. Specify the name of the identifier column
to exclude from synthesis. Default: \code{NULL}.}

\item{minnumlev}{integer. Threshold; numeric variables with <= \code{minnumlev} unique values are converted to factors (optional, default: \code{3})}

\item{npop}{Integer. Number of population replicates. Default is 1.}

\item{excl_col}{Character vector. Contains column names to exclude from synthesis. Default: \code{NULL}}

\item{seed}{integer. Random seed for synthetic data generation. If provided (not \code{NA}), generates a single dataset with this seed (fixed seed mode). If \code{NA}, uses search mode to find \code{nds} datasets meeting correlation threshold (optional, default: \code{NA})}

\item{seed_umap}{integer. Random seed for UMAP algorithm reproducibility (optional, default: \code{123})}

\item{palette}{character vector. Contains color codes (hex format) for custom plot color schemes. If provided, should contain at least 2 colors. Used for histograms, bar plots, and UMAP visualizations (optional, default: \code{c("#3a6eba", "#efdd3c", "#1a1866", "#f2b93b")})}

\item{diag_plots}{logical flag. If \code{TRUE}, generates diagnostic plots and UMAP visualizations (optional, default: \code{TRUE})}

\item{remove_duplicates}{logical flag. If \code{TRUE}, automatically removes exact duplicates between original and synthetic data by adding controlled noise (optional, default: \code{TRUE})}

\item{noise_level}{numeric. Proportion of standard deviation to use when adding noise to continuous variables for duplicate removal. E.g., 0.10 means 10\% of SD (optional, default: \code{0.10})}

\item{nds}{integer. Number of synthetic datasets to generate in search mode. Ignored in fixed seed mode (optional, default: \code{1})}

\item{tg_corrdif}{numeric. Target maximum absolute correlation difference threshold for dataset selection in search mode. Ignored in fixed seed mode (optional, default: \code{0.1})}
}
\value{
A list of lists, where each element contains results for one generated dataset:
\itemize{
\item \code{datagen} - Synthetic dataset returned by \code{synthpop::syn()} (data.frame)
\item \code{seed} - Random seed used to generate this dataset (integer or NA)
\item \code{exact_dupl_check} - Logical indicating if exact duplicates exist between original and synthetic data
\item \code{dplot_umap} - ggplot object with combined UMAP visualization comparing original and synthetic data (or \code{NULL} if diag_plots=FALSE)
\item \code{ks_test} - Tibble with Kolmogorov-Smirnov p-values and statuses for continuous variables (or \code{NULL} if no continuous variables)
\item \code{jsd_res} - Weighted mean Jensen-Shannon divergence (JSD) value for categorical variables (numeric or \code{NULL} if no categorical variables)
\item \code{corr_diff_mean} - Mean absolute difference between original and synthetic correlation matrices (numeric or \code{NULL} if no continuous variables)
\item \code{corr_diff_max} - Maximum absolute difference between original and synthetic correlation matrices (numeric or \code{NULL} if no continuous variables)
\item \code{dplot_corr_diff} - ggplot heatmap object showing correlation difference matrix (Synthetic - Original) (or \code{NULL} if diag_plots=FALSE or no continuous variables)
\item \code{dplot_cont} - List of ggplot histograms for continuous variables (or \code{NULL} if diag_plots=FALSE or no continuous variables)
\item \code{dplot_cat} - List of ggplot barplots for categorical variables (or \code{NULL} if diag_plots=FALSE or no categorical variables)
}
}
\description{
The function operates in two modes:
\itemize{
\item \strong{Fixed seed mode} (when \code{seed} is specified): Generates a single dataset using the provided seed
\item \strong{Search mode} (when \code{seed = NA}): Iteratively searches for \code{nds} datasets that meet the correlation difference threshold
}
}
\examples{
\donttest{
library(dplyr)

# Generate example dataset
data <- data.frame(
  id = 1:150,
  ALB = rnorm(150, mean = 3.5, sd = 0.5),
  ALT = rnorm(150, mean = 50, sd = 20),
  SEX = factor(sample(c("M", "F"), 150, replace = TRUE)),
  RACE = factor(sample(c("White", "Black", "Asian", "Other"), 150, replace = TRUE))
)

# EXAMPLE 1: Fixed seed mode - generate single dataset with specified seed
output_fixed <- sg_vpop_est(data_i = data,
                            id_col = "id",
                            seed = 123,        # Fixed seed mode
                            seed_umap = 40,
                            diag_plots = TRUE)

# Access the dataset and its diagnostics
print(head(output_fixed[[1]]$datagen, 10))
print(output_fixed[[1]]$ks_test)
print(output_fixed[[1]]$seed)           # Will be 123
print(output_fixed[[1]]$corr_diff_max)
print(output_fixed[[1]]$dplot_umap)

# EXAMPLE 2: Search mode - generate 3 datasets meeting correlation threshold
output_search <- sg_vpop_est(data_i = data,
                             id_col = "id",
                             seed = NA,        # Search mode (default)
                             seed_umap = 40,
                             diag_plots = TRUE,
                             nds = 3,          # Generate 3 datasets
                             tg_corrdif = 0.1) # Target correlation difference

# Compare metrics across all datasets
sapply(output_search, function(x) x$corr_diff_max)
sapply(output_search, function(x) x$jsd_res)
sapply(output_search, function(x) x$seed)  # Different seeds for each dataset

}
}
