Skip to content

Index

subsurfaceio.site_investigation.visualization

Site investigation visualization (plots, maps, reports, plot sets).

Classes:

Name Description
HtmlReportDataPage

Vs-depth (or vs-elevation) page.
HtmlReportMetadataPage

Scalar metadata bar page.
HtmlReportMixin

Mixin that writes a multi-page HTML report for a site investigation.
HtmlReportReferencePage

Published reference-figure overlay page.
InSituTestsPlot

Overlay plot of in-situ test depth series vs depth or elevation.
InSituTestsPlotMetadata

Bar/facet plot of in-situ test scalar metadata fields.
InSituTestsPlotSite

Site attachment and per-test styling for in-situ test plots.
InSituTestsReferencePlot

Overlay in-situ test results on a published reference figure.
PlotMetadataSets

Scalar metadata field tuples for bar/facet figures.
PlotRegistryBase

Collect class-level field tuples as named plot sets.
PlotSets

Depth-series field tuples for vs-depth (or vs-elevation) figures.
PlotlyMapMixin

Mixin that builds a Plotly map of in-situ test locations.

Attributes:

Name Type Description
HtmlReportPage TypeAlias

One HTML report page: data, metadata, or a reference figure.
HtmlReportPlotSet TypeAlias

Named HTML report outlines stored in REPORT_PAGES.
REPORT_PAGES dict[HtmlReportPlotSet, tuple[HtmlReportPage, ...]]
SiteInvestigationReferenceFigureName TypeAlias

Catalog names that SiteInvestigation can overlay.

HtmlReportPage module-attribute 

HtmlReportPage: TypeAlias = Annotated[
    HtmlReportDataPage
    | HtmlReportMetadataPage
    | HtmlReportReferencePage,
    Field(discriminator="kind"),
]

One HTML report page: data, metadata, or a reference figure.

HtmlReportPlotSet module-attribute 

HtmlReportPlotSet: TypeAlias = Literal[
    "spt_interpretation",
    "cpt_interpretation",
    "dmt_interpretation",
    "ist_raw",
    "liquefaction",
    "footing_settlements",
    "pile_capacity",
]

Named HTML report outlines stored in REPORT_PAGES.

REPORT_PAGES module-attribute 

REPORT_PAGES: dict[
    HtmlReportPlotSet, tuple[HtmlReportPage, ...]
] = {
    "spt_interpretation": (
        HtmlReportDataPage(kind="data", x=PlotSets.spt_raw),
        HtmlReportDataPage(
            kind="data", x=PlotSets.spt_interpretation_1
        ),
        HtmlReportDataPage(
            kind="data", x=PlotSets.spt_interpretation_2
        ),
        HtmlReportDataPage(
            kind="data", x=PlotSets.spt_interpretation_3
        ),
    ),
    "cpt_interpretation": (
        HtmlReportDataPage(kind="data", x=PlotSets.cpt_raw),
        HtmlReportDataPage(
            kind="data", x=PlotSets.cpt_basic
        ),
        HtmlReportDataPage(
            kind="data", x=PlotSets.cpt_normalized
        ),
        HtmlReportDataPage(
            kind="data", x=PlotSets.cpt_mod_normalized
        ),
        HtmlReportDataPage(
            kind="data", x=PlotSets.soil_transition
        ),
        HtmlReportDataPage(
            kind="data", x=PlotSets.cpt_interpretation_1
        ),
        HtmlReportDataPage(
            kind="data", x=PlotSets.cpt_interpretation_2
        ),
        HtmlReportDataPage(
            kind="data", x=PlotSets.cpt_interpretation_3
        ),
        HtmlReportDataPage(
            kind="data", x=PlotSets.cpt_interpretation_4
        ),
        HtmlReportDataPage(
            kind="data", x=PlotSets.cpt_interpretation_5
        ),
        HtmlReportReferencePage(
            kind="reference", name="SoilBehaviourType"
        ),
        HtmlReportReferencePage(
            kind="reference",
            name="NormalizedSoilBehaviourType",
        ),
        HtmlReportReferencePage(
            kind="reference",
            name="ModifiedSoilBehaviourType",
        ),
    ),
    "dmt_interpretation": (
        HtmlReportDataPage(kind="data", x=PlotSets.dmt_raw),
        HtmlReportDataPage(
            kind="data", x=PlotSets.dmt_basic
        ),
        HtmlReportDataPage(
            kind="data", x=PlotSets.dmt_interpretation
        ),
        HtmlReportReferencePage(
            kind="reference", name="SoilBehaviourTypeDMT"
        ),
    ),
    "ist_raw": (
        HtmlReportDataPage(kind="data", x=PlotSets.ist_raw),
    ),
    "liquefaction": (
        HtmlReportMetadataPage(
            kind="metadata", y=PlotMetadataSets.liquefaction
        ),
        HtmlReportDataPage(
            kind="data", x=PlotSets.liquefaction
        ),
        HtmlReportReferencePage(
            kind="reference", name="LiquefactionDamage"
        ),
    ),
    "footing_settlements": (
        HtmlReportDataPage(
            kind="data", x=PlotSets.footing_settlements
        ),
    ),
    "pile_capacity": (
        HtmlReportDataPage(
            kind="data", x=PlotSets.pile_capacity
        ),
        HtmlReportReferencePage(
            kind="reference", name="SoilTypeIndex"
        ),
    ),
}

