Skip to content

Index

subsurfaceio.site_investigation.io

Site investigation IO mixins (Excel, AGS, KML, DXF).

Classes:

Name Description
AssignmentItem

Map a 1-based file column to a registered field name.

IOAGSMixin

Mixin that reads and writes AGS 4 site-investigation files.

IOCPeTITExcelMixin

Mixin that loads CPT traces from a CPeT-IT Excel export.

IODXFCrossSectionMixin

Mixin adding cross-section DXF export to SiteInvestigation.

IODXFMapMixin

Mixin that writes a DXF plan of in-situ test locations.

IOExcelMixin

Mixin that reads and writes site-investigation Excel workbooks.

IOKMLMixin

Mixin that writes a KML map of in-situ test locations.

IONextGenerationLiquefactionAGSMixin

Mixin that loads Next-Generation Liquefaction AGS/CSV files.

InSituTestsLoadUserDefinedData

Build a site investigation from user CSV/Excel column assignments.

AssignmentItem pydantic-model

Bases: BaseModel

Map a 1-based file column to a registered field name.

Fields:

column pydantic-field

column: int

factor pydantic-field

factor: float | None = 1.0

field pydantic-field

field: str

IOAGSMixin

Mixin that reads and writes AGS 4 site-investigation files.

Methods:

Name Description
from_ags

Load a site investigation from an AGS 4 file.

write_ags

Write this site investigation as an AGS 4 file.

from_ags classmethod

from_ags(source: Any) -> T

Load a site investigation from an AGS 4 file.

Parameters:

Name Type Description Default
source Any

AGS file path or file-like object.

required

Returns:

Type Description
T

A new

T

write_ags

write_ags(
    path: Any, dict_version: Literal["4.2"] = "4.2"
) -> None

Write this site investigation as an AGS 4 file.

Parameters:

Name Type Description Default
path Any

Output AGS path.

required
dict_version Literal['4.2']

AGS dictionary version.

'4.2'

IOCPeTITExcelMixin

Mixin that loads CPT traces from a CPeT-IT Excel export.

Methods:

Name Description
from_cpetit_excel

Load CPT tests from a CPeT-IT Excel export.

from_cpetit_excel classmethod

from_cpetit_excel(
    source: Any,
    exported_as: Literal["normal", "custom"] = "normal",
) -> T

Load CPT tests from a CPeT-IT Excel export.

Parameters:

Name Type Description Default
source Any

Workbook path or file-like object.

required
exported_as Literal['normal', 'custom']

normal for "Export all CPT's to XLS file"; custom for "Custom Export to XLS".

'normal'

Returns:

Type Description
T

A new

T

IODXFCrossSectionMixin

Mixin adding cross-section DXF export to SiteInvestigation.

Methods:

Name Description
cross_section

Build a

write_cross_section_dxf

Export a cross-section DXF for this site investigation.

cross_section

cross_section(
    stations: list[CrossSectionStation] | None = None,
    *,
    vertical: Literal["depth", "elevation"] = "elevation",
    **kwargs: Any
) -> CrossSection

Build a CrossSection from this site investigation.

Parameters:

Name Type Description Default
stations list[CrossSectionStation] | None

Optional CrossSectionStation list; inferred from the site when omitted.

None
vertical Literal['depth', 'elevation']

Vertical axis; depth or elevation.

'elevation'
**kwargs Any

Forwarded to CrossSection.from_site.

{}

Returns:

Type Description
CrossSection

An unplotted cross-section model.

write_cross_section_dxf

write_cross_section_dxf(
    path: str | Path,
    *,
    stations: list[CrossSectionStation] | None = None,
    vertical: Literal["depth", "elevation"] = "elevation",
    **kwargs: Any
) -> None

Export a cross-section DXF for this site investigation.

Parameters:

Name Type Description Default
path str | Path

Output DXF path.

required
stations list[CrossSectionStation] | None

Optional CrossSectionStation list; inferred from the site when omitted.

None
vertical Literal['depth', 'elevation']

