# brainets/netchos architecture

> Architecture diagram of the GitHub repository brainets/netchos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brainets/netchos
- Repository: https://github.com/brainets/netchos

## Overview

1. **What this repo is**
   NetCHOS is a **Python plotting toolbox for network/connectivity data**. Its main purpose is to take structured network inputs and produce visualizations such as **circular plots, heatmaps, and network graphs**, with support for both static and interactive plotting styles.

2. **Top-level package boundary**
   The installable library lives under **`netchos/`**. That package is the runtime boundary for consumers; everything else in the repo supports it via examples, docs, packaging, and CI.

3. **Core plotting modules**
   The main visualization entry points are split by plot type:
   - **`netchos/circular.py`** for circular network layouts
   - **`netchos/heatmap.py`** for matrix-style connectivity plots
   - **`netchos/network.py`** for general network plotting / orchestration  
   This suggests the architecture is organized around **multiple specialized renderers** rather than one monolithic plotting engine.

4. **Utility layer**
   Shared logic is centralized under **`netchos/utils/`**:
   - **`categories.py`**: likely handles grouping, ordering, or hierarchical category logic
   - **`colors.py`**: color assignment and palettes
   - **`misc.py`**: small reusable helpers
   - **`plot.py`**: common plotting helpers shared by the renderers  
   This layer appears to contain the cross-cutting logic that keeps the plot-specific modules thin.

5. **Input/output and backend conversion**
   The **`netchos/io/`** package provides an integration layer for data and backend interoperability:
   - **`io_convert.py`**
   - **`io_mpl_to_px.py`** plus **`io_mpl_to_px.json`**
   - **`io_syslog.py`**  
   The presence of `mpl_to_px` strongly indicates a **conversion path from matplotlib-style objects/semantics to Plotly-style output**, which is important to the repo’s multi-backend architecture.

6. **Likely data flow**
   The typical flow is:
   - user supplies network/connectivity data
   - utility code normalizes categories/colors/layout-related metadata
   - a plot module builds the visualization
   - the I/O layer may convert or adapt the figure for another backend
   - output is returned as a static figure or an interactive Plotly object  
   In other words, the repo separates **data preparation**, **plot construction**, and **backend adaptation**.

7. **Visualization backends**
   The README explicitly mentions support for **matplotlib, seaborn, and plotly**. Architecturally, that means NetCHOS is not tied to a single rendering engine; instead it exposes plotting logic that can target multiple visualization ecosystems.

8. **Examples as usage contracts**
   The **`examples/`** directory contains runnable scripts and spreadsheet inputs:
   - `plot_circular.py`
   - `plot_heatmap.py`
   - `plot_network.py`
   - sample `.xlsx` files  
   These examples are important because they show the expected input shapes and serve as the main consumer-facing reference for the library’s API.

9. **Documentation subsystem**
   The **`docs/`** directory uses **Sphinx** (`conf.py`, `Makefile`, `source/`). This is a standard documentation boundary separate from runtime code, and it likely documents the plot APIs and usage patterns for each visualization type.

10. **Packaging and distribution**
    The repo is packaged as a Python library using **`setup.py`**, **`MANIFEST.in`**, and **`requirements.txt`**. This indicates a conventional source-distributed package rather than a service or compiled application.

11. **CI and project hygiene**
    The **`.github/workflows/ci.yml`** workflow provides continuous integration, probably for testing and packaging checks. That makes CI part of the repo’s delivery pipeline, but not part of the runtime architecture.

12. **External dependencies and runtime shape**
    NetCHOS is a **pure Python library** with plotting dependencies; it does not appear to include a server, database, or message queue. The primary external integration points are the plotting libraries themselves and spreadsheet-like inputs used in examples.

13. **How to draw the architecture**
    A clear diagram would show:
    - **Client code / examples**
    - **NetCHOS public package**
    - **Plot-specific modules** (`network`, `circular`, `heatmap`)
    - **Shared utilities** (`categories`, `colors`, `plot`, `misc`)
    - **I/O / backend conversion layer** (`io/*`)
    - **Output figures** to matplotlib/seaborn/plotly  
    Surrounding that, show **docs**, **examples**, **packaging**, and **CI** as supporting subsystems.

