2.8.1.1. pycsamt.site.base#

Functions

to_edis(x, *[, as_collection, copy, ...])

Unwrap site-like inputs to raw EDI objects.

to_sites(x, *[, recursive, on_dup, strict, ...])

Coerce an arbitrary EDI-like input into a Sites wrapper.

Classes

Site(source, *[, on_loss])

High-level wrapper for a single MT/CSAMT site backed by an EDIFile.

SiteMixin(source, *[, on_loss])

Lightweight wrapper exposing station-centric accessors and utilities for a single EDIFile.

Sites(edic, *[, on_loss])

Container for multiple Site objects with convenient indexing, selection, and bulk edit operations.
class pycsamt.site.base.SiteMixin(source, *, on_loss='warn')[source]

Bases: CoreObject

Lightweight wrapper exposing station-centric accessors and utilities for a single EDIFile.

The mixin normalizes common site operations around the underlying EDI content, including coordinate handling, impedance arrays, tipper, derived resistivity/phase, and convenient export to pandas.DataFrame.

Notes

The station name is resolved from EDI HEAD fields in the following order: dataid, station, sitename, name, STATION. If none is present, the file stem is used. See _station_name().

The Z tensor is treated as an array of shape (n, 2, 2) or flattened to (n, 4) as needed. The order is: Zxx, Zxy, Zyx, Zyy.

See also

pycsamt.seg.edi.EDIFile

Parsed SEG-EDI container.

pycsamt.site.base.Site

Concrete site wrapper that enforces a stable ID.

pycsamt.site.base.Sites

Collection helper for multiple sites.

References

[SiteMixin-1]

SEG EDI Format. Society of Exploration Geophysicists. Commonly used magnetotelluric exchange format.

Parameters:

  • source (Any)

  • on_loss (str)

property backend: str[source]

Which backend natively constructed this site.

Returns:

"edi" or "xml". The other representation is always available too (see edi and tf) but is lazily materialized and cached on first access.

Return type:

str

property edi: EDIFile[source]

The underlying EDIFile.

Returns:

When this site was constructed from an EDI object, the same object every time. When constructed from an EMTF XML document, an EDI view is materialized on first access via pycsamt.emtf.converters.edi.emtf_to_edi() and cached, so this always returns the same object on repeated access (safe for in-place mutation and identity-keyed caches elsewhere in the codebase).

Return type:

pycsamt.seg.edi.EDIFile

Notes

Materializing from XML may emit a DataLossWarning (or raise, depending on on_loss passed at construction) if the source document holds metadata the historical EDI format cannot represent.

property tf: Any[source]

The underlying EMTF document.

Returns:

When this site was constructed from an XML document, the same object every time. When constructed from an EDI object, a format-neutral view is materialized on first access via pycsamt.emtf.converters.edi.edi_to_emtf() and cached (lossless – XML is a strict superset of EDI).

Return type:

pycsamt.emtf.document.EMTF

See also

site_meta, site_layout, provenance, processing, copyright, quality_meta

Typed

mod:pycsamt.metadata accessors built on top of this document.

property name: str[source]

Station identifier resolved from the EDI header or file stem.

Returns:

Station name used for lookups and display.

Return type:

str

Notes

The resolution order is defined in _station_name(). XML-native sites resolve the name directly from the EMTF document without forcing EDI materialization.

property coords: tuple[float, float, float][source]

Geographic coordinates of the site.

Returns:

A 3-tuple (lat, lon, elev) in decimal degrees and meters.

Return type:

tuple of float

Notes

This accessor relies on _get_coords() which parses EDI HEAD latitude, longitude and elevation. XML-native sites read directly from the EMTF document without forcing EDI materialization.

property freq: Any[source]

Frequency vector extracted from the Z section.

Returns:

One-dimensional array of frequencies in Hz, or None if missing.

Return type:

array-like or None

See also

to_dataframe

Tabular export of arrays at each frequency.

property z: Any[source]

Complex impedance tensor across frequencies.

Returns:

Array with shape (n, 2, 2) or flattened to (n, 4) depending on context, or None if absent.

Return type:

array-like or None

Notes

Flattening order is Zxx, Zxy, Zyx, Zyy.

property z_err: Any[source]

Uncertainty associated with the impedance tensor.

Returns:

Error array aligned with SiteMixin.z, or None if absent.

Return type:

array-like or None

property rho: Any[source]

Apparent resistivity derived from the impedance tensor.

Returns:

Resistivity values per component and frequency, or None if not computed or absent.

Return type:

array-like or None

Notes

Derived fields may be recomputed downstream when the Z tensor or frequency vector is updated.

property phase: Any[source]

Impedance phase (degrees) derived from the tensor.

Returns:

