Skip to content

Index

subsurfaceio.reference_figure

Published geotechnical reference charts.

Catalog specs are preloaded once, immutable, and safe to share. Plot data_frame and optional overlays are passed at render time.

This package exports only the specifications and catalog. Each backend figure is imported from its own module, so consumers that only look up or interpolate a spec never pay for a rendering stack:

from subsurfaceio.reference_figure import reference_figure_catalog
from subsurfaceio.reference_figure.figure_plotly import PlotlyReferenceFigure

spec = reference_figure_catalog.get("USCSPlasticityChart")
fig = spec.render_plotly(data_frame=df).fig

MplReferenceFigure renders the same specification with matplotlib and requires the mpl extra; importing that module is what enforces the requirement.

Modules:

Name Description
figure_mpl

Matplotlib renderer for reference figure specs.
figure_plotly

Plotly renderer for reference figure specs.
overlays

Builders for annotation overlays drawn on reference figures.

Classes:

Name Description
CartesianLineShape

Cartesian reference curve (non-filled line).
CartesianPolygonShape

Cartesian filled polygon region.
Overlay

User or computed trace drawn on top of a reference figure.
ReferenceFigureCatalog

Namespace for predefined reference figures.
ReferenceFigureSpec

Specification of a published reference figure — not a rendered plot.
SecondaryAxis

Top or right axis tick mapping for dual-scale reference charts.
TernaryPolygonShape

Ternary filled polygon region.

Attributes:

Name Type Description
ReferenceFigureName TypeAlias

Literal union of all catalog figure names.
ReferenceFigureShape TypeAlias

Discriminated background shape: line, cartesian polygon, or ternary polygon.
reference_figure_catalog

Default catalog instance; preferred entry point for predefined figures.

ReferenceFigureName module-attribute 

ReferenceFigureName: TypeAlias = Literal[
    *reference_figures.keys(),
]

Literal union of all catalog figure names.

ReferenceFigureShape module-attribute 

ReferenceFigureShape: TypeAlias = Annotated[
    CartesianLineShape
    | CartesianPolygonShape
    | TernaryPolygonShape,
    Field(discriminator="kind"),
]

Discriminated background shape: line, cartesian polygon, or ternary polygon.

reference_figure_catalog module-attribute 

reference_figure_catalog = ReferenceFigureCatalog()

Default catalog instance; preferred entry point for predefined figures.

CartesianLineShape pydantic-model

Bases: ShapeBase

Cartesian reference curve (non-filled line).

Attributes:

Name Type Description
kind Literal['line']

Union tag; must be line.
x list[float]

Abscissa samples.
y list[float]

Ordinate samples.
line_dash str | None

Dash style, or None.

Fields:

  • name (str)
  • label (str | None)
  • color (str | None)
  • kind (Literal['line'])
  • x (list[float])
  • y (list[float])
  • line_dash (str | None)

Validators:

  • _coords_same_length

kind pydantic-field 

kind: Literal['line'] = 'line'

line_dash pydantic-field 

line_dash: str | None = 'solid'

x pydantic-field 

x: list[float]

y pydantic-field 

y: list[float]

CartesianPolygonShape pydantic-model

Bases: ShapeBase

Cartesian filled polygon region.

Attributes:

Name Type Description
kind Literal['polygon']

Union tag; must be polygon.
x list[float]

Vertex abscissas.
y list[float]

Vertex ordinates.
centroid tuple[float, float] | None

Optional label position.
alpha float

Fill opacity.

Fields:

  • name (str)
  • label (str | None)
  • color (str | None)
  • kind (Literal['polygon'])
  • x (list[float])
  • y (list[float])
  • centroid (tuple[float, float] | None)
  • alpha (float)

Validators:

  • _coords_same_length

alpha pydantic-field 

alpha: float = 1.0

centroid pydantic-field 

centroid: tuple[float, float] | None = None

kind pydantic-field 

kind: Literal['polygon'] = 'polygon'

x pydantic-field 

x: list[float]

y pydantic-field 

y: list[float]

Overlay pydantic-model

Bases: BaseModel

User or computed trace drawn on top of a reference figure.

