Computational phenotyping is the science of inferring clinically meaningful patient states from routinely collected data. Instead of relying on billing codes that record a diagnosis only after the fact, phenotyping algorithms attempt to detect conditions such as sepsis, kidney injury, or respiratory failure as they unfold. In critical care this problem is unusually hard. Patient physiology is non-stationary, meaning the underlying state changes rapidly. Observations arrive at irregular intervals, many measurements are missing for reasons related to the illness itself, and diagnostic codes carry no timestamp indicating when a disease process actually began. Standard retrospective benchmarks, which evaluate a model once at the end of a hospital stay, therefore fail to capture what clinicians actually need: estimates that update whenever a new observation becomes available.

RealPhe formalizes this challenge as causal phenotype estimation. Each prediction uses only information available at that moment, so a model estimating a patient’s conditions at hour twelve of an ICU stay cannot peek at data from hour thirteen. For development and evaluation, the framework aggregates irregular clinical events into two-hour intervals, a discretization that defines the training representation rather than the intended frequency of inference updates. Static cohort covariates are available from the start of the stay, while time-varying inputs contain only observations up to the prediction time. The current release evaluates this setting offline on retrospectively constructed trajectories; the authors are explicit that the software does not implement a live streaming or bedside deployment interface, and that it is not a certified medical device.

Architecturally, RealPhe is organized as a modular Python package wrapped in a reproducible workflow layer. Version 1.0.1, released under the GNU General Public License, replaced the original TensorFlow and Keras stack with PyTorch and introduced a reusable training engine. The codebase is divided into functional layers covering MIMIC-IV data access, preprocessing and task construction, model training, analytic tasks, and workflow provenance. Separate packages handle database querying, metrics and monitoring, the training loop with callbacks and custom losses, and executable tasks for cohort setup, evaluation, confidence intervals, feature importance, and mortality prediction. The scientific workflow itself is specified in a DVC pipeline whose stages run from cohort construction and signal extraction through adversarial validation, model training, and four phenotype-to-outcome mortality tasks.

The reproducibility machinery is where RealPhe departs from most research code. Parameters live in a configuration file, dependencies are pinned in pyproject.toml and uv.lock, and DVC records which artifacts depend on which stages. When a researcher changes, say, the temporal aggregation interval or a diagnosis-frequency threshold, the system recomputes only the affected preprocessing stages and their downstream model outputs, leaving unrelated cached results untouched. This makes methodological experimentation auditable: a scientist can swap an LSTM for a transformer, rerun a single command, and compare tracked metrics, plots, and aggregated predictions against every previous run. The design follows the reproducibility principles long championed by the MIMIC Code Repository community.

On the modeling side, the framework trains a single-layer Long Short-Term Memory network with dropout and a sigmoid output layer spanning 561 phenotypes simultaneously. Irregular clinical events are vectorized into two-hour time steps, with event-count features preserving information about missingness and measurement frequency. Preprocessing is strictly leakage-safe, with fold-specific imputation, scaling, and encoding, and a signal imputer that combines sample-and-hold imputation with training-set means. Variable-length patient sequences are collated as packed PyTorch batches that avoid wasting computation on padding, and the data pipeline uses multiprocessing, prefetching, and asynchronous transfers to keep the GPU fed. A weighted binary cross-entropy loss with a linear temporal ramp and label smoothing shapes training toward both early and late prediction quality.

Evaluation is deliberately multi-contextual. The framework reports first-step metrics that quantify phenotyping from the earliest measurements, time-distributed metrics that score causal predictions at successive two-hour points, and last-step metrics that allow comparison with retrospective benchmarks. Reliability is addressed through repeated ten-fold multi-label stratified cross-validation across seven random seeds, with predictions averaged across fold-specific models and seeds. Bootstrap confidence intervals, adversarial validation, and permutation feature importance round out the toolkit. The feature-importance procedure shuffles each input column once across all valid rows and time steps, measuring sensitivity to breaking the association between a feature and the rest of the input, though the authors caution it provides no causal estimate and does not preserve within-patient temporal alignment.

Software validation is unusually thorough for a research codebase. The repository includes 64 automated pytest cases built on small synthetic datasets that require no access to protected clinical data, covering the weighted temporal loss, ranking metrics, early stopping, preprocessing, packed sequences, and model serialization; all passed in the locked Python 3.12.13 environment. More striking is the end-to-end reproduction: the complete workflow was rerun with the same MIMIC-IV 2.0 data and configuration on a second computational system, moving from a TensorFlow-based v0.1.0 implementation to the PyTorch-based v1.0.1. All nine principal phenotyping metrics differed from the published values by at most 0.008, comfortably below a practical reproduction criterion of 0.01. Repeated complete runs in the same locked environment reproduced identical numerical results, confirming same-version repeatability.

The computational economics are also notable. A representative fold-specific training run covering 46,264 ICU stays and 561 phenotypes completed in 74.2 seconds on an NVIDIA GeForce RTX 5060 Ti, with peak host memory of 16.3 GiB and peak GPU memory of just 1.84 GiB. Offline inference over 13,045 test stays and 436,706 valid time steps ran at a median of 1.20 seconds per batch, a throughput of roughly 364,000 time steps per second. Because the LSTM is unidirectional and each input contains only past information, a single forward pass emits causal predictions at all valid time steps without recomputing retrospective prefixes. This efficiency makes repeated cross-validation feasible on hardware accessible to ordinary academic laboratories, lowering the barrier to rigorous benchmarking.

The implications extend beyond the ICU. Downstream multilayer perceptron models consume phenotype probabilities to predict 24-hour, ICU, in-hospital, and 30-day mortality, and the associated methodological study reported competitive performance, including an in-hospital mortality AUC-ROC of 0.913 after 24 hours that outperformed several traditional severity scores at the same time point. Attributing risk to clinically meaningful disease-state probabilities rather than raw vital signs opens a path toward more interpretable prediction. The authors point to several research directions the platform enables: controlled comparisons of temporal backbones from GRU-D to transformers and state-space models, systematic study of how missingness assumptions and cohort exclusions affect early versus retrospective performance, and auditing of healthcare-process biases. They are equally clear about limits: external multicenter validation, prospective evaluation, privacy-preserving federated approaches, and governance review all remain prerequisites before any clinical use, leaving RealPhe for now as a rigorous research foundation rather than a bedside tool.

Subject of Research: Reproducible real-time computational phenotyping of critical care patients from electronic health records using machine learning

Article Title: RealPhe: A reproducible framework for real-time phenotyping in critical care from electronic health records

Article References: Picheta, P., & Deniziak, S. (2026). RealPhe: A reproducible framework for real-time phenotyping in critical care from electronic health records. SoftwareX, 36, Article 103083. https://doi.org/10.1016/j.softx.2026.103083

Image Credits: AI Generated

DOI: 10.1016/j.softx.2026.103083

Keywords: RealPhe, computational phenotyping, electronic health records, critical care, MIMIC-IV, machine learning, LSTM, reproducibility, PyTorch, DVC, mortality prediction, intensive care