SiteInvestigationReferenceFigureName module-attribute 

SiteInvestigationReferenceFigureName: TypeAlias = Literal[
    *SITE_INVESTIGATION_REFERENCE_FIGURES,
]

Catalog names that SiteInvestigation can overlay.

HtmlReportDataPage pydantic-model

Bases: BaseModel

Vs-depth (or vs-elevation) page.

Rendered with get_data_geotech_figure.

Attributes:

Name Type Description
kind Literal['data']

Union tag; must be data.
x tuple[str, ...]

Depth-series field names for one figure.
y Literal['depth', 'elevation']

Vertical axis; depth or elevation.

Config:

  • frozen: True
  • extra: forbid

Fields:

  • kind (Literal['data'])
  • x (tuple[str, ...])
  • y (Literal['depth', 'elevation'])

kind pydantic-field 

kind: Literal['data']

model_config class-attribute instance-attribute 

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

x pydantic-field 

x: tuple[str, ...]

y pydantic-field 

y: Literal['depth', 'elevation'] = 'depth'

HtmlReportMetadataPage pydantic-model

Bases: BaseModel

Scalar metadata bar page.

Rendered with get_metadata_geotech_figure.

Attributes:

Name Type Description
kind Literal['metadata']

Union tag; must be metadata.
y tuple[str, ...]

Metadata field names for one figure.

Config:

  • frozen: True
  • extra: forbid

Fields:

  • kind (Literal['metadata'])
  • y (tuple[str, ...])

kind pydantic-field 

kind: Literal['metadata']

model_config class-attribute instance-attribute 

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

y pydantic-field 

y: tuple[str, ...]

HtmlReportMixin

Mixin that writes a multi-page HTML report for a site investigation.

Methods:

Name Description
write_html_report

Write a multi-page HTML report of in-situ test figures.

write_html_report 

write_html_report(
    path: str | Path,
    pages: HtmlReportPlotSet | Sequence[HtmlReportPage],
    plot_module: Literal["plotly", "mpl"] = "plotly",
) -> Path

Write a multi-page HTML report of in-situ test figures.

pages is a named outline in REPORT_PAGES or an explicit sequence of HtmlReportPage models. Data pages call get_data_geotech_figure, metadata pages call get_metadata_geotech_figure, and reference pages call get_reference_figure.

Parameters:

Name Type Description Default
path str | Path

Output HTML path.

 required
pages HtmlReportPlotSet | Sequence[HtmlReportPage]

Named outline (cpt_interpretation, liquefaction, …) or an explicit page list.

 required
plot_module Literal['plotly', 'mpl']

Figure backend.

 'plotly'

Returns:

Type Description
Path

The written path.

HtmlReportReferencePage pydantic-model

Bases: BaseModel

Published reference-figure overlay page.

Rendered with get_reference_figure.

Attributes:

Name Type Description
kind Literal['reference']