Attributes:

Name Type Description
x Any

Abscissa value(s).
y Any

Ordinate value(s).
name str | None

Legend label.
mode TraceMode

Plotly trace mode ('markers', 'lines', etc.).
color Color | None

Marker or line color.
marker_symbol MarkerSymbol | None

Plotly marker symbol when mode includes markers.

Config:

  • frozen: True
  • extra: forbid

Fields:

color pydantic-field 

color: Color | None = None

marker_symbol pydantic-field 

marker_symbol: MarkerSymbol | None = 'circle'

mode pydantic-field 

mode: TraceMode = 'markers'

model_config class-attribute instance-attribute 

model_config = ConfigDict(frozen=True, extra='forbid')

name pydantic-field 

name: str | None = None

x pydantic-field 

x: Any

y pydantic-field 

y: Any

ReferenceFigureCatalog

Namespace for predefined reference figures.

Use reference_figure_catalog.get(name) and reference_figure_catalog.names(). Pass annotation overlays at render time via overlays on render_mpl / render_plotly.

Methods:

Name Description
get

Return the cached immutable spec for name.
names

Return all catalog figure names.

get 

get(name: ReferenceFigureName) -> ReferenceFigureSpec

Return the cached immutable spec for name.

Parameters:

Name Type Description Default
name ReferenceFigureName

Catalog figure name.

 required

Returns:

Type Description
ReferenceFigureSpec

Cached immutable spec.

Raises:

Type Description
KeyError

When name is not in the catalog.

names 

names() -> tuple[str, ...]

Return all catalog figure names.

Returns:

Type Description
tuple[str, ...]

Catalog figure names in definition order.

ReferenceFigureSpec pydantic-model

Bases: BaseModel

Specification of a published reference figure — not a rendered plot.

Cached catalog specs are immutable and shareable. Annotation overlays (sieve D-values, Atterberg flow curves) are passed via the overlays argument to render_plotly / render_mpl.

Attributes:

Name Type Description
plot_model DiscriminatedPlotModel

Discriminated Plotly Express / matplotlib-express model.
reference_data list[ReferenceFigureShape] | None

Background lines and polygon regions from the catalog.
secondary_axis SecondaryAxis | None

Optional top/right tick label maps.
reference str | None

Bibliography id from the catalog, or None.

Config:

  • frozen: True
  • extra: forbid

Fields:

model_config class-attribute instance-attribute 

model_config = ConfigDict(frozen=True, extra='forbid')

plot_model pydantic-field 

plot_model: DiscriminatedPlotModel

reference pydantic-field 

reference: str | None = None

reference_data pydantic-field 

reference_data: list[ReferenceFigureShape] | None = None

secondary_axis pydantic-field 

secondary_axis: SecondaryAxis | None = None

as_reference_data 

as_reference_data() -> ReferenceDataSet

Convert line-family background curves to a ReferenceDataSet.

Returns:

Type Description
ReferenceDataSet

Tabular curves sharing a common x-column.

Raises:

Type Description
NotImplementedError

For ternary plot models.
ValueError

When background data is empty, not cartesian lines, or the lines do not share the same x values.

assign_polygons_labels_from_xy_data 

assign_polygons_labels_from_xy_data(
    x: ndarray,
    y: ndarray,
    clip_xy_to_axis_limits: bool = False,
    not_found_label: object = STRING_DTYPE_NA,
) -> np.ndarray

Assign each (x, y) pair the polygon name that contains it.

Parameters:

Name Type Description Default
x ndarray

Abscissa values.

 required
y ndarray

Ordinate values.

 required
clip_xy_to_axis_limits bool

Clip inputs to plot_model axis ranges first.

 False
not_found_label object

Label for points outside all polygons.

 STRING_DTYPE_NA

Returns:

Type Description
ndarray

Array of polygon names (string dtype).

Raises:

Type Description
NotImplementedError

For ternary plot models.
ValueError

When background data is missing or not cartesian polygons.

get_reference_data_by_id 

get_reference_data_by_id(
    reference_data_label: str,
) -> ReferenceFigureShape | None

Return the background element whose name matches reference_data_label.

