Spezi Data Pipeline: Streamlining FHIR-based interoperable digital health data workflows

Abstract

The increasing adoption of digital health technologies has amplified the need for robust, interoperable solutions to manage complex healthcare data. We present the Spezi Data Pipeline, an open-source Python toolkit designed to streamline the analysis of digital health data, from secure access and retrieval through processing, visualization, and export. The Pipeline is integrated into the larger Stanford Spezi open-source ecosystem for developing research and translational digital health software systems. Leveraging Health Level Seven (HL7) Fast Healthcare Interoperability Resources (FHIR)-based data representations, the Pipeline enables standardized handling of diverse data types, including sensor-derived observations, electrocardiogram (ECG) recordings, and clinical questionnaires–across research and clinical environments. We detail the modular system architecture and demonstrate its application using real-world data from the Pediatric Apple Watch Study (PAWS) at Stanford University, in which the Pipeline facilitated efficient extraction, transformation, and clinician-driven review of Apple Watch ECG data, supporting annotation and comparative analysis alongside traditional monitors. By reducing the need for bespoke data engineering and enabling prospective, clinician-in-the-loop analysis within standardized workflows, the Spezi Data Pipeline supports reproducible and interoperable clinical research using routinely collected digital health data.

Introduction

In a rapidly evolving healthcare landscape, the progressive digitization of data presents a transformative opportunity to enhance clinical outcomes and operational efficiencies. Amidst rising healthcare expenditures and suboptimal outcomes in the United States, there is a pressing need for innovations that align with the “triple aim” of healthcare improvement: enhancing the individual experience of care, improving the health of populations, and reducing per capita cost¹. Digital health technologies, including mobile applications, wearable biometric sensors, telehealth platforms, and computational analytics, represent promising modalities for achieving these objectives through optimized care delivery processes and augmented clinical decision support^2–5.

Realizing the full potential of digital health, however, requires overcoming significant challenges in data management. Integrating digital health data from mobile applications and connected devices into research workflows poses significant challenges arising from fragmented storage systems, proprietary data formats, and inconsistent access protocols. Retrieving and harmonizing these data sources often requires substantial technical effort and domain expertise, particularly to ensure data integrity and analytical consistency. For data science and biomedical research applications, maintaining high data quality is crucial, as inconsistencies or formatting issues can distort results and impair reproducibility.

Standardizing health data remains a critical challenge, particularly where operational systems and research workflows intersect. Health data is inherently heterogeneous, encompassing device-generated metrics, patient-reported outcomes, and clinical records-each with distinct formats, resolutions, and metadata requirements. Standards such as Open mHealth⁶, HL7 FHIR⁷, and the OMOP Common Data Model (CDM)⁸ have enabled more consistent representations of health data and facilitated seamless data exchange in clinical settings. Despite widespread adoption in clinical systems, however, their integration into research infrastructure has lagged behind. In practice, researchers often lack accessible, end-to-end tooling that bridges standardized data storage with analysis-ready representations, forcing reliance on ad hoc scripts and bespoke preprocessing pipelines that are difficult to reproduce, validate, and scale across studies.

Bridging this gap is essential: robust, data-driven research increasingly depends on access to high-quality, harmonized data aligned with evolving interoperability standards. Without such alignment, researchers are forced to rely on ad hoc pipelines and manual harmonization efforts, which are error-prone and difficult to scale. Broader adoption of these standards in research environments offers a unique opportunity to standardize data handling practices, simplify integration and interpretation, and accelerate advances in biomedical science.

However, a critical layer of infrastructure is still missing–one that would allow researchers to fully leverage these standardized formats. Without tools for structured access, transformation, and visualization, the potential of interoperability remains underrealized.

Preparing raw health data for analysis involves multiple complex steps, including filtering, temporal alignment, feature extraction, and normalization. The challenge is even more pronounced when working with high-dimensional data such as electrocardiogram (ECG) recordings or longitudinal survey responses, which require both technical fluency and domain expertise to analyze meaningfully. Although major cloud providers offer robust APIs-such as Google Cloud Healthcare API⁹ and Azure Health Data Services¹⁰—these solutions are often tightly coupled to specific platforms, require significant customization, and may lack the modularity needed for integration into diverse research workflows. Additionally, while platforms such as Cortex¹¹ have demonstrated successful reuse of digital health data across studies, many lack integration with clinical data standards like FHIR, limiting their ability to support scalable, interoperable research aligned with broader healthcare infrastructure.

The Stanford Spezi ecosystem addresses these limitations, providing an open-source, standardsbased foundation for digital and mobile health research¹². The ecosystem’s data collection components are cloud-agnostic and support seamless integration of data stored in standardized formats, with strong emphasis on HL7 FHIR-based representations. To close the gap between standardized data storage and usable research outputs, we introduce a new component of the ecosystem: the Spezi Data Pipeline–a lightweight, extensible toolkit for extracting, processing, and analyzing digital health data in a reproducible and scalable manner (Fig. 1). This Python-based framework is designed to streamline the entire digital health data lifecycle-encompassing access, retrieval, restructuring, analysis, exploration, and export-while adhering to FHIR standards for enhanced interoperability. By providing structured access to hierarchical health data and transforming it into flat, analysis-ready formats, the Pipeline lowers the barrier to working with complex, structured health data and enhances the ability to generate repeatable insights across studies.

