Index

subsurfaceio.site_investigation

Site investigation models, calculations, plots, and export.

SiteInvestigation holds in-situ tests (in_situ_tests: CPT, DMT, borehole / SPT, IST, UDT), laboratory specimens (laboratory), and field strata.

Run interpretation (Robertson CPT, Marchetti DMT, SPT). Liquefaction triggering: CPT (Robertson, Idriss 2008, Boulanger 2014, Saye 2021), DMT (Marchetti), SPT (Cetin 2004, Idriss 2008, Boulanger 2014, Cetin 2018); shear-induced building settlement (Bray 2017). Shallow-foundation settlements and capacity, and pile capacity from in-situ data. Aggregate and run parametric studies with analysis. Plot, map, and write HTML reports with visualization (including published reference-figure overlays); draw graphical logs through subsurfaceio.logplot. Read and write Excel, CPeT-IT, AGS (including Next-Generation Liquefaction), KML maps, DXF maps, and DXF cross-sections (subsurfaceio.cross_section) through io.

from subsurfaceio.project import ProjectMetadata
from subsurfaceio.site_investigation import SiteInvestigation

site = SiteInvestigation(
    project_metadata=ProjectMetadata(project_id='demo'),
)
fig = site.get_data_geotech_figure(x=['cone_tip_resistance']).plot().fig

Modules:

Name	Description
`analysis`	Site investigation analysis (aggregation, parametric).
`in_situ_tests`	In-situ test models (CPT, DMT, borehole, IST, UDT).
`io`	Site investigation IO mixins (Excel, AGS, KML, DXF).
`laboratory`	Laboratory test models for borehole specimens.
`strata`	Field log strata models and helpers.
`visualization`	Site investigation visualization (plots, maps, reports, plot sets).

Classes:

Name	Description
`SiteInvestigation`	Site investigation container for in-situ tests, calculations, plots, and maps.

Functions:

Name	Description
`get_elevation_vector`	Elevation samples derived from surface elevation minus depth.
`set_cpts_from_cpetit_associated_file`	Fill CPT data from each test's CPeT-IT associated Excel file.

SiteInvestigation `pydantic-model`

Bases: Model, IOExcelMixin, IOCPeTITExcelMixin, IOAGSMixin, IONextGenerationLiquefactionAGSMixin, IOKMLMixin, IODXFMapMixin, IODXFCrossSectionMixin, PlotlyMapMixin, HtmlReportMixin

Site investigation container for in-situ tests, calculations, plots, and maps.

Fields:

project_metadata (ProjectMetadata)
in_situ_tests (list[DiscriminatedInSituTest])

Validators:

_validate_in_situ_tests → in_situ_tests

in_situ_tests `pydantic-field`

in_situ_tests: list[DiscriminatedInSituTest]

project_metadata `pydantic-field`

project_metadata: ProjectMetadata

add_test

add_test(test: InSituTest) -> Self

Append an in-situ test and bind it to this site.

Parameters:

Name	Type	Description	Default
`test`	`InSituTest`	Test to add. `metadata.test_id` must be unique on the site.	required

Returns:

Type	Description
`Self`	This site investigation.

Raises:

Type	Description
`ValueError`	When `test_id` is missing or duplicated, or a sample id collides with an existing borehole sample.

calculate_footing_capacity

calculate_footing_capacity() -> Self

Run shallow-foundation capacity on each supporting test and store results.

Tests without data or without FootingCapacityMixin are skipped.

Returns:

Type	Description
`Self`	This site investigation.

calculate_footing_settlements

calculate_footing_settlements() -> Self

Run shallow-foundation settlement on each supporting test and store results.

Tests without data or without FootingSettlementsMixin are skipped.

Returns:

Type	Description
`Self`	This site investigation.

calculate_interpretation

calculate_interpretation() -> Self

Run interpretation on each test that supports it and store results.

Tests without data or without InterpretationMixin are skipped.

Returns:

