# w-decker/wiscs architecture

> Architecture diagram of the GitHub repository w-decker/wiscs, 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/w-decker/wiscs
- Repository: https://github.com/w-decker/wiscs

## Overview

##### Main Components
- Parameter Management: The process starts with setting up experimental parameters. These parameters (e.g., perceptual, conceptual, task-related, standard deviations, correlations, and counts) are defined and stored using the “params” logic in wiscs/params.py. The parameters are set via the set_params() function available in the package’s API.
- Simulation Engine: The core simulation functionality is implemented in wiscs/simulate.py through the DataGenerator class. This component uses the parameters provided (either as defaults or user-specified) to:
- Construct a baseline data matrix (computing expected reaction times).
- Introduce random effects for subjects, questions, items, etc.
- Integrate noise using methods like Cholesky decomposition (as indicated by the README) to preserve the correlation structure among random effects.
- Plotting Component: Data visualization is handled in wiscs/plotting.py. This module provides various plotting utilities (bar graphs, histograms, scatter plots, heatmaps, etc.) which operate on the DataGenerator’s output.
- Utility and Configuration Functions: Additional support functions (in utils.py), configuration settings (in config.py), and possibly formula calculations (in formula.py) are parts of the support structure enabling the simulation process.

##### Relationships and Interactions Between Components
- The Parameter Manager (using functions in wiscs/params.py) initializes and validates the experimental parameters.
- Once parameters are set, the Simulation Engine (DataGenerator in wiscs/simulate.py) retrieves these parameters internally (or can override them via its fit_transform() method) to generate the simulated data.
- The generated data is exposed through attributes (e.g., DG.data) and is convertible to other formats (using DG.to_pandas() for pandas DataFrame conversion).
- The Plotting Module then takes in a DataGenerator instance to produce various data visualizations, showcasing the simulated reaction time data.
- The internal logic of the simulation might rely on other internal modules like utils.py and formula.py, which support calculations and configurations for generating realistic experimental variability.

##### Important Architectural Patterns
- Modular Design: Each functional area (parameter handling, simulation, plotting) is isolated in its own module, promoting clarity and maintainability.
- Separation of Concerns: The project distinctly separates parameter configuration from data generation and plotting, which simplifies testing and potential future extensions.
- Dependency Injection: The simulation module can either use preset parameters or accept new ones on-the-fly, allowing for flexible component interaction.
- Functional Pipeline: The sequential flow from parameter setup → data generation → data visualization illustrates a well-defined pipeline.

##### Relevant Technologies and Libraries
- Python as the core language.
- Standard libraries for numerical computations and possibly numpy (for operations such as generating random variates and performing Cholesky decomposition).
- Pandas for data manipulation (as seen in the conversion utility).
- Matplotlib or similar libraries are likely used in the Plotting module, although not explicitly mentioned in the README.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Simulation Pipeline
    subgraph "Simulation Pipeline"
        PM["Parameter Manager (wiscs/params.py)"]:::params
        SE["Simulation Engine (DataGenerator) (wiscs/simulate.py)"]:::simulate
        PLOT["Plotting Module (wiscs/plotting.py)"]:::plotting
        PM -->|"parameter_dictionary"| SE
        SE -->|"simulated_data_output"| PLOT
    end

    %% Supporting Modules
    subgraph "Support Modules"
        UTIL["Utility Functions (wiscs/utils.py)"]:::utils
        CONFIG["Configuration Functions (wiscs/config.py)"]:::config
        FORMULA["Formula Calculations (wiscs/formula.py)"]:::formula
    end

    %% Support interactions from Simulation Engine
    SE -.->|"helper_functions"| UTIL
    SE -.->|"config_settings"| CONFIG
    SE -.->|"calculation_formulas"| FORMULA

    %% Click Events
    click PM "https://github.com/w-decker/wiscs/blob/main/wiscs/params.py"
    click SE "https://github.com/w-decker/wiscs/blob/main/wiscs/simulate.py"
    click PLOT "https://github.com/w-decker/wiscs/blob/main/wiscs/plotting.py"
    click UTIL "https://github.com/w-decker/wiscs/blob/main/wiscs/utils.py"
    click CONFIG "https://github.com/w-decker/wiscs/blob/main/wiscs/config.py"
    click FORMULA "https://github.com/w-decker/wiscs/blob/main/wiscs/formula.py"

    %% Styles
    classDef params fill:#ffdd99,stroke:#d35400,stroke-width:2px;
    classDef simulate fill:#a9d0f5,stroke:#2980b9,stroke-width:2px;
    classDef plotting fill:#abebc6,stroke:#27ae60,stroke-width:2px;
    classDef utils fill:#d5f5e3,stroke:#52be80,stroke-width:2px;
    classDef config fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef formula fill:#fad7a0,stroke:#e67e22,stroke-width:2px;
```
