# yaroslavsobolev/robowski-maps architecture

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

- Interactive diagram: https://gitdiagram.com/yaroslavsobolev/robowski-maps
- Repository: https://github.com/yaroslavsobolev/robowski-maps

## Overview

##### Project type and purpose
- This is a scientific software suite (Python-based monorepo) that automates robotic experiments (pipetting, washing, microspectrometry), ingests raw spectral and run data, performs calibration and spectral unmixing, fits kinetic models, and visualizes chemical reaction hyperspaces for a Nature paper.

##### High-level components
A. Hardware Control Layer
- zeus-pipetter: scripts (main.py, scheduler.py, pipetter.py, etc.) and Arduino/GRBL firmware for pipetting robot automation and NanoDrop spectrometer control
- washing_station: AxiDraw/FlowEZ pump interface to wash vial plates
- CRAIC automation: PyAutoGUI + OpenCV barcode capture to drive CRAIC microspectrometer GUI (under robowski/uv_vis_absorption_spectroscopy/craic_automation)

B. Data Ingestion & Calibration
- raw data files: spectrophotometer CSV/DSW/MSP files, run_info CSV, etc. stored under run-specific directories or BPRF/test folders
- calibration routines: calibrator.py, bkg_pca.py, absorbance_errorbar_model.py (under robowski/uv_vis_absorption_spectroscopy)
- environment variable ROBOCHEM_DATA_PATH points to large raw dataset archive

C. Spectral Unmixing & Data Processing
- spectral_unmixing_tutorial.ipynb & robowski/uv_vis_absorption_spectroscopy/examples: high-level “calibration_*.py” then “process_*.py” scripts produce results/product_concentration.csv
- summary_of_reaction_yield_data: consolidated CSV yield tables

D. Kinetic Modeling
- robowski/kinetics_models/E1_kinetics, simpleSN1_kinetics, Ugi_kinetics modules implement model fitting, bootstrapping, MCMC (emcee), and output numpy/CSV artifacts

E. Visualization
- robowski/visualize_results: static and animated viewers (mayavi), scripts to generate 3D/4D maps (plot_3d_map_for_*.py, view_4d_data_for_*.py)
- scripts under misc_scripts/figures_for_articles for publication-quality figures

F. Utilities, Theory & Tests
- geometric_algorithms, smoothness_theory, outlier_handling, misc_scripts modules for auxiliary computations, simulation, outlier marking
- tests folder contains end-to-end and unit tests for data parsing, processing, and expected outputs

##### Relationships & data flow
- Hardware Control → Raw Data Files
↳ Data Ingestion reads raw CSV/DSW/MSP
↳ Calibration produces calibration models (.npy, PCA components)
↳ Spectral Unmixing uses calibration + raw spectra → product_concentration.csv
↳ Summary tables assembled in summary_of_reaction_yield_data
↳ Kinetic Modeling consumes yields → model output arrays/plots
↳ Visualization consumes yields & model predictions → 3D/4D maps
↳ Notebooks link everything interactively

