# lorenzgoenner/maze_analysis architecture

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

- Interactive diagram: https://gitdiagram.com/lorenzgoenner/maze_analysis
- Repository: https://github.com/lorenzgoenner/maze_analysis

## Overview

##### Project type and purpose
- This is a Python-based research analysis codebase for modeling human decision‐making in a maze environment.

##### File structure
- Top‐level scripts (runnable mains):
- visualize_steps.py
- fit_SR_neighbours.py
- fit_planning.py
- fit_Q-learning.py
- Core helper modules:
- init_door_config.py (maze setup)
- maze_functions.py (environment utilities)
- log_info.py (parsing raw log files)
- model_fitting.py (generic fitting routines)
- Q_learning.py, planning.py, successor_rep.py (model‐specific implementations)
- Exploratory/aux analysis scripts:
- learning_rates.py, reaction_times.py, trunc_script_lg.py
- Static data/config:
- initial_layout.txt (room‐door mapping)
- No external services or databases—pure file‐based I/O.

##### Key insights from the README
- The “main” scripts orchestrate the pipeline: load data, configure the maze, compute parameter fits, and output results.
- Helper modules provide reusable functions for parsing logs, initializing environment, and low‐level model computations.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Input
    subgraph "Data Input" 
        direction TB
        RawLogs["Raw Log Files"]:::data
        LayoutFile["initial_layout.txt"]:::data
    end

    %% Preprocessing
    subgraph "Preprocessing Layer"
        direction TB
        LogParser["log_info.py"]:::preprocess
        MazeConfigurator["init_door_config.py"]:::preprocess
        EnvUtils["maze_functions.py"]:::preprocess
    end

    %% Core Modeling
    subgraph "Core Modeling Layer"
        direction TB
        FittingEngine["model_fitting.py"]:::core
        QLearning["Q_learning.py"]:::core
        Planning["planning.py"]:::core
        SuccRep["successor_rep.py"]:::core
    end

    %% Orchestrator Scripts
    subgraph "Orchestrator Scripts"
        direction TB
        FitQLearn["fit_Q-learning.py"]:::orchestrator
        FitPlan["fit_planning.py"]:::orchestrator
        FitSR["fit_SR_neighbours.py"]:::orchestrator
        Visualize["visualize_steps.py"]:::orchestrator
    end

    %% Exploratory Analysis
    subgraph "Exploratory Analysis"
        direction TB
        LearnRates["learning_rates.py"]:::exploratory
        ReactTimes["reaction_times.py"]:::exploratory
        TruncLG["trunc_script_lg.py"]:::exploratory
    end

    %% Outputs
    subgraph "Outputs"
        direction TB
        FitResults["Fit Results (CSV/JSON)"]:::output
        Visuals["Plots/Visualizations"]:::output
    end

    %% Connections
    RawLogs -->|feeds| LogParser
    LayoutFile -->|feeds| MazeConfigurator
    LogParser -->|parsed data| FitQLearn
    MazeConfigurator -->|config data| FitQLearn
    EnvUtils -->|environment utils| FitQLearn

    FitQLearn -->|uses| FittingEngine
    FitQLearn -->|model impl| QLearning
    FitPlan -->|uses| FittingEngine
    FitPlan -->|model impl| Planning
    FitSR -->|uses| FittingEngine
    FitSR -->|model impl| SuccRep

    FittingEngine -->|writes| FitResults
    FitQLearn -->|outputs| FitResults
    FitPlan -->|outputs| FitResults
    FitSR -->|outputs| FitResults

    FitResults -->|input| LearnRates
    FitResults -->|input| ReactTimes
    FitResults -->|input| TruncLG

    RawLogs -->|input| Visualize
    MazeConfigurator -->|input| Visualize
    Visualize -->|produces| Visuals

    %% Click Events
    click LayoutFile "https://github.com/lorenzgoenner/maze_analysis/blob/master/initial_layout.txt"
    click LogParser "https://github.com/lorenzgoenner/maze_analysis/blob/master/log_info.py"
    click MazeConfigurator "https://github.com/lorenzgoenner/maze_analysis/blob/master/init_door_config.py"
    click EnvUtils "https://github.com/lorenzgoenner/maze_analysis/blob/master/maze_functions.py"
    click FittingEngine "https://github.com/lorenzgoenner/maze_analysis/blob/master/model_fitting.py"
    click QLearning "https://github.com/lorenzgoenner/maze_analysis/blob/master/Q_learning.py"
    click Planning "https://github.com/lorenzgoenner/maze_analysis/blob/master/planning.py"
    click SuccRep "https://github.com/lorenzgoenner/maze_analysis/blob/master/successor_rep.py"
    click FitQLearn "https://github.com/lorenzgoenner/maze_analysis/blob/master/fit_Q-learning.py"
    click FitPlan "https://github.com/lorenzgoenner/maze_analysis/blob/master/fit_planning.py"
    click FitSR "https://github.com/lorenzgoenner/maze_analysis/blob/master/fit_SR_neighbours.py"
    click Visualize "https://github.com/lorenzgoenner/maze_analysis/blob/master/visualize_steps.py"
    click LearnRates "https://github.com/lorenzgoenner/maze_analysis/blob/master/learning_rates.py"
    click ReactTimes "https://github.com/lorenzgoenner/maze_analysis/blob/master/reaction_times.py"
    click TruncLG "https://github.com/lorenzgoenner/maze_analysis/blob/master/trunc_script_lg.py"

    %% Styles
    classDef data fill:#D6E9FF,stroke:#4A90E2;
    classDef preprocess fill:#E8F5E9,stroke:#4CAF50;
    classDef core fill:#FFF3E0,stroke:#FB8C00;
    classDef orchestrator fill:#FFFDE7,stroke:#FDD835;
    classDef exploratory fill:#FCE4EC,stroke:#EC407A;
    classDef output fill:#F3E5F5,stroke:#8E24AA;
```