Parameters:

Name Type Description Default
reference_data_label str

name of the background element.

 required

Returns:

Type Description
ReferenceFigureShape | None

Matching shape, or None if absent.

interpolate_at_x 

interpolate_at_x(
    x: float | ndarray,
    reference_data_label: str = "self",
    kind: str = "linear",
    fill_value: float | None = None,
    label_search_closest_value: float | None = None,
    switch_x_and_y: bool = False,
) -> float | np.ndarray

Interpolate along a reference curve at one or more abscissa values.

Catalog curves that represent the primary relationship use the conventional name 'self'.

Parameters:

Name Type Description Default
x float | ndarray

Value(s) on the plot x-axis (or y-axis when switch_x_and_y).

 required
reference_data_label str

name of the background element to sample. Defaults to 'self', the catalog convention for the primary curve.

 'self'
kind str

Interpolation kind passed to scipy (default linear).

 'linear'
fill_value float | None

Value for out-of-range x; None leaves NaN.

 None
label_search_closest_value float | None

When set, pick the curve whose name suffix =value is nearest to this number.

 None
switch_x_and_y bool

Interpolate y as a function of x on the chart by swapping stored coordinates.

 False

Returns:

Type Description
float | ndarray

Interpolated ordinate value(s).

Raises:

Type Description
NotImplementedError

For ternary plot models.
ValueError

When no matching cartesian line exists.

render_mpl 

render_mpl(**plot_kwargs: Any) -> MplReferenceFigure

Render a MplReferenceFigure with optional plot overrides.

Parameters:

Name Type Description Default
**plot_kwargs Any

Overrides forwarded to the figure constructor (for example data_frame and overlays).

 {}

Returns:

Type Description
MplReferenceFigure

Plotted matplotlib figure.

render_plotly 

render_plotly(**plot_kwargs: Any) -> PlotlyReferenceFigure

Render a PlotlyReferenceFigure with optional plot overrides.

Parameters:

Name Type Description Default
**plot_kwargs Any

Overrides forwarded to the figure constructor (for example data_frame and overlays).

 {}

Returns:

Type Description
PlotlyReferenceFigure

Plotted Plotly figure.

SecondaryAxis pydantic-model

Bases: BaseModel

Top or right axis tick mapping for dual-scale reference charts.

Used by sieve and hydrometer charts to show particle size alongside sieve numbers. Keys are axis data values; values are tick labels.

Attributes:

Name Type Description
x dict[float, str] | None

Map of x-axis data values to tick labels.
y dict[float, str] | None

Map of y-axis data values to tick labels.
font_size float

Tick label size in CSS pixels.

Config:

  • frozen: True
  • extra: forbid

Fields:

  • x (dict[float, str] | None)
  • y (dict[float, str] | None)
  • font_size (float)

font_size pydantic-field 

font_size: float = 11.0

model_config class-attribute instance-attribute 

model_config = ConfigDict(frozen=True, extra='forbid')

x pydantic-field 

x: dict[float, str] | None = None

y pydantic-field 

y: dict[float, str] | None = None

TernaryPolygonShape pydantic-model

Bases: ShapeBase

Ternary filled polygon region.

Attributes:

Name Type Description
kind Literal['ternary']

Union tag; must be ternary.
a list[float]

First barycentric coordinate samples.
b list[float]

Second barycentric coordinate samples.
c list[float]

Third barycentric coordinate samples.
centroid tuple[float, float, float] | None

Optional label position.
alpha float

Fill opacity.

Fields:

  • name (str)
  • label (str | None)
  • color (str | None)
  • kind (Literal['ternary'])
  • a (list[float])
  • b (list[float])
  • c (list[float])
  • centroid (tuple[float, float, float] | None)
  • alpha (float)

Validators:

  • _coords_same_length

a pydantic-field 

a: list[float]

alpha pydantic-field 

alpha: float = 1.0

b pydantic-field 

b: list[float]

c pydantic-field 

c: list[float]

centroid pydantic-field 

centroid: tuple[float, float, float] | None = None

kind pydantic-field 

kind: Literal['ternary'] = 'ternary'