2.23.6.3. pycsamt.format.structure#

PCGS - pyCSAMT Common Geological Structure.

PCGS is a small, portable document for field structural evidence – planar measurements (strike/dip), linear measurements (trend/plunge), and fault traces – collected along one or several survey lines, so it can travel between projects and applications on its own and be recognised and loaded straight into Map View’s Geology section.

Like pycsamt.format.geology (PCGL) and pycsamt.format.borehole (PCBH), PCGS is a thin document envelope (id, timestamps, provenance, versioning) around an existing pycsamt class – here, pycsamt.geology.structural.StructuralModel – rather than a parallel data model.

Canonical encoding is UTF-8 JSON, canonical extension .pcgs.json. A model can also be assembled from up to three CSV files (one each for planar measurements, linear measurements, and fault traces), the same tables pycsamt.geology.structural.StructuralModel.from_csv() already accepts – see that method for the column layout, including the optional line column for a multi-line survey.

Example

>>> from pycsamt.format.structure import StructModel
>>> from pycsamt.geology.structural import FaultTrace, StructuralModel
>>> model = StructuralModel(
...     faults=[FaultTrace(x=500.0, dip_deg=70.0, downthrown_side="right")],
... )
>>> doc = StructModel.from_structural_model(model, title="Site A structure")
>>> doc.issues()
[]

Functions

read_structure(path)

Read a .pcgs.json file.

structure_from_csv(**kwargs)

Module-level convenience alias for StructModel.from_csv().

structure_from_dict(payload)

Build and validate a StructModel from a dict.

structure_to_dict(doc)

Return a canonical JSON-safe dict for doc.

write_structure(doc, path)

Write doc as canonical .pcgs.json.

Classes

StructModel(document_id, created_at, ...[, ...])

A versioned, portable structural-geology document.

Exceptions

StructModelValidationError

Raised when a PCGS document fails validation.
class pycsamt.format.structure.StructModel(document_id, created_at, created_by, model, pcgs_version='0.1.0', title='', description='', metadata=<factory>)[source]

Bases: PyCSAMTObject, MetadataMixin

A versioned, portable structural-geology document.

Parameters:
document_id: str
created_at: str
created_by: str
model: StructuralModel
pcgs_version: str = '0.1.0'
title: str = ''
description: str = ''
metadata: dict[str, Any]
property planar[source]
property linear[source]
property faults[source]
classmethod from_structural_model(model=None, *, document_id=None, created_by='pycsamt', title='', description='')[source]
Parameters:
Return type:

StructModel

classmethod from_csv(*, planar_path=None, linear_path=None, faults_path=None, delimiter=',', document_id=None, created_by='pycsamt CSV importer', title='')[source]

Load a document from up to three CSV files – see pycsamt.geology.structural.StructuralModel.from_csv().

Parameters:

  • planar_path (str | Path | None)

  • linear_path (str | Path | None)

  • faults_path (str | Path | None)

  • delimiter (str)

  • document_id (str | None)

  • created_by (str)

  • title (str)

Return type:

StructModel

issues()[source]
Return type:

list[str]

validate()[source]

Validate object state.

Subclasses can override this hook. The base implementation intentionally accepts all states.

Return type:

None

exception pycsamt.format.structure.StructModelValidationError[source]

Bases: ValueError

Raised when a PCGS document fails validation.

pycsamt.format.structure.read_structure(path)[source]

Read a .pcgs.json file.

Parameters:

path (str | Path)

Return type:

StructModel

pycsamt.format.structure.write_structure(doc, path)[source]

Write doc as canonical .pcgs.json.

Parameters:
Return type:

Path

pycsamt.format.structure.structure_from_csv(**kwargs)[source]

Module-level convenience alias for StructModel.from_csv().

Parameters:

kwargs (Any)

Return type:

StructModel

pycsamt.format.structure.structure_to_dict(doc)[source]

Return a canonical JSON-safe dict for doc.

Parameters:

doc (StructModel)

Return type:

dict[str, Any]

pycsamt.format.structure.structure_from_dict(payload)[source]

Build and validate a StructModel from a dict.

Parameters:

payload (dict[str, Any])

Return type:

StructModel