How brainets/netchos works
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: utils/__init__.py Shared utils · netchos/__init__.py NetCHOS · io/__init__.py I/O layer · network.py Network plot
Components 21
Runtime
Installable library and its core plotting subsystems.
- NetCHOS · Installable library boundary for connectivity plotting.
netchos/__init__.py - Network plot · General network plotting and orchestration entry point.
netchos/network.py - Circular plot · Circular network layout and rendering logic.
netchos/circular.py - Heatmap plot · Matrix-style connectivity visualization logic.
netchos/heatmap.py - Shared utils · Cross-cutting helpers used by the plotting modules.
netchos/utils/__init__.py - Categories · Category grouping, ordering, and hierarchy helpers.
netchos/utils/categories.py - Colors · Color assignment and palette helpers.
netchos/utils/colors.py - Plot helpers · Common plotting helpers shared across renderers.
netchos/utils/plot.py - Misc helpers · Small reusable helper functions.
netchos/utils/misc.py - I/O layer · Backend and format adaptation for plotting outputs.
netchos/io/__init__.py - Convert · General conversion utilities for figure and data interchange.
netchos/io/io_convert.py - MPL to PX · Conversion bridge from matplotlib-style semantics to Plotly-style output.
netchos/io/io_mpl_to_px.py - Syslog I/O · Logging or system-output related I/O support.
netchos/io/io_syslog.py
Support
Examples, documentation, packaging, and CI.
- Examples · Runnable example scripts and sample spreadsheet inputs.
examples/README.rst - Docs · Sphinx documentation source and build configuration.
docs/source/index.rst - Packaging · Python package metadata and source distribution setup.
setup.py - CI · Continuous integration checks and automation.
.github/workflows/ci.yml
Other components
- Client code · User scripts or notebooks that call into the library.
- Matplotlib · Static plotting backend targeted by the library.
- Seaborn · Statistical plotting ecosystem supported by the library.
- Plotly · Interactive plotting backend targeted through conversion.
Connections 28
- 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.