# yizhan-oliver-shu/jump-models architecture

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

- Interactive diagram: https://gitdiagram.com/yizhan-oliver-shu/jump-models
- Repository: https://github.com/yizhan-oliver-shu/jump-models

## Overview

##### Project Type and Purpose
- The project is an open-source Python library for statistical jump models (JMs) used primarily for regime identification in time series data.
- Its API follows a scikit‐learn style, making it intuitive for users familiar with the scikit‐learn paradigm.
- It provides implementations for different jump models (original JM, continuous JM (CJM), and sparse JM (SJM)) plus extensions for online prediction.

##### File Structure
- Top-Level Files & Configuration:
– Files like .gitignore, LICENSE, README.md, and pyproject.toml are standard for open-source projects.
– The environment.yaml file suggests that reproducibility is ensured through a managed environment.
- Primary Code Package (“jumpmodels” folder):
– Contains key modules:
- base.py – likely contains core abstract classes or shared functionality.
- jump.py – houses the main JumpModel class implementing the core functionalities.
- sparse_jump.py – implements the SparseJumpModel with feature selection.
- preprocess.py – for data preprocessing steps.
- plot.py – for rendering model outputs using matplotlib (with optional LaTeX support).
– The “utils” subfolder within “jumpmodels” includes modules for calculation, clustering, indexing, and validation.
- Examples:
– The “examples/nasdaq” folder includes Jupyter notebooks and Python scripts that demonstrate how to use the library. It even contains sample datasets (in CSV, pickle formats) and output plots.

##### Architectural Elements
- Main Components:
– Core Model Components: JumpModel and SparseJumpModel (in jumpmodels/jump.py and jumpmodels/sparse_jump.py).
– Supporting Modules: base classes, preprocessing (preprocess.py), and plotting (plot.py).
– Utilities: Various helper functions organized in the utils subfolder (calculation, cluster, index, validation).
– Client/Usage Examples: “examples” folder where users can see end-to-end usage, including data retrieval, model training, online prediction, and plotting.
- External Dependencies:
– Standard dependencies include numpy, pandas, scipy, scikit-learn, and matplotlib.
– Optional dependency on LaTeX for enhanced plot rendering.
- Communication Flow:
– A user (or client application) imports model classes from the jumpmodels package.
– When a algorithm’s method (e.g., .fit() or .predict()) is called, the core logic in jumpmodels/jump.py or sparse_jump.py interacts with preprocessing functions, utility calculations, and plotting functions.
– The library exposes both batch and online prediction functionality.

– Rectangles for major components.
– Rounded rectangles or ovals for API endpoints.
- If possible, use grouping (container boundaries) to show the hierarchical nature (for example, grouping all modules inside the “jumpmodels” package).

## Diagram (Mermaid)

```mermaid
graph TD
    %% User / Client Code
    UC["User/Client Code (Examples)"]:::client

    %% JumpModels Library Subgraph
    subgraph "JumpModels Library"
        %% API Layer
        subgraph "API Layer"
            JM["JumpModel (Core Algorithm)"]:::api
            SJM["SparseJumpModel (Feature Selection)"]:::api
        end
        %% Support Components
        subgraph "Support Components"
            BC["Base Components"]:::support
            PP["Preprocessing Module"]:::support
            VP["Visualization Component"]:::support
            UM["Utility Modules"]:::utils
        end
    end

    %% Configuration & Environment (split into two nodes)
    subgraph "Configuration & Environment"
        conf_py["pyproject.toml"]:::config
        conf_env["environment.yaml"]:::config
    end

    %% External Dependencies
    ED["External Dependencies: numpy, pandas, scipy, scikit-learn, matplotlib, LaTeX"]:::external

    %% Flow from User to API
    UC -->|"calls"| JM
    UC -->|"calls"| SJM

    %% API Layer calling Support Components
    JM -->|"calls"| BC
    SJM -->|"calls"| BC

    JM -->|"calls"| PP
    SJM -->|"calls"| PP

    JM -->|"calls"| VP
    SJM -->|"calls"| VP

    JM -->|"calls"| UM
    SJM -->|"calls"| UM

    %% Configuration and Dependencies connecting to the Library (illustrative connections)
    conf_py -->|"configures"| JM
    conf_env -->|"configures"| JM
    ED -->|"dependencies"| JM

    %% Click Events
    click UC "https://github.com/yizhan-oliver-shu/jump-models/tree/master/examples/nasdaq/"
    click JM "https://github.com/yizhan-oliver-shu/jump-models/blob/master/jumpmodels/jump.py"
    click SJM "https://github.com/yizhan-oliver-shu/jump-models/blob/master/jumpmodels/sparse_jump.py"
    click BC "https://github.com/yizhan-oliver-shu/jump-models/blob/master/jumpmodels/base.py"
    click PP "https://github.com/yizhan-oliver-shu/jump-models/blob/master/jumpmodels/preprocess.py"
    click VP "https://github.com/yizhan-oliver-shu/jump-models/blob/master/jumpmodels/plot.py"
    click UM "https://github.com/yizhan-oliver-shu/jump-models/tree/master/jumpmodels/utils/"
    click conf_py "https://github.com/yizhan-oliver-shu/jump-models/blob/master/pyproject.toml"
    click conf_env "https://github.com/yizhan-oliver-shu/jump-models/blob/master/environment.yaml"

    %% Styles
    classDef client fill:#7FDBFF,stroke:#1C82AD,stroke-width:2px;
    classDef api fill:#FFDC00,stroke:#FF851B,stroke-width:2px;
    classDef support fill:#B10DC9,stroke:#85144b,stroke-width:2px;
    classDef utils fill:#3D9970,stroke:#2ECC40,stroke-width:2px;
    classDef config fill:#AAAAAA,stroke:#777777,stroke-width:2px;
    classDef external fill:#FF851B,stroke:#FF4136,stroke-width:2px;
```