Phase values per component and frequency, or None if not computed or absent.

Return type:

array-like or None

property tipper: Any[source]

Vertical magnetic transfer function (tipper).

Returns:

Two columns (Tx, Ty) per frequency, or None if missing.

Return type:

array-like or None

property meta: dict[str, Any][source]

Minimal metadata snapshot collected from the EDI.

Returns:

Dictionary that may include station, name, lat, lon, elev, dataid, sitename, and an INFO sub-dict if present.

Return type:

dict

Notes

Values are read on a best-effort basis and non-existing keys are omitted.

to_dataframe(kind='z', *, api=None)[source]

Export core arrays to a tidy pandas.DataFrame.

Parameters:

  • kind ({"z", "imp", "impedance", "resphase", "rp",) – “rho_phase”, “tip”, “tipper”, “t”}, optional Selects which quantity to export. The default is "z".

  • api (bool | None)

Returns:

Frame indexed by frequency (name "f"). Columns depend on kind: - "z": Zxx, Zxy, Zyx, Zyy (complex values). - "resphase": pairs of columns per component

rho_* and phi_*.

  • "tipper": Tx, Ty.

Return type:

pandas.DataFrame

Raises:

ValueError – If kind is not recognized.

Notes

Missing arrays yield empty frames with the correct index.

Examples

>>> df = site.to_dataframe("z")
>>> df.columns
Index(["Zxx","Zxy","Zyx","Zyy"], dtype="object")

See also

quality_flags

Quick presence checks of available arrays.

quality_flags()[source]

Report presence and basic validity of key arrays.

Returns:

Flags: has_freq, has_z, has_z_err, has_rho, has_phase, has_tipper. A flag is True if the array exists, has non-zero size, and all values are finite.

Return type:

dict

Examples

>>> site.quality_flags()["has_z"]
True
has_component(comp)[source]

Check if a given component contains any finite value.

Parameters:

comp (str) – One of "Zxx", "Zxy", "Zyx", "Zyy" for impedance, or "tip", "tx", "ty", "tipper" for tipper.

Returns:

True if the component exists and has at least one finite value.

Return type:

bool

Notes

Component names are case-insensitive.

Examples

>>> site.has_component("Zxy")
True
summary()[source]

Summarize site identity, geometry, and data coverage.

Returns:

Keys include: name, nfreq, lat, lon, elev, components (present Z components), and tipper (boolean).

Return type:

dict

Examples

>>> s = site.summary()
>>> s["name"], s["nfreq"]
('E01', 37)
rename(new, *, inplace=False)[source]

Set a new station identifier across common header fields.

Parameters:

  • new (str) – New station name or ID.

  • inplace (bool, optional) – If True, modify this instance. If False, return a new Site. The default is False.

Returns:

The modified site (new instance unless inplace).

Return type:

Site

Notes

The method writes to EDI HEAD fields dataid, station, sitename, name (best effort) and also updates edi.name. Downstream containers that derive station IDs from the file stem may be configured to prefer edi.name to preserve the rename.

Examples

>>> s2 = site.rename("X_E01")
>>> s2.name
'X_E01'
set_coords(lat, lon, elev=None, *, inplace=False)[source]

Update the site coordinates in the EDI HEAD section.

Parameters:

  • lat (float) – Latitude in decimal degrees.

  • lon (float) – Longitude in decimal degrees.

  • elev (float, optional) – Elevation in meters. If None, elevation is left unchanged. The default is None.

  • inplace (bool, optional) – If True, modify this instance. If False, return a new Site. The default is False.

Returns:

The modified site (new instance unless inplace).

Return type:

Site

Notes

Latitude and longitude are validated by utility functions to ensure plausible values.

Examples

>>> site = site.set_coords(10.0, 20.0, 100.0)
>>> site.coords
(10.0, 20.0, 100.0)
set_empty(*, inplace=False)[source]

Clear Z-related arrays to an empty dataset.

Parameters:

inplace (bool, optional) – If True, modify this instance. If False, return a new Site. The default is False.

Returns:

The modified site (new instance unless inplace).

Return type:

Site

Notes

The following arrays are replaced with empty arrays: freq, z, z_error, rho, and phase. Use this to initialize a skeleton record without data.

Examples

>>> s2 = site.set_empty()
>>> s2.to_dataframe("z").empty
True
class pycsamt.site.base.Site(source, *, on_loss='warn')[source]

Bases: SiteMixin

High-level wrapper for a single MT/CSAMT site backed by an EDIFile. The class enforces a stable, file-stem-based station identifier and exposes convenient accessors for coordinates, impedance Z, tipper, and derived quantities.

