Reference
Plotly-based plotting utilities and an extensible plotting interface for pyspect.
This module provides
- update_theme: Configures a Plotly figure with light/dark 2D/3D themes, common font, axis styles, and background colors. The function mutates the provided figure (template, paper/plot background) and supplies a template_layout for consistent styling.
- with_figure: A decorator that ensures a Plotly figure is available, normalizes
keyword arguments, and applies theming and layout updates. Depending on dim:
- dim=None: no axis remapping
- dim=2: xaxis_ and yaxis_ kwds map to layout_xaxis_ / layout_yaxis_
- dim=3: xaxis_, yaxis_, zaxis_ map to layout_scene_; camera_ maps to layout_scene_camera_ It also collects theme_ and layout_ prefixes to feed update_theme and figure layout.
The core interface is PlotlyImpl[R] (subclass of AxesImpl), which offers:
- A general dispatcher PlotlyImpl.plot(..., method="name") that calls either
self.plot_name or self.name on provided inputs.
- Three transformation hooks to implement in subclasses:
- transform_to_bitmap(inp, axes): 2D boolean array
- transform_to_surface(inp, axes): 2D float array
- transform_to_isosurface(inp, axes): 3D float array
Ready-to-use plotting methods (decorated with with_figure) build meshes over axis
bounds (min/max) via numpy.meshgrid (indexing='ij'), label axes using axis_name/unit,
and add corresponding Plotly traces:
- plot_bitmap: 2D Heatmap of a boolean mask (True mapped to value in [zmin, zmax]).
- plot_contour: 2D contour lines from a 2D scalar field.
- plot_surface: 3D surface (z from 2D scalar field) with scene aspectmode='cube'.
- plot_isosurface: 3D isosurface at a given level from a 3D volume; caps hidden and
surface_count=1 by default; scene aspectmode='cube'.
The nested PlotlyImpl.PLOT namespace provides spherical-to-cartesian helpers and a set of precomputed camera.eye presets (e.g., EYE_HI_NE, EYE_MH_S, EYE_ZENITH, etc.) to quickly position 3D views.
PlotlyImpl is designed for easy extension, adding plotting functionality to implementations that inherit from it.
PlotlyImpl
Bases: AxesImpl
Example plotting interface.
Integrate these methods where pyspect emits data/sets/meshes
and call with either an existing fig= or let it create one.
PLOT
sph_to_cart(r, theta, phi)
staticmethod
Spherical (deg) → cartesian dict compatible with Plotly camera.eye.
animate(frames, fig, **kwds)
Create a slider-based Plotly animation by reusing plot methods.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
frames
|
list[Any]
|
List of frame inputs. Each frame can be either:
- a single plot input |
required |
method
|
Plotting method passed to |
required | |
fig
|
BaseFigure
|
Figure to animate into. If not provided, a new figure is created. |
required |
**kwds
|
Plot kwargs plus optional |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
BaseFigure
|
The figure containing initial traces, frames, and controls. |
plot(*args, method, fig, **kwds)
General plotting interface.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*args
|
R | tuple[R, dict]
|
TODO. |
()
|
method
|
str
|
Plotting method to use. Implementation must provide |
required |
fig
|
BaseFigure
|
Existing figure to plot into. If not provided, a new figure is created. |
required |
**kwds
|
Additional keyword arguments passed to the plotting method. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
BaseFigure
|
The figure containing the plots. |
plot_bitmap(inp, *, value=0.5, axes=(0, 1), fig, **kwds)
Plot a 2D bitmap.
This method visualizes the input data as a 2D bitmap using a heatmap. To select the color
for the "True" values in the bitmap, use the value argument. This must be within the
range defined by zmin and zmax (arguments to go.Heatmap). zmin and zmax default to
0 and 1, respectively.
Note: Requires the transform_to_bitmap method to be implemented.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to plot. |
required |
value
|
float
|
Value to represent "True" in the bitmap. |
0.5
|
axes
|
Axes2D
|
Two axes to project onto. |
(0, 1)
|
fig
|
BaseFigure
|
Figure to plot into. If not provided, a new figure is created. |
required |
**kwds
|
Additional keyword arguments for the heatmap. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
BaseFigure
|
The figure containing the bitmap plot. |
plot_contour(inp, *, axes=(0, 1), fig, **kwds)
Plot a 2D contour.
This method visualizes the input data as a 2D contour using a contour plot. The contour
levels are determined by the values in the 2D array returned by transform_to_surface.
Note: Requires the transform_to_surface method to be implemented.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to plot. |
required |
axes
|
Axes2D
|
Two axes to project onto. |
(0, 1)
|
fig
|
BaseFigure
|
Figure to plot into. If not provided, a new figure is created. |
required |
**kwds
|
Additional keyword arguments for the contour plot. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
BaseFigure
|
The figure containing the contour plot. |
plot_fill(inp, *, axes=(0, 1), fig, **kwds)
Plot a filled 2D area.
This method visualizes the input data as a filled area using a scatter plot with
fill='toself'. The area is defined by the points returned by transform_to_scatter.
Note: Requires the transform_to_scatter method to be implemented.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to plot. |
required |
axes
|
Axes2D
|
Two axes to project onto. |
(0, 1)
|
fig
|
BaseFigure
|
Figure to plot into. If not provided, a new figure is created. |
required |
**kwds
|
Additional keyword arguments for the scatter plot. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
BaseFigure
|
The figure containing the filled area plot. |
plot_isosurface(inp, *, level=0.0, axes=(0, 1, 2), fig, **kwds)
Plot a 3D isosurface.
This method visualizes the input data as a 3D isosurface using an isosurface plot. The
isosurface is extracted at the specified level from the 3D volume returned by
transform_to_isosurface.
Note: Requires the transform_to_isosurface method to be implemented.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to plot. |
required |
level
|
float
|
Level at which to extract the isosurface. |
0.0
|
axes
|
Axes3D
|
Three axes to project onto. |
(0, 1, 2)
|
fig
|
BaseFigure
|
Figure to plot into. If not provided, a new figure is created. |
required |
**kwds
|
Additional keyword arguments for the isosurface plot. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
BaseFigure
|
The figure containing the isosurface plot. |
plot_surface(inp, *, axes=(0, 1), fig, **kwds)
Plot a 3D surface.
This method visualizes the input data as a 3D surface using a surface plot. The height of
the surface is determined by the values in the 2D array returned by transform_to_surface.
Note: Requires the transform_to_surface method to be implemented.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to plot. |
required |
axes
|
Axes2D
|
Two axes to project onto. |
(0, 1)
|
fig
|
BaseFigure
|
Figure to plot into. If not provided, a new figure is created. |
required |
**kwds
|
Additional keyword arguments for the surface plot. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
BaseFigure
|
The figure containing the surface plot. |
transform_to_bitmap(inp, axes, **kwds)
Transform input data to a bitmap (2D boolean array).
This is a stub implementation. Actual implementation depends on the data type R.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to transform. |
required |
axes
|
Axes2D
|
Two axes to project onto. |
required |
**kwds
|
Additional keyword arguments for the transformation. |
{}
|
Returns:
| Type | Description |
|---|---|
ndarray
|
A 2D boolean numpy array representing the bitmap. |
transform_to_isosurface(inp, axes, **kwds)
Transform input data to a 3D volume (3D float array).
This is a stub implementation. Actual implementation depends on the data type R.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to transform. |
required |
axes
|
Axes3D
|
Three axes to project onto. |
required |
**kwds
|
Additional keyword arguments for the transformation. |
{}
|
Returns:
| Type | Description |
|---|---|
ndarray
|
A 3D float numpy array whose value represents the volume. |
transform_to_scatter(inp, axes, **kwds)
Transform input data to scatter points (N x 2 float array).
This is a stub implementation. Actual implementation depends on the data type R.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to transform. |
required |
axes
|
Axes2D
|
Two axes to project onto. |
required |
**kwds
|
Additional keyword arguments for the transformation. |
{}
|
Returns:
| Type | Description |
|---|---|
ndarray
|
An (N, 2) float numpy array representing the scatter points. |
transform_to_surface(inp, axes, **kwds)
Transform input data to a 3D surface (2D float array).
This is a stub implementation. Actual implementation depends on the data type R.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inp
|
R
|
Input data to transform. |
required |
axes
|
Axes2D
|
Two axes to project onto. |
required |
**kwds
|
Additional keyword arguments for the transformation. |
{}
|
Returns:
| Type | Description |
|---|---|
ndarray
|
A 2D float numpy array whose value represents the surface. |
collect_keys(d, *keys, default=...)
Collect a subset of keys from d.
Behavior:
- If default is Ellipsis (the default), include only keys that exist in d.
- Otherwise, include all requested keys, filling missing ones with default.
Returns: - New dict containing the selected keys.
collect_prefix(d, prefix, remove=False)
Extract and remove items whose keys start with prefix.
Side effect:
- Matching items are popped from d.
Parameters:
- d: source dictionary (mutated)
- prefix: string to match at the start of each key
- remove: if True, strip prefix from keys in the returned dict;
if False, keep original keys
Returns: - New dict of the extracted items.
flatten(nested, *, sep='_', inplace=False)
Flatten nested mappings into a single level by joining keys with sep.
Example: - {"a": {"b": 1}, "c": 2} -> {"a_b": 1, "c": 2} (sep="_")
Parameters:
- nested: mapping to flatten; nested values that are mappings are expanded
- sep: string inserted between joined key parts
- inplace: if True and nested is mutable, mutate it in place; otherwise return a new dict
Returns:
- A flat dict (or the mutated input when inplace=True).
iterwin(seq, winlen=1)
Yield fixed-size windows from an indexable sequence by striding.
Equivalent to: zip((seq[i::winlen] for i in range(winlen))). For generic iterables, prefer: zip([iter(seq)] * winlen).
Parameters: - seq: indexable sequence (supports slicing) - winlen: positive window/stride length
Yields:
- Tuples of length winlen with elements at positions i mod winlen
prefix_keys(d, prefix)
Return a new dict with prefix added to every key in d.
setdefaults(d, *args, **kwds)
Set default key/value pairs on dict d without overwriting existing keys.
Calling conventions: - Keyword form: setdefaults(d, a=1, b=2) - Dict form: setdefaults(d, {'a': 1, 'b': 2}) - Variadic kv: setdefaults(d, 'a', 1, 'b', 2) # even number of args
Raises: - TypeError/ValueError if the calling convention is invalid.
update_theme(name=None, *, aspectratio='4:3', fig)
Apply layout for 2D/3D light/dark themes.
with_figure(f=None, *, dim=None)
Decorator to handle figure creation and theming for plotting methods. Parameters: dim: Dimensionality of the plot (2 or 3).