Union tag; must be reference.
name SiteInvestigationReferenceFigureName

Catalog figure that SiteInvestigation can populate.

Config:

  • frozen: True
  • extra: forbid

Fields:

kind pydantic-field 

kind: Literal['reference']

model_config class-attribute instance-attribute 

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

name pydantic-field 

name: SiteInvestigationReferenceFigureName

InSituTestsPlot pydantic-model

Bases: InSituTestsPlotSite

Overlay plot of in-situ test depth series vs depth or elevation.

Each contributing test is one legend entry (color='test_id'). Tests that lack every requested x field are skipped.

Fields:

  • width (float | None)
  • height (float | None)
  • plot_module (Literal['plotly', 'mpl'])
  • x (list[str])
  • y (Literal['depth', 'elevation'])

x pydantic-field 

x: list[str]

y pydantic-field 

y: Literal['depth', 'elevation'] = 'depth'

get_frames 

get_frames() -> pl.DataFrame

Build a concatenated depth-series frame for x.

Returns:

Type Description
DataFrame

Polars frame with test_id, depth (and elevation when
DataFrame

requested), plus the requested x columns.

Raises:

Type Description
ValueError

When no test can supply any requested x field.

get_geotech_figure 

get_geotech_figure(
    axis_map: dict | None = None, **kwargs: Any
) -> GeotechFigureT

Build an unplotted depth-series overlay renderer.

Parameters:

Name Type Description Default
axis_map dict | None

Optional axis overrides merged onto the default map.

 None
**kwargs Any

Plotly Express / matplotlib-express overrides.

 {}

Returns:

Type Description
GeotechFigureT

GeotechFigure (or the matplotlib equivalent). Call plot() to draw.

InSituTestsPlotMetadata pydantic-model

Bases: InSituTestsPlotSite

Bar/facet plot of in-situ test scalar metadata fields.

Each contributing test is one legend entry (color='test_id'). Tests that lack the requested y fields are skipped.

Fields:

facet_col_wrap pydantic-field 

facet_col_wrap: int = 2

x pydantic-field 

x: Literal['test_id'] = 'test_id'

y pydantic-field 

y: list[str]

get_frames 

get_frames() -> pl.DataFrame

Build a concatenated metadata frame for y.

Returns:

Type Description
DataFrame

Polars frame with test_id plus the requested y columns.

Raises:

Type Description
ValueError

When no test can supply any requested y field.

get_geotech_figure 

get_geotech_figure(**kwargs: Any) -> GeotechFigureT

Build an unplotted metadata bar/facet renderer.

Parameters:

Name Type Description Default
**kwargs Any

Plotly Express / matplotlib-express overrides.

 {}

Returns:

Type Description
GeotechFigureT

GeotechFigure (or the matplotlib equivalent). Call plot() to draw.

InSituTestsPlotSite pydantic-model

Bases: Model

Site attachment and per-test styling for in-situ test plots.

Fields:

color_discrete_map property 

color_discrete_map: dict[str, str]

Per-test_id color for tests that set an explicit color.

height pydantic-field 

height: float | None = 8.27 * 96

plot_module pydantic-field 

plot_module: Literal['plotly', 'mpl'] = 'plotly'

site property 

site: SiteInvestigation

Site bound by attach_site.

style_map property 

style_map: dict[str, StyleMap]

Per-test_id line/marker style from each test's plot settings.

symbol_map property 

symbol_map: dict[str, str]

Per-test_id marker symbol from each test's plot settings.

width pydantic-field 

width: float | None = 11.69 * 96

attach_site 

attach_site(site: SiteInvestigation) -> Self

Bind this plot spec to a site investigation.

Parameters:

Name Type Description Default
site SiteInvestigation

Site whose in-situ tests supply traces and styling.

 required

Returns:

Type Description
Self

This plot spec.

InSituTestsReferencePlot pydantic-model

Bases: InSituTestsPlotSite

Overlay in-situ test results on a published reference figure.

Each contributing test is one legend entry (color='test_id'), matching InSituTestsPlot. Tests that lack the axes for name are skipped; null overlay values in a kept test are left in the frame (the renderer omits them). Plasticity and liquefaction-susceptibility charts use specimen Atterberg limits, not SPT data. Ishihara H1 of inf (no layer with FS≤1) is kept and is not clipped to the published 0–10 m x-axis.

