Train PI Ensemble Models

High-level function for training PI (variant-importance score) ensemble models. Loads pre-annotated case and control data, imputes missing values, trains models, and saves them to disk.

train_PI_models(
  case_csv,
  control_source,
  output_dir,
  n_models = 100,
  controls_per_model = NULL,
  controls_multiplier = 1,
  max_controls = 50000,
  model_type = "GLM",
  features = NULL,
  chromosomes = 1:22,
  random_seed = NULL,
  verbose = 1
)

Arguments

case_csv

Path to the annotated case variants CSV file.

control_source

Path to control data. Either:

• A directory containing chr*.csv or chr*.gds files

• A single CSV or GDS file

output_dir

Directory where model RDS files will be saved.

n_models

Number of ensemble models to train. Default: 100.

controls_per_model

Number of controls sampled per model. Default: NULL (automatically set to match the number of cases times controls_multiplier). If specified explicitly, overrides the automatic calculation.

controls_multiplier

Multiplier for automatic controls_per_model calculation. Only used when controls_per_model = NULL. Default: 1 (equal number of controls and cases). Set to 2 for twice as many controls as cases, etc.

max_controls

Maximum number of control variants to load. If the source contains more variants, proportional sampling is performed during loading to limit memory usage. Default: 50000. Set to NULL to load all variants (not recommended for large datasets).

model_type

Model type: "GLM" (default) or "LASSO".

features

Character vector of annotation features to use. Default: NULL (uses 11 default FAVOR features).

chromosomes

Integer vector of chromosomes to include for controls. Default: 1:22.

random_seed

Random seed for reproducibility. Applied BEFORE any sampling operations (control loading and model training). Default: NULL.

verbose

Verbosity level: 0 (silent), 1 (progress), 2 (detailed).

Value

A list with components:

models

List of fitted model objects (length = n_models)

metadata

List with training metadata: n_cases, n_controls, n_models, controls_per_model, controls_multiplier, model_type, features, output_dir, random_seed

Details

The function performs the following steps:

1. Set random seed (if provided) for reproducibility

2. Load case annotations from CSV

3. Load control annotations from CSV/GDS (samples if max_controls set)

4. Calculate controls_per_model if not specified (n_cases * multiplier)

5. Impute NA values with column median

6. Train ensemble using model_PI()

7. Save models to output directory

Controls Per Model

By default, the number of controls sampled per model matches the number of cases (controls_multiplier = 1). This creates balanced training sets. Use controls_multiplier = 2 or higher to oversample controls, which may improve model stability when controls are abundant.

Reproducibility

When random_seed is set, all random operations are reproducible:

• Control variant sampling (if max_controls < total controls)

• Control selection within each model

Running with the same seed produces identical models.

Memory Usage

For large control datasets (millions of variants), use max_controls to limit memory usage. A value of 100,000-500,000 is typically sufficient since each model only samples controls_per_model variants.

Examples

if (FALSE) { # \dontrun{
# Default: controls_per_model = number of cases
result <- train_PI_models(
  case_csv = "als_cases_annotated.csv",
  control_source = "/path/to/favor_csv/",
  output_dir = "piModels/als/",
  n_models = 100,
  random_seed = 42
)

# Use 2x controls per case
result <- train_PI_models(
  case_csv = "als_cases_annotated.csv",
  control_source = "/path/to/favor_csv/",
  output_dir = "piModels/als_2x/",
  controls_multiplier = 2,
  random_seed = 42
)

# Explicit controls_per_model (overrides multiplier)
result <- train_PI_models(
  case_csv = "als_cases_annotated.csv",
  control_source = "/path/to/favor_csv/",
  output_dir = "piModels/als_500ctrls/",
  controls_per_model = 500,
  random_seed = 42
)
} # }