[274] Implement new color_discrete_map param

[tpvasconcelos]

Closes #274

Relates to #315

Copilot Summary

This pull request introduces a new color_discrete_map parameter to the ridgeplot API, allowing users to directly map trace labels to specific colors for more precise control over ridgeline coloring. The changes include updates to documentation and examples to demonstrate this feature, internal refactoring to support the new parameter, and improvements to type utilities for better collection handling.

New Feature: Discrete Color Mapping

• Added a color_discrete_map parameter to the ridgeplot function, enabling users to specify exact colors for traces by label. This is now documented and demonstrated in both the API and usage examples. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10]

Documentation and Example Updates

• Updated the getting started guide and example scripts to show how to use the new color_discrete_map parameter for customizing trace colors, replacing older approaches using colorscale and colormode. [1] [2] [3] [4] [5] [6] [7]

Internal Refactoring for Coloring Logic

• Refactored coloring logic in _figure_factory.py and trace classes to use a boolean fillgradient in the coloring context, and to apply color_discrete_map when provided, bypassing the default colorscale logic. [1] [2] [3] [4] [5] [6]

Type Utilities and Validation Improvements

• Added new type guards like is_collection_l2 and is_densities in _types.py, and refactored normalise_row_attrs in _utils.py to accept both shallow and deep collections, improving robustness and flexibility in input validation. [1] [2] [3] [4] [5] [6] [7]

Miscellaneous Improvements

• Minor code cleanup, import adjustments, and helper additions for testing and debugging, including new helpers in test_helpers.py and layout changes in documentation examples for consistency. [1] [2] [3]

These changes collectively make the ridgeplot API more flexible and user-friendly, especially for users who want exact control over trace coloring.

---

📚 Documentation preview 📚: https://ridgeplot--348.org.readthedocs.build/en/348/

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (4cc1f63) to head (2fa71d4).
⚠️ Report is 103 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #348   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           18        18           
  Lines          648       659   +11     
  Branches        82        85    +3     
=========================================
+ Hits           648       659   +11     

Flag	Coverage Δ
combined-src	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull Request Overview

Copilot reviewed 17 out of 19 changed files in this pull request and generated 2 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}