Site also accepts an EMTF XML document instead of an EDI object – see from_xml(). Either way, edi and tf are both always available: the representation not natively supplied is lazily materialized and cached from the other via pycsamt.emtf.converters.edi.edi_to_emtf()/emtf_to_edi, so every existing EDI-shaped accessor keeps working unchanged regardless of which format the site was built from.

When constructed from EDI, the constructor normalizes EDI HEAD fields so that dataid (and, if absent, station) matches the site stem resolved by _stem_from_edi(). If an in-memory edi.name exists, the stem may prefer it so that a prior rename is preserved. This normalization improves name-based indexing, deterministic selection, and downstream joins in collections. XML-native sites keep the station identity already recorded in the document instead.

Parameters:

  • source (pycsamt.seg.edi.EDIFile or pycsamt.emtf.document.EMTF) – Parsed SEG-EDI container, or an EMTF XML document, holding one station. The EDI file may be constructed from disk or synthesized in memory.

  • on_loss ({"warn", "raise", "ignore"}, default "warn") – Policy applied if edi is later materialized from an XML-native site and the document holds metadata the historical EDI format cannot represent.

Variables:

  • edi (pycsamt.seg.edi.EDIFile) – Underlying (possibly lazily materialized) EDI object. Use with care; prefer the typed accessors of SiteMixin (e.g., freq, z).

  • tf (pycsamt.emtf.document.EMTF) – Underlying (possibly lazily materialized) EMTF XML document. See also site_meta, provenance, processing, site_layout, copyright, quality_meta.

  • backend (str) – "edi" or "xml" – which representation is native.

  • name (str) – Normalized station identifier. By default this equals the file stem, unless a previous explicit rename is in effect.

  • coords (tuple of float) – Geographic location as (lat, lon, elev). Latitude and longitude are in degrees; elevation is in meters.

Notes

Identity policy

The site identity is derived from header fields in the following order: dataid, station, sitename, name, STATION. If none are present, the file stem is used. The constructor ensures that dataid is set to the resolved stem to stabilize lookups.

Array conventions

The impedance tensor \(Z\) may be represented as a 3D array with shape (n, 2, 2) or flattened to (n, 4) in the component order Zxx, Zxy, Zyx, Zyy. Frequencies are 1D of length n. The tipper has two columns Tx and Ty.

Derived fields

Apparent resistivity and phase are derived from \(Z\) and the frequency vector. When Z or frequency slices are applied, recomputation is triggered after arrays are aligned to avoid inconsistent shapes.

Robustness

Accessors are defensive. Missing arrays produce empty frames or None. Coordinates are validated for range using utility checks.

Examples

Basic construction and inspection
>>> from pycsamt.seg.edi import EDIFile
>>> from pycsamt.site.base import Site
>>> e = EDIFile("E01.edi")  # parse from disk
>>> s = Site(e)
>>> s.name
'E01'
>>> s.coords
(..., ..., ...)
>>> s.summary()["nfreq"] >= 0
True
Tabular export
>>> from pycsamt.site.base import Site
>>> dfz = s.to_dataframe("z")
>>> list(dfz.columns)
['Zxx', 'Zxy', 'Zyx', 'Zyy']
>>> dfrp = s.to_dataframe("resphase")
>>> sorted([c for c in dfrp.columns if c.startswith("rho_")])[:2]
['rho_zxx', 'rho_zxy']
Rename without mutating the original instance
>>> s2 = s.rename("X_E01")  # returns a new Site
>>> s2.name
'X_E01'
>>> s.name  # original unchanged
'E01'
Coordinate update
>>> s3 = s.set_coords(10.0, 20.0, 100.0)
>>> s3.coords
(10.0, 20.0, 100.0)
With a collection
>>> from pycsamt.site.base import Sites
>>> e2 = EDIFile("E02.edi")
>>> col = Sites([s.edi, Site(e2).edi])
>>> [t.name for t in col]
['E01', 'E02']
>>> col["E02"].summary()["name"]
'E02'

See also

pycsamt.site.base.SiteMixin

Mixin providing typed accessors and utilities.

pycsamt.site.base.Sites

Collection helper for selection, slicing, and bulk edits.

pycsamt.seg.edi.EDIFile

Low-level SEG-EDI container.

References

[Site-1]

SEG EDI Format Specification. Society of Exploration Geophysicists. Exchange format for magnetotelluric and related EM data.

[Site-2]

Chave, A. D., and Jones, A. G. (Eds.) (2012). The Magnetotelluric Method. Cambridge University Press.

[Site-3]

Simpson, F., and Bahr, K. (2005). Practical Magnetotellurics. Cambridge University Press.

classmethod from_edi(source, *, on_loss='warn')[source]

Construct a Site from an EDI object or a path to one.

