huevat 0.1.0__tar.gz

huevat-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

huevat-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Huevat contributors
+Copyright (c) 2026 sketchplot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

huevat-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+exclude project_plan.md
+exclude uv.lock
+recursive-include docs *.md *.json *.png
+exclude docs/PACKAGING_AUDIT.md
+recursive-include licenses *.txt
+prune tests
+prune tools
+include tests/test_core.py tests/test_space.py tests/test_release.py tests/test_doctor.py
+recursive-include examples *.py *.md
+prune research
+prune artifacts
+recursive-include src/huevat/data *.json
+include .python-version

huevat-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: huevat
+Version: 0.1.0
+Summary: Screened scientific palettes, gradients and coordinated figure styles
+Author-email: Clay Wood <clayewood@gmail.com>
+Maintainer-email: Clay Wood <clayewood@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://pypi.org/project/huevat/
+Project-URL: Source, https://github.com/clay-wood/huevat
+Project-URL: Documentation, https://github.com/clay-wood/huevat/blob/main/docs/QUICKSTART.md
+Project-URL: Issues, https://github.com/clay-wood/huevat/issues
+Project-URL: Changelog, https://github.com/clay-wood/huevat/blob/main/docs/RELEASE_NOTES.md
+Keywords: color,colormap,palette,scientific-visualization,matplotlib,plotly
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: licenses/colorbrewer-Apache-2.0.txt
+License-File: licenses/colorcet-CC-BY-4.0.txt
+License-File: licenses/colorspacious-MIT.txt
+License-File: licenses/matplotlib-LICENSE.txt
+License-File: licenses/sketchplot-MIT.txt
+Provides-Extra: design
+Requires-Dist: numpy>=1.24; extra == "design"
+Requires-Dist: scipy>=1.10; extra == "design"
+Requires-Dist: colorspacious==1.1.2; extra == "design"
+Provides-Extra: research
+Requires-Dist: numpy>=1.24; extra == "research"
+Requires-Dist: scipy>=1.10; extra == "research"
+Requires-Dist: matplotlib>=3.8; extra == "research"
+Requires-Dist: colorspacious==1.1.2; extra == "research"
+Requires-Dist: colorcet==3.2.1; extra == "research"
+Provides-Extra: matplotlib
+Requires-Dist: matplotlib>=3.9; extra == "matplotlib"
+Provides-Extra: plotly
+Requires-Dist: plotly<8,>=6; extra == "plotly"
+Provides-Extra: ultraplot
+Requires-Dist: ultraplot<3,>=2.7; extra == "ultraplot"
+Dynamic: license-file
+
+# Huevat
+
+Scientific color palettes and gradients for **Matplotlib, Plotly and UltraPlot**.
+Choose colors for categories, continuous fields, or values above and below a center.
+
+![Clearer categorical palettes and the four default gradients on light and dark backgrounds](https://raw.githubusercontent.com/clay-wood/huevat/main/docs/images/palettes.png)
+
+Clearer is the default categorical palette. Use `background="dark"` for dark figures.
+
+[Quick start](https://github.com/clay-wood/huevat/blob/main/docs/QUICKSTART.md) · [Plotting examples](https://github.com/clay-wood/huevat/blob/main/examples/README.md) ·
+[Figure doctor](https://github.com/clay-wood/huevat/blob/main/docs/FIGURE_DOCTOR.md) · [API guide](https://github.com/clay-wood/huevat/blob/main/docs/API.md) ·
+[Release notes](https://github.com/clay-wood/huevat/blob/main/docs/RELEASE_NOTES.md)
+
+## Recent updates
+
+- **18 named gradients**, including six new choices: **Cobalt, Copper, Dusk,
+  Orchid, Tundra and Verdant**, each with light and dark versions.
+- **Revised Aerosol, Bathymetry and Thermal** to distinguish the reported
+  lookalike routes. Earlier versions remain available through their saved
+  recipes and immutable design IDs.
+- **Nine colors by default** with `gradient.discrete()`. Diverging and Spectral
+  gradients include the exact neutral as the fifth color. Explicit even counts
+  are supported and omit the midpoint.
+- **Named suffixes:** `_r` reverses, `_d` selects dark, and `_d_r` or `_r_d`
+  combines both.
+
+All eighteen named gradients are supported. Numerical screening results and
+usage guidance are available in the methods documentation.
+See the [release notes](https://github.com/clay-wood/huevat/blob/main/docs/RELEASE_NOTES.md)
+and [installation and release guide](https://github.com/clay-wood/huevat/blob/main/docs/RELEASE.md).
+
+## Install
+
+Install Huevat from PyPI with your plotting library:
+
+```sh
+python -m pip install "huevat[matplotlib]"
+python -m pip install "huevat[plotly]"
+python -m pip install "huevat[ultraplot]"
+```
+
+Requires Python 3.10+. For colors alone, use `python -m pip install huevat`.
+
+## Make a plot
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+import huevat as hv
+from huevat.adapters import matplotlib as hmpl
+
+xx, yy = np.meshgrid(np.linspace(-3, 3, 160), np.linspace(-2, 2, 100))
+field = (8 * np.exp(-((xx - .7)**2 + (yy - .1)**2))
+         - 2 * np.exp(-((xx + 1.1)**2 + (yy + .2)**2) / .4))
+gradient = hv.diverging()
+nine_colors = gradient.discrete()  # default: 9, including the neutral midpoint
+boundaries = [-2, -1.5, -1, -.5, -.1, .1, 1, 2, 4, 8]
+palette = hv.categorical(5)
+
+fig, axes = plt.subplots(1, 3, figsize=(12, 3.5), layout="constrained")
+continuous = axes[0].imshow(field, cmap=hmpl.colormap(gradient), origin="lower",
+                            norm=hmpl.normalizer(-2, 8, center=0))
+discrete = axes[1].imshow(field, cmap=hmpl.colormap(nine_colors), origin="lower",
+                          norm=hmpl.boundary_normalizer(nine_colors, boundaries))
+axes[0].set_title("Continuous · zero at neutral")
+axes[1].set_title("9 colors · neutral bin around zero")
+fig.colorbar(continuous, ax=axes[0], orientation="horizontal")
+fig.colorbar(discrete, ax=axes[1], orientation="horizontal")
+
+axes[2].set_prop_cycle(hmpl.cycle(palette, markers=["o", "s", "^", "D", "v"],
+                                 linestyles=["-", "--", ":", "-.", "-"]))
+x = np.linspace(0, 1, 25)
+for i, label in enumerate(["Blue", "Teal", "Ochre", "Coral", "Purple"]):
+    axes[2].plot(x, .12 * i + .08 * np.sin(2 * np.pi * x + i / 2),
+                 label=label, markevery=4)
+axes[2].set_title("Clearer · specified markers and dashes")
+axes[2].legend(fontsize=8, loc="upper right")
+plt.show()
+```
+
+For a field, pass `hmpl.colormap(hv.sequential())` to `imshow` or `pcolormesh`.
+Use `hv.diverging()` with `hmpl.normalizer(vmin, vmax, center=0)` for signed data.
+The discrete example uses nine colors, with zero inside the neutral bin
+from −0.1 to +0.1. Choose bin boundaries to suit your data.
+
+![Continuous signed field, nine-bin diverging field with a neutral center, and categorical lines](https://raw.githubusercontent.com/clay-wood/huevat/main/research/adapters-v1/matplotlib-light.png)
+
+[See complete examples for all three plotting libraries.](https://github.com/clay-wood/huevat/blob/main/examples/README.md)
+
+## More gradients
+
+Eighteen additional gradients cover general plots, seismic data, terrain, depth,
+and atmospheric fields, with supported light and dark variants.
+
+![The eighteen named gradients on light and dark backgrounds](https://raw.githubusercontent.com/clay-wood/huevat/main/docs/images/gradients.png)
+
+```python
+gradient = hv.gradient("bathymetry")
+new_gradient = hv.gradient("verdant")
+reversed_gradient = hv.gradient("thermal_r")
+dark_gradient = hv.gradient("thermal_d")
+dark_reversed_gradient = hv.gradient("thermal_d_r")
+print(hv.gradient_names())
+```
+
+The revised routes are:
+
+| Gradient | Current route | Previously similar to |
+| --- | --- | --- |
+| Aerosol | Deep red → magenta → pale violet | Rosewood |
+| Bathymetry | Pale cyan → turquoise → deep ocean, darkening with depth | Mineral |
+| Thermal | Violet → neutral → green | Balance |
+
+Append `_r` to reverse a named gradient or `_d` to select its dark version;
+combine them as `_d_r` or `_r_d`. `gradient.reversed()` also changes direction.
+`_d` is equivalent to `background="dark"`; combining it with an explicit
+`background="light"` is an error.
+
+For separate colors, `gradient.discrete()` selects nine bins. Diverging scales
+include their neutral midpoint; explicit even counts remain available.
+
+```python
+signed = hv.diverging()
+nine_colors = signed.discrete()  # neutral is nine_colors.colors[4]
+assert nine_colors.colors[4] == hv.to_hex(signed.at(0.5))
+```
+
+Check `hv.known_counts(gradient)` for tested counts.
+`hv.optimized_discrete(gradient, n)` searches for better-spaced colors and
+requires the `design` extra.
+
+![Nine-bin diverging gradients with a visible neutral midpoint](https://raw.githubusercontent.com/clay-wood/huevat/main/docs/images/gradient-bins.png)
+
+## Figure doctor
+
+Coordinate colors, markers and dashes in an existing figure. Repeated labels
+keep the same style across panels.
+
+| Before | After |
+| --- | --- |
+| ![Original figure with similar colors](https://raw.githubusercontent.com/clay-wood/huevat/main/research/doctor-v1/matplotlib-light-before.png) | ![Figure doctor proposal with distinct colors, markers and dashes](https://raw.githubusercontent.com/clay-wood/huevat/main/research/doctor-v1/matplotlib-light-separation.png) |
+
+Install with `python -m pip install "huevat[design,matplotlib]"`, or replace
+`matplotlib` with `plotly` or `ultraplot`.
+
+```python
+from huevat import doctor
+
+scene = doctor.inspect(fig)
+closer, separation, simple = doctor.propose(scene)
+preview = doctor.preview(fig, separation)
+change = doctor.apply(fig, separation)
+change.undo()
+```
+
+[Figure doctor guide](https://github.com/clay-wood/huevat/blob/main/docs/FIGURE_DOCTOR.md) explains previews, fixed colors and
+keeping styles across figures. Review the result at the size you intend to use.
+
+## Save colors
+
+```python
+hv.export(palette).write("palette.json")
+restored = hv.load_export(open("palette.json", encoding="utf-8").read()).design
+hv.export(hv.diverging(), n=7, format="csv").write("colors.csv")
+```
+
+JSON saves a design for reuse. CSV and hex give you color lists; CSS is also
+available. See the [quick start](https://github.com/clay-wood/huevat/blob/main/docs/QUICKSTART.md) for labels and more examples.

huevat-0.1.0/README.md

@@ -0,0 +1,168 @@
+# Huevat
+
+Scientific color palettes and gradients for **Matplotlib, Plotly and UltraPlot**.
+Choose colors for categories, continuous fields, or values above and below a center.
+
+![Clearer categorical palettes and the four default gradients on light and dark backgrounds](https://raw.githubusercontent.com/clay-wood/huevat/main/docs/images/palettes.png)
+
+Clearer is the default categorical palette. Use `background="dark"` for dark figures.
+
+[Quick start](https://github.com/clay-wood/huevat/blob/main/docs/QUICKSTART.md) · [Plotting examples](https://github.com/clay-wood/huevat/blob/main/examples/README.md) ·
+[Figure doctor](https://github.com/clay-wood/huevat/blob/main/docs/FIGURE_DOCTOR.md) · [API guide](https://github.com/clay-wood/huevat/blob/main/docs/API.md) ·
+[Release notes](https://github.com/clay-wood/huevat/blob/main/docs/RELEASE_NOTES.md)
+
+## Recent updates
+
+- **18 named gradients**, including six new choices: **Cobalt, Copper, Dusk,
+  Orchid, Tundra and Verdant**, each with light and dark versions.
+- **Revised Aerosol, Bathymetry and Thermal** to distinguish the reported
+  lookalike routes. Earlier versions remain available through their saved
+  recipes and immutable design IDs.
+- **Nine colors by default** with `gradient.discrete()`. Diverging and Spectral
+  gradients include the exact neutral as the fifth color. Explicit even counts
+  are supported and omit the midpoint.
+- **Named suffixes:** `_r` reverses, `_d` selects dark, and `_d_r` or `_r_d`
+  combines both.
+
+All eighteen named gradients are supported. Numerical screening results and
+usage guidance are available in the methods documentation.
+See the [release notes](https://github.com/clay-wood/huevat/blob/main/docs/RELEASE_NOTES.md)
+and [installation and release guide](https://github.com/clay-wood/huevat/blob/main/docs/RELEASE.md).
+
+## Install
+
+Install Huevat from PyPI with your plotting library:
+
+```sh
+python -m pip install "huevat[matplotlib]"
+python -m pip install "huevat[plotly]"
+python -m pip install "huevat[ultraplot]"
+```
+
+Requires Python 3.10+. For colors alone, use `python -m pip install huevat`.
+
+## Make a plot
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+import huevat as hv
+from huevat.adapters import matplotlib as hmpl
+
+xx, yy = np.meshgrid(np.linspace(-3, 3, 160), np.linspace(-2, 2, 100))
+field = (8 * np.exp(-((xx - .7)**2 + (yy - .1)**2))
+         - 2 * np.exp(-((xx + 1.1)**2 + (yy + .2)**2) / .4))
+gradient = hv.diverging()
+nine_colors = gradient.discrete()  # default: 9, including the neutral midpoint
+boundaries = [-2, -1.5, -1, -.5, -.1, .1, 1, 2, 4, 8]
+palette = hv.categorical(5)
+
+fig, axes = plt.subplots(1, 3, figsize=(12, 3.5), layout="constrained")
+continuous = axes[0].imshow(field, cmap=hmpl.colormap(gradient), origin="lower",
+                            norm=hmpl.normalizer(-2, 8, center=0))
+discrete = axes[1].imshow(field, cmap=hmpl.colormap(nine_colors), origin="lower",
+                          norm=hmpl.boundary_normalizer(nine_colors, boundaries))
+axes[0].set_title("Continuous · zero at neutral")
+axes[1].set_title("9 colors · neutral bin around zero")
+fig.colorbar(continuous, ax=axes[0], orientation="horizontal")
+fig.colorbar(discrete, ax=axes[1], orientation="horizontal")
+
+axes[2].set_prop_cycle(hmpl.cycle(palette, markers=["o", "s", "^", "D", "v"],
+                                 linestyles=["-", "--", ":", "-.", "-"]))
+x = np.linspace(0, 1, 25)
+for i, label in enumerate(["Blue", "Teal", "Ochre", "Coral", "Purple"]):
+    axes[2].plot(x, .12 * i + .08 * np.sin(2 * np.pi * x + i / 2),
+                 label=label, markevery=4)
+axes[2].set_title("Clearer · specified markers and dashes")
+axes[2].legend(fontsize=8, loc="upper right")
+plt.show()
+```
+
+For a field, pass `hmpl.colormap(hv.sequential())` to `imshow` or `pcolormesh`.
+Use `hv.diverging()` with `hmpl.normalizer(vmin, vmax, center=0)` for signed data.
+The discrete example uses nine colors, with zero inside the neutral bin
+from −0.1 to +0.1. Choose bin boundaries to suit your data.
+
+![Continuous signed field, nine-bin diverging field with a neutral center, and categorical lines](https://raw.githubusercontent.com/clay-wood/huevat/main/research/adapters-v1/matplotlib-light.png)
+
+[See complete examples for all three plotting libraries.](https://github.com/clay-wood/huevat/blob/main/examples/README.md)
+
+## More gradients
+
+Eighteen additional gradients cover general plots, seismic data, terrain, depth,
+and atmospheric fields, with supported light and dark variants.
+
+![The eighteen named gradients on light and dark backgrounds](https://raw.githubusercontent.com/clay-wood/huevat/main/docs/images/gradients.png)
+
+```python
+gradient = hv.gradient("bathymetry")
+new_gradient = hv.gradient("verdant")
+reversed_gradient = hv.gradient("thermal_r")
+dark_gradient = hv.gradient("thermal_d")
+dark_reversed_gradient = hv.gradient("thermal_d_r")
+print(hv.gradient_names())
+```
+
+The revised routes are:
+
+| Gradient | Current route | Previously similar to |
+| --- | --- | --- |
+| Aerosol | Deep red → magenta → pale violet | Rosewood |
+| Bathymetry | Pale cyan → turquoise → deep ocean, darkening with depth | Mineral |
+| Thermal | Violet → neutral → green | Balance |
+
+Append `_r` to reverse a named gradient or `_d` to select its dark version;
+combine them as `_d_r` or `_r_d`. `gradient.reversed()` also changes direction.
+`_d` is equivalent to `background="dark"`; combining it with an explicit
+`background="light"` is an error.
+
+For separate colors, `gradient.discrete()` selects nine bins. Diverging scales
+include their neutral midpoint; explicit even counts remain available.
+
+```python
+signed = hv.diverging()
+nine_colors = signed.discrete()  # neutral is nine_colors.colors[4]
+assert nine_colors.colors[4] == hv.to_hex(signed.at(0.5))
+```
+
+Check `hv.known_counts(gradient)` for tested counts.
+`hv.optimized_discrete(gradient, n)` searches for better-spaced colors and
+requires the `design` extra.
+
+![Nine-bin diverging gradients with a visible neutral midpoint](https://raw.githubusercontent.com/clay-wood/huevat/main/docs/images/gradient-bins.png)
+
+## Figure doctor
+
+Coordinate colors, markers and dashes in an existing figure. Repeated labels
+keep the same style across panels.
+
+| Before | After |
+| --- | --- |
+| ![Original figure with similar colors](https://raw.githubusercontent.com/clay-wood/huevat/main/research/doctor-v1/matplotlib-light-before.png) | ![Figure doctor proposal with distinct colors, markers and dashes](https://raw.githubusercontent.com/clay-wood/huevat/main/research/doctor-v1/matplotlib-light-separation.png) |
+
+Install with `python -m pip install "huevat[design,matplotlib]"`, or replace
+`matplotlib` with `plotly` or `ultraplot`.
+
+```python
+from huevat import doctor
+
+scene = doctor.inspect(fig)
+closer, separation, simple = doctor.propose(scene)
+preview = doctor.preview(fig, separation)
+change = doctor.apply(fig, separation)
+change.undo()
+```
+
+[Figure doctor guide](https://github.com/clay-wood/huevat/blob/main/docs/FIGURE_DOCTOR.md) explains previews, fixed colors and
+keeping styles across figures. Review the result at the size you intend to use.
+
+## Save colors
+
+```python
+hv.export(palette).write("palette.json")
+restored = hv.load_export(open("palette.json", encoding="utf-8").read()).design
+hv.export(hv.diverging(), n=7, format="csv").write("colors.csv")
+```
+
+JSON saves a design for reuse. CSV and hex give you color lists; CSS is also
+available. See the [quick start](https://github.com/clay-wood/huevat/blob/main/docs/QUICKSTART.md) for labels and more examples.

huevat-0.1.0/docs/API.md

@@ -0,0 +1,100 @@
+# API guide
+
+```python
+import huevat as hv
+```
+
+Start with the [quick start](QUICKSTART.md) or the [palette gallery](../README.md).
+
+## Choose colors
+
+| Function | Use |
+| --- | --- |
+| `categorical(n, background="light", style="clearer")` | Distinct categories; default palettes cover 2–12 colors |
+| `sequential(background="light")` | Ordered values from low to high |
+| `diverging(background="light")` | Values on either side of a center |
+| `multihue(background="light")` | Ordered values with a wider hue range |
+| `spectral(background="light")` | A diverging gradient with several hues |
+| `gradient(name, background=None)` | One of eighteen supported gradients; defaults to light, `_d` selects dark, `_r` reverses |
+| `gradient_names(family=None, domain=None)` | List named gradients, optionally filtered |
+| `gradient_info(name)` | Read a named gradient's intended uses and direction |
+
+Use `background="dark"` for dark figures. A categorical palette provides hex
+strings in `.colors`. A gradient provides RGB tuples through `.at(t)`.
+
+## Sample and inspect
+
+| Operation | Use |
+| --- | --- |
+| `g.at(t)` | Read a color at a position from 0 to 1 |
+| `g.reversed()` | Reverse a gradient |
+| `g.discrete(n=9, context=None)` | Select evenly spaced colors; nine bins include a diverging neutral |
+| `known_counts(g)` | List prepared counts that passed the checks |
+| `nearby_counts(g, n, context=None)` | Find tested counts near the one requested |
+| `optimized_discrete(g, n, context=None, grid=257, max_seconds=10)` | Search for better-spaced positions; requires `design` |
+| `summarize(source)` | Read a short summary of the color checks |
+| `source.report` | Read the full numerical results |
+
+Some counts fail the color checks; an unlisted count has not necessarily failed.
+Sample positions do not set physical data-bin boundaries.
+Explicit even counts retain their requested size and omit the neutral midpoint.
+Named suffixes compose in either order: `gradient("balance_d_r")` equals
+`gradient("balance", background="dark").reversed()`. `_d` conflicts with an
+explicit `background="light"`; repeated suffixes are invalid. `gradient_info`
+accepts suffixes and returns the base route's metadata; `gradient_names` lists
+base names.
+
+## Save and load
+
+```python
+hv.export(palette, labels=labels).write("palette.json")
+saved = hv.load_export(open("palette.json", encoding="utf-8").read())
+palette = saved.design
+colors_by_label = saved.color_map
+
+hv.export(gradient, n=7, format="csv").write("colors.csv")
+```
+
+`export(design, format="json", n=None, context=None, labels=None, source=None)`
+supports `json`, `csv`, `hex` and `css`. The result has `.text`, `.report` and
+`.write(path)`. JSON preserves the design and labels; CSV and hex provide color
+lists. CSS approximates continuous gradients with checked color stops.
+Its optional `tolerance=.002` and `max_stops=1025` control that approximation.
+
+For JSON, export a gradient with `n=7` or supply its original gradient as
+`export(palette, source=gradient)`. Categorical palettes and palettes from
+`optimized_discrete` already contain the information needed to save them.
+Labels must be unique and match the number of colors.
+
+`load_export(value, validate=True)` returns `.design`, `.source`, `.labels`
+and, for labeled palettes, `.color_map`. Loading unfamiliar designs can require
+`design` to repeat the checks. `validate=False` skips those checks and leaves
+the result unvalidated.
+
+You can also save with `.to_recipe()` or `.to_json()` and restore with
+`load_recipe(value, validate=True)`.
+
+## Find a particular design
+
+`design_ids(family=None, background=None, role=None)` lists saved designs.
+`design_info(id)` describes one; `get_design(id)` loads it. Roles are `default`,
+`legacy` and `collection`. Saving an ID lets you request the same design later.
+
+## Plotting and Figure doctor
+
+Adapters live in `huevat.adapters.matplotlib`, `.plotly` and `.ultraplot`.
+See the [complete plotting examples](../examples/README.md).
+
+Figure doctor provides `inspect`, `diagnose`, `propose`, `preview`, `apply` and
+`load_proposal`. Its suggestions require the `design` extra. See the
+[Figure doctor guide](FIGURE_DOCTOR.md).
+
+## Errors
+
+`ValueError` indicates an invalid argument. `QualityError` means a color check
+failed. `ConstraintConflictError` means the fixed gradient cannot meet the
+requested count under the selected rules. `SearchExhaustedError` means the
+search ended without finding a passing result. Color-check errors include
+their numerical report.
+
+The [methods notes](METHODS_H1.md) describe the checks and their limits.

huevat-0.1.0/docs/FIGURE_DOCTOR.md

@@ -0,0 +1,83 @@
+# Figure doctor
+
+Improve an existing line or scatter figure with coordinated colors, markers
+and dashes. Matplotlib, Plotly and UltraPlot are supported.
+
+| Before | After |
+| --- | --- |
+| ![Original figure](../research/doctor-v1/matplotlib-light-before.png) | ![Suggested colors, markers and dashes](../research/doctor-v1/matplotlib-light-separation.png) |
+
+## Compare suggestions
+
+Install from PyPI with `python -m pip install "huevat[design,matplotlib]"`.
+Replace `matplotlib` with `plotly` or `ultraplot` for those libraries.
+
+```python
+from huevat import doctor
+
+scene = doctor.inspect(fig)
+closer, separation, simple = doctor.propose(scene)
+preview = doctor.preview(fig, separation)
+gray = doctor.preview(fig, separation, condition="grayscale")
+
+change = doctor.apply(fig, separation)
+change.undo()
+```
+
+- **Closer** keeps more of the original color appearance.
+- **Separation** prioritizes series that cross or run close together.
+- **Simple** uses fewer additional markers and dashes.
+
+Suggestions can be similar when the same choice works best for the figure.
+Preview creates a copy. For Matplotlib and UltraPlot, save it with
+`preview.savefig("preview.png")` or display it in a notebook. For Plotly, use
+`preview.show()`. `apply` changes the original figure; `undo` restores the
+previous styles and checks for changes made since the suggestion was applied.
+
+## Keep specific colors or styles
+
+```python
+options = doctor.propose(scene, locked={
+    "Reference": {"color": "#4379a3"},
+    "Treatment": {"marker": "square", "dash": "dash"},
+})
+```
+
+Fixed styles stay exact. If they prevent colors from passing the checks, the
+report says so. Markers and dashes can still help readers follow the series.
+
+## Keep labels consistent across figures
+
+```python
+next_scene = doctor.inspect(next_fig)
+next_options = doctor.propose(next_scene, assignments=separation.assignments)
+```
+
+The same label keeps its style when series are reordered or temporarily absent.
+Use consistent, unique labels for categories you want to match.
+
+## Check and save a suggestion
+
+```python
+print(separation.report["color_screen_pass"])
+gray = doctor.preview(fig, separation, condition="grayscale")
+simulated = doctor.preview(fig, separation, condition="deutan-100")
+
+saved_json = separation.to_json()
+restored = doctor.load_proposal(saved_json)
+```
+
+A saved suggestion applies to the same figure data and settings. Use its
+`.assignments` to carry styles to a different figure.
+
+## Supported figures
+
+Figure doctor edits ordinary Cartesian lines and scatter series with uniform
+colors. It supports repeated labels across panels and respects each panel's
+background. Images, colorbars, uncertainty bands and unsupported plot types
+are kept as they are. Plotly works best with explicit numeric coordinates,
+trace modes and colors. Not every legend or custom artist can be updated.
+
+Color checks cover the supported marks. They do not assess the whole figure;
+crossing detection can miss small features. Review the preview at the intended
+figure size. The [methods notes](METHODS_H4C.md) give detailed coverage.