from subsurfaceio.site_investigation import SiteInvestigation

fig = site.get_reference_figure(
    name='ModifiedSoilBehaviourType',
).plot().fig

Fields:

name pydantic-field 

name: SiteInvestigationReferenceFigureName

get_figure 

get_figure(**kwargs: Any) -> ReferenceFigureT

Build an unplotted reference-figure renderer for the site overlay.

Parameters:

Name Type Description Default
**kwargs Any

Plotly Express / matplotlib-express overrides merged into the catalog plot model.

 {}

Returns:

Type Description
ReferenceFigureT

PlotlyReferenceFigure or MplReferenceFigure from plot_module. Call plot() to draw.

get_frames 

get_frames() -> pl.DataFrame

Build a concatenated overlay frame for name.

Returns:

Type Description
DataFrame

Polars frame with test_id plus the catalog x/y columns.

Raises:

Type Description
ValueError

When no test can supply both catalog axes.

plot 

plot(**kwargs: Any) -> Any

Render the overlay and return the backend figure object.

Parameters:

Name Type Description Default
**kwargs Any

Plotly Express / matplotlib-express overrides merged into the catalog plot model.

 {}

Returns:

Type Description
Any

Plotly or matplotlib figure from plot_module.

PlotMetadataSets

Bases: PlotRegistryBase

Scalar metadata field tuples for bar/facet figures.

Pass a set as y to get_metadata_geotech_figure or as HtmlReportMetadataPage.y.

Attributes:

Name Type Description
liquefaction tuple[str, ...]

Liquefaction profile-sum scalars.

liquefaction class-attribute 

liquefaction: tuple[str, ...] = (
    "liquefaction_potential_index_sum",
    "liquefaction_severity_number_sum",
    "liquefaction_settlement_sum",
    "lateral_displacement_index_sum",
)

Liquefaction profile-sum scalars.

PlotRegistryBase

Collect class-level field tuples as named plot sets.

Subclass attributes that are flat tuple[str, ...] values (not nested page outlines) are the atomic sets returned by atomic_sets.

Methods:

Name Description
atomic_sets

Named field tuples for a single figure (not nested page outlines).

atomic_sets classmethod 

atomic_sets() -> dict[str, tuple[str, ...]]

Named field tuples for a single figure (not nested page outlines).

Returns:

Type Description
dict[str, tuple[str, ...]]

Mapping of attribute name to parameter-name tuple.

PlotSets

Bases: PlotRegistryBase

Depth-series field tuples for vs-depth (or vs-elevation) figures.

Pass a set as x to get_data_geotech_figure or as HtmlReportDataPage.x. Named outlines in REPORT_PAGES compose these sets into multi-page HTML reports.

Attributes:

Name Type Description
cpt_basic tuple[str, ...]

CPT corrected tip, friction ratio, and non-normalized SBT.
cpt_interpretation_1 tuple[str, ...]

CPT permeability, equivalent SPT, and strength interpretation.
cpt_interpretation_2 tuple[str, ...]

CPT stiffness and undrained-strength interpretation.
cpt_interpretation_3 tuple[str, ...]

CPT velocity, state, and peak-friction interpretation.
cpt_interpretation_4 tuple[str, ...]

CPT unit-weight and index-property interpretation.
cpt_interpretation_5 tuple[str, ...]

CPT clean-sand equivalent resistance and residual strength.
cpt_mod_normalized tuple[str, ...]

CPT modified stress-normalized traces and SBT.
cpt_normalized tuple[str, ...]

CPT stress-normalized traces and SBT.
cpt_raw tuple[str, ...]

CPT raw traces.
dmt_basic tuple[str, ...]

DMT corrected p0/p1/p2 pressures.
dmt_interpretation tuple[str, ...]

DMT Marchetti interpretation traces.
dmt_raw tuple[str, ...]

DMT raw A/B/C readings.
footing_settlements tuple[str, ...]

Shallow-foundation settlement traces.
ist_raw tuple[str, ...]

