Index
General-purpose plotting API.
Describe a plot as a serializable specification, then render it with either backend. The specifications mirror the Plotly Express chart signatures, so a payload can cross a process boundary and be drawn on the far side.
This package exports only the specifications, which cost nothing beyond pydantic to import. Each backend figure is imported from its own module, so consumers that only build or inspect specifications never pay for a rendering stack, and the import itself states which backend is being pulled in:
from subsurfaceio.plot import Line
from subsurfaceio.plot.figure_plotly import PlotlyFigure
fig = PlotlyFigure(
plot_model=Line(plot_type='line', x=[0, 1, 2], y=[0, 1, 4]),
).plot().fig
MplFigure renders the same specification with
matplotlib and requires the mpl extra; importing that module is what
enforces the requirement.
Modules:
| Name | Description |
|---|---|
base |
Backend-agnostic figure contract. |
figure_mpl |
Matplotlib backend for express plot specifications. |
figure_plotly |
Plotly backend for express plot specifications. |
mixins |
Backend figure mixins composed onto |
Classes:
| Name | Description |
|---|---|
Bar |
Specification for a bar chart, mirroring |
Line |
Specification for a line plot, mirroring |
Scatter |
Specification for a scatter plot, mirroring |
ScatterTernary |
Specification for a ternary scatter, mirroring |
SubplotInfo |
One subplot, paired with the variables mapped to its axes. |
Attributes:
| Name | Type | Description |
|---|---|---|
DiscriminatedPlotModel |
TypeAlias
|
Plot specification resolved from the |
PlotModel |
TypeAlias
|
Any supported plot specification. |
module-attribute
Plot specification resolved from the plot_type discriminator.
Use this as the field annotation so a serialized payload selects its own model.
module-attribute
Any supported plot specification.
pydantic-model
Bases: BaseModel
Specification for a bar chart, mirroring plotly.express.bar.
Config:
extra:forbid
Fields:
-
plot_type(Literal['bar']) -
data_frame(Any) -
x(Any) -
y(Any) -
color(Any) -
pattern_shape(Any) -
facet_row(Any) -
facet_col(Any) -
facet_col_wrap(int | None) -
facet_row_spacing(Any) -
facet_col_spacing(Any) -
hover_name(Any) -
hover_data(Any) -
custom_data(Any) -
text(Any) -
base(Any) -
error_x(Any) -
error_x_minus(Any) -
error_y(Any) -
error_y_minus(Any) -
animation_frame(Any) -
animation_group(Any) -
category_orders(Any) -
labels(Any) -
color_discrete_sequence(Any) -
color_discrete_map(Any) -
color_continuous_scale(Any) -
pattern_shape_sequence(Any) -
pattern_shape_map(Any) -
range_color(Any) -
color_continuous_midpoint(Any) -
opacity(Any) -
orientation(Any) -
barmode(Any) -
log_x(bool) -
log_y(bool) -
range_x(Any) -
range_y(Any) -
text_auto(bool) -
title(Any) -
subtitle(Any) -
template(Any) -
width(Any) -
height(Any)
pydantic-model
Bases: BaseModel
Specification for a line plot, mirroring plotly.express.line.
Config:
extra:forbid
Fields:
-
plot_type(Literal['line']) -
data_frame(Any) -
x(Any) -
y(Any) -
line_group(Any) -
color(Any) -
line_dash(Any) -
symbol(Any) -
hover_name(Any) -
hover_data(Any) -
custom_data(Any) -
text(Any) -
facet_row(Any) -
facet_col(Any) -
facet_col_wrap(int | None) -
facet_row_spacing(Any) -
facet_col_spacing(Any) -
error_x(Any) -
error_x_minus(Any) -
error_y(Any) -
error_y_minus(Any) -
animation_frame(Any) -
animation_group(Any) -
category_orders(Any) -
labels(Any) -
orientation(Any) -
color_discrete_sequence(Any) -
color_discrete_map(Any) -
line_dash_sequence(Any) -
line_dash_map(Any) -
symbol_sequence(Any) -
symbol_map(Any) -
markers(bool) -
log_x(bool) -
log_y(bool) -
range_x(Any) -
range_y(Any) -
line_shape(Any) -
render_mode(Any) -
title(Any) -
subtitle(Any) -
template(Any) -
width(Any) -
height(Any)
pydantic-model
Bases: BaseModel
Specification for a scatter plot, mirroring plotly.express.scatter.
Config:
extra:forbid
Fields:
-
plot_type(Literal['scatter']) -
data_frame(Any) -
x(Any) -
y(Any) -
color(Any) -
symbol(Any) -
size(Any) -
hover_name(Any) -
hover_data(Any) -
custom_data(Any) -
text(Any) -
facet_row(Any) -
facet_col(Any) -
facet_col_wrap(int | None) -
facet_row_spacing(Any) -
facet_col_spacing(Any) -
error_x(Any) -
error_x_minus(Any) -
error_y(Any) -
error_y_minus(Any) -
animation_frame(Any) -
animation_group(Any) -
category_orders(Any) -
labels(Any) -
orientation(Any) -
color_discrete_sequence(Any) -
color_discrete_map(Any) -
color_continuous_scale(Any) -
range_color(Any) -
color_continuous_midpoint(Any) -
symbol_sequence(Any) -
symbol_map(Any) -
opacity(Any) -
size_max(Any) -
marginal_x(Any) -
marginal_y(Any) -
trendline(Any) -
trendline_options(Any) -
trendline_color_override(Any) -
trendline_scope(Any) -
log_x(bool) -
log_y(bool) -
range_x(Any) -
range_y(Any) -
render_mode(Any) -
title(Any) -
subtitle(Any) -
template(Any) -
width(Any) -
height(Any)
pydantic-model
Bases: BaseModel
Specification for a ternary scatter, mirroring plotly.express.scatter_ternary.
Config:
extra:forbid
Fields:
-
plot_type(Literal['scatter_ternary']) -
data_frame(Any) -
a(Any) -
b(Any) -
c(Any) -
color(Any) -
symbol(Any) -
size(Any) -
text(Any) -
hover_name(Any) -
hover_data(Any) -
custom_data(Any) -
animation_frame(Any) -
animation_group(Any) -
category_orders(Any) -
labels(Any) -
color_discrete_sequence(Any) -
color_discrete_map(Any) -
color_continuous_scale(Any) -
range_color(Any) -
color_continuous_midpoint(Any) -
symbol_sequence(Any) -
symbol_map(Any) -
opacity(Any) -
size_max(Any) -
title(Any) -
subtitle(Any) -
template(Any) -
width(Any) -
height(Any)
dataclass
One subplot, paired with the variables mapped to its axes.
Attributes:
| Name | Type | Description |
|---|---|---|
row |
int
|
One-based row index, counted so that row 1 is the bottom row,
matching the express |
col |
int
|
One-based column index, counted left to right. |
x_var |
str | None
|
Variable drawn on the x-axis, or |
y_var |
str | None
|
Variable drawn on the y-axis, or |
subplot |
Any
|
Backend subplot handle. A |