Configuration Reference¶

OneEHR experiments are driven by a single TOML config file. This page documents the public configuration contract for preprocessing, modeling, testing, and analysis.

See examples/tjh/mortality_patient.toml for a complete working example.

[dataset]¶

File paths for the three-table input spec. At minimum, dynamic is required.

[dataset]
dynamic = "data/dynamic.csv"
static = "data/static.csv"
label = "data/label.csv"

[preprocess]¶

Controls how irregular events are binned and features are built.

[preprocess]
bin_size = "1d"
numeric_strategy = "mean"
categorical_strategy = "onehot"
code_selection = "frequency"
top_k_codes = 100
min_code_count = 1

Preprocessing Pipeline¶

The pipeline field defines an ordered sequence of preprocessing operations fitted on the train split and applied to all splits. When pipeline is empty (the default), numeric features are filled with 0 at train/test time as a safety net.

Each step is a TOML table with an op key and operation-specific parameters. The cols parameter supports glob patterns ("num__*", "cat__*"), explicit lists, or null (all columns).

Supported operations:

Example: LOCF with mean fallback (recommended for time-series EHR):

[preprocess]
pipeline = [
  { op = "forward_fill", cols = "num__*", group_key = "patient_id", order_key = "bin_time", fallback = { strategy = "mean" } },
]

Example: Outlier handling + imputation + normalization:

[preprocess]
pipeline = [
  { op = "zscore_filter", cols = "num__*", threshold = 3.0 },
  { op = "impute", cols = "num__*", strategy = "median" },
  { op = "standardize", cols = "num__*" },
]

[task]¶

Defines the prediction task.

# Binary classification
[task]
kind = "binary"
prediction_mode = "patient"

# Multiclass classification
[task]
kind = "multiclass"
prediction_mode = "patient"
num_classes = 5

# Survival analysis (time-to-event with censoring)
[task]
kind = "survival"
prediction_mode = "patient"

# Multi-label classification (e.g., ICD coding)
[task]
kind = "multilabel"
prediction_mode = "patient"

[split]¶

Patient-level group split configuration. All strategies guarantee no patient appears in multiple splits.

[split]
kind = "random"
seed = 42
val_size = 0.1
test_size = 0.2

[split]
kind = "time"
time_boundary = "2012-01-01"

[[models]]¶

Model selection and per-model hyperparameters. Use [[models]] to train multiple models in one experiment. Each entry has a name and an optional params dict for model-specific hyperparameters.

[[models]]
name = "xgboost"
[models.params]
n_estimators = 100
max_depth = 4
learning_rate = 0.1

[[models]]
name = "gru"
[models.params]
hidden_dim = 64
num_layers = 1

[trainer]¶

Training loop configuration for deep learning models.

[trainer]
device = "auto"
seed = 42
max_epochs = 30
batch_size = 64
lr = 1e-3
early_stopping = true
patience = 5

Monitor AUROC instead of loss for binary tasks:

[trainer]
monitor = "val_auroc"
monitor_mode = "max"
early_stopping = true
patience = 10

The trainer tracks a per-epoch history of train_loss, val_loss, and the monitored metric (if not val_loss). This history is saved in meta.json under train_metrics.history.

[[systems]]¶

LLM system definitions for cross-system comparison via oneehr test.

[[systems]]
name = "gpt4o_eval"
kind = "llm"
framework = "single_llm"
backend = "openai"
model = "gpt-4o"
api_key_env = "OPENAI_API_KEY"

[output]¶

Run directory configuration.

Artifacts are written to {root}/{run_name}/. See Artifacts for the full directory layout.

[output]
root = "runs"
run_name = "tjh"