Load and standardise a real multi-omic dataset for GAN training

Accepts the exposure, outcome, mediator (optional), and negative-control panels as features x samples matrices together with a sample-level covariate frame, and returns the tidy structures used by train_gan_on_real_data() and the calibration step of run_single_iteration().

Usage

load_real_input_data(
  X_matrix = NULL,
  Y_matrix = NULL,
  M_matrix = NULL,
  W_matrix = NULL,
  covariates_df = NULL,
  example = FALSE,
  marginal_method = "auto",
  residualize_on = c("XC", "XCW"),
  Z_matrix = NULL
)

Arguments

X_matrix

Exposure panel, features x samples (e.g. an exposure or molecular score across probes). Column means become the per-sample exposure.

Y_matrix

Outcome, either a scalar vector of length n_samples (e.g. a clinical or molecular trait) or a features x samples matrix. When a vector, it defines n_samples; when a matrix, n_samples and n_features.

M_matrix

Mediator panel, features x samples (e.g. gene or transcript expression). When supplied, its per-sample summary is added to the GAN training frame (so the generator learns the mediator's marginal distribution) and its residual correlation matrix is computed and stored.

W_matrix

Optional negative-control panel, features x samples. When supplied the controls are treated as user-provided real structure; when NULL they are generated by a negative-control model at simulation time.

covariates_df

Optional data frame of sample-level covariates. A sample_id column is used to align samples if present; recognised columns sex, GA, mother_ethnicity are encoded, and any other numeric columns are z-scored and kept. Names colliding with estimator-reserved tokens are renamed with a cov_ prefix.

example

Force return of the built-in example dataset. Default FALSE (auto-enabled when no matrices are given).

marginal_method

Marginal fitting method for the feature-level copula texture model (mediator panel): "auto" (default, uses parametric if KS test passes at p > 0.05, otherwise empirical), "empirical" (always empirical CDF), or "parametric" (always best parametric fit by AIC). See train_feature_texture().

residualize_on

Character: "XC" (default) residualizes the Y/W correlation on exposure + covariates only; "XCW" additionally residualizes on the W bridge proxy (PC1 of W), reducing U-signature double-counting. Recommended only when the completeness-capture test reports "strong".

Z_matrix

Defunct. Renamed to X_matrix; passing a value errors with a message pointing to X_matrix. Retained in the signature only to catch and redirect old calls.

Value

A list with gan_training_data (sample x variable data frame with exposure level, outcome level, mediator level, and encoded covariates), original_matrices (X, Y, M, W), covariates (encoded frame), feature_correlations (list with Y, W residual correlation matrices, or NULL for absent panels), feature_texture (an iconic_feature_texture object for the mediator panel, or NULL when no M matrix is supplied), sample_names, feature_names, n_samples, n_features.

Details

In addition to the sample-level training frame (one row per sample with exposure level, outcome level, and encoded covariates), the function computes feature-level residual correlation matrices for each available panel (Y, M, W). These capture the cross-feature correlation structure that remains after removing the sample-level signal, so the simulation can inject realistic correlated noise into the mediator and negative- control panels.

If no matrices are supplied a small built-in example dataset is returned, so the pipeline can be exercised end-to-end without real data.

Examples

dat <- load_real_input_data(example = TRUE)
names(dat)
#> [1] "gan_training_data"    "original_matrices"    "covariates"          
#> [4] "feature_correlations" "feature_texture"      "sample_names"        
#> [7] "feature_names"        "n_samples"            "n_features"