mtslearn: Machine Learning in Python for Medical Time Series

Abstract: Medical time-series data captures the dynamic progression of patient conditions, playing a vital role in modern clinical decision support systems. However, real-world clinical data is highly heterogeneous and inconsistently formatted. Furthermore, existing machine learning tools often have steep learning curves and fragmented workflows. Consequently, a significant gap remains between cutting-edge AI technologies and clinical application. To address this, we introduce mtslearn, an end-to-end integrated toolkit specifically designed for medical time-series data. First, the framework provides a unified data interface that automates the parsing and alignment of wide, long, and flat data formats. This design significantly reduces data cleaning overhead. Building on this, mtslearn provides a complete pipeline from data reading and feature engineering to model training and result visualization. Furthermore, it offers flexible interfaces for custom algorithms. Through a modular design, mtslearn simplifies complex data engineering tasks into a few lines of code. This significantly lowers the barrier to entry for clinicians with limited programming experience, empowering them to focus more on exploring medical hypotheses and accelerating the translation of advanced algorithms into real-world clinical practice. mtslearn is publicly available at https://github.com/PKUDigitalHealth/mtslearn.

• The paper presents mtslearn, a unified toolkit that streamlines preprocessing, feature engineering, and model integration for diverse clinical time-series data.
• It standardizes wide, long, and flattened data formats and supports both static and temporal prediction paradigms using established and custom models.
• Empirical evaluations on COVID-19 and sepsis datasets demonstrate competitive performance with state-of-the-art methods, enhancing clinical decision support.

mtslearn: A Unified Python Toolkit for Medical Time-Series ML

Background and Motivation

Medical time-series data, central to modern EHR and continuous monitoring, represent the temporal evolution of patient states and support critical tasks such as dynamic risk scoring and event prediction. However, the widespread heterogeneity of real-world clinical data—diverse tabular formats, missingness patterns, and asynchrony across data sources—renders conventional ML workflows fragile and inefficient. Legacy toolkits either offer fragmented coverage (dedicated to either preprocessing, modeling, or evaluation), possess steep learning curves, or lack explicit support for healthcare-centric time series. The disconnect between rapidly-evolving AI methodology and practical clinical deployment persists, as technical debt in data transformation and model integration inhibits translational impact.

Design Principles and Framework Architecture

The mtslearn framework directly addresses the end-to-end engineering pain points experienced by clinical researchers. Instead of further complicating modeling stacks with new algorithmic proposals, mtslearn unifies established statistical methods and deep learning models within a common, modular, and extensible Python pipeline. The evolutionary trajectory of clinical prediction modeling is encapsulated in the toolkit’s design (Figure 1).

Figure 1: Evolution from static tabular modeling to integrated pipelines, emphasizing classic and established AI medical tools.

A core design objective is format-agnostic data handling: mtslearn automates the ingestion and realignment of the three most prevalent clinical data schemas—wide, long, and flattened. The interface parses and standardizes arbitrary tabular representations, minimizing manual intervention and sharply reducing preprocessing overhead for downstream analytics (Figure 2).

Figure 2: mtslearn's input interface unifies wide, long, and flattened formats to a standard structure, enabling automated downstream processing.

The modular pipeline begins with format standardization and continues through feature engineering (both static and time-series), data cleaning (missing value imputation, outlier management, scaling), model training, and final evaluation (Figure 3). The design critically supports four core clinical ML paradigms: static-to-static, static-to-temporal, temporal-to-static, and temporal-to-temporal mappings.

Figure 3: Overview of the mtslearn pipeline, highlighting the modular workflow from raw data to evaluation.

Automatic structural transformation before and after data reading is visualized in Figure 4, illustrating the framework’s ability to align and consolidate distributed temporal measurements into unified sample matrices with minimal friction.

Figure 4: Data ingestion module converts disparate files and formats into a singlular, temporally-aligned structure for ML processing.

Core Functional Modules