Parameters:

  • source (pycsamt.seg.edi.EDIFile or str or pathlib.Path) – Parsed EDI object, or a path that will be read via EDIFile(source).

  • on_loss ({"warn", "raise", "ignore"}, default "warn") – Policy used if this site’s tf is later materialized and something needs to be converted back.

Returns:

A site backed natively by EDI.

Return type:

Site

See also

from_xml

Construct from an EMTF XML document instead.

classmethod from_xml(source, *, on_loss='warn')[source]

Construct a Site from an EMTF XML document or path.

Parameters:

  • source (pycsamt.emtf.document.EMTF or str or pathlib.Path) – Parsed EMTF document, or a path that will be read via pycsamt.emtf.document.EMTF.from_xml().

  • on_loss ({"warn", "raise", "ignore"}, default "warn") – Policy applied when this site’s edi view is later materialized and the document holds metadata the historical EDI format cannot represent.

Returns:

A site backed natively by the richer EMTF XML model; z, freq, tipper, and friends keep working exactly as for an EDI-backed site (via a cached, lazily materialized EDI view), while tf, site_meta, provenance, and related properties expose the full richer metadata.

Return type:

Site

See also

from_edi

Construct from a SEG EDI object instead.

Site.to_xml

Serialize a site back to EMTF XML.

to_xml(target=None, **kwargs)[source]

Serialize this site to EMTF XML.

Parameters:

  • target (str or pathlib.Path, optional) – Destination path. If None, the XML document is returned as a string instead of being written.

  • **kwargs – Forwarded to pycsamt.emtf.document.EMTF.write_xml() (when target is given) or pycsamt.emtf.document.EMTF.to_xml() (otherwise).

Returns:

The XML document as a string when target is None; otherwise the return value of write_xml().

Return type:

str or Any

See also

from_xml

The inverse constructor.

tf

The underlying EMTF document used here.

property site_meta: Any[source]

pycsamt.metadata.SiteMeta for this site (via tf).

property site_layout: Any[source]

pycsamt.metadata.SiteLayout channel geometry (via tf).

property provenance: Any[source]

pycsamt.metadata.ProvenanceMeta creator/submitter info.

property processing: Any[source]

pycsamt.metadata.ProcessingMeta processing/software info.

property copyright: Any[source]

pycsamt.metadata.CopyrightInfo release/citation info.

property quality_meta: Any[source]

pycsamt.metadata.TransferFunctionQuality QC rating/comments.

to_edi(*, copy=False)[source]

Return the underlying EDI object.

Parameters:

copy (bool, default False) – If True, return a best-effort deep copy of the wrapped EDI object. If copying fails, the original object is returned.

Returns:

EDI object wrapped by this Site.

Return type:

pycsamt.seg.edi.EDIFile

See also

pycsamt.site.base.to_edis

General unwrapping helper for Site/Sites and mixed inputs.

update_metadata(update, *, inplace=False)[source]

Update station, coordinate, HEAD, or INFO metadata.

Parameters:
Return type:

Site

class pycsamt.site.base.Sites(edic, *, on_loss='warn')[source]

Bases: CoreObject

Container for multiple Site objects with convenient indexing, selection, and bulk edit operations.

Sites wraps each provided EDIFile into a Site, ensuring that station identity is normalized consistently. You can iterate, index by integer, or look up by case-insensitive station name. Bulk operations such as renaming, frequency slicing, and masking are provided via edit_all().

Parameters:

  • edic (pycsamt.seg.collection.EDICollection or sequence of) –

    pycsamt.seg.edi.EDIFile, pycsamt.emtf.document.EMTF, or

    Site

    Parsed EDI collection, or any sequence mixing EDI objects, EMTF XML documents, and already-constructed Site instances. Items are wrapped into Site instances (existing Site items are used as-is) in the order provided.

  • on_loss (str)

Variables:

_items (list of Site) – Internal sequence of sites. This is considered private. Iterate over Sites instead of accessing it directly.

Notes

Identity and lookup

Each site inside the container uses the same naming policy as Site. Name-based lookups with sites["E01"] are case-insensitive and match the normalized station name. If duplicates exist, the first match is returned.

Order preservation

Ordering of input items is preserved. Integer indexing with sites[i] retrieves the i-th Site.

Bulk edits

edit_all() supports three common operations: - rename: compute a new name from the old name. - freq_slice: apply a frequency slice (slice)

consistently across Z, freq, errors, and derived fields.

  • mask: apply a boolean mask to the Z tensor rows.

Use inplace=True to modify the container, otherwise a new Sites is returned.

Geospatial helpers

closest() uses geodetic distance to find the nearest site to a given latitude and longitude. Sites with missing or non-finite coordinates are skipped.

Topography integration