IST shear and compressional velocity.
liquefaction tuple[str, ...]

Liquefaction triggering and consequence traces.
pile_capacity tuple[str, ...]

CPT pile-capacity traces.
site_response tuple[str, ...]

Site-response input traces assembled from in-situ interpretation.
soil_transition tuple[str, ...]

CPT soil-behavior-type index and transition flag.
spt_interpretation_1 tuple[str, ...]

SPT strength and residual-strength interpretation.
spt_interpretation_2 tuple[str, ...]

SPT clay strength and compressibility interpretation.
spt_interpretation_3 tuple[str, ...]

SPT stiffness and at-rest earth-pressure interpretation.
spt_raw tuple[str, ...]

SPT raw traces and index tests.

cpt_basic class-attribute 

cpt_basic: tuple[str, ...] = (
    "corrected_cone_tip_resistance",
    "friction_ratio",
    "pore_pressure",
    "non_normalized_soil_behavior_type_index",
    "soil_behavior_type_label",
)

CPT corrected tip, friction ratio, and non-normalized SBT.

cpt_interpretation_1 class-attribute 

cpt_interpretation_1: tuple[str, ...] = (
    "permeability",
    "corrected_blow_count",
    "elasticity_modulus",
    "relative_density",
    "friction_angle",
)

CPT permeability, equivalent SPT, and strength interpretation.

cpt_interpretation_2 class-attribute 

cpt_interpretation_2: tuple[str, ...] = (
    "constrained_modulus",
    "small_strain_shear_modulus",
    "undrained_shear_strength",
    "undrained_shear_strength_ratio",
    "overconsolidation_ratio",
)

CPT stiffness and undrained-strength interpretation.

cpt_interpretation_3 class-attribute 

cpt_interpretation_3: tuple[str, ...] = (
    "shear_velocity",
    "state_parameter",
    "coefficient_of_earth_pressure_at_rest",
    "sensitivity",
    "peak_friction_angle",
)

CPT velocity, state, and peak-friction interpretation.

cpt_interpretation_4 class-attribute 

cpt_interpretation_4: tuple[str, ...] = (
    "unit_weight",
    "water_content",
    "void_ratio",
    "dry_unit_weight",
    "porosity",
    "plasticity_index",
)

CPT unit-weight and index-property interpretation.

cpt_interpretation_5 class-attribute 

cpt_interpretation_5: tuple[str, ...] = (
    "corrected_cone_tip_resistance",
    "stress_normalized_cone_resistance",
    "soil_behavior_type_index",
    "clean_sand_normalized_cone_resistance",
    "normalized_residual_shear_strength",
)

CPT clean-sand equivalent resistance and residual strength.

cpt_mod_normalized class-attribute 

cpt_mod_normalized: tuple[str, ...] = (
    "stress_normalized_cone_resistance",
    "normalized_friction_ratio",
    "normalized_pore_pressure",
    "modified_soil_behavior_type_index",
    "modified_soil_behavior_type_label",
)

CPT modified stress-normalized traces and SBT.

cpt_normalized class-attribute 

cpt_normalized: tuple[str, ...] = (
    "stress_normalized_cone_resistance",
    "normalized_friction_ratio",
    "normalized_pore_pressure_ratio",
    "soil_behavior_type_index",
    "normalized_soil_behavior_type_label",
)

CPT stress-normalized traces and SBT.

cpt_raw class-attribute 

cpt_raw: tuple[str, ...] = (
    "cone_tip_resistance",
    "sleeve_friction",
    "pore_pressure",
)

CPT raw traces.

dmt_basic class-attribute 

dmt_basic: tuple[str, ...] = (
    "corrected_pressure_p0",
    "corrected_pressure_p1",
    "corrected_pressure_p2",
)

DMT corrected p0/p1/p2 pressures.

dmt_interpretation class-attribute 

dmt_interpretation: tuple[str, ...] = (
    "material_index",
    "material_description",
    "constrained_modulus",
    "undrained_shear_strength",
    "friction_angle",
    "horizontal_stress_index",
    "shear_velocity",
)

DMT Marchetti interpretation traces.

dmt_raw class-attribute 