• Processor: Ingests and standardizes wide, long, and flattened tabular data, extracting subject identifiers, timestamps, labels, and features, and handles essential preliminary cleaning.
• StaticProcessor: Aggregates temporal features for classical ML models, computes global statistics, and manages splitting, outlier removal, imputation, and normalization for static features.
• TSProcessor: Prepares 3D multivariate sequences for deep models—handles varied sequence lengths via padding and interpolation, utilizes localized imputation with masking, and assures robust scaling.
• Classifier Interface: Static and temporal outputs are supported through two principal classes—Static_Classifier and Temporal_Classifier. Both expose unified .fit() and .predict() APIs, accepting either feature matrices or tensors per paradigm.

Integration of algorithms is flexible: the toolkit ships with baseline models (XGBoost, Cox, LSTM, Transformer) and supports injection of arbitrary user-defined models adhering to standard .fit/.predict conventions. Thus, the framework is future-proof with respect to methodological advances, enabling direct incorporation of new architectures as they emerge.

Empirical Evaluation

Static Prediction: COVID-19 Mortality

On the COVID19-375 dataset, mtslearn demonstrates the static-input, static-output paradigm, where vital sign trajectories are aggregated to static descriptors. Performance is summarized as:

• Precision/Recall/F1: 0.96–0.97 across outcome classes
• Accuracy: 0.96

This result aligns or outperforms previously reported logistic regression and XGBoost metrics in analogous ICU mortality classification tasks as reported by [deng2022], [wang2025], and [yan2020]. The automated handling of missingness and robust data normalization further enhances reliability, particularly under real-world noisy acquisition.

Time-Series Classification: Sepsis Early Detection

Evaluation on the PhysioNet 2019 sepsis dataset highlights mtslearn’s capacity for end-to-end temporal classification, leveraging a Transformer backbone. Using sequence-level stratified splits and forward-filling for MCAR temporal missingness, results include:

• Accuracy: 0.97 (dominated by the negative class)
• AUROC (temporal): Demonstrates high discrimination for early sepsis prediction, although recall for positive samples (0.24) indicates further work on class imbalance is warranted.

These results are competitive with recent literature, e.g., [chen2022], [zhou2023], [kuruwitaa.2025], although as with all ML sepsis prediction, calibration and real-world deployment demand stringent post-hoc validation.

Comparison to Existing Toolkits

While contemporary toolkits such as TemporAI [saveliev2023], Clairvoyance [jarrett2023], Darts [herzen2022], pyts [faouzi2020], and NeuroKit2 [makowski2021] have contributed to time-series ML pipelines, mtslearn’s unique value lies in:

• Direct alignment of healthcare-centric data schemas (comprehensive support for wide/long/flattened).
• A scikit-learn-inspired, minimal-boilerplate API.
• Deep modular integration (preprocessing, feature engineering, classic + deep models, diagnostics) with minimal external configuration.
• Extensibility for user-customized modeling and rapid incorporation of recent algorithmic advances without codebase modification.
• Explicit support for all four clinically relevant static/temporal input-output mappings.

Implications and Future Directions

Practically, mtslearn lowers the technical barrier for translation of ML research into clinical decision-support prototypes. This has substantial implications for real-world application, particularly in settings where clinical informaticists lack advanced software engineering resources. Theoretically, by enabling standardization and reproducibility of pre- and post-modeling analysis, the toolkit supports more robust benchmarking and facilitates the identification of generalizable methods across diverse cohorts.

Current limitations recognized by the authors include: the lack of built-in explainability mechanisms (no direct SHAP, LIME, or attention visualization integration), and comparatively basic coverage of new generation architectures (e.g., SSMs, GNNs, or hybrid multi-modal fusion). Future toolkit versions would benefit from the addition of explicit XAI modules and out-of-the-box support for federated/distributed clinical ML, as explored by [li2024].

Conclusion

mtslearn offers a unified, extensible, and accessible pipeline for medical time-series machine learning. By integrating standardized data parsing, robust feature engineering, and flexible model deployment into a single framework, it bridges key engineering gaps that have long impeded the practical impact of clinical AI research. The open interface design and modular extensibility ensure continued alignment with advances in temporal modeling, setting a new practical standard for applied healthcare ML prototyping and translation.

(2603.29432)