with_topography() aligns site coordinates and elevation with a user-provided frame, returning a new container unless inplace=True is requested.

Profile conversion

to_profile() attempts to build a Profile when that optional dependency is available. Otherwise, a lightweight dict describing a chainage-ordered sequence is returned.

Persistence

write() emits one EDI file per site into a target directory. If an EDI object provides to_file, it is used; otherwise a placeholder is written.

Robustness and errors

  • __getitem__ raises KeyError when a name is not found. Prefer get() to obtain None instead.

  • Bulk operations ignore missing arrays on a best-effort basis so that other arrays can still be processed.

Examples

Build from a few EDI files
>>> from pycsamt.seg.edi import EDIFile
>>> from pycsamt.site.base import Sites
>>> e1, e2 = EDIFile("E01.edi"), EDIFile("E02.edi")
>>> sites = Sites([e1, e2])
>>> len(sites)
2
>>> [s.name for s in sites]
['E01', 'E02']
Indexing and lookup
>>> sites[0].name
'E01'
>>> sites["e02"].name
'E02'
>>> sites.get("missing") is None
True
Bulk rename without mutating the original container
>>> def rnm(n):
...     return "X_" + n
>>> out = sites.edit_all(rename=rnm, inplace=False)
>>> [s.name for s in out]
['X_E01', 'X_E02']
>>> [s.name for s in sites]
['E01', 'E02']
Frequency slice across all arrays
>>> sl = slice(1, None)  # drop the first frequency
>>> out2 = sites.edit_all(freq_slice=sl, inplace=False)
>>> f0 = sites["E01"].freq
>>> f1 = out2["E01"].freq
>>> len(f1) == len(f0) - 1
True
Selection by names or predicate
>>> subset = sites.select(names=["E02"])
>>> [s.name for s in subset]
['E02']
>>> # predicate: keep sites with tipper available
>>> subset2 = sites.select(
...     predicate=lambda s: s.has_component("tipper")
... )
>>> isinstance(subset2, Sites)
True
Nearest station to a target location
>>> near = sites.closest(lat=10.0, lon=20.0, tol=None)
>>> near is None or hasattr(near, "name")
True
Persist to a directory
>>> import tempfile, pathlib
>>> tmp = pathlib.Path(tempfile.mkdtemp())
>>> out_paths = sites.write(
...     tmp, template="{station}.edi", exist_ok=True
... )
>>> all(p.exists() for p in out_paths)
True

See also

pycsamt.site.base.Site

Site wrapper used for each element in the container.

pycsamt.seg.collection.EDICollection

Parsed collection produced by the core parser.

pycsamt.site.profile.Profile

Optional profile object produced by to_profile().

References

[Sites-1]

SEG EDI Format Specification. Society of Exploration Geophysicists.

[Sites-2]

Chave, A. D., and Jones, A. G. (2012). The Magnetotelluric Method. Cambridge University Press.

[Sites-3]

Simpson, F., and Bahr, K. (2005). Practical Magnetotellurics. Cambridge University Press.

property edic: list[EDIFile][source]
by_index(i)[source]

Retrieve a site by zero-based index.

Parameters:

i (int) – Position in the container.

Returns:

The site at the requested index.

Return type:

Site

Examples

>>> sites.by_index(0).name == sites[0].name
True
get(name)[source]

Safe lookup by case-insensitive station name.

Parameters:

name (str) – Station identifier to find.

Returns:

Matching site, or None if not present.

Return type:

Site or None

Examples

>>> sites.get("missing") is None
True
>>> sites.get("E01").name
'E01'

See also

__getitem__

Raises on missing names.

as_list()[source]

Return the underlying list of EDI objects.

Returns:

The EDI objects corresponding to each site.

Return type:

list of pycsamt.seg.edi.EDIFile

Notes

This is useful when passing the dataset to utilities that operate on EDI-level structures rather than on sites.

Examples

>>> edis = sites.as_list()
>>> hasattr(edis[0], "get_section")
True
property ordering: dict[str, Any][source]

Describe the most recent ordering decision for this container.

ordered(by=None, *, inplace=False, min_linearity=None, max_cross_track_ratio=None, min_coordinate_fraction=None)[source]

Return sites in a deterministic spatial or identity order.

by='auto' applies chainage ordering only when the finite coordinates describe one credible, approximately straight survey line. Otherwise it preserves input order. by='chainage' forces projection onto the PCA profile axis; sites without usable coordinates are retained at the end in their original order.

Other modes are 'input', 'station' (natural numeric station order), 'latitude'/'lat', and 'longitude'/'lon'. Station names remain identifiers and are never changed.

Parameters:

  • by (str | None)

  • inplace (bool)

  • min_linearity (float | None)

  • max_cross_track_ratio (float | None)

  • min_coordinate_fraction (float | None)