Fig. 1. End-to-end architecture of the Spezi Data Pipeline.

This diagram illustrates the modular workflow of the Spezi Data Pipeline, from secure data access to downstream processing, exploration, and export. FHIR-compliant resources are retrieved from a cloud database, flattened into a structured tabular representation, and passed through processing modules for analysis. The Pipeline supports both data exploration (e.g., visualization of observations, ECG signals, and questionnaire scores) and data export, and is designed to operate within an interactive Python notebook environment. HL7®, FHIR®, and the FHIR flame design are the registered trademarks of Health Level Seven International, and their use does not constitute endorsement by HL7. Components of this figure were generated using generative AI tools.

To evaluate the Pipeline’s performance, we present results from its integration into the real-world PAWS at Stanford University. This deployment illustrates how the Pipeline supports the ingestion, transformation, and analysis of longitudinal mobile health data within an active, prospective study. Ultimately, by providing a standardized, modular solution, the Spezi Data Pipeline aims to reduce the need for bespoke development, improve efficiency, and enhance the reliability of health data management–facilitating improved patient outcomes, reducing operational costs, and enabling scalable, high-quality healthcare delivery.

Results

Real-world validation of the spezi data pipeline in the PAWS study

The Spezi Data Pipeline was implemented in the Pediatric Apple Watch Study (PAWS) to evaluate its ability to streamline access, processing, and visualization of digital health data stored in Firebase Firestore (Fig. 2). The Pipeline successfully enabled secure retrieval and transformation of ECG recordings and related health metrics into a structured, compressed tabular format, which could be exported locally for analysis.

Fig. 2. Overview of the adoption of the Spezi Data Pipeline for PAWS.

The PAWS data stored on Firebase Firestore is accessed and fetched by the data access module. The Spezi Data Pipeline visualization tools are integrated in a Python notebook, allowing clinicians to review, annotate, and compare ECG recordings. The figure contains test data for demonstration purposes. Components of this figure were generated using generative AI tools. HL7®, FHIR®, and the FHIR flame design are registered trademarks of Health Level Seven International. The Firebase icon is a trademark of Google LLC. Use does not imply endorsement.

Wearable ECG data access and clinical visualization

Apple Watch ECG recordings from the pediatric participants enrolled in PAWS were analyzed. At the time of analysis, 100+ subjects (age range: 6.1–18 years) were enrolled in PAWS, and a total of 4000+ electrocardiogram (ECG) recordings had been collected. A selection of representative cases demonstrates the utility of the Spezi Data Pipeline in visualizing and exploring ECG recordings collected from pediatric participants.

Representative pediatric ECG phenotypes

Figure 3 presents a normal sinus rhythm tracing with an average heart rate of 66 bpm. Through the Pipeline’s standardized data access and visualization modules, the tracing can be easily inspected to reveal upright P waves, narrow QRS complexes, and normal PR intervals, consistent with typical pediatric conduction patterns.

Fig. 3. Representative normal ECG from a pediatric participant.

The tracing demonstrates normal sinus rhythm with age-appropriate heart rate and intervals similar to a typical Lead I ECG tracing. The P waves are upright, the PR interval is within normal limits, and QRS complexes are narrow and upright, consistent with normal conduction in a healthy pediatric heart.

Figure 4 shows a baseline ECG from another participant with Wolff-Parkinson-White (WPW) syndrome. The Pipeline enables clear visualization of intermittent pre-excitation, including widened QRS complexes and short PR intervals, patterns that are readily identifiable through harmonized rendering of the signal data.

Fig. 4. Representative ECG tracing from a pediatric participant with Wolff-Parkinson-White (WPW) syndrome.

The participant’s baseline heart rate was 66 bpm. The tracing shows sinus rhythm with intermittent wide QRS complexes, consistent with intermittent preexcitation. These findings are characteristic of WPW syndrome and illustrate the presence of an accessory pathway.

In Fig. 5, a third participant experienced an episode of supraventricular tachycardia (SVT) with a heart rate of approximately 190 bpm. The Spezi Data Pipeline enables detailed visualization of this event, capturing a narrow complex, regular tachycardia in a symptomatic child during palpitations and demonstrating the platform’s ability to support arrhythmia identification in pediatric patients.

Fig. 5. ECG tracing from a pediatric participant demonstrating supraventricular tachycardia (SVT).

The single lead ECG shows a regular, narrow complex tachycardia consistent with SVT. The ECG tracing was captured during a symptomatic episode of palpitations and demonstrated SVT at a rate of 190 bpm.

