spec: add heatmap-adjacency specification (#5258)

## New Specification: `heatmap-adjacency`

Related to #5240

---

### specification.md

# heatmap-adjacency: Network Adjacency Matrix Heatmap

## Description

A matrix-based representation of a network or graph where rows and
columns represent nodes and cell color indicates the presence or weight
of edges between them. This visualization complements node-link diagrams
by excelling at revealing clusters, structural patterns, and density in
large or dense networks where node-link layouts become cluttered.
Reordering nodes by cluster, degree, or community membership exposes
block-diagonal structure and makes group boundaries immediately visible.

## Applications

- Visualizing social network connections to detect community structure
and cliques
- Displaying brain connectivity matrices in neuroscience to identify
functionally linked regions
- Analyzing bilateral trade relationships between countries to reveal
trading blocs
- Showing co-occurrence patterns in text analysis to find related terms
or topics

## Data

- `source` (categorical) — source node identifier
- `target` (categorical) — target node identifier
- `weight` (float, optional) — edge weight or connection strength;
defaults to 1 (binary presence) when absent
- Size: 20–200 nodes (adjacency matrix will be nodes × nodes)
- Example: A social network of 50 people with friendship strength scores

## Notes

- Nodes should be reorderable by cluster, degree, or community
assignment to expose block-diagonal structure
- For undirected graphs the matrix is symmetric; implementations should
fill both triangles
- Color intensity maps to edge weight; absent edges should use a
distinct background (e.g., white or near-white)
- Optional dendrogram along axes to show hierarchical clustering of node
ordering
- Include a colorbar legend showing the weight scale
- Axis tick labels should display node names; for large networks
consider showing only group boundaries

---

**Next:** Add `approved` label to the issue to merge this PR.

---
:robot: *[spec-create
workflow](https://github.com/MarkusNeusinger/pyplots/actions/runs/24290821552)*

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

plots/heatmap-adjacency/specification.md

@@ -0,0 +1,29 @@
+# heatmap-adjacency: Network Adjacency Matrix Heatmap
+
+## Description
+
+A matrix-based representation of a network or graph where rows and columns represent nodes and cell color indicates the presence or weight of edges between them. This visualization complements node-link diagrams by excelling at revealing clusters, structural patterns, and density in large or dense networks where node-link layouts become cluttered. Reordering nodes by cluster, degree, or community membership exposes block-diagonal structure and makes group boundaries immediately visible.
+
+## Applications
+
+- Visualizing social network connections to detect community structure and cliques
+- Displaying brain connectivity matrices in neuroscience to identify functionally linked regions
+- Analyzing bilateral trade relationships between countries to reveal trading blocs
+- Showing co-occurrence patterns in text analysis to find related terms or topics
+
+## Data
+
+- `source` (categorical) — source node identifier
+- `target` (categorical) — target node identifier
+- `weight` (float, optional) — edge weight or connection strength; defaults to 1 (binary presence) when absent
+- Size: 20–200 nodes (adjacency matrix will be nodes × nodes)
+- Example: A social network of 50 people with friendship strength scores
+
+## Notes
+
+- Nodes should be reorderable by cluster, degree, or community assignment to expose block-diagonal structure
+- For undirected graphs the matrix is symmetric; implementations should fill both triangles
+- Color intensity maps to edge weight; absent edges should use a distinct background (e.g., white or near-white)
+- Optional dendrogram along axes to show hierarchical clustering of node ordering
+- Include a colorbar legend showing the weight scale
+- Axis tick labels should display node names; for large networks consider showing only group boundaries

plots/heatmap-adjacency/specification.yaml

@@ -0,0 +1,29 @@
+# Specification-level metadata for heatmap-adjacency
+# Auto-synced to PostgreSQL on push to main
+
+spec_id: heatmap-adjacency
+title: Network Adjacency Matrix Heatmap
+
+# Specification tracking
+created: "2026-04-11T20:22:41Z"
+updated: null
+issue: 5240
+suggested: MarkusNeusinger
+
+# Classification tags (applies to all library implementations)
+# See docs/reference/tagging-system.md for detailed guidelines
+tags:
+  plot_type:
+    - heatmap
+    - network
+  data_type:
+    - network
+    - categorical
+    - numeric
+  domain:
+    - general
+    - science
+  features:
+    - color-mapped
+    - correlation
+    - comparison