Return type:

Sites

to_edis(*, copy=False, progress=False, verbose=0)[source]

Return the underlying EDI objects as a list.

Parameters:

  • copy (bool, default False) – If True, return best-effort deep copies of the EDI objects.

  • progress (bool or {'auto'}, default False) – Enable progress display while unwrapping.

  • verbose (int, default 0) – Verbosity forwarded to progress/reporting helpers.

Returns:

EDI objects in site order.

Return type:

list of pycsamt.seg.edi.EDIFile

See also

to_edicollection

Return an EDICollection instead.

pycsamt.site.base.to_edis

General unwrapping helper.

to_edicollection(*, copy=False, progress=False, verbose=0)[source]

Return the underlying EDI objects as an EDICollection.

Parameters:

  • copy (bool, default False) – If True, return best-effort deep copies of the EDI objects.

  • progress (bool or {'auto'}, default False) – Enable progress display while unwrapping.

  • verbose (int, default 0) – Verbosity assigned to the returned collection.

Returns:

Collection built from the underlying EDI objects.

Return type:

pycsamt.seg.collection.EDICollection

to_emtf_list()[source]

Return the underlying EMTF XML documents as a list.

Returns:

One document per site, in site order. EDI-native sites are lazily converted and cached via Site.tf; XML-native sites are returned as-is, with no information loss.

Return type:

list of pycsamt.emtf.document.EMTF

See also

write_xml

Persist these documents to a directory.

to_edis

The EDI-side equivalent.

write_xml(outdir, **kwargs)[source]

Write one EMTF XML file per site into a directory.

Parameters:

  • outdir (str or pathlib.Path) – Destination directory. It is created if missing.

  • **kwargs – Forwarded to Site.to_xml() for each site.

Returns:

Paths to the written files, named "{station}.xml".

Return type:

list of pathlib.Path

See also

to_emtf_list

In-memory equivalent without writing to disk.

Sites.write

The EDI-side equivalent.

closest(lat, lon, tol=None)[source]

Find the closest site to a target coordinate using geodetic distance.

Parameters:

  • lat (float) – Target latitude in decimal degrees.

  • lon (float) – Target longitude in decimal degrees.

  • tol (float, optional) – Maximum allowed distance in meters. If provided and the nearest site is farther than tol, return None. The default is None.

Returns:

Nearest site or None if all sites are too far or lack valid coordinates.

Return type:

Site or None

Notes

Coordinates are validated. Sites with non-finite values are skipped. Distance is computed in meters using a geodetic model.

Examples

>>> near = sites.closest(10.0, 20.0)
>>> near is None or hasattr(near, "name")
True
>>> sites.closest(0.0, 0.0, tol=1.0) is None
True
map(fn)[source]

Apply a function to every site and collect the results.

Parameters:

fn (callable) – Function of signature fn(site) -> Any.

Returns:

Results collected in order.

Return type:

list

Examples

>>> sites.map(lambda s: s.name)[:2]
['E01', 'E02']
rename(names, *, inplace=False, missing='raise', allow_duplicates=False)[source]

Rename stations from a mapping, sequence, or callable.

Parameters:
Return type:

Sites

update_metadata(updates, *, inplace=False, missing='raise', allow_duplicates=False)[source]

Apply declarative station, HEAD, INFO, and coordinate updates.

Parameters:
Return type:

Sites

edit_all(*, rename=None, freq_slice=None, mask=None, inplace=False)[source]

Bulk-edit all sites with optional rename, frequency slicing, and tensor masking.

Parameters:

  • rename (callable, optional) – Function rename(old_name) -> new_name. If provided, each site is renamed accordingly.

  • freq_slice (slice, optional) – Row-wise slice applied consistently to frequency, impedance Z, errors, and derived arrays.

  • mask (callable, optional) – Function mask(df) -> bool_series where df is the output of site.to_dataframe("z"). Rows where the mask is False are set to NaN in Z.

  • inplace (bool, optional) – If True, modify this container and return it. If False, return a new Sites. Default is False.

Returns:

The edited container (possibly the same instance).

Return type:

Sites

Notes

  • When inplace=False, sites are shallow-cloned so that edits do not affect the original container.

  • Frequency slicing is applied atomically to avoid temporary shape mismatches between freq and Z-derived arrays.

  • Missing arrays are tolerated on a best-effort basis.

Examples