Collectively, these cases highlight how the Pipeline supports reproducible exploration of wearable ECG data, enabling researchers and clinicians to visualize normal conduction, baseline abnormalities, and transient arrhythmic events within a unified analytic environment. Rather than relying on device-specific outputs, the Spezi Data Pipeline provides a flexible framework for inspecting, comparing, and interpreting signals in a research context.

Clinician-in-the-loop review and annotation workflow

Visualization tools integrated into the interactive dashboard (integrated in a Python notebook) allowed clinicians to efficiently review, annotate, and compare ECG traces, with all diagnoses and quality assessments saved back to the cloud. Throughout the process, patient identifiers remained encoded to protect privacy, and access to identifiable information was restricted to valid clinical scenarios. Overall, integration of the Spezi Data Pipeline provided an efficient and robust solution for data processing, exploration, and visualization within the PAWS digital health study. The Pipeline enabled seamless extraction, structuring, and analysis of complex health data, significantly improving workflow efficiency and supporting clinician-driven review while maintaining high standards of data security and interoperability.

Longitudinal data aggregation and visualization

Furthermore, the Spezi Data Pipeline data processing and data exploration modules enabled the seamless acquisition, harmonization, and visualization of diverse physiological measurements, including step counts, calories burned, VO₂max, physical effort, and heart rate across multiple users. This streamlined approach facilitated rapid data filtering and aggregation, while automated identifier masking ensured robust patient privacy protection throughout the analytic workflow. The integrated functionalities of the Spezi Data Pipeline enabled automatic aggregation of either average or total daily values for each physiological measurement (Figs. 6–10); when appropriate, the full distribution of multiple daily measurements for each user was visualized (Fig. 11). Five representative users were arbitrarily selected for visualization purposes. Apparent differences in temporal coverage across users reflect heterogeneity in enrollment dates and follow-up duration, rather than missing or selectively filtered data. Because participants entered the study at different time points and contributed data for varying lengths of time, longitudinal visualizations naturally exhibit user-specific temporal spans along the horizontal axis. The tool provides flexibility to select specific user IDs and date ranges for targeted investigation. User identifiers were masked throughout to ensure privacy.

Fig. 7. Total daily calories burned for five representative users.

The figure shows the total calories burned each day for the same set of users. Differences in temporal coverage across users arise from heterogeneous enrollment times and follow-up durations, resulting in user-specific longitudinal spans rather than missing or selectively filtered data.

Fig. 8. Daily average VO₂max for five representative users.

The plot presents the daily mean VO₂max values for each user. Differences in temporal coverage across users arise from heterogeneous enrollment times and follow-up durations, resulting in user-specific longitudinal spans rather than missing or selectively filtered data.

Fig. 9. Daily average physical effort for five representative users.

This figure shows the daily average physical effort, as estimated by the wearable device, for each user. Differences in temporal coverage across users arise from heterogeneous enrollment times and follow-up durations, resulting in user-specific longitudinal spans rather than missing or selectively filtered data.

Fig. 6. Total daily step counts for five representative users.

Each line represents the total number of steps recorded per day for each user over the observation period. Differences in temporal coverage across users arise from heterogeneous enrollment times and follow-up durations, resulting in user-specific longitudinal spans rather than missing or selectively filtered data.

Fig. 10. Daily average heart rate for five representative users.

The plot presents the mean heart rate recorded per day for each user. Differences in temporal coverage across users arise from heterogeneous enrollment times and follow-up durations, resulting in user-specific longitudinal spans rather than missing or selectively filtered data.

Fig. 11. Heart rate data distributions for five representative users.

The plot presents the distribution of all heart rate measurements (dots) for each user. Multiple heart rate recordings per day are visualized to illustrate intra-day variability. Differences in temporal coverage across users arise from heterogeneous enrollment times and follow-up durations, resulting in user-specific longitudinal spans rather than missing or selectively filtered data.

Complementing the above, Fig. 12 demonstrates how the Spezi Data Pipeline can be used to quantify and visualize the number of ECG recordings contributed by each participant. The distribution highlights heterogeneity in monitoring frequency and engagement, with most participants providing fewer than 100 recordings, while a subset contributed substantially more.

Fig. 12. Distribution of ECG recordings per participant.

The histogram summarizes the number of Apple Watch ECG recordings contributed by each subject. While most participants recorded fewer than 100 ECGs, a subset contributed substantially more recordings, indicating variability in engagement and monitoring frequency across the cohort.

Study participation and data contribution patterns

To further contextualize study participation, Fig. 13 illustrates participant follow-up duration, measured in weeks, using the Pipeline’s visualization framework. While the majority of subjects were active for 10 weeks or less, a substantial subset remained engaged for over 50 weeks. These views underscore how the Pipeline supports exploration of study dynamics, allowing researchers to assess longitudinal variability in individual data contribution and retention.

Fig. 13. Distribution of participant follow-up duration in the PAWS study.

The histogram shows the number of weeks each participant remained active in the study. Most subjects contributed data for fewer than 10 weeks, while a smaller subset remained enrolled for extended periods exceeding 50 weeks. This distribution reflects heterogeneity in enrollment timing and follow-up duration rather than differential data filtering or attrition.