Type	Description
`Self`	This site investigation.

calculate_liquefaction

calculate_liquefaction() -> Self

Run liquefaction triggering on each supporting test and store results.

Tests without data or without LiquefactionMixin are skipped.

Returns:

Type	Description
`Self`	This site investigation.

calculate_liquefaction_shear_induced_building_settlement

calculate_liquefaction_shear_induced_building_settlement() -> (
    Self
)

Run Bray 2017 settlement on each supporting test and store results.

Tests without data or without LiquefactionShearInducedBuildingSettlementMixin are skipped.

Returns:

Type	Description
`Self`	This site investigation.

calculate_pile_capacity

calculate_pile_capacity() -> Self

Run pile capacity on each supporting test and store results.

Tests without data or without PileMixin are skipped.

Returns:

Type	Description
`Self`	This site investigation.

correlate_null_unit_weight

correlate_null_unit_weight() -> Self

Fill missing borehole unit weights from SPT correlations.

Returns:

Type	Description
`Self`	This site investigation.

get_data_geotech_figure

get_data_geotech_figure(
    x: list[str],
    y: Literal["depth", "elevation"] = "depth",
    axis_map: dict | None = None,
    width: float | None = 11.69 * 96,
    height: float | None = 8.27 * 96,
    plot_module: Literal["plotly", "mpl"] = "plotly",
    **kwargs: Any
) -> GeotechFigureT

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

Each contributing test is one legend entry, matching get_metadata_geotech_figure. Tests that lack every requested x field are skipped.

Parameters:

Name	Type	Description	Default
`x`	`list[str]`	Depth-series field names (for example CPT raw traces).	required
`y`	`Literal['depth', 'elevation']`	Vertical axis; `depth` or `elevation`.	`'depth'`
`axis_map`	`dict \| None`	Optional axis overrides merged onto the default map.	`None`
`width`	`float \| None`	Figure width in pixels.	`11.69 * 96`
`height`	`float \| None`	Figure height in pixels.	`8.27 * 96`
`plot_module`	`Literal['plotly', 'mpl']`	Figure backend.	`'plotly'`
`**kwargs`	`Any`	Plotly Express / matplotlib-express overrides.	`{}`

Returns:

Type	Description
`GeotechFigureT`	Unplotted geotech-figure renderer. Call `plot()` to draw.

get_metadata_geotech_figure

get_metadata_geotech_figure(
    y: list[str],
    x: Literal["test_id"] = "test_id",
    facet_col_wrap: int = 2,
    width: float | None = 11.69 * 96,
    height: float | None = 8.27 * 96,
    plot_module: Literal["plotly", "mpl"] = "plotly",
    **kwargs: Any
) -> GeotechFigureT

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

Each contributing test is one legend entry, matching get_data_geotech_figure. Tests that lack every requested y field are skipped.

Parameters:

Name	Type	Description	Default
`y`	`list[str]`	Metadata field names (for example liquefaction summary sums).	required
`x`	`Literal['test_id']`	Category axis; always `test_id`.	`'test_id'`
`facet_col_wrap`	`int`	Facet wrap passed to Plotly Express / matplotlib.	`2`
`width`	`float \| None`	Figure width in pixels.	`11.69 * 96`
`height`	`float \| None`	Figure height in pixels.	`8.27 * 96`
`plot_module`	`Literal['plotly', 'mpl']`	Figure backend.	`'plotly'`
`**kwargs`	`Any`	Plotly Express / matplotlib-express overrides.	`{}`

Returns:

Type	Description
`GeotechFigureT`	Unplotted geotech-figure renderer. Call `plot()` to draw.

get_reference_figure

get_reference_figure(
    name: SiteInvestigationReferenceFigureName,
    width: float | None = 11.69 * 96,
    height: float | None = 8.27 * 96,
    plot_module: Literal["plotly", "mpl"] = "plotly",
    **kwargs: Any
) -> ReferenceFigureT