##### Architectural patterns & principles
- Layered, modular monorepo
- Hardware interface modules isolated from core library
- Core library (“robowski” package) organized by functionality (uv_vis_absorption_spectroscopy, kinetics_models, visualize_results, etc.)
- Extensibility: new reactions or hardware can be added as new subfolders under examples or new modules
- Reproducibility: environment.yml / requirements.txt for environment isolation; tests ensure regression safety

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Source
    DataArchive["ROBOCHEM_DATA_PATH (Raw Data Archive)"]:::external
    CloudZenodo["Zenodo / External Data"]:::external

    %% Hardware Control Layer
    subgraph "Hardware Control Layer"
        direction TB
        Pipetting["zeus-pipetter"]:::hardware
        Washing["washing_station"]:::hardware
        CRAIC["CRAIC Automation"]:::hardware
    end

    %% Raw Data Store
    RawData[(Raw Data Files)]:::data

    %% Data Ingestion & Calibration
    subgraph "Data Calibration & Ingestion" 
        direction TB
        Calibrator["calibrator.py"]:::processing
        PCA["bkg_pca.py"]:::processing
        ErrorModel["absorbance_errorbar_model.py"]:::processing
    end

    %% Spectral Unmixing
    subgraph "Spectral Unmixing"
        direction TB
        Tutorial["spectral_unmixing_tutorial.ipynb"]:::processing
        Examples["examples"]:::processing
        ProductCSV[(product_concentration.csv)]:::data
    end

    %% Summary Store
    Summary[(summary_of_reaction_yield_data)]:::data

    %% Kinetic Modeling
    subgraph "Kinetic Modeling" 
        direction TB
        E1["E1_kinetics"]:::modeling
        SN1["simpleSN1_kinetics"]:::modeling
        Ugi["Ugi_kinetics"]:::modeling
        ModelOutput[(Model Outputs CSV/Plots)]:::data
    end

    %% Visualization
    subgraph "Visualization"
        direction TB
        VizFramework["visualize_results"]:::visual
        FigScripts["figures_for_articles"]:::visual
        VisualOutput[(3D/4D Maps)]:::data
    end

    %% Utilities & Theory
    subgraph "Utilities & Theory"
        direction TB
        GeoAlgo["geometric_algorithms"]:::utilities
        Smooth["smoothness_theory"]:::utilities
        Outlier["outlier_handling"]:::utilities
        Misc["misc_scripts"]:::utilities
    end

    %% Test Suite
    Tests["tests"]:::testing

    %% Environment & Config
    EnvFiles["environment.yml / environment_without_mayavi.yml"]:::config
    BuildConfig["pyproject.toml / setup.cfg / requirements.txt"]:::config

    %% Data Flow Connections
    Pipetting -->|collects data| RawData
    Washing -->|collects data| RawData
    CRAIC -->|captures spectra| RawData
    DataArchive -->|provides raw files| RawData
    CloudZenodo -->|external dataset| RawData

    RawData -->|read by| Calibrator
    RawData -->|read by| PCA
    RawData -->|read by| ErrorModel

    Calibrator -->|generates models| ProductCSV
    PCA -->|PCA components| ProductCSV
    ErrorModel -->|errorbars| ProductCSV

    ProductCSV -->|input to| Summary

    Summary -->|yields data| E1
    Summary -->|yields data| SN1
    Summary -->|yields data| Ugi

    E1 -->|model results| ModelOutput
    SN1 -->|model results| ModelOutput
    Ugi -->|model results| ModelOutput

    Summary -->|drives| VizFramework
    ModelOutput -->|drives| VizFramework
    Misc -->|figure scripts| FigScripts
    VizFramework -->|renders| VisualOutput
    FigScripts -->|publishes| VisualOutput

    %% Tests spanning stages
    Tests --> Calibrator
    Tests --> PCA
    Tests --> ErrorModel
    Tests --> Tutorial
    Tests --> E1
    Tests --> VizFramework

    %% Configurations
    EnvFiles ---|defines env| HardwareControlLayer
    EnvFiles ---|defines env| DataCalibration&Ingestion
    EnvFiles ---|defines env| SpectralUnmixing
    EnvFiles ---|defines env| KineticModeling
    BuildConfig ---|project metadata| robowskiPackage

    %% Click Events
    click Pipetting "https://github.com/yaroslavsobolev/robowski-maps/tree/main/zeus-pipetter/"
    click Washing "https://github.com/yaroslavsobolev/robowski-maps/tree/main/washing_station/"
    click CRAIC "https://github.com/yaroslavsobolev/robowski-maps/tree/main/robowski/uv_vis_absorption_spectroscopy/craic_automation/"
    click PCA "https://github.com/yaroslavsobolev/robowski-maps/blob/main/robowski/uv_vis_absorption_spectroscopy/bkg_pca.py"
    click ErrorModel "https://github.com/yaroslavsobolev/robowski-maps/blob/main/robowski/uv_vis_absorption_spectroscopy/absorbance_errorbar_model.py"
    click Calibrator "https://github.com/yaroslavsobolev/robowski-maps/blob/main/robowski/uv_vis_absorption_spectroscopy/calibrator.py"
    click Tutorial "https://github.com/yaroslavsobolev/robowski-maps/blob/main/notebooks/spectral_unmixing_tutorial.ipynb"
    click Examples "https://github.com/yaroslavsobolev/robowski-maps/tree/main/robowski/uv_vis_absorption_spectroscopy/examples/"
    click E1 "https://github.com/yaroslavsobolev/robowski-maps/tree/main/robowski/kinetics_models/E1_kinetics/"
    click SN1 "https://github.com/yaroslavsobolev/robowski-maps/tree/main/robowski/kinetics_models/simpleSN1_kinetics/"
    click Ugi "https://github.com/yaroslavsobolev/robowski-maps/tree/main/robowski/kinetics_models/Ugi_kinetics/"
    click VizFramework "https://github.com/yaroslavsobolev/robowski-maps/tree/main/robowski/visualize_results/"
    click GeoAlgo "https://github.com/yaroslavsobolev/robowski-maps/tree/main/robowski/geometric_algorithms/"
    click Smooth "https://github.com/yaroslavsobolev/robowski-maps/tree/main/robowski/smoothness_theory/"
    click Outlier "https://github.com/yaroslavsobolev/robowski-maps/tree/main/robowski/outlier_handling/"
    click Misc "https://github.com/yaroslavsobolev/robowski-maps/tree/main/robowski/misc_scripts/"
    click Tests "https://github.com/yaroslavsobolev/robowski-maps/tree/main/tests/"
    click Summary "https://github.com/yaroslavsobolev/robowski-maps/tree/main/summary_of_reaction_yield_data/"

    %% Styles
    classDef hardware fill:#D0E6FF,stroke:#0059b3,color:#003366;
    classDef processing fill:#E6F7D0,stroke:#4C8C00,color:#336600;
    classDef modeling fill:#FFE0B2,stroke:#FF8C00,color:#994C00;
    classDef visual fill:#EAD1F7,stroke:#8C1AFF,color:#4C0059;
    classDef utilities fill:#F2F2F2,stroke:#666666,color:#333333;
    classDef testing fill:#FFCCCC,stroke:#CC0000,color:#660000;
    classDef data fill:#FFFFFF,stroke:#000000,color:#000000,stroke-dasharray: 3 3;
    classDef external fill:#F0F0F0,stroke:#888888,color:#444444,stroke-dasharray: 5 5;
    classDef config fill:#FFF2CC,stroke:#CC9900,color:#806600;
```
