# sawelch-niva/vm_explorer architecture

> Architecture diagram of the GitHub repository sawelch-niva/vm_explorer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sawelch-niva/vm_explorer
- Repository: https://github.com/sawelch-niva/vm_explorer

## Overview

##### Project’s Purpose and Overall Structure
- The project is an analytical tool built using R. Its focus is on exploring and visualizing datasets related to aquaculture, species information (including copper and trophic data), and mapping/regional exposures.
- The overall purpose seems to be to ingest raw data (spreadsheets, CSVs, GeoJSON), process and analyze this data via different R scripts, and then produce visual outputs including plots and possibly compartment trees.

##### Main Components
a. Data Layer:
- Input Files: Represent files from the R/data folder that include Excel sheets, CSV files (e.g., Aquaculture_Total_Weight.xlsx, copper_species_lookup.csv, trophic_data.csv), and GeoJSON files.
- Example External Files: The additional example_copper_data.csv can be noted as a sample input.
b. Processing/Analytical Layer:
- Core R Scripts: Scripts like RUNME.R (likely the orchestrator), farmed_fish_plot.R, fishbase_fragment.R, plot_density_tissue_concentration.R, plot_map_regional_exposure.R, and plot_pca_factors.R. Each of these represents a module that handles a specific type of data analysis or visualization.
c. Presentation/UI/Visualization Layer:
- Plots Output: The “plots” directory likely stores generated visualizations.
- Theme Customization: The R/theme folder contains scripts (fct_fonts.R and fct_theme.R) that standardize the visual presentation (fonts/themes) of the outputs.
d. Project Configuration:
- Rproj file (Vm_Exploration.Rproj) sets up the project environment within RStudio.
- The .gitignore file for repository management.

##### Interactions and Data Flow
- That each analytical module (each R script) takes data from the input layer, processes it, and then communicates with the visualization layer to produce plots and output files.
- The theme components are used by the plotting scripts to format the visual outputs consistently.
- Optionally, show that the compartment_tree.gv (Graphviz output) may represent relationships between compartments or data clusters, potentially used alongside analytical outputs.

##### Architectural Patterns and Design Principles
- Modular Design: Each script appears designed to handle a discrete aspect of the analysis (e.g., mapping, PCA, density plotting).
- Separation of Concerns: Data ingestion, processing, and visualization concerns are clearly separated into different folders and files.
- Configurability and Reusability: The theme scripts are in a dedicated folder, reflecting a DRY (Don’t Repeat Yourself) approach for styling, and the use of a project file (.Rproj) suggests an organized development environment.

##### Relevant Technologies and Frameworks
- Programming Language: R.
- Data Formats: Excel, CSV, GeoJSON.
- Visualization Libraries: Though not explicitly mentioned, the various plot_* scripts likely rely on R packages such as ggplot2, and might use Graphviz for the compartment tree.
- Environment: RStudio (as indicated by the Rproj file).

##### Instructing the Principal Software Engineer
- Rather than a simplistic overview, break down the processing layer into its individual analysis modules. This will help in mapping dependencies (for example, if plot_map_regional_exposure.R relies on processed geographic data from the GeoJSON file).
- Use annotated labels to denote which R scripts handle specific functionalities (e.g., mapping, PCA analysis, density plotting).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Data Layer"
        DATA["Input Data Files (R/data)"]:::data
    end

    subgraph "Processing Layer"
        RUNME["RUNME.R (Orchestrator)"]:::processing
        FISHPLOT["Farmed Fish Plot (R/farmed_fish_plot.R)"]:::processing
        FISHFRAG["Fishbase Fragment (R/fishbase_fragment.R)"]:::processing
        DENSITY["Density Tissue Plot (R/plot_density_tissue_concentration.R)"]:::processing
        MAPEXP["Regional Exposure Map (R/plot_map_regional_exposure.R)"]:::processing
        PCA["PCA Factors Plot (R/plot_pca_factors.R)"]:::processing
    end

    subgraph "Visualization/Output Layer"
        THEME["Plot Styling/Themes (R/theme)"]:::visual
        PLOTS["Generated Visualizations (plots)"]:::visual
        COMP["Compartment Diagram (compartment_tree.gv)"]:::visual
    end

    subgraph "Project Configuration"
        CONFIG["Project Config (Vm_Exploration.Rproj)"]:::config
        GIT["Version Control (.gitignore)"]:::config
    end

    %% Data ingestion flow
    DATA -->|"ingests"| RUNME

    %% Orchestrator triggers processing modules
    RUNME -->|"triggers"| FISHPLOT
    RUNME -->|"triggers"| FISHFRAG
    RUNME -->|"triggers"| DENSITY
    RUNME -->|"triggers"| MAPEXP
    RUNME -->|"triggers"| PCA
    RUNME -->|"generates"| COMP

    %% Processing modules output visualizations
    FISHPLOT -->|"outputs"| PLOTS
    FISHFRAG -->|"outputs"| PLOTS
    DENSITY -->|"outputs"| PLOTS
    MAPEXP -->|"outputs"| PLOTS
    PCA -->|"outputs"| PLOTS

    %% Visualization layer uses theme styling
    THEME -->|"styles"| PLOTS

    %% Project configuration influences processing
    CONFIG -->|"configures"| RUNME

    %% Styles
    classDef data fill:#e8faff,stroke:#007acc,stroke-width:2px;
    classDef processing fill:#fff3cd,stroke:#ff9f00,stroke-width:2px;
    classDef visual fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef config fill:#f8d7da,stroke:#dc3545,stroke-width:2px;

    %% Click Events
    click DATA "https://github.com/sawelch-niva/vm_explorer/tree/master/R/data"
    click RUNME "https://github.com/sawelch-niva/vm_explorer/blob/master/R/RUNME.R"
    click FISHPLOT "https://github.com/sawelch-niva/vm_explorer/blob/master/R/farmed_fish_plot.R"
    click FISHFRAG "https://github.com/sawelch-niva/vm_explorer/blob/master/R/fishbase_fragment.R"
    click DENSITY "https://github.com/sawelch-niva/vm_explorer/blob/master/R/plot_density_tissue_concentration.R"
    click MAPEXP "https://github.com/sawelch-niva/vm_explorer/blob/master/R/plot_map_regional_exposure.R"
    click PCA "https://github.com/sawelch-niva/vm_explorer/blob/master/R/plot_pca_factors.R"
    click THEME "https://github.com/sawelch-niva/vm_explorer/tree/master/R/theme"
    click PLOTS "https://github.com/sawelch-niva/vm_explorer/tree/master/plots"
    click COMP "https://github.com/sawelch-niva/vm_explorer/blob/master/compartment_tree.gv"
    click CONFIG "https://github.com/sawelch-niva/vm_explorer/blob/master/Vm_Exploration.Rproj"
    click GIT "https://github.com/sawelch-niva/vm_explorer/blob/master/.gitignore"
```
