# metodologianavarrabiomed/mice-ext-val architecture

> Architecture diagram of the GitHub repository metodologianavarrabiomed/mice-ext-val, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/metodologianavarrabiomed/mice-ext-val
- Repository: https://github.com/metodologianavarrabiomed/mice-ext-val

## Overview

This project is an R package designed to facilitate the external validation of predictive models—specifically Cox and logistic regression models—in the context of multiple imputation analysis. Its purpose is to provide a set of functions that define models (mv_model_cox and mv_model_logreg), calculate predictions (including two types of recalibration), compute performance metrics (like the Harrell’s C-index), and produce visualizations such as calibration plots and C-index forestplots.

##### Main Components
- Code Base and Package Structure:
- The DESCRIPTION, NAMESPACE, and other configuration files indicate it is a standard R package.
- Data Layer:
- The “data” directory holds example datasets (e.g., framingham.rda) used for demonstration or testing.
- Testing and Documentation:
- The “tests” directory contains unit tests (using testthat) that assure the validity of functions.
- The “docs” and “vignettes” directories contain documentation and guides (using pkgdown and Quarto) that explain usage and workflow.
- Model Workflow Components:
- Model Definition: Functions like mv_model_cox and mv_model_logreg.
- Prediction Calculation: Functions starting with calculate_predictions and “calculate_predictions_recalibrated_type_1”/“type_2”.
- Aggregation and Metric Calculation: e.g., calculate_c_index.
- Visualization: Functions like get_calibration_plot_data, get_calibration_plot, and get_c_index_forestplot.
- Supporting Files:
- Configuration (e.g., pkgdown.yml) and GitHub workflows to ensure continuous integration and documentation generation.

##### Out the Relationships and Data Flow
- Analysis Pipeline for Each Imputed Dataset:
- Model Application:
- Link each imputed dataset node to a “Results Analysis” node (each computed using a predict function).
- Aggregate these individual results into a unified “Aggregated Results” node.
- Post-Aggregation Actions:
▪ A “Calibration Plot” node (through get_calibration_plot_data and get_calibration_plot functions).
▪ A “C-index Forestplot” node (via get_c_index_forestplot).
- Support Infrastructure:
- A peripheral section indicating “Testing” with testthat and “Documentation” (docs, vignettes) as supportive pillars in the overall design.

##### Important Architectural Patterns
- Modularity: The package cleanly separates model definition, prediction calculation, performance metric aggregation, and visualization into distinct function groups.
- Reusability: Functions are designed to be chained using R’s native pipe operator (|>), showing a clear pipeline processing from raw imputed data through to final output.
- Extensibility: The presence of different prediction calculation methods and plotting functions indicates a design meant to be extended for additional statistical models or recalibration approaches.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Layer"
        A["Multiple Imputed Data Source"]:::data
        click A "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/data/framingham.rda"
    end

    subgraph "Imputation Datasets"
        B["Imputed Analysis Dataset 1 ... n"]:::data
    end

    A --> B

    subgraph "Analysis Pipeline"
        C["Results Analysis"]:::analysis

        subgraph "Model Definition"
            D1["mv_model_cox"]:::module
            click D1 "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/mv_model_cox.R"
            D2["mv_model_logreg"]:::module
            click D2 "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/mv_model_logreg.R"
        end

        subgraph "Prediction Calculation"
            E1["calculate_predictions"]:::module
            click E1 "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/calculate_predictions.R"
            E2["calculate_predictions_cox"]:::module
            click E2 "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/calculate_predictions.cox.R"
            E3["calculate_predictions_logreg"]:::module
            click E3 "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/calculate_predictions.logreg.R"

            F1["calculate_predictions_recalibrated_type_1"]:::module
            click F1 "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/calculate_predictions_recalibrated_type_1.R"
            F2["calculate_predictions_recalibrated_type_1_cox"]:::module
            click F2 "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/calculate_predictions_recalibrated_type_1.cox.R"
            F3["calculate_predictions_recalibrated_type_1_logreg"]:::module
            click F3 "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/calculate_predictions_recalibrated_type_1.logreg.R"

            G1["calculate_predictions_recalibrated_type_2"]:::module
            click G1 "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/calculate_predictions_recalibrated_type_2.R"
            G2["calculate_predictions_recalibrated_type_2_cox"]:::module
            click G2 "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/calculate_predictions_recalibrated_type_2.cox.R"
            G3["calculate_predictions_recalibrated_type_2_logreg"]:::module
            click G3 "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/calculate_predictions_recalibrated_type_2.logreg.R"
        end

        subgraph "Performance Metric Calculation"
            H["calculate_c_index"]:::module
            click H "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/calculate_c_index.R"
        end

        %% Internal connections within Analysis Pipeline
        D1 --- D2
        D2 --> E1
        E1 --- E2
        E2 --- E3
        E3 --> F1
        F1 --- F2
        F2 --- F3
        F3 --> G1
        G1 --- G2
        G2 --- G3
        G3 --> H

        %% Overall flow from imputed datasets into analysis
        B --> C
        D1 --> C
        D2 --> C
        E1 --> C
        F1 --> C
        G1 --> C
        H --> C
    end

    subgraph "Aggregation and Visualization"
        I["Aggregated Results"]:::analysis
        C --> I

        J["Calibration Plot"]:::visualization
        K["C-index Forestplot"]:::visualization
        I --> J
        I --> K

        subgraph "Calibration Plot Functions"
            L["get_calibration_plot_data"]:::module
            click L "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/get_calibration_plot_data.R"
            M["get_calibration_plot"]:::module
            click M "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/get_calibration_plot.R"
            N["get_stratified_calibration_plot"]:::module
            click N "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/get_stratified_calibration_plot.R"
        end

        subgraph "C-index Forestplot Functions"
            O["get_forestplot_data"]:::module
            click O "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/get_forestplot_data.R"
            P["get_forestplot"]:::module
            click P "https://github.com/metodologianavarrabiomed/mice-ext-val/blob/master/R/get_forestplot.R"
        end

        L --> J
        M --> J
        N --> J
        O --> K
        P --> K
    end

    subgraph "Support Infrastructure"
        Q["Testing (testthat)"]:::support
        click Q "https://github.com/metodologianavarrabiomed/mice-ext-val/tree/master/tests/"
        R["Documentation (docs)"]:::support
        click R "https://github.com/metodologianavarrabiomed/mice-ext-val/tree/master/docs/"
        S["Usage Guides (vignettes)"]:::support
        click S "https://github.com/metodologianavarrabiomed/mice-ext-val/tree/master/vignettes/"
    end

    %% Styling classes
    classDef data fill:#FDEBD0,stroke:#E67E22,stroke-width:2px;
    classDef analysis fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef visualization fill:#D5F5E3,stroke:#2ECC71,stroke-width:2px;
    classDef support fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef module fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
```
