# raeslab/lorepy architecture

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

- Interactive diagram: https://gitdiagram.com/raeslab/lorepy
- Repository: https://github.com/raeslab/lorepy

## Overview

##### Main components
- Core Library Module – The primary functionality lives inside the src/lorepy directory. Here, you have:
- lorepy.py: Implements the main function (loreplot) to generate logistic regression plots.
- uncertainty.py: Provides the uncertainty_plot function that uses resampling (or jackknifing) to illustrate prediction intervals.
- External Dependencies – The library leverages several key Python packages:
- pandas (for DataFrame manipulations and plotting using DataFrame.plot.area).
- matplotlib (for rendering plots, scatter plots, etc.).
- scikit-learn (for implementing logistic regression and for alternative classifiers like SVC and Random Forest).
- User Application Layer – This represents how a user would integrate lorepy into their own code (illustrated in the README examples). It includes:
- Data input (pandas DataFrame).
- Customization options, such as passing additional plotting arguments (colormap, scatter_kws, etc.).
- Documentation & Examples – The docs and example.py files provide additional context for users and testers but don’t affect runtime behavior.

##### Relationships and interactions
- The user code (client) provides input data (a DataFrame) and configuration parameters (like 'x' and 'y' column names, optional arguments like add_dots, jitter, etc.) to the loreplot function.
- The loreplot function internally:
- Preprocesses the input data as needed.
- Uses scikit-learn (by default, a logistic regression model, but it can accept any classifier implementing fit and predict_proba) to fit and predict probabilities.
- Leverages pandas to structure the data and uses its plotting capabilities where applicable.
- Calls matplotlib to render the final plot.
- Similarly, the uncertainty_plot function wraps a similar internal workflow with additional resampling for uncertainty estimation.
- Optional customizations (e.g., disabling sample dots, setting custom colormaps, adjusting scatter options) are passed from the user through the API down into the plotting calls.

##### Architectural patterns and design principles
- Separation of concerns is evident: the core statistical/modeling functionality (using scikit-learn) is separated from the plotting details (matplotlib and pandas integrations).
- The design supports a plugin-like flexibility where different classifiers can be swapped in, making the system extensible.
- Clear modularity – tests, documentation, and CI workflows indicate that the project follows best practices for testing and deployment.

##### Relevant technologies, frameworks, and libraries
- Python library structure with setup.py for installation.
- pandas for DataFrame management and area plotting.
- matplotlib for rendering plots.
- scikit-learn for machine learning models.
- GitHub Actions for continuous integration.
- Pytest for testing.

##### Final recommendations
- Avoid overly generic components. Instead, strive for specificity that reflects lorepy’s purpose (e.g., annotate where customizations like “confounders” or “jitter” are applied).
- Extensibility: by showing that the classifier can be swapped, underline the architectural decision to allow multiple models via a plug-and-play approach.
- The testing, documentation, and deployment artifacts (like .github/workflows and docs/) can be boxed separately to show the project’s adherence to modern software development practices, even if they are not part of the runtime mechanism.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% User Application Layer
    subgraph "User Application Layer"
        ExampleLore["User App: lorepy Example"]:::user
        ExampleUnc["User App: uncertainty Example"]:::user
        CustomOpts["Customization Options (e.g., colormap, scatter_kws)"]:::user
    end

    %% Core Library Module
    subgraph "Core Library"
        LoreplotFunc["Core Library: loreplot() Function"]:::core
        UncertaintyFunc["Core Library: uncertainty_plot() Function"]:::core
    end

    %% External Dependencies
    subgraph "External Dependencies"
        MLModel["ML Model (scikit-learn)"]:::external
        DataManager["Data Manager (pandas)"]:::external
        PlotRenderer["Plot Renderer (matplotlib)"]:::external
    end

    %% Testing and Continuous Integration
    subgraph "Testing & CI"
        TestPlot["Test: tests/test_plot.py"]:::testing
        TestUncertainty["Test: tests/test_uncertainty.py"]:::testing
        CIWorkflow["CI Workflow: .github/workflows/autocheck.yml"]:::testing
    end

    %% Documentation & Examples
    subgraph "Documentation & Examples"
        Readme["Documentation: README.md"]:::docs
        DocsDir["Docs Directory (docs/)"]:::docs
    end

    %% Connections from User Application Layer to Core Library
    ExampleLore -->|"calls"| LoreplotFunc
    ExampleUnc -->|"calls"| UncertaintyFunc
    CustomOpts -->|"configures"| LoreplotFunc

    %% Internal interactions within Core Library Functions
    LoreplotFunc -->|"preprocesses\ndata & fits model"| MLModel
    LoreplotFunc -->|"manages data"| DataManager
    LoreplotFunc -->|"renders plot"| PlotRenderer

    UncertaintyFunc -->|"resampling for\nuncertainty estimation"| MLModel
    UncertaintyFunc -->|"renders plot"| PlotRenderer

    %% External Dependencies interactions (Data flow emphasis)
    DataManager -.->|"provides\ndata support"| PlotRenderer

    %% Supporting Development and Deployment flows
    LoreplotFunc ---|"verified by"| TestPlot
    UncertaintyFunc ---|"verified by"| TestUncertainty
    TestPlot ---|"CI monitored by"| CIWorkflow
    TestUncertainty ---|"CI monitored by"| CIWorkflow

    %% Documentation references
    ExampleLore ---|"documented in"| Readme
    ExampleUnc ---|"documented in"| Readme
    LoreplotFunc ---|"details in"| DocsDir
    UncertaintyFunc ---|"details in"| DocsDir

    %% Click Events
    click LoreplotFunc "https://github.com/raeslab/lorepy/blob/main/src/lorepy/lorepy.py"
    click UncertaintyFunc "https://github.com/raeslab/lorepy/blob/main/src/lorepy/uncertainty.py"
    click ExampleLore "https://github.com/raeslab/lorepy/blob/main/example.py"
    click ExampleUnc "https://github.com/raeslab/lorepy/blob/main/example_uncertainty.py"
    click TestPlot "https://github.com/raeslab/lorepy/blob/main/tests/test_plot.py"
    click TestUncertainty "https://github.com/raeslab/lorepy/blob/main/tests/test_uncertainty.py"
    click CIWorkflow "https://github.com/raeslab/lorepy/blob/main/.github/workflows/autocheck.yml"
    click Readme "https://github.com/raeslab/lorepy/blob/main/README.md"
    click DocsDir "https://github.com/raeslab/lorepy/tree/main/docs"

    %% Style Definitions
    classDef user fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef core fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef external fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef testing fill:#ffcdd2,stroke:#b71c1c,stroke-width:2px;
    classDef docs fill:#d1c4e9,stroke:#4a148c,stroke-width:2px;
```
