# fish-quant/comseg architecture

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

- Interactive diagram: https://gitdiagram.com/fish-quant/comseg
- Repository: https://github.com/fish-quant/comseg

## Overview

##### Project Type and Purpose
- ComSeg is an open‐source Python library (spa­tial point‐cloud segmentation framework) for single‐cell spatial RNA profiling.
- It processes CSV spot coordinates + expression data → builds a graph → applies clustering algorithms → outputs an AnnData object (scanpy/Anndata format).

##### High-Level Architecture (Components)
a. User Interface / Entry Points
- CLI or Python API (import comseg)
- Scripts or Jupyter notebooks in docs/userguide for Quick_start
b. Data Ingestion & Preprocessing
- comseg.dataset: reads CSV, builds raw data structures
- comseg.utils.preprocessing: filters data, normalizes counts
c. Graph Construction & Utilities
- comseg.utils.utils_graph: builds spatial graph (nodes=spots or cells)
- comseg.utils.custom_louvain: community detection helpers
d. Core Algorithms
- comseg.clustering: main segmentation routines (Louvain, custom methods)
- comseg.model: higher-level orchestration (ties preprocessing + clustering + postprocessing)
- comseg.dictionary: building/comparing “cell signature” dictionaries
e. Output & Visualization
- Returns an AnnData object with .X (expression), .obs (coordinates), .obsm (.graph)
- comseg.utils.plot: plotting functions for QC and final segmentation maps
f. Packaging & Documentation
- pyproject.toml + requirements.txt: build and runtime dependencies
- docs/: Sphinx sources + build pipeline (readthedocs.yml)
- dist/ + old_dist/: published wheels and tarballs

##### Relationships & Data Flow
- User → CLI/API → dataset.read_csv
→ preprocessing.clean()
→ graph_utils.build_graph()
→ clustering.run()
→ model.aggregate_results()
→ dictionary.generate_signatures()
→ output: AnnData
- Packaging & docs sit alongside code; CI/CD (e.g., ReadTheDocs) consumes source to publish docs.

##### Architectural Patterns & Design Principles
- Modular design: each submodule encapsulates a single concern (SRP)
- Data‐flow pipeline: clear sequence of transformations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    subgraph "API Layer"
        CLI["CLI / Python API"]:::inputoutput
    end

    %% Core Processing
    subgraph "Core Processing"
        Dataset["Dataset Module"]:::processing
        Preprocess["Preprocessing Module"]:::processing
        subgraph "Graph Construction & Utilities"
            GraphUtils["Graph Utilities"]:::processing
            CustomLouvain["Custom Louvain Helpers"]:::algorithms
        end
        Clustering["Clustering Engine"]:::algorithms
        Model["Model Orchestrator"]:::processing
        Dictionary["Dictionary Generator"]:::algorithms
    end

    %% Output & Visualization
    subgraph "Output & Visualization"
        AnnData[(AnnData Object)]:::inputoutput
        Plot["Plotting Utilities"]:::processing
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Packaging["Packaging & Configuration"]:::infrastructure
        Docs["Documentation Sources"]:::infrastructure
        Dist["Published Distributions"]:::infrastructure
    end

    %% Main Data Flow
    CLI --> Dataset --> Preprocess --> GraphUtils --> CustomLouvain --> Clustering --> Model --> Dictionary --> AnnData --> Plot

    %% Peripheral Links
    CLI -.-> Docs
    Packaging -.-> Dist
    Docs -.-> Dist

    %% Legend
    subgraph "Legend" 
        direction LR
        IO["Input/Output"]:::inputoutput
        PROC["Processing"]:::processing
        ALG["Algorithms"]:::algorithms
        INF["Infrastructure"]:::infrastructure
    end

    %% Click Events
    click CLI "https://github.com/fish-quant/comseg/blob/master/src/comseg/__init__.py"
    click Dataset "https://github.com/fish-quant/comseg/blob/master/src/comseg/dataset.py"
    click Preprocess "https://github.com/fish-quant/comseg/blob/master/src/comseg/utils/preprocessing.py"
    click GraphUtils "https://github.com/fish-quant/comseg/blob/master/src/comseg/utils/utils_graph.py"
    click CustomLouvain "https://github.com/fish-quant/comseg/blob/master/src/comseg/utils/custom_louvain.py"
    click Plot "https://github.com/fish-quant/comseg/blob/master/src/comseg/utils/plot.py"
    click Clustering "https://github.com/fish-quant/comseg/blob/master/src/comseg/clustering.py"
    click Model "https://github.com/fish-quant/comseg/blob/master/src/comseg/model.py"
    click Dictionary "https://github.com/fish-quant/comseg/blob/master/src/comseg/dictionary.py"
    click Packaging "https://github.com/fish-quant/comseg/blob/master/pyproject.toml"
    click Docs "https://github.com/fish-quant/comseg/tree/master/docs/source"
    click Dist "https://github.com/fish-quant/comseg/tree/master/dist/"

    %% Styles
    classDef inputoutput fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef processing fill:#90EE90,stroke:#333,stroke-width:1px
    classDef algorithms fill:#FFA500,stroke:#333,stroke-width:1px
    classDef infrastructure fill:#D3D3D3,stroke:#333,stroke-width:1px
```
