DataTools4Heart_Milestone MS12_Documentation and user manuals for the toolbox and VAs available for researchers, cardiologists, and data managers

Page 1 of 12 DataTools4Heart A European Health Data Toolbox for Enhancing Cardiology Data Interoperability, Reusability and Privacy Milestone MS12: Documentation and user manuals for the toolbox and VAs available for researchers, cardiologists, and data managers Reference MS12_ DataTools4Heart_AT_30092025 Lead Beneficiary ATH Author(s) Konstantinos Kechagias (ATH), Laia Codó, Carles Hernandez-Ferrer (BSC), Jorge Fabila, Cristian Izquierdo (UB) Dissemination level Public Means of verification Available at the platform and project’s web-site Official Delivery Date 30/09/2025 Date of validation of the WP leader 29/09/2025 Date of validation by the Project Coordinator 30/09/2025 Project Coordinator Signature DataTools4Heart is funded by the European Union’s Horizon Europe Framework Under Grant Agreement No. 101057849. Page 2 of 12 Version Log Issue Date Version Involved Comments 18/08/2025 0.1 Konstantinos Kechagias Initial Draft & ToC Structure 16/09/2025 0.2 Konstantinos Kechagias, Laia Codó, Carles Hernandez-Ferrer, Jorge Fabila, Cristian Izquierdo First Document Review 29/09/2025 0.3 Konstantinos Kechagias, Carles Hernandez-Ferrer, Jorge Fabila, Cristian Izquierdo Final Draft Review 30/09/2025 Final Cristian Izquierdo, Xènia Puig, Karim Lekadir Revised and corrected final version Executive Summary Milestone MS12 establishes the availability of user-oriented documentation and manuals for the DataTools4Heart (DT4H) toolbox and Virtual Assistants (VAs). The objective is to provide end-users, namely researchers, cardiologists, and data managers, with structured guidance on how to navigate and interact with DT4H components in their respective contexts. The manuals focus on user flows, outlining the steps and interactions required to perform typical tasks with the toolbox and VAs. For researchers, the documentation provides pathways to explore data and analytical functionalities; for cardiologists, it demonstrates the integration of VAs within clinical decision support workflows; and for data managers, it specifies how the toolbox supports data access, governance, and compliance. Prepared in a concise, accessible, and role-specific manner, the documentation enables stakeholders to quickly identify the functionalities most relevant to their activities. To ensure usability and dissemination, the manuals are consolidated in the DT4H documentation hub hosted on GitHub, which serves as the central access point for all components and tools. The means of verification for this milestone is the confirmed availability of these user guides and manuals in the DT4H repositories. This milestone ensures that the DT4H toolbox and VAs are not only technically operational but also practically usable and aligned with the workflows of the intended enduser communities. Page 3 of 12 Table of Contents Version Log ................................................................................................................................. 2 Executive Summary .................................................................................................................... 2 Acronyms .................................................................................................................................... 3 List of figures .............................................................................................................................. 3 1 Introduction .............................................................................................................................. 4 1.1 Purpose of the Milestone (ATH) ...................................................................................... 4 1.2 Relation to Project Objectives and Work Packages (ATH) ............................................... 4 2 Methodology ............................................................................................................................ 4 2.1 Documentation Development Process (BSC, UB) ........................................................... 5 2.2 Target User Groups (Researchers, Cardiologists, Data Managers) (BSC, UB) ............... 6 3 Documentation and User Manuals (ATH) ................................................................................. 6 3.1 Platform Documentation (technical manuals) (BSC, UB) ................................................. 6 3.2 Virtual Assistant Documentation (ATH) ........................................................................... 6 3.3 Metadata Catalogue ........................................................................................................ 7 3.4 MIP Documentation ......................................................................................................... 7 3.5 FLCore ............................................................................................................................ 7 4 Accessibility, Dissemination, and Verification ......................................................................... 12 4.1 Availability in DT4H Repositories (BSC, UB, ATH) ........................................................ 12 5 Conclusion ............................................................................................................................. 12 Acronyms FEM: Federated Execution Manager VA: Virtual Assistant List of figures Figure 1. Structure of the centralized documentation repository on GitHub Pages Page 4 of 12 1 Introduction The DataTools4Heart (DT4H) project delivers a toolbox of privacy-preserving components for federated cardiology data analysis, together with a Virtual Assistant (VA) to support intuitive use. To ensure these tools can be effectively adopted, clear documentation is required. Milestone MS12 confirms the availability of user manuals for a selected set of toolbox components and the VA. These manuals focus on user flows and task-oriented guidance, enabling researchers, cardiologists, and data managers to apply the tools in practice without deep technical expertise. 1.1 Purpose of the Milestone The purpose of MS12 is to verify that accessible user documentation is provided for the DT4H toolbox components and the VA. The manuals outline typical workflows for different user groups and are published on both the DT4H platform and the project website, ensuring transparency, usability, and wider uptake of project results. 1.2 Relation to Project Objectives and Work Packages Milestone MS12 contributes to the project’s objectives of usability, transparency, and adoption by providing role-specific documentation for the DT4H toolbox and the Virtual Assistant. The manuals enable researchers, cardiologists, and data managers to follow clear user flows, ensuring that technical outcomes can be effectively applied in practice. This milestone is closely linked to: ● WP6 – Integrated Platform, Virtual Assistants, and Sustainability, which delivers the toolbox components and the VA addressed in the manuals. ● WP7 – Clinical Use Cases: Design, Implementation and Validation, where user documentation supports testing and validation in clinical settings. ● WP8 – Coordination, Management, Dissemination, Communication and Exploitation, through the publication and dissemination of manuals via the DT4H platform and project website. Through these connections, MS12 ensures that technical developments are complemented by accessible documentation, facilitating clinical validation and long-term sustainability. 2 Methodology To ensure that the documentation and user manuals are easily accessible and consistently maintained, a centralized documentation hub has been established using GitHub Pages (https://github.com/DataTools4Heart/documentation-hub). By consolidating all materials in one place, the hub provides a single-entry point for researchers, cardiologists, and data managers, avoiding fragmentation and facilitating intuitive navigation across the platform’s resources. The repository has been designed with a clear and modular structure that supports both transparency and long-term scalability. At the root level, each of the main platform components is allocated a dedicated folder, namely ai-dashboard, metadata-catalogue, and virtual-assistant, each containing its respective documentation. Complementing these, a tools-manuals directory has been created to host subfolders for every tool that can be triggered via the main platform, with each tool maintaining its own documentation space. In addition, an assets folder is included to store supplementary materials such as figures, images, and configuration files that enrich the manuals and improve user understanding. Page 5 of 12 All manuals are authored in Markdown (.md), a lightweight markup format that ensures both human readability and compatibility with GitHub Pages. This choice not only enables straightforward collaborative editing and version control through GitHub but also guarantees that updates and extensions can be integrated without disrupting the existing structure. The Markdown-based workflow further supports modular growth, as new components and tools can be added seamlessly while maintaining consistency in style and format. The overall repository structure is illustrated in Figure 1, which presents the folder organization of the documentation hub. This figure highlights the hierarchical arrangement of components, tools, and supporting assets, thereby offering users a clear overview of where to locate the documentation of interest. By combining structured organization, web accessibility, and collaborative editing features, the methodology ensures that the documentation remains a reliable, scalable, and user-friendly resource for all target stakeholders. Figure 1. Structure of the centralized documentation repository on GitHub Pages. 2.1 Documentation Development Process The development of documentation for individual tools follows a standardized workflow designed to ensure consistency and maintainability across the documentation hub. Tool developers are required to use the standard “fork and pull request” model, working directly with the GitHub repository at https://github.com/DataTools4Heart/documentation-hub. The process consists of the following steps: 1. Access the repository by visiting https://github.com/DataTools4Heart/documentation-hub. Page 6 of 12 2. Clone or fork the repository and create a dedicated branch for the new tool. Create a folder named after the tool, following CSS naming conventions (lowercase words separated by hyphens, e.g., my-amazing-tool). 3. Add an index.md file in this folder containing the main documentation, and include any additional .md files if needed, referenced from the index.md. 4. Update the root-level index.md file by inserting a link to the new tool’s documentation under the Tools Manuals section, maintaining alphabetical order. Commit and push all changes to the branch or fork. 5. Open a pull request to merge the branch or fork into the main branch of the official repository. Following these steps ensures that all tool documentation is consistently integrated into the centralized hub, maintaining clarity, accessibility, and version control. 2.2 Target User Groups (Researchers, Cardiologists, Data Managers) (BSC, UB) For clinical users, DT4H FL platform integrates virtual assistants, a wide range of AI models, and intuitive interfaces that allow seamless navigation and query access to structured patient data, risk stratification tools, and diagnostic models. These features are designed to support decision-making processes, assist in cohort exploration, and integrate directly into clinical workflows for more precise diagnosis and improved patient care. Cardiologists can benefit from federation-enabled analytics, enabling collaborative studies while safeguarding patient privacy. The platform itself does not contain a specific inference interface, but clinicians can easily export their own generated AI models to be deployed in their clinical practice tools. Manual users of the FL platform include AI models explanations that are easily interpretable for non-technical/software developers’ experts. 3 Documentation and User Manuals 3.1 Platform Documentation (technical manuals) The Federated Execution Manager (FEM) was designed to run and monitor data analytics tools across a network of remote nodes without exposing their sensitive data or requiring data transfer from the original source. The guideline is for a researcher or data scientist to use it though the AI Dashboard is located at the documentation hub under the section of "AI Dashboard". You can find this section here: https://datatools4heart.github.io/documentation-hub/ai-dashboard/ 3.2 Virtual Assistant Documentation The Virtual Assistant (VA) was designed to support clinical researchers in cardiology by enabling natural language interaction through a chat interface. It allows researchers to explore studies, discover patient cohorts, and request metadata in a federated and privacy-preserving way without requiring data transfer from hospital nodes. The VA supports interaction in seven European languages, ensuring accessibility across the research community. The VA guideline is located at the documentation hub under the section of "Virtual Assistant": https://datatools4heart.github.io/documentation-hub/virtual-assistant/ Page 7 of 12 3.3 Metadata Catalogue The DataTools4Heart Catalogue is an AI-ready cardiology dataset discovery portal based on the Mica (OBiBa) platform. It provides public access to study metadata, dataset descriptions, and AI features. The user manual for researchers and clinicians is accessible at the documentation hub under the section of "Metadata Catalogue". You can find this section here: https://datatools4heart.github.io/documentation-hub/metadata-catalogue/ 3.4 MIP Documentation The Medical Informatics Platform (MIP) is a user-friendly federated learning and analytics platform with an intuitive, graphical user interface tailored for clinicians. https://github.com/KFilippopolitis/documentation-hub/blob/mip-doc/docs/mip/index.md 3.5 FLCore This library provides a flexible and extensible framework for running experiments in a federated learning environment, enabling the training and evaluation of different machine learning models across distributed datasets. Figure 2. Screenshot of the Virtual Research Environment (VRE) of DT4H. The following methods are currently implemented along with the flower aggregation method used and the code used for selecting a specific method. Model Flwr aggregation method Code Logistic regression Federated Average logistic_regression SGD classifier Federated Average lsvc Page 8 of 12 Elastic net Federated Average elastic_net Random Forest Custom weighted_random_forest Deep Learning Federated Average neural_network Parameters are provided using a command line interface and are organized by category and include their name, type, default value, and a brief explanation. These arguments can be modified at runtime to customize data handling, model configuration, training setup, and infrastructure details. The next table summarizes the variables needed for the client. Parameter Type Default value Description --dataset str None Name of the dataloader to use –data_id data_id str Identifier of the dataset file – normalization_metho d str IQR Normalization method. Options: `IQR`, `STD`, `MIN_MAX`. –train_labels list[str] None Labels used for training. –target_label list[str] None Target label(s) for prediction. –train_size float 0.8 Fraction of dataset used for training. Must be in [0,1). –num_clients int 1 Number of clients in the federated setting. –model str random_forest Base model to train. –num_rounds int 50 Number of federated training rounds. -- checkpoint_selection _metric str precision Metric used to select checkpoints. –dropout_method str None Dropout method applied during Page 9 of 12 training. –smooth_method str None Weight smoothing method. –random_forest json {"balanced_rf": "true"} Parameters for training a Random Forest model. The balanced_rf flag indicates whether to balance the class weights during training. – weighted_random_fo rest json {"balanced_rf": "true", "levelOfDetail": "DecisionTree"} Parameters for a Weighted Random Forest. In addition to balanced_rf, this variant includes levelOfDetail, which specifies the granularity of decision trees. --neural_network json {"dropout_p": 0.2, "device": "cpu", "local_epochs": 10} Configuration parameters for Neural Networks. Includes dropout probability (dropout_p), training device (cpu or cuda), and the number of local training epochs. –T int 20 Number of Monte Carlo dropout samples used for uncertainty estimation in Bayesian-style neural networks. –linear_models json {“n_features”: 9} Number of input features expected by the linear model --sandbox_path str /sandbox Path to the sandbox directory used for isolated execution or