# mouseland/kilosort architecture

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

- Interactive diagram: https://gitdiagram.com/mouseland/kilosort
- Repository: https://github.com/mouseland/kilosort

## Overview

##### Main Components
- Data Input & Configuration:
– This component covers data ingestion (reading binary files) and configuration handling (via parameters in kilosort/parameters.py). It represents the starting point where users supply data (via the GUI or command line).
- Preprocessing Module:
– Modules such as kilosort/preprocessing.py and kilosort/data_tools.py handle preparatory steps (e.g., filtering, normalization).
- Core Spike Detection & Clustering Engine:
– Break this into subcomponents:
- Spike Detection (kilosort/spikedetect.py)
- Template Matching (kilosort/template_matching.py)
- Clustering (e.g., kilosort/clustering_qr.py)
- Hierarchical clustering (kilosort/hierarchical.py)
- Supplementary functions (e.g., kilosort/utils.py)
- Postprocessing & Simulation:
– Postprocessing routines (kilosort/postprocessing.py) and simulation (kilosort/simulation.py) form another layer in the pipeline.
- Graphical User Interface (GUI):
– The GUI components (inside kilosort/gui/) encapsulate:
▪ Data display (data_view_box.py, probe_view_box.py)
▪ Parameter settings (settings_box.py)
▪ Run control (run_box.py, launch.py)
▪ Logging and message handling (logger.py, message_log_box.py)
- External Integration:
– There is a dedicated pathway for integration with Phy. The output files are generated (in a Phy-compatible format) so that manual curation can be performed externally.
- Testing & Documentation:
– Although not part of the runtime, include nodes for tests (in the tests directory) and documentation (docs/) that help validate and explain system behavior.

##### Relationships & Data Flow
– Connect the output from the core engine to “Postprocessing & Simulation.”

##### Architectural Patterns & Design Principles
– Emphasize the pipeline pattern where data flows sequentially through the processing stages.
– Highlight the separation of concerns: the GUI (view and controller roles) is distinct from the core processing modules (model/algorithm).
– Note that the project supports both direct command-line usage (via kilosort/__main__.py and run_kilosort.py) and a full-featured GUI interface.
– Mention that unit testing (with pytest and tox configuration) underscores a design guided by modularity and reliability.