Overlay in-situ tests on a published reference figure.

Each contributing test is one legend entry, matching get_data_geotech_figure. Tests that lack the axes for name are skipped; null values in a kept test stay in the overlay frame. Plasticity and liquefaction susceptibility charts use specimen Atterberg limits, not SPT data. LiquefactionDamage keeps Ishihara H1 of inf (no liquefiable layer).

Parameters:

Name	Type	Description	Default
`name`	`SiteInvestigationReferenceFigureName`	Catalog figure that SiteInvestigation can populate.	required
`width`	`float \| None`	Figure width in pixels.	`11.69 * 96`
`height`	`float \| None`	Figure height in pixels.	`8.27 * 96`
`plot_module`	`Literal['plotly', 'mpl']`	Figure backend.	`'plotly'`
`**kwargs`	`Any`	Plotly Express / matplotlib-express overrides.	`{}`

Returns:

Type	Description
`ReferenceFigureT`	Unplotted reference-figure renderer. Call `plot()` to draw.

get_test_by_id

get_test_by_id(test_id: str) -> InSituTest

Return the in-situ test with test_id.

Parameters:

Name	Type	Description	Default
`test_id`	`str`	`metadata.test_id` to look up.	required

Returns:

Type	Description
`InSituTest`	The matching test.

Raises:

Type	Description
`KeyError`	When no test has that id.

get_tests_by_ids

get_tests_by_ids(test_ids: list[str]) -> Self

Return a new site containing only the requested tests.

Parameters:

Name	Type	Description	Default
`test_ids`	`list[str]`	`metadata.test_id` values, in the order to keep.	required

Returns:

Type	Description
`Self`	A new site with the same project metadata.

Raises:

Type	Description
`KeyError`	When any id is missing.

get_tests_by_type

get_tests_by_type(
    test_type: Literal["BORH", "CPT", "DMT", "IST", "UDT"],
) -> Self

Return a new site containing only tests of test_type.

Parameters:

Name	Type	Description	Default
`test_type`	`Literal['BORH', 'CPT', 'DMT', 'IST', 'UDT']`	Discriminator value (`BORH`, `CPT`, `DMT`, `IST`, or `UDT`).	required

Returns:

Type	Description
`Self`	A new site with the same project metadata.

model_post_init

model_post_init(__context: Any) -> None

set_latitude_and_longitude_from_utm

set_latitude_and_longitude_from_utm() -> Self

Set latitude/longitude on each test from easting and northing.

Returns:

Type	Description
`Self`	This site investigation.

set_utm_from_latitude_and_longitude

set_utm_from_latitude_and_longitude() -> Self

Set easting/northing on each test from latitude and longitude.

Returns:

Type	Description
`Self`	This site investigation.

get_elevation_vector

get_elevation_vector(test: InSituTest) -> list[float]

Elevation samples derived from surface elevation minus depth.

set_cpts_from_cpetit_associated_file

set_cpts_from_cpetit_associated_file(
    site: SiteInvestigation,
    exported_as: Literal["normal", "custom"] = "normal",
) -> SiteInvestigation

Fill CPT data from each test's CPeT-IT associated Excel file.

Index

subsurfaceio.site_investigation

SiteInvestigation pydantic-model

in_situ_tests pydantic-field

project_metadata pydantic-field

add_test

calculate_footing_capacity

calculate_footing_settlements

calculate_interpretation

calculate_liquefaction

calculate_liquefaction_shear_induced_building_settlement

calculate_pile_capacity

correlate_null_unit_weight

get_data_geotech_figure

get_metadata_geotech_figure

get_reference_figure

get_test_by_id

get_tests_by_ids

get_tests_by_type

model_post_init

set_latitude_and_longitude_from_utm

set_utm_from_latitude_and_longitude

get_elevation_vector

set_cpts_from_cpetit_associated_file

SiteInvestigation `pydantic-model`

in_situ_tests `pydantic-field`

project_metadata `pydantic-field`