Discussion

This study introduces the Spezi Data Pipeline, an open-source Python package developed to address critical ongoing challenges in interoperability, scalability, and data integrity in digital health data management. By adhering to HL7 FHIR standards, the Pipeline ensures that diverse health data–from sensor-derived observations to clinical questionnaire responses–can be securely and consistently handled across research and clinical environments. The modular architecture (comprising data access, flattening, processing, exploration, and export modules) enables flexible integration into existing workflows and supports a broad range of analytical and visualization tasks.

Beyond its architectural design, the Spezi Data Pipeline enables systematic, modular testing across all core components, simulating diverse user interactions and health metrics to rigorously validate functionality and reliability. Its ability to transform complex, hierarchical FHIR resources into flat, analysis-ready tables is essential for efficient downstream data exploration and modeling, supporting rapid and reproducible analytics. Integrated visualization tools provide clear, actionable insights into activity, nutrition, vitals, and risk scores, demonstrating the platform’s utility for both clinical research and operational decision-making.

The Pipeline’s real-world utility was further validated through its deployment in the Pediatric Apple Watch Study (PAWS) at Stanford University. Integration with Firebase Firestore enabled secure, FHIR-compliant retrieval and transformation of ECG and related health data, ensuring data integrity and interoperability throughout. The interactive dashboard, developed on top of the Pipeline, facilitated efficient clinician review, annotation, and comparison of ECG traces, with all actions securely logged and synchronized to the cloud. Over 4000 ECGs have been recorded by study participants and reviewed using this Pipeline. This workflow enhanced PAWS’s efficiency and reproducibility, maintaining strict data privacy and security standards through the use of encoded patient identifiers and controlled access to sensitive information.

This work leveraged the Pediatric Apple Watch Study as a clinically grounded evaluation opportunity; however, the Spezi Data Pipeline’s utility is not limited to pediatric cardiology/ECG data. Its reliance on standardized FHIR resource structures and coded observations enables direct reuse across a broad range of routinely collected digital health datasets, including activity tracking, physiological monitoring, and patient-reported outcomes from diverse devices and study designs. By decoupling data ingestion and analysis from device-specific formats, the Pipeline supports transferability across studies and institutions, addressing a common barrier to scalable clinical digital health research.

Several prior efforts have addressed the transformation of structured health data into analysis-ready formats^13–16. Tools such as FIDDLE, Pathling, and FhirExtinguisher provide mechanisms for preprocessing EHR data, querying FHIR resources, or flattening hierarchical structures using FHIRPath expressions. These approaches have been highly effective for retrospective analyses and large-scale analytics. In contrast, the Spezi Data Pipeline is designed to operate as clinical research infrastructure embedded within prospective digital health studies. Rather than optimizing for large-scale batch analytics alone, the Pipeline emphasizes modular integration with data collection systems, schema validation at ingestion, clinician-facing visualization, and bidirectional annotation workflows. The prospective deployment within the Pediatric Apple Watch Study demonstrates how FHIR-based frameworks can support real-time data review and clinical interpretation, extending beyond offline transformation or query-focused tools.

Despite widespread adoption of FHIR in clinical systems, few research-focused tools offer seamless end-to-end pipelines for transforming FHIR-based health data into analysis-ready formats. The Spezi Data Pipeline fills this infrastructure gap by combining standards-based design with accessible, open-source tooling, lowering the barrier for health data science. This design not only supports efficient reuse of structured health data across studies, but also advances the reproducibility and transparency goals central to open science. By automating the preprocessing of FHIR resources–often a time-consuming and error-prone task–Spezi enables more consistent benchmarking and collaborative research on digital health datasets.

The explicit integration of open-source FHIR schema validation is critical for translating digital health pipelines into clinical research settings. By enforcing standards compliance at the point of data ingestion, the Spezi Data Pipeline ensures that downstream analyses operate on structurally valid and semantically consistent clinical observations. This is particularly important when working with heterogeneous, routinely collected data originating from multiple devices, applications, or collection protocols. Schema-level validation reduces silent failure modes, supports reproducibility across studies, and enables reliable reuse of analytic workflows beyond a single deployment, thereby strengthening the Pipeline’s generalizability and clinical relevance.

Taken together, the Pipeline’s modular architecture enables seamless integration with existing systems while maintaining strict compliance with interoperability standards, allowing research teams to focus on scientific questions rather than technical implementation details. By streamlining FHIR-compliant workflows and enabling structured expert review, the Spezi Data Pipeline lowers technical barriers, reduces resource demands, and facilitates the translation of complex health data into actionable insights.