##### Relevant Technologies & Frameworks
– Python is the core language.
– PyTorch (for GPU computations) is a significant library for supporting high-performance processing.
– PyQt (for GUI elements) is used.
– The environment and dependency management via conda and pip installation scripts indicate robust deployment practices.
– Integration with third-party software such as Phy for manual curation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Input & Configuration
    subgraph "Data Input & Configuration"
        dc1["Configuration Handler"]
        dc2["Data Ingestion"]
        dc3["Main Runner"]
        dc4["Run Script"]
    end

    %% Preprocessing Module
    subgraph "Preprocessing Module"
        pp1["Preprocessing"]
        pp2["Data Tools"]
    end

    %% Core Spike Detection & Clustering Engine
    subgraph "Core Spike Detection & Clustering Engine"
        cpe1["Spike Detection"]
        cpe2["Template Matching"]
        cpe3["Clustering"]
        cpe4["Hierarchical Clustering"]
        cpe5["Utility Functions"]
    end

    %% Postprocessing & Simulation
    subgraph "Postprocessing & Simulation"
        ps1["Postprocessing"]
        ps2["Simulation"]
    end

    %% Graphical User Interface (GUI)
    subgraph "Graphical User Interface (GUI)"
        gui1["Data View"]
        gui2["Probe View"]
        gui3["Settings Panel"]
        gui4["Run Control: Run Box"]
        gui5["Run Control: Launch"]
        gui6["Logger"]
        gui7["Message Log"]
    end

    %% Testing & Documentation
    subgraph "Testing & Documentation"
        td1["Tests"]
        td2["Documentation"]
    end

    %% External Integration
    ei1["Phy Integration"]

    %% Pipeline Flow
    dc2 --> pp1
    dc1 --> pp1
    dc3 --> pp1
    dc4 --> pp1

    pp1 --> cpe1
    cpe1 --> cpe2
    cpe2 --> cpe3
    cpe3 --> cpe4
    cpe4 --> cpe5
    cpe5 --> ps1
    ps1 --> ps2
    ps1 --> ei1

    %% GUI Bidirectional Connections
    dc1 <--> gui3
    cpe1 <--> gui4
    ps1 --> gui1

    %% Styles
    class dc1,dc2,dc3,dc4 config;
    class pp1,pp2 preprocess;
    class cpe1,cpe2,cpe3,cpe4,cpe5 core;
    class ps1,ps2 postprocessing;
    class gui1,gui2,gui3,gui4,gui5,gui6,gui7 gui;
    class td1,td2 testing;
    class ei1 external;

    %% Click Events for Data Input & Configuration
    click dc1 "https://github.com/mouseland/kilosort/blob/main/kilosort/parameters.py"
    click dc2 "https://github.com/mouseland/kilosort/blob/main/kilosort/io.py"
    click dc3 "https://github.com/mouseland/kilosort/blob/main/kilosort/__main__.py"
    click dc4 "https://github.com/mouseland/kilosort/blob/main/kilosort/run_kilosort.py"

    %% Click Events for Preprocessing Module
    click pp1 "https://github.com/mouseland/kilosort/blob/main/kilosort/preprocessing.py"
    click pp2 "https://github.com/mouseland/kilosort/blob/main/kilosort/data_tools.py"

    %% Click Events for Core Spike Detection & Clustering Engine
    click cpe1 "https://github.com/mouseland/kilosort/blob/main/kilosort/spikedetect.py"
    click cpe2 "https://github.com/mouseland/kilosort/blob/main/kilosort/template_matching.py"
    click cpe3 "https://github.com/mouseland/kilosort/blob/main/kilosort/clustering_qr.py"
    click cpe4 "https://github.com/mouseland/kilosort/blob/main/kilosort/hierarchical.py"
    click cpe5 "https://github.com/mouseland/kilosort/blob/main/kilosort/utils.py"

    %% Click Events for Postprocessing & Simulation
    click ps1 "https://github.com/mouseland/kilosort/blob/main/kilosort/postprocessing.py"
    click ps2 "https://github.com/mouseland/kilosort/blob/main/kilosort/simulation.py"

    %% Click Events for Graphical User Interface (GUI)
    click gui1 "https://github.com/mouseland/kilosort/blob/main/kilosort/gui/data_view_box.py"
    click gui2 "https://github.com/mouseland/kilosort/blob/main/kilosort/gui/probe_view_box.py"
    click gui3 "https://github.com/mouseland/kilosort/blob/main/kilosort/gui/settings_box.py"
    click gui4 "https://github.com/mouseland/kilosort/blob/main/kilosort/gui/run_box.py"
    click gui5 "https://github.com/mouseland/kilosort/blob/main/kilosort/gui/launch.py"
    click gui6 "https://github.com/mouseland/kilosort/blob/main/kilosort/gui/logger.py"
    click gui7 "https://github.com/mouseland/kilosort/blob/main/kilosort/gui/message_log_box.py"

    %% Click Events for Testing & Documentation
    click td1 "https://github.com/mouseland/kilosort/tree/main/tests/"
    click td2 "https://github.com/mouseland/kilosort/tree/main/docs/"

    %% Class Definitions for Styles
    classDef config fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef preprocess fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef core fill:#ffff99,stroke:#333,stroke-width:2px;
    classDef postprocessing fill:#ffb6c1,stroke:#333,stroke-width:2px;
    classDef gui fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef testing fill:#afeeee,stroke:#333,stroke-width:2px;
    classDef external fill:#ffd700,stroke:#333,stroke-width:2px;
```
