# paviag/pf-bula-castillo-garcia architecture

> Architecture diagram of the GitHub repository paviag/pf-bula-castillo-garcia, 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/paviag/pf-bula-castillo-garcia
- Repository: https://github.com/paviag/pf-bula-castillo-garcia

## Overview

##### Project Components
- Data Input/Raw Data: The project likely uses medical images that may come from DICOM files. Although the data source isn’t fully detailed here, the existence of a dicom_reader (in src/preprocessing/dicom_reader.py) indicates the initial data acquisition.
- Preprocessing Module: This module (found in src/preprocessing) includes components to read images (image_handler), process annotations (annotation_processor), and a main script to kick off preprocessing. It is responsible for preparing the raw image and annotation data.
- Augmentation Module: Residing in src/augmentation, this part contains the image_augmentation tool and an annotation_handler. It’s meant to further modify or enrich your data – for instance, applying rotations, flips, or more sophisticated augmentation strategies to improve model generalization.
- Model Module: Located in src/model, with scripts like model.py and model_setup.py, this module defines the neural network structure. Note that YOLO weights (yolo11n.pt and yolov8n.pt) present at the root signify that the model may leverage transfer learning with YOLO-family architectures.
- Tuning Module: In src/tuning, several scripts (study_manager.py, train_index.py, trainer.py, and main.py) suggest usage of a hyperparameter tuning framework (possibly using something like Optuna as hinted by the CSV output filename “optuna_best_trials.csv”). This component manages iterative experiments on model parameters.
- Evaluation Module: In src/evaluation (main.py), this plug-in evaluates model performance, likely reading outputs from the training/tuning phase and generating performance metrics.
- Configuration and Utilities: The configuration file in src/config/config.py and additional helper scripts (e.g., src/extra/utils.py) underscore the use of centralized settings and various utility functions for smoother integration between modules.
- Output Directory: The output folder holds results (validation outputs, annotations, best trial summaries) which serve as the final feedback from the entire pipeline.

##### Mapping Relationships and Interactions
- Data flows into the preprocessing module first where raw data from an external source is parsed and formatted.
- The preprocessed data then moves to the augmentation module where image and annotation data are augmented to create variability required for robust training.
- Augmented data is passed to the model module where the neural network (perhaps initialized or fine-tuned via supplied YOLO weights) is defined and trained.
- The tuning module sits around the training process to optimize hyperparameters through an iterative scaling loop, feeding best configurations back to the model training.
- Following training, the evaluation module runs an assessment on model outputs. The evaluation results, along with other logs, are stored in the output directory.
- Throughout these steps, configuration settings (from src/config/config.py) provide centralized parameters and control, while auxiliary utilities (in src/extra) offer additional support functions.

##### Architectural Patterns and Technologies
- The project is structured as a sequential deep-learning pipeline where each module is clearly separated (a form of separation of concerns). This might loosely follow an MVC-like pattern by separating out data handling (preprocessing and augmentation) from the model and evaluation components.
- There is also an experimentation loop present in the tuning module, which implies a systematic approach to hyperparameter optimization (potentially using libraries such as Optuna).
- External pre-trained weights from YOLO models point to leveraging established architectures with transfer learning.

## Diagram (Mermaid)

```mermaid
flowchart TD
    DS["Data Source"]:::data

    subgraph "Preprocessing Module"
        dicom_reader["DICOM Reader"]:::preprocessing
        image_handler["Image Handler"]:::preprocessing
        annotation_processor["Annotation Processor"]:::preprocessing
        preprocessing_main["Preprocessing Pipeline Script"]:::preprocessing
    end

    subgraph "Augmentation Module"
        image_augmentation["Image Augmentation"]:::augmentation
        annotation_handler["Annotation Handler"]:::augmentation
        augmentation_main["Augmentation Launcher"]:::augmentation
    end

    subgraph "Model Module"
        model_definition["Model Definition"]:::model
        model_setup["Model Setup"]:::model
        yolo_weight1["YOLO Weight (yolo11n.pt)"]:::model
        yolo_weight2["YOLO Weight (yolov8n.pt)"]:::model
    end

    subgraph "Tuning Module"
        tuning_manager["Tuning Management"]:::tuning
        train_index["Training Index"]:::tuning
        tuning_trainer["Training/Optimization Script"]:::tuning
        tuning_main["Tuning Main"]:::tuning
    end

    subgraph "Evaluation Module"
        evaluation_main["Evaluation Script"]:::evaluation
    end

    output["Output Directory"]:::output

    subgraph "Configuration & Utilities"
        config["Configuration Settings"]:::config
        utilities["Utility Functions"]:::config
    end

    %% Data flow connections
    DS -->|"ingests"| dicom_reader
    dicom_reader -->|"reads"| image_handler
    image_handler -->|"processes"| annotation_processor
    annotation_processor -->|"initiates"| preprocessing_main

    preprocessing_main -->|"feeds"| augmentation_main
    augmentation_main -->|"triggers"| image_augmentation
    augmentation_main -->|"triggers"| annotation_handler

    augmentation_main -->|"supplies data to"| model_definition
    model_definition -->|"configured by"| model_setup
    model_setup -->|"loads"| yolo_weight1
    model_setup -->|"loads"| yolo_weight2

    model_definition -->|"optimizes"| tuning_trainer
    tuning_trainer -->|"executes loop"| tuning_main
    tuning_main -->|"updates"| model_definition

    model_definition -->|"evaluated by"| evaluation_main
    evaluation_main -->|"generates"| output

    %% Configuration and Utilities support
    config -.-> preprocessing_main
    config -.-> augmentation_main
    config -.-> model_definition
    config -.-> tuning_main
    config -.-> evaluation_main

    utilities -.-> preprocessing_main
    utilities -.-> augmentation_main
    utilities -.-> model_definition
    utilities -.-> tuning_main
    utilities -.-> evaluation_main

    %% Click Events
    click dicom_reader "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/preprocessing/dicom_reader.py"
    click image_handler "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/preprocessing/image_handler.py"
    click annotation_processor "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/preprocessing/annotation_processor.py"
    click preprocessing_main "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/preprocessing/main.py"
    click image_augmentation "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/augmentation/image_augmentation.py"
    click annotation_handler "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/augmentation/annotation_handler.py"
    click augmentation_main "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/augmentation/main.py"
    click model_definition "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/model/model.py"
    click model_setup "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/model/model_setup.py"
    click yolo_weight1 "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/yolo11n.pt"
    click yolo_weight2 "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/yolov8n.pt"
    click tuning_manager "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/tuning/study_manager.py"
    click train_index "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/tuning/train_index.py"
    click tuning_trainer "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/tuning/trainer.py"
    click tuning_main "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/tuning/main.py"
    click evaluation_main "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/evaluation/main.py"
    click config "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/config/config.py"
    click utilities "https://github.com/paviag/pf-bula-castillo-garcia/blob/main/src/extra/utils.py"
    click output "https://github.com/paviag/pf-bula-castillo-garcia/tree/main/output"

    %% Styles
    classDef data fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef preprocessing fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef augmentation fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef model fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef tuning fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef evaluation fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef output fill:#E6E6FA,stroke:#333,stroke-width:2px;
```
