Design decisions¶

This page explains why the app is structured the way it is.

Why long-format input¶

Long format (entity, time, row-level target) is flexible across domains:

• sensors
• transactions
• patient timelines
• behavior sequences

The app converts this generic shape into fixed-length windows, which keeps the UI simple and model-compatible.

Why split by entity¶

Validation split is performed by entity instead of random windows to avoid leakage:

• random window split can put related windows from the same entity into both train and validation
• entity-level split better reflects generalization to unseen sequences

Why checkpoint loading has multiple paths¶

User checkpoints vary:

• pure state_dict
• full nn.Module
• Lightning checkpoint that needs Class.load_from_checkpoint

Supporting all three reduces integration friction and avoids forcing one training stack.

Why scaler is optional but explicit¶

Model quality and explanations depend on feature scaling consistency.

• If users provide training-time scaler stats (mean, std), inference is consistent.
• If not provided, app computes a fallback scaler from current data so workflows remain usable.

Why TimeSHAP API resolution is dynamic¶

TimeSHAP and SHAP internals can change across versions.

The app resolves functions at runtime and includes compatibility handling for kernel API differences so users get actionable diagnostics instead of opaque import failures.