dmt_raw: tuple[str, ...] = (
    "raw_a_reading",
    "raw_b_reading",
    "raw_c_reading",
)

DMT raw A/B/C readings.

footing_settlements class-attribute 

footing_settlements: tuple[str, ...] = (
    "stress_influence_factor",
    "imposed_stress",
    "footing_settlement_inc",
    "footing_settlement",
)

Shallow-foundation settlement traces.

ist_raw class-attribute 

ist_raw: tuple[str, ...] = (
    "shear_velocity",
    "compressional_velocity",
)

IST shear and compressional velocity.

liquefaction class-attribute 

liquefaction: tuple[str, ...] = (
    "liquefaction_safety_factor",
    "liquefaction_probability",
    "liquefaction_potential_index",
    "liquefaction_severity_number",
    "lateral_displacement_index",
    "lateral_spread_displacement",
    "liquefaction_settlement",
)

Liquefaction triggering and consequence traces.

pile_capacity class-attribute 

pile_capacity: tuple[str, ...] = (
    "soil_type_index_label",
    "equivalent_cone_resistance",
    "effective_cone_resistance",
    "effective_cone_resistance_geometric_mean",
    "pile_tip_resistance",
    "pile_shaft_resistance",
    "pile_ultimate_resistance",
)

CPT pile-capacity traces.

site_response class-attribute 

site_response: tuple[str, ...] = (
    "corrected_blow_count",
    "fines_content",
    "plasticity_index",
    "unit_weight",
    "undrained_shear_strength",
    "overconsolidation_ratio",
    "uniformity_coefficient",
    "diameter_at_50_percent_finer",
    "friction_angle",
    "peak_friction_angle",
    "shear_velocity",
    "coefficient_of_earth_pressure_at_rest",
    "soil_behavior_type_index",
    "material_index",
    "uscs_symbol",
)

Site-response input traces assembled from in-situ interpretation.

soil_transition class-attribute 

soil_transition: tuple[str, ...] = (
    "soil_behavior_type_index",
    "soil_transition",
)

CPT soil-behavior-type index and transition flag.

spt_interpretation_1 class-attribute 

spt_interpretation_1: tuple[str, ...] = (
    "corrected_blow_count",
    "normalized_blow_count",
    "relative_density",
    "friction_angle",
    "post_liquefaction_residual_shear_strength",
    "uscs_symbol",
)

SPT strength and residual-strength interpretation.

spt_interpretation_2 class-attribute 

spt_interpretation_2: tuple[str, ...] = (
    "corrected_blow_count",
    "undrained_shear_strength",
    "overconsolidation_ratio",
    "remolded_undrained_shear_strength",
    "compression_ratio",
    "recompression_ratio",
    "constrained_modulus",
    "uscs_symbol",
)

SPT clay strength and compressibility interpretation.

spt_interpretation_3 class-attribute 

spt_interpretation_3: tuple[str, ...] = (
    "corrected_blow_count",
    "shear_velocity",
    "small_strain_shear_modulus",
    "elasticity_modulus",
    "coefficient_of_earth_pressure_at_rest",
    "uscs_symbol",
)

SPT stiffness and at-rest earth-pressure interpretation.

spt_raw class-attribute 

spt_raw: tuple[str, ...] = (
    "uscs_symbol",
    "blow_count",
    "fines_content",
    "water_content",
    "liquid_limit",
    "plasticity_index",
)

SPT raw traces and index tests.

PlotlyMapMixin

Mixin that builds a Plotly map of in-situ test locations.

Methods:

Name Description
get_plotly_map

Scatter map of tests that have latitude and longitude.

get_plotly_map 

get_plotly_map(
    zoom: int = 15,
    map_style: Literal[
        "basic", "open-street-map", "satellite-streets"
    ] = "basic",
) -> go.Figure

Scatter map of tests that have latitude and longitude.

Parameters:

Name Type Description Default
zoom int

Initial map zoom.

 15
map_style Literal['basic', 'open-street-map', 'satellite-streets']

Plotly map style.

 'basic'

Returns:

Type Description
Figure

Plotly scatter-map figure. Tests missing coordinates are skipped.