Main entry points: [`netchos/utils/__init__.py`](https://github.com/brainets/netchos/blob/main/netchos/utils/__init__.py) (Shared utils), [`netchos/__init__.py`](https://github.com/brainets/netchos/blob/main/netchos/__init__.py) (NetCHOS), [`netchos/io/__init__.py`](https://github.com/brainets/netchos/blob/main/netchos/io/__init__.py) (I/O layer), [`netchos/network.py`](https://github.com/brainets/netchos/blob/main/netchos/network.py) (Network plot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_pkg["NetCHOS<br/>python package<br/>[__init__.py]"]
  node_network["Network plot<br/>renderer<br/>[network.py]"]
  node_circular["Circular plot<br/>renderer<br/>[circular.py]"]
  node_heatmap["Heatmap plot<br/>renderer<br/>[heatmap.py]"]
  node_utils["Shared utils<br/>helpers<br/>[__init__.py]"]
  node_categories["Categories<br/>ordering<br/>[categories.py]"]
  node_colors["Colors<br/>palette<br/>[colors.py]"]
  node_plotutils["Plot helpers<br/>[plot.py]"]
  node_misc["Misc helpers<br/>utilities<br/>[misc.py]"]
  node_io["I/O layer<br/>adapter<br/>[__init__.py]"]
  node_convert["Convert<br/>adapter<br/>[io_convert.py]"]
  node_mpltopx["MPL to PX<br/>backend bridge<br/>[io_mpl_to_px.py]"]
  node_syslog["Syslog I/O<br/>logging io<br/>[io_syslog.py]"]
end

subgraph group_support["Support"]
  node_examples["Examples<br/>usage<br/>[README.rst]"]
  node_docs["Docs<br/>documentation<br/>[index.rst]"]
  node_packaging["Packaging<br/>distribution<br/>[setup.py]"]
  node_ci["CI<br/>workflow<br/>[ci.yml]"]
end

node_client["Client code<br/>consumer"]
node_matplotlib(("Matplotlib<br/>render backend"))
node_seaborn(("Seaborn<br/>render backend"))
node_plotly(("Plotly<br/>render backend"))

node_client -->|"uses"| node_pkg
node_examples -->|"calls"| node_network
node_examples -->|"calls"| node_circular
node_examples -->|"calls"| node_heatmap
node_pkg -->|"exposes"| node_network
node_pkg -->|"exposes"| node_circular
node_pkg -->|"exposes"| node_heatmap
node_network -->|"depends on"| node_utils
node_circular -->|"depends on"| node_utils
node_heatmap -->|"depends on"| node_utils
node_utils -->|"contains"| node_categories
node_utils -->|"contains"| node_colors
node_utils -->|"contains"| node_plotutils
node_utils -->|"contains"| node_misc
node_network -->|"adapts"| node_io
node_circular -->|"adapts"| node_io
node_heatmap -->|"adapts"| node_io
node_io -->|"contains"| node_convert
node_io -->|"contains"| node_mpltopx
node_io -->|"contains"| node_syslog
node_mpltopx -->|"bridges"| node_matplotlib
node_mpltopx -->|"bridges"| node_plotly
node_network -.->|"targets"| node_seaborn
node_circular -.->|"renders with"| node_matplotlib
node_heatmap -.->|"renders with"| node_matplotlib
node_docs -->|"documents"| node_pkg
node_packaging -->|"packages"| node_pkg
node_ci -->|"checks"| node_packaging

click node_pkg "https://github.com/brainets/netchos/blob/main/netchos/__init__.py"
click node_network "https://github.com/brainets/netchos/blob/main/netchos/network.py"
click node_circular "https://github.com/brainets/netchos/blob/main/netchos/circular.py"
click node_heatmap "https://github.com/brainets/netchos/blob/main/netchos/heatmap.py"
click node_utils "https://github.com/brainets/netchos/blob/main/netchos/utils/__init__.py"
click node_categories "https://github.com/brainets/netchos/blob/main/netchos/utils/categories.py"
click node_colors "https://github.com/brainets/netchos/blob/main/netchos/utils/colors.py"
click node_plotutils "https://github.com/brainets/netchos/blob/main/netchos/utils/plot.py"
click node_misc "https://github.com/brainets/netchos/blob/main/netchos/utils/misc.py"
click node_io "https://github.com/brainets/netchos/blob/main/netchos/io/__init__.py"
click node_convert "https://github.com/brainets/netchos/blob/main/netchos/io/io_convert.py"
click node_mpltopx "https://github.com/brainets/netchos/blob/main/netchos/io/io_mpl_to_px.py"
click node_syslog "https://github.com/brainets/netchos/blob/main/netchos/io/io_syslog.py"
click node_examples "https://github.com/brainets/netchos/blob/main/examples/README.rst"
click node_docs "https://github.com/brainets/netchos/blob/main/docs/source/index.rst"
click node_packaging "https://github.com/brainets/netchos/blob/main/setup.py"
click node_ci "https://github.com/brainets/netchos/blob/main/.github/workflows/ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pkg,node_network,node_circular,node_heatmap,node_utils,node_categories,node_colors,node_plotutils,node_misc,node_io,node_convert,node_mpltopx,node_syslog toneBlue
class node_examples,node_docs,node_packaging,node_ci toneAmber
class node_client,node_matplotlib,node_seaborn,node_plotly toneNeutral
```

## Components

### Runtime

Installable library and its core plotting subsystems.

- [NetCHOS](https://github.com/brainets/netchos/blob/main/netchos/__init__.py): python package · Installable library boundary for connectivity plotting. · `netchos/__init__.py`
- [Network plot](https://github.com/brainets/netchos/blob/main/netchos/network.py): renderer · General network plotting and orchestration entry point. · `netchos/network.py`
- [Circular plot](https://github.com/brainets/netchos/blob/main/netchos/circular.py): renderer · Circular network layout and rendering logic. · `netchos/circular.py`
- [Heatmap plot](https://github.com/brainets/netchos/blob/main/netchos/heatmap.py): renderer · Matrix-style connectivity visualization logic. · `netchos/heatmap.py`
- [Shared utils](https://github.com/brainets/netchos/blob/main/netchos/utils/__init__.py): helpers · Cross-cutting helpers used by the plotting modules. · `netchos/utils/__init__.py`
- [Categories](https://github.com/brainets/netchos/blob/main/netchos/utils/categories.py): ordering · Category grouping, ordering, and hierarchy helpers. · `netchos/utils/categories.py`
- [Colors](https://github.com/brainets/netchos/blob/main/netchos/utils/colors.py): palette · Color assignment and palette helpers. · `netchos/utils/colors.py`
- [Plot helpers](https://github.com/brainets/netchos/blob/main/netchos/utils/plot.py): plot helper · Common plotting helpers shared across renderers. · `netchos/utils/plot.py`
- [Misc helpers](https://github.com/brainets/netchos/blob/main/netchos/utils/misc.py): utilities · Small reusable helper functions. · `netchos/utils/misc.py`
- [I/O layer](https://github.com/brainets/netchos/blob/main/netchos/io/__init__.py): adapter · Backend and format adaptation for plotting outputs. · `netchos/io/__init__.py`
- [Convert](https://github.com/brainets/netchos/blob/main/netchos/io/io_convert.py): adapter · General conversion utilities for figure and data interchange. · `netchos/io/io_convert.py`
- [MPL to PX](https://github.com/brainets/netchos/blob/main/netchos/io/io_mpl_to_px.py): backend bridge · Conversion bridge from matplotlib-style semantics to Plotly-style output. · `netchos/io/io_mpl_to_px.py`
- [Syslog I/O](https://github.com/brainets/netchos/blob/main/netchos/io/io_syslog.py): logging io · Logging or system-output related I/O support. · `netchos/io/io_syslog.py`

### Support

Examples, documentation, packaging, and CI.

- [Examples](https://github.com/brainets/netchos/blob/main/examples/README.rst): usage · Runnable example scripts and sample spreadsheet inputs. · `examples/README.rst`
- [Docs](https://github.com/brainets/netchos/blob/main/docs/source/index.rst): documentation · Sphinx documentation source and build configuration. · `docs/source/index.rst`
- [Packaging](https://github.com/brainets/netchos/blob/main/setup.py): distribution · Python package metadata and source distribution setup. · `setup.py`
- [CI](https://github.com/brainets/netchos/blob/main/.github/workflows/ci.yml): workflow · Continuous integration checks and automation. · `.github/workflows/ci.yml`

### Other components

- **Client code**: consumer · User scripts or notebooks that call into the library.
- **Matplotlib**: render backend · Static plotting backend targeted by the library.
- **Seaborn**: render backend · Statistical plotting ecosystem supported by the library.
- **Plotly**: render backend · Interactive plotting backend targeted through conversion.

## Connections

- Client code → NetCHOS: uses · Consumers import the installable package.
- Examples → Network plot: calls · Example scripts demonstrate the network plotting API.
- Examples → Circular plot: calls · Example scripts demonstrate circular plots.
- Examples → Heatmap plot: calls · Example scripts demonstrate heatmap plots.
- NetCHOS → Network plot: exposes · The package exports the general network plotting entry point.
- NetCHOS → Circular plot: exposes · The package exports the circular plotting entry point.
- NetCHOS → Heatmap plot: exposes · The package exports the heatmap plotting entry point.
- Network plot → Shared utils: depends on · Network plotting shares common helpers.
- Circular plot → Shared utils: depends on · Circular plotting shares common helpers.
- Heatmap plot → Shared utils: depends on · Heatmap plotting shares common helpers.
- Shared utils → Categories: contains · Category handling is centralized in the utility layer.
- Shared utils → Colors: contains · Color handling is centralized in the utility layer.
- Shared utils → Plot helpers: contains · Shared plotting helpers live here.
- Shared utils → Misc helpers: contains · Miscellaneous helpers live here.
- Network plot → I/O layer: adapts · Network plotting can route through backend conversion.
- Circular plot → I/O layer: adapts · Circular plotting can route through backend conversion.
- Heatmap plot → I/O layer: adapts · Heatmap plotting can route through backend conversion.
- I/O layer → Convert: contains · General conversion routines.
- I/O layer → MPL to PX: contains · Matplotlib-to-Plotly bridge.
- I/O layer → Syslog I/O: contains · Syslog-related I/O support.
- MPL to PX → Matplotlib: bridges · Accepts matplotlib-style inputs and semantics.
- MPL to PX → Plotly: bridges · Produces Plotly-style interactive output.
- Network plot → Seaborn: targets · Network plotting is designed to work within the seaborn ecosystem.
- Circular plot → Matplotlib: renders with · Static circular plots can be rendered via matplotlib.
- Heatmap plot → Matplotlib: renders with · Static heatmaps can be rendered via matplotlib.
- Docs → NetCHOS: documents · Documentation describes the library API.
- Packaging → NetCHOS: packages · Packaging metadata builds and distributes the library.
- CI → Packaging: checks · CI validates project setup and distribution readiness.
