spec: add parallel-categories-basic specification (#2505)

## New Specification: `parallel-categories-basic`

Related to #2501

---

### specification.md

# parallel-categories-basic: Basic Parallel Categories Plot

## Description

A parallel categories plot visualizes categorical data across multiple
dimensions, with vertical axes representing each categorical variable
and ribbons connecting categories to show observation flow. Unlike
parallel coordinates (which use lines for numeric data), parallel
categories use width-proportional ribbons to show counts or frequencies,
making it ideal for understanding how categorical values co-occur and
flow across multiple classification dimensions.

## Applications

- Analyzing customer journey paths from acquisition channel through
product category to purchase outcome
- Visualizing survey response patterns across multiple demographic or
preference questions
- Exploring classification results showing predicted vs actual
categories with feature breakdowns
- Understanding multi-stage process flows like support ticket routing
through departments

## Data

- `dimension_1` through `dimension_n` (categorical) - Multiple
categorical variables for each observation
- `count` (numeric, optional) - Observation count or weight for
aggregated data
- Size: 3-6 categorical dimensions, each with 2-8 unique values
- Example: Titanic survival data with class, sex, age group, and
survival status

## Notes

- Ribbon width should be proportional to observation count or frequency
- Color by first dimension (source) or last dimension (outcome) for
clarity
- Interactive highlighting helps trace paths through multiple categories
- Consider ordering categories within each dimension to minimize ribbon
crossings
- Too many categories per dimension reduces readability; aggregate rare
values if needed

---

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

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

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

Author: github-actions[bot]

plots/parallel-categories-basic/specification.md

@@ -0,0 +1,27 @@
+# parallel-categories-basic: Basic Parallel Categories Plot
+
+## Description
+
+A parallel categories plot visualizes categorical data across multiple dimensions, with vertical axes representing each categorical variable and ribbons connecting categories to show observation flow. Unlike parallel coordinates (which use lines for numeric data), parallel categories use width-proportional ribbons to show counts or frequencies, making it ideal for understanding how categorical values co-occur and flow across multiple classification dimensions.
+
+## Applications
+
+- Analyzing customer journey paths from acquisition channel through product category to purchase outcome
+- Visualizing survey response patterns across multiple demographic or preference questions
+- Exploring classification results showing predicted vs actual categories with feature breakdowns
+- Understanding multi-stage process flows like support ticket routing through departments
+
+## Data
+
+- `dimension_1` through `dimension_n` (categorical) - Multiple categorical variables for each observation
+- `count` (numeric, optional) - Observation count or weight for aggregated data
+- Size: 3-6 categorical dimensions, each with 2-8 unique values
+- Example: Titanic survival data with class, sex, age group, and survival status
+
+## Notes
+
+- Ribbon width should be proportional to observation count or frequency
+- Color by first dimension (source) or last dimension (outcome) for clarity
+- Interactive highlighting helps trace paths through multiple categories
+- Consider ordering categories within each dimension to minimize ribbon crossings
+- Too many categories per dimension reduces readability; aggregate rare values if needed

plots/parallel-categories-basic/specification.yaml

@@ -0,0 +1,30 @@
+# Specification-level metadata for parallel-categories-basic
+# Auto-synced to PostgreSQL on push to main
+
+spec_id: parallel-categories-basic
+title: Basic Parallel Categories Plot
+
+# Specification tracking
+created: 2025-12-29T23:55:26Z
+updated: null
+issue: 2501
+suggested: MarkusNeusinger
+
+# Classification tags (applies to all library implementations)
+# See docs/concepts/tagging-system.md for detailed guidelines
+tags:
+  plot_type:
+    - parallel-categories
+    - flow
+    - categorical
+  data_type:
+    - categorical
+    - frequency
+  domain:
+    - general
+    - business
+    - statistics
+  features:
+    - basic
+    - proportional
+    - multi-dimensional