Although the Spezi Data Pipeline is designed as a generalizable, modular framework, the scope of the present study was limited to physiological metrics and questionnaire responses collected within a single institution. Evaluations across other supported resource types, diverse clinical settings, populations, and health systems will be critical to assessing the Pipeline’s cross-contextual utility. Future efforts include ecosystem expansion through additional modular components, enhanced support for diverse server connections, and alignment with complementary initiatives, such as JupyterHealth¹⁷. As an open-source framework, the Spezi Data Pipeline is designed to be extensible and community-driven, encouraging researchers and developers to contribute new capabilities tailored to their domain-specific needs. These continued efforts will further strengthen the foundation for interoperable, reproducible, and scalable digital health research-ultimately enabling more efficient study designs and improved patient outcomes.

Methods

The Spezi Data Pipeline is an MIT-licensed¹⁸ Python toolkit for standards-based digital health data management within the open-source Stanford Spezi ecosystem¹². The Pipeline integrates existing Software Development Kits (SDKs) and libraries into a customizable, modular, FHIR protocol-adherent package with the goal of enabling consistent, secure data handling and interoperability. In this paper, we detail the Spezi Data Pipeline’s design, including its utility in calculating patient activity indices and deriving risk scores from common clinical questionnaires. We then evaluate the Pipeline’s in situ applicability, discussing its implementation in the ongoing Pediatric Apple Watch Study at Stanford University.

The Spezi Data Pipeline package is available to install as a dependency in integrated development environments (IDEs) (e.g., Jupyter Notebook, Google Colaboratory), as well as in standalone Python scripts or larger data processing pipelines. This facilitates seamless integration into a wide range of workflows and enhances the efficiency and reliability of digital health data management. The code, documentation, and usage examples are hosted on GitHub¹⁸, enabling easy access and collaboration.

Spezi Data Pipeline system design

The Spezi Data Pipeline supports a wide range of resource data types collected via smartphones and their connected devices, including heart rate, blood pressure, heart rate variability (HRV), electrocardiogram recordings (ECGs), clinical questionnaire responses, and metrics pertaining to activity and nutrition. Such data is henceforth collectively referred to as “personal health sensor observations,” or, simply, “observations.” The Spezi Data Pipeline is designed to process a wide range of observations, enabling their collection and analysis across diverse digital health projects and applications. Observations are managed using Logical Observation Identifiers Names and Codes (LOINC) codes or other coding standards (such as Apple Health identifiers), providing a standardized method for data handling and classification. Queries for specific data types are implemented by programmatically filtering retrieved FHIR resources based on these standardized codes, rather than relying on backend-specific FHIR REST search interfaces, thereby maintaining portability across different storage backends and access mechanisms. A sample FHIR-compliant observation instance is presented in Listing 1.

