pycsamt.iot.session#

Field acquisition session — the hub of the IoT subpackage.

A FieldSession connects devices, stations, telemetry packets, edge QC, and synchronisation, and exports the result into pyCSAMT-facing structures: station descriptors (to_sites()), a processing-pipeline input (to_pipeline_input()), and a reproducible provenance manifest (export_manifest()).

Example

>>> from pycsamt.iot import FieldSession, DeviceConfig
>>> session = FieldSession("SSL2026", devices=[DeviceConfig("node-1",
...                                            station="S01",
...                                            channels=["ex", "hy"])])
>>> _ = session.add_packet({"device_id": "node-1", "timestamp": 100.0,
...                         "topic": "t", "kind": "qc",
...                         "payload": {"station": "S01", "accepted": True,
...                                     "channels": ["ex", "hy"],
...                                     "frequency_band_hz": [1.0, 1000.0]}})
>>> status = session.assess()
>>> sites = session.to_sites()

Classes

FieldSession(survey_id, *[, devices, ...])

Stateful container for one IoT-enabled field acquisition session.

class pycsamt.iot.session.FieldSession(survey_id, *, devices=None, stations=None, monitoring_config=None, sync_config=None, operator=None, method=None, metadata=None)[source]#

Bases: PyCSAMTObject, MetadataMixin

Stateful container for one IoT-enabled field acquisition session.

Parameters:

survey_id (str)
devices (Iterable[DeviceConfig | Mapping[str, Any]] | None)
stations (Iterable[StationConfig | Mapping[str, Any]] | None)
monitoring_config (MonitoringConfig | None)
sync_config (SyncConfig | None)
operator (str | None)
method (str | None)
metadata (dict[str, Any])

property n_devices: int[source]#

property n_stations: int[source]#

property n_packets: int[source]#

validate()[source]#

Validate the session (required by PyCSAMTObject).

Return type:: None

add_device(device)[source]#

Register a device, auto-creating its station when named.

Parameters:: device (DeviceConfig | Mapping[str, Any])
Return type:: DeviceConfig

add_station(station)[source]#

Register (or merge into) a station.

Parameters:: station (StationConfig | Mapping[str, Any])
Return type:: StationConfig

add_packet(packet)[source]#

Append one telemetry packet, registering unknown devices.

Parameters:: packet (TelemetryPacket | Mapping[str, Any])
Return type:: TelemetryPacket

add_packets(packets)[source]#

Append many telemetry packets.

Parameters:: packets (Iterable[TelemetryPacket | Mapping[str, Any]])
Return type:: None

assess(*, now=None)[source]#

Assess telemetry quality with the session monitoring config.

Parameters:: now (float | None)
Return type:: MonitoringStatus

station_table(*, api=None)[source]#

Return the registered stations as a pyCSAMT table.

Parameters:: api (bool | None)
Return type:: Any

to_sites()[source]#

Return acquisition-level station descriptors.

These are StationConfig objects enriched from telemetry (channels and method observed in packets). They are acquisition descriptors, not EDI-backed pycsamt.site.base.Site objects, which require processed impedance data.

Once impedance is available, to_edifiles() and to_sites_collection() promote these descriptors into EDI-backed sites ready for the processing pipeline.

Return type:: list[StationConfig]

to_pipeline_input()[source]#

Return a serialisable hand-off for the processing pipeline.

Contains, per station, the location, channels, observed method, accepted frequency band, and QC acceptance — everything the downstream pyCSAMT processing flow needs to know from acquisition.

Return type:: dict[str, Any]

to_edifiles(impedance, freq=None, *, method=None, savepath=None, write=False, acqby='pycsamt.iot')[source]#

Promote per-station impedance into EDIFile objects.

A thin convenience over pycsamt.iot.bridge.field_session_to_edifiles(): each EDI is enriched with the geometry this session recorded for the station. See that function for the accepted impedance mapping forms and the meaning of write/savepath.

Parameters:

impedance (Mapping[str, Any])
freq (Any)
method (str | None)
savepath (str | None)
write (bool)
acqby (str)

Return type:

dict[str, Any]

to_sites_collection(impedance, freq=None, *, method=None)[source]#

Return an EDI-backed pycsamt.site.base.Sites collection.

This is the processing hand-off: given per-station impedance, it builds one EDI per station and wraps them into a Sites collection that can be fed straight to pycsamt.pipeline.Pipeline.run(). Requires the optional geospatial stack (pyproj).

Parameters:

impedance (Mapping[str, Any])
freq (Any)
method (str | None)

Return type:

Any

to_manifest()[source]#

Build a reproducible AcquisitionManifest.

Return type:: AcquisitionManifest

export_manifest(path, *, indent=2)[source]#

Write the acquisition manifest to path and return its path.

Parameters:

path (str)
indent (int)

Return type:

str

to_dict()[source]#

Return a serialisable representation of the whole session.

Return type:: dict[str, Any]

to_json(*, indent=2)[source]#

Return the session as a JSON string.

Parameters:: indent (int)
Return type:: str

classmethod from_dict(data)[source]#

Reconstruct a session from to_dict() output.

Parameters:: data (Mapping[str, Any])
Return type:: FieldSession

classmethod from_json(text)[source]#

Reconstruct a session from a JSON string.

Parameters:: text (str)
Return type:: FieldSession

write_json(path, *, indent=2)[source]#

Write the session JSON to path and return its path.

Parameters:

path (str)
indent (int)

Return type:

str

classmethod read_json(path)[source]#

Load a session from a JSON file.

Parameters:: path (str)
Return type:: FieldSession