Rename with a prefix
>>> def rnm(n):
...     return "X_" + n
>>> out = sites.edit_all(rename=rnm)
>>> [s.name for s in out][:2]
['X_E01', 'X_E02']
Slice away the first frequency
>>> sl = slice(1, None)
>>> out2 = sites.edit_all(freq_slice=sl)
>>> len(out2["E01"].freq) == len(sites["E01"].freq) - 1
True
Mask the top half of rows in Z
>>> def top_half(frame):
...     m = np.ones(len(frame), dtype=bool)
...     m[: len(frame) // 2] = False
...     return m
>>> out3 = sites.edit_all(mask=top_half)
>>> df = out3["E01"].to_dataframe("z")
>>> np.isnan(df.iloc[0].values).all()
True

See also

Site.rename

Per-site rename helper.

Site.to_dataframe

Source for building masks.

with_topography(frame, *, inplace=False)[source]

Align site coordinates and elevation from a tabular frame.

Parameters:

  • frame (Any) – A table-like object (e.g., pandas.DataFrame) with station identifiers and columns for latitude, longitude, and elevation. Column names are resolved by the topography utility.

  • inplace (bool, optional) – If True, modify this container and return it. If False, return a new Sites. Default is False.

Returns:

Container with updated coordinates.

Return type:

Sites

Notes

Sites are matched by normalized station identifiers. The operation is performed on a best-effort basis; unmatched stations are left unchanged.

Examples

>>> import pandas as pd
>>> df = pd.DataFrame(
...     {
...         "station": ["E01", "E02"],
...         "latitude": [10.0, 11.0],
...         "longitude": [20.0, 21.0],
...         "elevation": [100.0, 200.0],
...     }
... )
>>> out = sites.with_topography(df, inplace=False)
>>> tuple(round(v, 3) for v in out["E01"].coords)
(10.0, 20.0, 100.0)
select(names=None, predicate=None)[source]

Filter sites by explicit names or by a boolean predicate.

Parameters:

  • names (sequence of str, optional) – Case-insensitive station names to retain. If provided, this takes precedence over predicate.

  • predicate (callable, optional) – Function predicate(site) -> bool. Sites for which the function returns True are retained.

Returns:

New container with the selected sites.

Return type:

Sites

Notes

If neither names nor predicate is provided, the method returns a shallow copy of the current container.

Examples

>>> subset = sites.select(names=["E02"])
>>> [s.name for s in subset]
['E02']
>>> subset2 = sites.select(predicate=lambda s: s.has_component("Zxy"))
>>> isinstance(subset2, Sites)
True
classmethod from_any(source, topo_src=None)[source]

Construct a container from heterogeneous inputs by using a normalized loading session.

Parameters:

  • source (Any) – Input that can be understood by the loader. Supported cases include: - an EDICollection, - a list of EDIFile, - a single EDIFile, - or an iterable that yields EDIs.

  • topo_src (Any, optional) – Optional topography source passed to the session for use during loading. The default is None.

Returns:

Parsed container. Returns an empty container if the input cannot be interpreted.

Return type:

Sites

Notes

The method uses normalize_session() to handle parsing, discovery, and optional topography alignment in a consistent way.

Examples

>>> from pycsamt.seg.collection import EDICollection
>>> # edicol = ...  # suppose we already parsed a folder
>>> # sites = Sites.from_any(edicol)
>>> # isinstance(sites, Sites)
True
write(outdir, *, template='{station}.edi', exist_ok=False)[source]

Write one EDI file per site to a directory.

Parameters:

  • outdir (str or pathlib.Path) – Destination directory. It is created if missing.

  • template (str, optional) – Filename template. The token {station} is replaced by the normalized station name. Default is "{station}.edi".

  • exist_ok (bool, optional) – If False and a file already exists, raise FileExistsError. If True, overwrite. Default is False.

Returns:

Paths to the written files.

Return type:

list of pathlib.Path

Raises:

FileExistsError – If a target file exists and exist_ok is False.

Notes

Serialization goes through pycsamt.emtf.converters.edi.write_edi(), which writes the underlying EDIFile to an exact target path (working around write()’s own default of deriving a new_-prefixed name under a local edi_out/ directory when not given an explicit new_edifn/ savepath).

Examples

>>> import tempfile, pathlib
>>> tmp = pathlib.Path(tempfile.mkdtemp())
>>> paths = sites.write(tmp, exist_ok=True)
>>> all(p.exists() for p in paths)
True
to_profile(origin, azimuth, *, crs=None)[source]

Convert sites to a 1D profile aligned with a specified azimuth, returning either a rich Profile object or a lightweight fallback.

Parameters:

  • origin (tuple of float) – (lat, lon) in decimal degrees defining the profile origin.

  • azimuth (float) – Profile azimuth in degrees. North is 0 and angles increase clockwise.

  • crs (int, optional) – Optional CRS code for libraries that require it. Not used in the lightweight fallback. Default is None.

Returns:

If Profile is available, a Profile is returned. Otherwise a dict is returned with keys "origin", "azimuth", and "sites" in chainage order.

Return type:

Profile or dict

Notes

The fallback computes local chainage by a flat approximation around origin:

\[\begin{split}ch = dx * \\sin(az) + dy * \\cos(az)\end{split}\]

where dx and dy are metric offsets relative to the origin. Sites lacking valid coordinates are skipped.

Examples

>>> prof = sites.to_profile(origin=(0.0, 0.0), azimuth=90.0)
>>> hasattr(prof, "chainages") or isinstance(prof, dict)
True

See also

pycsamt.site.profile.Profile

Rich profile object when available.

pycsamt.site.base.to_sites(x, *, recursive=True, on_dup='replace', strict=False, verbose=0)[source]

Coerce an arbitrary EDI-like input into a Sites wrapper.

This helper normalizes many inputs to a uniform Sites interface:

  • If x is already a Sites instance, it is returned unchanged.

  • If x is an EDICollection or a sequence of EDIFile objects, a new Sites wrapper is created.

  • If x is an iterable yielding EDI-like items, they are collected and wrapped.

The operation is light-weight and does not deep-copy the underlying EDI objects. The returned Sites simply holds references to the same items.

Parameters:

  • x (Any) – A Sites instance, an EDICollection, a sequence of EDIFile objects, or an iterable yielding EDI-like items.

  • recursive (bool)

  • on_dup (str)

  • strict (bool)

  • verbose (int)

Returns:

A Sites wrapper over the provided items.

Return type:

pycsamt.site.base.Sites

Notes

Use this utility at API boundaries to conveniently accept multiple input forms while providing a consistent downstream interface. If you need independent copies of the underlying data, perform your own cloning before calling to_sites.

Examples

Wrap a list of EDIFile objects:

>>> from pycsamt.site.selection import to_sites
>>> s = to_sites([e1, e2, e3])
>>> len(s)
3

Wrap an existing Sites (no-op):

>>> s2 = to_sites(s)
>>> s2 is s
True

Wrap an EDICollection:

>>> s3 = to_sites(coll)  # coll is an EDICollection
>>> [t.name for t in s3]
['A01', 'A02']

See also

pycsamt.site.base.Sites

Wrapper providing per-site convenience methods.

pycsamt.site.base.Sites.from_any

Alternate constructor with session normalization.

pycsamt.site.base.to_edis(x, *, as_collection=False, copy=False, recursive=True, on_dup='replace', strict=False, verbose=0, progress=False)[source]

Unwrap site-like inputs to raw EDI objects.

This is the inverse boundary of to_sites(). It accepts a single Site, a Sites collection, an EDICollection, raw EDI objects, path-like inputs, or mixed iterables containing those forms. The returned objects are the underlying EDI containers used by low-level writers, exporters, and EM processing functions.

Parameters:

  • x (Any) – Site-like input to unwrap. Supported values include Site, Sites, EDIFile, EDICollection, path-like inputs, or iterables containing site/EDI-like objects.

  • as_collection (bool, default False) – If True, return an EDICollection. Otherwise a single input returns one EDI object and multi-item inputs return a list.

  • copy (bool, default False) – If True, return best-effort deep copies of the EDI objects. If copying fails for an item, that item is returned unchanged.

  • recursive (bool, default True) – Forwarded to path-like discovery through EDICollection.

  • on_dup ({'replace', 'keep', 'keep_first', 'keep_last', 'raise'}, default 'replace') – Duplicate station policy. replace and keep are forwarded to path loading. keep_first, keep_last, and raise are enforced after collection construction.

  • strict (bool, default False) – If True, raise when an object cannot be unwrapped to EDI. If False, invalid items are skipped.

  • verbose (int, default 0) – Verbosity forwarded to collection construction and duplicate policy diagnostics.

  • progress (bool or {'auto'}, default False) – Enable progress display while unwrapping iterable inputs.

Returns:

Raw EDI object(s), depending on the input shape and as_collection.

Return type:

EDIFile, list of EDIFile, or EDICollection

Notes

The operation is shallow by default. It returns the same EDI objects wrapped by Site or Sites. Pass copy=True when the caller should be able to mutate the returned objects independently.

Examples

>>> from pycsamt.site.base import Site, Sites, to_edis
>>> site = Site(edi)
>>> raw = to_edis(site)
>>> raw is edi
True
>>> raws = to_edis(Sites([edi]))
>>> len(raws)
1
>>> coll = to_edis(Sites([edi]), as_collection=True)
>>> len(coll)
1

See also

to_sites

Wrap raw EDI-like inputs into Sites.

Site.to_edi

Convenience method for one Site.

Sites.to_edis

Convenience method for a Sites collection.