pycsamt.seg.xa#

Functions

build_dataset(edis, *[, drop_empty])

Build a multi-site xarray Dataset from an iterable of EDIFile.

Classes

`EDIAcc`(ds)	An xarray accessor for convenient interaction with EDI datasets.
`XAMixin`()	A mixin that adds convenient xarray exports to collection classes.

class pycsamt.seg.xa.XAMixin[source]#

Bases: object

A mixin that adds convenient xarray exports to collection classes.

This mixin provides a bridge between collection-like objects (such as EDICollection) and the powerful, multi-dimensional data structures offered by the xarray library. Any class that is iterable over EDIFile instances can inherit from this mixin to gain methods for data conversion and metadata extraction.

to_xarray(drop_empty=True)[source]#

Converts the entire collection into a single, comprehensive xarray.Dataset. This method leverages build_dataset() to handle the conversion and concatenation of multiple EDI files.

Parameters:: drop_empty (bool)
Return type:: Dataset

meta_table()[source]#

Extracts only the site-level metadata (e.g., coordinates, filenames, data quality flags) from the collection and returns it as a clean, tabular xarray.Dataset, omitting the bulky transfer function data.

Return type:: Dataset

Notes

This mixin is designed to be lightweight and does not impose any specific storage or indexing strategy on the host class; it only requires that the host class implements the __iter__ method to yield EDIFile objects.
The site identifiers used in the resulting datasets follow the same robust inference rules as build_dataset().

Properties#

stationslist[str]: A list of all unique station or site names present in the dataset’s site coordinate.

get(site)[source]#

Selects and returns a new xarray.Dataset containing data for only a single site, specified by its name. The selection is case-insensitive.

Parameters:: site (str)
Return type:: Dataset

band(fmin=None, fmax=None)[source]#

Filters the dataset to a specific frequency range. Returns a new dataset containing only the data within the inclusive frequency bounds.

Parameters:

fmin (float | None)
fmax (float | None)

Return type:

Dataset

plot_apparent_resistivity(site, \*\*kwargs)[source]#

Generates a standard plot of apparent resistivity and phase curves for the off-diagonal tensor components (XY and YX) of a specified site.

Parameters:

site (str)
components (list[str])
phase_mod (int | None)
figsize (tuple[int, int])
show_grid (bool)
grid_props (dict | None)
savefig (str | None)

attrs()[source]#

Returns a dictionary of the dataset’s global attributes.

Return type:: dict[str, object]

See also

build_dataset: The function used to create datasets compatible with this accessor.

Examples

>>> from pycsamt.seg import EDICollection, build_dataset
>>> edi_collection = EDICollection.from_sources("data/edis/")
>>> ds = build_dataset(edi_collection)
>>>
>>> # Get a list of all station names
>>> print(ds.edi.stations)
['S01', 'S02', 'S03', ...]
>>>
>>> # Select data for a single station (case-insensitive)
>>> site_data = ds.edi.get('s01')
>>>
>>> # Filter the data to a specific frequency band (e.g., 1 to 100 Hz)
>>> filtered_ds = ds.edi.band(fmin=1.0, fmax=100.0)
>>>
>>> # Create a standard plot for a site
>>> fig, axes = ds.edi.plot_apparent_resistivity(site='S01')
>>> # fig.show() # Uncomment to display plot

property stations: list[str][source]#

get(site)[source]#

Selects data for a single site (case-insensitive).

Parameters:: site (str)
Return type:: Dataset

plot_apparent_resistivity(site, components=None, phase_mod=None, figsize=(8, 8), show_grid=True, grid_props=None, savefig=None, **plot_kwargs)[source]#

Generates a standard plot of apparent resistivity and phase.

This method provides a flexible interface for visualizing MT (magnetotelluric) data, allowing customization of components, phase wrapping, and plot aesthetics.

Parameters:

site (str) – The site identifier to plot.
components (list of str, default=["xy", "yx"]) – A list of tensor components to plot (e.g., “xy”, “yx”, “xx”). The selection is case-insensitive.
phase_mod (int, optional) – If provided, wraps the phase to a specific quadrant. For example, phase_mod=90 will display phases in the [0, 90] degree range, useful for visualizing data in a single quadrant.
figsize (tuple[int, int], default=(8, 6)) – The figure size for the plot.
show_grid (bool, default=True) – Whether to display a grid on both subplots.
grid_props (dict, optional) – Additional properties to customize the grid lines (e.g., {'color': 'grey', 'linestyle': '--', 'linewidth': 0.5}).
savefig (str, optional) – If a path is provided, the plot will be saved to that file.
**plot_kwargs – Additional keyword arguments passed directly to xarray’s .plot.line() method for customizing the lines.

Returns:

fig (matplotlib.figure.Figure) – The matplotlib Figure object.
axes (np.ndarray of matplotlib.axes.Axes) – An array containing the two subplot Axes objects.

Examples

>>> # Basic plot of off-diagonal components
>>> fig, axes = ds.edi.plot_apparent_resistivity(site='S01')
>>> # fig.show()

>>> # Plot all components and save the figure
>>> fig, axes = ds.edi.plot_apparent_resistivity(
...     site='S01',
...     components=['xy', 'yx', 'xx', 'yy'],
...     savefig='S01_all_components.png'
... )

>>> # Plot with phase wrapped to the first quadrant and custom styling
>>> fig, axes = ds.edi.plot_apparent_resistivity(
...     site='S01',
...     phase_mod=90,
...     grid_props={'color': 'red', 'linestyle': ':'},
...     marker='o'  # passed to plot.line
... )

attrs()[source]#

Returns the global attributes of the Dataset.

Return type:: dict[str, object]

band(fmin=None, fmax=None)[source]#

Parameters:

fmin (float | None)
fmax (float | None)

Return type:

Dataset

has_spectra()[source]#

Return type:: bool

spectra()[source]#

Return type:: Dataset

has_timeseries()[source]#

Return type:: bool

timeseries()[source]#

Return type:: Dataset

Parameters:: ds (xr.Dataset)

pycsamt.seg.xa.build_dataset(edis, *, drop_empty=True)[source]#

Build a multi-site xarray Dataset from an iterable of EDIFile.

This function iterates through a collection of parsed EDIFile objects, converts each one into a single-site xarray.Dataset, and then concatenates them into a unified, multi-site dataset.

Parameters:

edis (Iterable of EDIFile) – An iterable (e.g., a list or a EDICollection) of parsed EDI objects.
drop_empty (bool, default=True) – If True, any EDIFile object that contains no frequency data will be skipped and excluded from the final dataset.

Returns:

A single dataset containing data from all valid EDI files. The dataset is indexed by a site dimension, and site-specific metadata (latitude, longitude, etc.) are stored as non-dimensional coordinates aligned with this dimension.

Return type:

xr.Dataset

Notes

The resulting dataset is structured with dimensions for sites, frequencies, and tensor components. This structure is ideal for vectorized computations and advanced plotting across multiple sites.

This function correctly handles site-specific metadata by assigning it to coordinates, preventing data loss during concatenation, which is a common pitfall when storing metadata in global attributes.