The Spezi Data Pipeline supports the manipulation and analysis of StructuredDataCapture specification-adherent clinical questionnaire responses (https://build.fhir.org/ig/HL7/sdc/). Supported surveys include the Social Support Questionnaire (SSQ)¹⁹, the Patient Health Questionnaire (PHQ-9)²⁰, and the Walking Impairment Questionnaire (WIQ)²¹. Through efficient handling and analysis of clinical questionnaire responses, the Pipeline enables the rapid extraction of actionable insights from patient-reported data, facilitating responsive patient assessment and personalized treatment planning.

The Spezi Data Pipeline consists of five core modules: Data Access, Data Flattening, Data Processing, Data Exploration, and Data Export (Fig. 1). These modules interact with each other, serving collectively as a comprehensive toolbox for end-to-end data extraction. Importantly, modules can also function as separate components for specific operations in a given system, ensuring modularity and flexibility in the system’s design.

Data access

At the foundation of the Pipeline, the Data Access module establishes a connection to the server, functioning as the core component for retrieving information stored in the cloud. This implementation can leverage existing Python SDKs (e.g., Firebase²²) for accessing data stored on Google Firebase Firestore, and provides flexibility for developers to set up their own connections to custom cloud platforms or data storage mechanisms.

To support interoperability across systems, the module requires data to be stored in the FHIR format and relies on the open-source Python fhir.resources package²³, which provides validated classes for all FHIR resources defined in the HL7 FHIR specification⁷. All retrieved health data is validated at ingestion using this library, prior to any flattening or transformation steps. Validation verifies required fields, data types, coded elements (e.g., LOINC), timestamps, and overall resource structure. Resources that fail schema validation are rejected from downstream processing, preventing malformed, incomplete, or non-standard clinical observations from propagating through analytic workflows. This early validation step establishes a well-defined and reproducible contract for all downstream modules, independent of data source or device vendor.

Once this contract is established, the Data Access module permits complete or partial dataset retrieval. Queries for specific data types are expressed using standardized coding systems (e.g., LOINC), enabling targeted access to relevant FHIR resources. Retrieved resources are then instantiated as FHIR resource objects using the fhir.resources package, providing a structured in-memory representation for downstream processing.

Finally, to support extensibility and deployment flexibility, the Data Access module is intentionally backend-agnostic and does not assume a specific storage or server implementation. It operates on FHIR-compliant resources retrieved from cloud-hosted data stores using configurable data access logic. Support for additional storage backends can be achieved by implementing alternative data access components without modifying downstream processing, flattening, or analysis modules.

Listing 1: FHIR Observation example for step count measurements. The listing illustrates a standardized FHIR Observation resource capturing wearable-derived step count data, including categorical metadata, LOINC-based semantic labeling, subject linkage, timestamping, and quantitative value encoding. This representation enables portable, backend-agnostic processing within the Spezi Data Pipeline.

Data flattening

Transforming stored data into FHIR resource objects enhances data integrity, but the resulting hierarchical format can complicate data exploration and analysis. The Data Flattening module is a vital part of the Spezi Data Pipeline, providing tools and classes to convert FHIR data from its native structure into a flattened, tabular Pandas.DataFrame format for simplified analysis and modeling. This tool implements an enhanced Pandas.DataFrame called FHIRDataFrame, which retains all resource-related metadata.

Although individual FHIR resource types require domain-specific field mappings, the flattening methodology follows a consistent pattern across resources. Each resource is decomposed into a canonical set of identifiers, timestamps, coded elements, and value fields, which are then mapped into a standardized tabular representation. Resource-specific extractors encapsulate this logic, allowing new FHIR profiles or extensions to be supported by implementing additional extractors without modifying the core logic. This design balances extensibility with semantic fidelity to the underlying clinical data.

The resulting flattened tables are organized by FHIR resource type, with each table containing entries corresponding to a specific resource class (e.g., Observation, QuestionnaireResponse). Column schemas vary by resource type (e.g., observation, questionnaire response, etc.). For Observation resources, each table includes entries for the user identifier, resource identifier, quantity name, unit, value, LOINC code, display name, device-associated code (if present), and time and date of the entry. For ECG observations, additional columns include number of measurements, sampling frequency, ECG classification, heart rate (with units), and the ECG recording metadata. For QuestionnaireResponse resources, each output table contains columns for the user’s identifier, resource identifier, authored date, questionnaire title, question identifier, question text, answer code, and answer text. Codified questionnaire prompts and responses (in the form of identifiers and codes) in the flattened table should be mapped to their actual text representations to facilitate meaningful analysis and interpretation.

As an example, the FHIR Observation shown in Listing 1 is flattened into a single row within a FHIRDataFrame by extracting key fields from the hierarchical structure, including the patient identifier, observation identifier, coded measurement type (e.g., LOINC code and display name), numeric value and unit, and effective timestamp. Nested elements such as valueQuantity.value and valueQuantity.unit are mapped to scalar columns, while coded fields are resolved into standardized identifiers and human-readable labels. This flattening process preserves semantic context while producing analysis-ready tabular data suitable for statistical modeling and visualization.

The Data Flattening tool can additionally be used to extract a comprehensive list of users and their relevant identifying and demographic information, enabling the mapping of user identifiers to their data for subsequent analysis at a later stage.

Data processing

The Data Processing module contains tools for filtering, selecting, and processing data, utilizing custom classes and methods to filter outliers, aggregating daily data (e.g., summing or averaging), and selecting data within particular windows of time or for specific users. These functionalities offer flexibility in tailoring datasets to the needs of particular studies, streamlining data exploration and analysis.

The functions within this module are tailored to the type of resource being processed (Table 1). For example: clinicians and researchers often employ clinical questionnaires to derive risk scores relevant to their purpose. The Data Processing module includes built-in functions that automatically generate risk scores based on the particular survey, with calculation formulas for certain questionnaire types provided as part of the package. Additionally, the module allows developers to implement custom risk score calculations if alternative methodologies or new questionnaires are required. For instance, a commonly used clinical questionnaire is the Patient Health Questionnaire-9 (PHQ-9)²⁰ (illustrated in Listing 2). The Spezi Data Pipeline supports automated extraction and scoring of PHQ-9 responses and similarly structured questionnaire data. It should be noted that risk score calculations are implemented through modular processing functions that operate on flattened questionnaire response tables. Questionnaires that share common estimation strategies—such as summation, averaging, weighted averaging, or other aggregation-based scoring approaches—can reuse the same processing function by specifying the appropriate configuration and mapping of questionnaire items. When a questionnaire requires a distinct scoring methodology, a new processing function can be introduced without modifying other Pipeline components. This design enables consistent reuse of scoring logic across questionnaires while preserving flexibility for questionnaire-specific implementations.

Table 1.

Core functions implemented in the data processing module of the Spezi Data Pipeline

Function	Resource type	Description
Outliers filtering	Observation	Filters out non-representative and abnormal data values.
User(s) selection	Observation	Selects and returns data for specific users based on the user ID.
Date(s) selection	Observation	Filters and returns data within a specified date range.
Daily data aggregation	Observation	Aggregates daily data, summing values within a day.
Daily averaging	Observation	Calculates the daily average of the data.
Activity index calculation	Observation	Calculate the 7-day moving average of step counts.
Risk score calculation	QuestionnaireResponse	Calculates the risk score based on the questionnaire responses.

The table summarizes the main processing operations supported by the Pipeline, including filtering, user and date selection, temporal aggregation, and derived metric computation.

Listing 2: PHQ-9 Questions and Scoring Methodology. This listing illustrates the nine-item Patient Health Questionnaire (PHQ-9) with corresponding scoring criteria. Each item is rated from 0 (Not at all) to 3 (Nearly every day), and the total score is used to assess depression severity.

Data exploration

The Data Exploration module provides tools for visualizing various types of data, supporting both individual and combined datasets. This module offers different visualization options depending on the nature of the data (e.g., bar plots, scatter plots, line charts), including specialized tools for plotting observations and ECGs. Designed for healthcare professionals, researchers, and data analysts, the module extends foundational visualization capabilities, introducing advanced functionalities such as individual ECG lead visualization, date and user filtering, and customizable plotting aesthetics. The Data Exploration module additionally includes functions for plotting and analyzing variations in risk scores derived from stored questionnaire responses, aiding in the identification of trends in patient-reported outcomes.

Data export

The Data Export module enables users to export data and visuals in various formats. Tables can be exported to .CSV/.XLSX formats, and plots and figures to .PNG/.TIFF/.JPEG formats. This module ensures that processed and visualized data can be easily shared and applied across diverse use cases. Notably, tabular data is optimized for machine learning applications, ensuring data integrity, standardization, and basic processing. This capability supports the integration of findings into broader data analysis workflows, enhancing the reproducibility, scalability, and impact of digital health studies.

Pediatric Apple Watch study: system evaluation

To evaluate the Spezi Data Pipeline’s utility in a real-world clinical research setting, we deployed it within the ongoing Pediatric Apple Watch Study (PAWS) at Stanford University. This implementation involved managing diverse digital health observations collected from mobile applications and wearable devices, including measurements such as heart rate, daily step counts, estimated energy expenditure (calories burned), levels of physical activity or exertion, and maximum oxygen uptake (${VO}_2\max$), an indicator of cardiovascular fitness. All data is structured according to the FHIR standard, preserving their hierarchical format with proper use of standardised coding systems (e.g., LOINC), timestamps, and patient identifiers. These FHIR resources were stored in Firebase Firestore, enabling the Pipeline’s Data Access module to retrieve and process them efficiently in a cloud-native architecture.

Heart rhythm abnormalities are a leading cause of death in children with congenital heart disease. Early detection and characterization of arrhythmias in pediatric patients can be critical for developing treatment strategies that improve survival rates and overall quality of life. Children presenting with arrhythmia symptoms typically require ambulatory monitoring to determine the etiology of their symptoms. However, existing medical grade monitors often have limited wear times, bulky designs, and irritating adhesives, rendering them impractical for long-term use.

Convincing evidence supports the use of the Apple Watch for arrhythmia characterization in adults, but data on its efficacy in pediatric populations remain limited. In recognition of this gap, the Pediatric Apple Watch Study (PAWS) at Lucile Packard Children’s Hospital at Stanford University–a prospective, single-center observation study–aims to determine whether the Apple Watch can be used as a cardiac event monitor for children by comparing Apple Watch ECG recordings and traditional ambulatory cardiac monitors in pediatric patients undergoing clinical arrhythmia evaluation.

The PAWS mobile application was built using the modular Spezi digital health ecosystem. Leveraging Spezi modules allowed seamless integration with the Apple Watch, enabling efficient data collection and secure transfer to Firebase. Pediatric patients aged 6–18 years who were undergoing clinically indicated arrhythmia monitoring with a Zio patch, 24–48 h Holter monitor, or event monitor recording device were enrolled in the study. Participants were required to possess the developmental ability, as determined by both the patient and their parents, to safely wear the Apple Watch and utilize the patient-activated trigger functions on both the clinical monitor and the Apple Watch.

Patients younger than 6 years of age, those unable to effectively utilize the triggered features of either device, or those unable to use the Apple Watch were excluded from participation. All eligible patients were offered participation during routine clinical visits. Study participants were given an Apple Watch to be worn for a duration of 6 months and instructed to record an Apple Watch ECG tracing each time they felt symptoms concerning for an arrhythmia.

The study protocol was reviewed and approved by the Stanford University Institutional Review Board (IRB) under protocol number #67366. All research involving human participants was conducted in accordance with the Declaration of Helsinki and with the ethical standards of the responsible institutional and national committees on human experimentation. Informed consent was obtained from all participants and/or their legal guardians, as applicable. No animal studies are included in this work. The research team adhered strictly to all relevant institutional guidelines and regulations governing the use of human subject data.

In order to effectively compare the Apple Watch against current gold-standard monitors, a data visualization dashboard was developed with Spezi Data Pipeline to enable physicians to analyze incoming Apple Watch data alongside recordings from standard monitors. The resulting dashboard tracks whether ECGs have been reviewed by clinicians and allows annotations on tracing quality, ECG diagnoses, and reviewer comments, ensuring a comprehensive evaluation of the Apple Watch’s performance in detecting and characterizing arrhythmias in children. The following steps detail the process of leveraging the Pipeline to establish an efficient method for accessing cloud-stored study data and preparing them for later analysis and review.

The first step involved accessing the FHIR observations stored in Firebase Firestore, which included step counts, heart rate, and ECG recordings. The Spezi Data Pipeline was configured to connect to the Firebase Firestore server, using secure authentication protocols to ensure data privacy and security. Specifically, raw HealthKit observations collected from the Apple Watch were transformed into HL7 FHIR-compliant resources using the Spezi data ingestion layer prior to storage. These FHIR-formatted JSON resources were then stored in a Firebase-backed cloud database and retrieved by the Data Access module using configurable, study-specific access logic. The data of interest-including ECG recordings stored as FHIR observations, were specified through the Pipeline’s interface. Support for additional storage backends can be achieved by implementing alternative data access components without modifying downstream processing, flattening, or analysis modules. Upon retrieval, the ECG data were processed and transformed into a structured flat-table format, including fields such as patient ID, resource ID, timestamp, heart rate, ECG waveform data, and Apple Watch-provided classifications. These classifications helped to facilitate the identification and prioritization of abnormal recordings for review. The resulting table was exported locally for the study’s records and then fed into the software’s exploration tools.

Although the Pediatric Apple Watch Study serves as the primary validation use case, the Spezi Data Pipeline is designed to operate on any FHIR-compliant Observation or QuestionnaireResponse resource, independent of device vendor. This includes routinely collected data streams such as accelerometry-derived activity metrics, heart rate and heart rate variability, oxygen saturation, sleep summaries, and patient-reported outcomes generated by smartphones, wearables, or clinical devices. Because all processing and querying are performed using standardized codes (e.g., LOINC) and FHIR resource structures, the same infrastructure can be applied without modification to datasets collected across different devices or studies.

Two workflows were developed in order to load, pre-process, and evaluate the stored ECG data. These workflows incorporated the open-source Spezi Data Pipeline alongside an additional data review component, enabling clinicians to assign diagnoses and annotate recordings with relevant notes. A custom-built interactive tool was specifically designed for reviewing ECG data. This tool integrates the visualization capabilities of the Spezi Data Pipeline into an interactive dashboard in the form of a Python notebook. Clinicians access the system by connecting to the database, downloading the required data, and utilizing the tool to load and evaluate ECG recordings. Clinicians must enter their initials to initiate the review process, after which the dashboard displays the number of recordings available for review. For each ECG trace, clinicians can assign a diagnosis from predefined categories, including “Normal Sinus Rhythm,” “Sinus Tachycardia,” “Supraventricular Tachycardia (SVT),” “Ectopic Atrial Tachycardia (EAT),” “Atrial Fibrillation (AF),” “Ventricular Tachycardia (VT),” “Heart Block,” or “Other.” Clinicians can additionally assess trace quality using a five-tier scale ("Uninterpretable,” “Poor Quality,” “Adequate,” “Good,” or “Excellent”), and have the option to add patient- or trace-specific notes to provide further context or clarification. All annotations and diagnoses are saved and stored back to the cloud. A schematic representation of the interactive dashboard is shown in Fig. 2.

Additionally, an alternative workflow is available, enabling clinicians to navigate through the ECG recording and allowing the selection and visualization of specific recordings using various filters, including age group, ECG classification (as provided by the AppleWatch), user ID, and date. The notebook-based interactive dashboard is illustrated in Fig. 2.

Author contributions

V.B. led the conceptualization and development of the Spezi Data Pipeline, carried out all code implementation, and drafted the manuscript. O.A. conceived the study, provided overall supervision, and contributed to study design. P.S. contributed to study design. A.R. developed components of the questionnaire module. A.Z. and S.R.C. provided clinical expertise, contributed to recruitment, and oversaw execution of the Pediatric Apple Watch Study (PAWS). M.T. contributed to the data collection algorithm. L.A. contributed to proofreading and text improvements. V.R. contributed to data analysis and interpretation. All authors discussed the results, provided feedback, and contributed to the final manuscript.

Data availability

The real-world data from the Pediatric Apple Watch Study (PAWS) is not publicly available due to patient privacy considerations and regulatory restrictions. Access to PAWS data is governed by Stanford University Institutional Review Board (IRB) protocols and may be granted upon request, subject to appropriate ethical approvals and data use agreements.

Code availability

The Spezi Data Pipeline codebase is available on GitHub. It is also distributed as a Python package via PyPI: https://pypi.org/project/spezi-data-pipeline/0.1.0/. Documentation, usage examples, and contribution guidelines are provided in the GitHub repository. An experimental codebase demonstrating how to use the spezi_data_pipeline package for managing, analyzing, and visualizing healthcare data from Firebase Firestore is available at https://github.com/StanfordSpezi/SpeziDataPipelineTemplate. This template showcases practical examples and use cases to support integration into real-world research workflows.

Competing interests

The authors declare no competing interests.