# shianghu/xi-pi architecture

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

- Interactive diagram: https://gitdiagram.com/shianghu/xi-pi
- Repository: https://github.com/shianghu/xi-pi

## Overview

##### Project type and purpose
- This is an open-source MATLAB toolbox (“XiPi toolbox”) for separating periodic and aperiodic neural activity in spectral data, plus a set of figure-generation scripts that reproduce results from a research paper.

##### File structure
- Top-level folders:
- Figure – eight subfolders (Figure1…Figure8), each containing data, handler (scripts), and results (.fig or .mat).
- SharedData – common .mat files used by multiple figures.
- XiPi_toolbox – the core toolbox, subdivided into:
– XiPeaks-master/unim (core scmem_unim algorithm and fitting routines)
– appDesigner (MATLAB .mlapp GUIs)
– standalone functions (xp_importdata, xp_calculateSpec, xp_separateSpec, xp_parameterize, etc.)
- third_party_toolbox – two MATLAB toolboxes (auto-axis and barplot) that XiPi leverages for plotting.
- tutorial – a simple demo script and data for users.
- assets – images used in README.

##### Key insights from README
- Core API:
- xp_importdata → xp_calculateSpec → scmem_unim → xp_separateSpec → xp_parameterize
- scmem_unim (in XiPeaks-master/unim) is the algorithm engine.
- Dependencies: MATLAB environment, plus optional FOOOF toolbox.
- Extensibility points: adding new spectral estimators or parameterization methods, replacing the scmem core, or customizing GUIs.

##### Detail is paramount
- Every major folder or module as a component.
- Shared data sources separately.
- Extension hooks (custom .mlapp GUIs, SLMtools).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Sources"
        direction TB
        RawData["Raw Neural Recordings (.mat)"]:::data
        SharedData["Shared Data Repository"]:::data
    end

    %% Preprocessing Layer
    subgraph "Import & Preprocessing" 
        direction TB
        Import["xp_importdata()"]:::io
        SpecCalc["xp_calculateSpec()"]:::io
    end

    %% Core Engine Layer
    subgraph "XiPi Engine (Core Modules)"
        direction TB
        SLM["SLM Utilities"]:::core
        Algorithm["scmem_unim()"]:::core
        ParamCore["Parameterization Routines"]:::core
    end

    %% API & Batch Wrappers Layer
    subgraph "API & Batch Wrappers"
        direction TB
        SeparateAPI["xp_separateSpec()"]:::core
        ParameterizeAPI["xp_parameterize()"]:::core
    end

    %% Visualization & UI Layer
    subgraph "Visualization & UI"
        direction TB
        GUIs["appDesigner GUIs"]:::viz
        ThirdParty["Third-Party Plotting"]:::third
        Figures["Figure Handlers & Results"]:::viz
    end

    %% Tutorial & Assets
    subgraph "Miscellaneous"
        direction TB
        Tutorial["Tutorial Demo"]:::misc
        Assets["Static Assets"]:::misc
    end

    %% Output Layer
    subgraph "Output"
        direction TB
        Components["Aperiodic & Periodic Components (.mat)"]:::data
        FiguresOut["Figures (.fig)"]:::data
        Logs["Summary Stats & Logs"]:::data
    end

    %% Data Flow
    RawData -->|"load .mat"| Import -->|"time series"| SpecCalc -->|"PSD matrix"| Algorithm -->|"separate spec"| SeparateAPI -->|"aperiodic/periodic data"| ParameterizeAPI -->|"fit params"| ParamCore -->|"parameters"| Components
    SharedData --> Import
    SeparateAPI -->|"batch outputs"| FiguresOut
    ParameterizeAPI --> Logs

    %% Visualization & UI Flows
    Figures -->|"calls core API"| Import
    GUIs -->|"interactive calls"| Import
    ThirdParty -->|"plot enhancements"| Figures

    %% Tutorial & Assets Usage
    Tutorial --> Import
    Assets --> Figures

    %% Click Events
    click SharedData "https://github.com/shianghu/xi-pi/tree/main/Figure/SharedData"
    click Import "https://github.com/shianghu/xi-pi/blob/main/XiPi_toolbox/xp_importdata.m"
    click SpecCalc "https://github.com/shianghu/xi-pi/blob/main/XiPi_toolbox/xp_calculateSpec.m"
    click SeparateAPI "https://github.com/shianghu/xi-pi/blob/main/XiPi_toolbox/xp_separateSepc.m"
    click ParameterizeAPI "https://github.com/shianghu/xi-pi/blob/main/XiPi_toolbox/xp_parameterize.m"
    click Algorithm "https://github.com/shianghu/xi-pi/blob/main/XiPi_toolbox/XiPeaks-master/unim/scmem_unim.m"
    click SLM "https://github.com/shianghu/xi-pi/tree/main/XiPi_toolbox/SLM - Shape Language Modeling/SLMtools"
    click GUIs "https://github.com/shianghu/xi-pi/tree/main/XiPi_toolbox/appDesigner"
    click ThirdParty "https://github.com/shianghu/xi-pi/tree/main/third_party_toolbox/matlab-auto-axis"
    click Tutorial "https://github.com/shianghu/xi-pi/blob/main/tutorial/tutorial.m"
    click Assets "https://github.com/shianghu/xi-pi/tree/main/assets"

    %% Styles
    classDef data fill:#cbd5e8,stroke:#024f9d,color:#024f9d,stroke-width:1px
    classDef io fill:#d4edda,stroke:#1e7e34,color:#1e7e34,stroke-width:1px
    classDef core fill:#cfe2ff,stroke:#084298,color:#084298,stroke-width:1px
    classDef viz fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px
    classDef third fill:#ffe5d9,stroke:#d1495b,color:#d1495b,stroke-width:1px
    classDef misc fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-width:1px
```