Vertical axis; depth or elevation.

'elevation'
**kwargs Any

Forwarded to CrossSection.from_site.

{}

IODXFMapMixin

Mixin that writes a DXF plan of in-situ test locations.

Methods:

Name Description
write_dxf_map

Write a DXF plan of tests with easting and northing.

write_dxf_map

write_dxf_map(path: Any) -> None

Write a DXF plan of tests with easting and northing.

Parameters:

Name Type Description Default
path Any

Output DXF path. Tests missing coordinates are skipped.

required

IOExcelMixin

Mixin that reads and writes site-investigation Excel workbooks.

Methods:

Name Description
from_excel

Load project source data and analysis settings from Excel.

write_excel

Write this site investigation to an Excel workbook.

from_excel classmethod

from_excel(source: Any, project_id: str) -> T

Load project source data and analysis settings from Excel.

Restores raw/reported data and *_settings sheets only. Derived calculation result sheets (interpretation/liquefaction/footing/pile outputs) are ignored if present.

Parameters:

Name Type Description Default
source Any

Workbook path or file-like object.

required
project_id str

Project id used to filter rows.

required

Returns:

Type Description
T

A new

T

write_excel

write_excel(
    path: Any,
    as_labels: bool = True,
    include_calculations: bool = False,
) -> None

Write this site investigation to an Excel workbook.

Parameters:

Name Type Description Default
path Any

Output workbook path.

required
as_labels bool

When true, write registered display labels as headers.

True
include_calculations bool

When true, also write calculation-result sheets.

False

IOKMLMixin

Mixin that writes a KML map of in-situ test locations.

Methods:

Name Description
write_kml_map

Write a KML placemark map of tests with latitude and longitude.

write_kml_map

write_kml_map(path: Any) -> None

Write a KML placemark map of tests with latitude and longitude.

Parameters:

Name Type Description Default
path Any

Output KML path. Tests missing coordinates are skipped.

required

IONextGenerationLiquefactionAGSMixin

Mixin that loads Next-Generation Liquefaction AGS/CSV files.

Methods:

Name Description
from_next_generation_liquefaction_ags

Load a site investigation from an NGL AGS/CSV file.

from_next_generation_liquefaction_ags classmethod

from_next_generation_liquefaction_ags(source: Any) -> T

Load a site investigation from an NGL AGS/CSV file.

Parameters:

Name Type Description Default
source Any

File path.

required

Returns:

Type Description
T

A new

T

InSituTestsLoadUserDefinedData pydantic-model

Bases: Model

Build a site investigation from user CSV/Excel column assignments.

Fields:

columns_assignments pydantic-field

columns_assignments: list[AssignmentItem] = [
    AssignmentItem(column=1, field="depth", factor=1.0)
]

data_type pydantic-field

data_type: Literal['BORH', 'CPT', 'DMT', 'IST'] = 'CPT'

delimiter pydantic-field

delimiter: Literal[*list(keys()),] = 'comma (,)'

first_line pydantic-field

first_line: int = 2

import_all_sheets pydantic-field

import_all_sheets: bool = True

available_datasets classmethod

available_datasets() -> list[str]

Built-in column-assignment presets (BORH, CPT, DMT, IST).

handle_files

handle_files(
    files: list[str | Path],
    file_type: Literal["text", "excel"] = "text",
) -> SiteInvestigation

Read text or Excel files and return a SiteInvestigation.

Parameters:

Name Type Description Default
files list[str | Path]

Paths to CSV/text or Excel files.

required
file_type Literal['text', 'excel']

text for delimited files, excel for workbooks.

'text'

Returns:

Type Description
SiteInvestigation

A new

SiteInvestigation

load_dataset classmethod

load_dataset(
    dataset_id: str,
) -> InSituTestsLoadUserDefinedData

Return a loader preset for dataset_id.

Parameters:

Name Type Description Default
dataset_id str

One of available_datasets.

required

Returns:

Type Description
InSituTestsLoadUserDefinedData

A loader with default column assignments for that test type.