pycsamt.zonge.processing

pycsamt.zonge.processing

This module provides the ASTATIC class, which contains methods for advanced data conditioning and analysis, such as static shift correction, filtering, and data merging, mirroring the capabilities of Zonge’s ASTATIC program.

Classes

ASTATIC([avg_data, verbose])

A class for advanced processing of Zonge AVG data.

class pycsamt.zonge.processing.ASTATIC(avg_data=None, verbose=False, **kws)

Bases: Zonge

A class for advanced processing of Zonge AVG data.

This class provides a suite of methods for data conditioning and analysis that mirror the functionality of Zonge’s ASTATIC software [1]. It operates on a loaded AMTAVG object, allowing for complex operations like static shift correction, data filtering, and interpolation.

Parameters:

• avg_data (BaseAVG, optional) – An initialized and loaded AVG object. If provided, the processor is immediately ready for use.

• verbose (bool, default False) – If True, log messages will be printed to the console during processing operations, providing insight into the process.

Variables:

avg (AMTAVG or None) – The AVG data object that the processor is operating on. It is populated by either passing it to the constructor or by using the read() method.

read(source, meta=None)

Loads a data source into the processor.

Parameters:

• source (str | Path | AVGFrame | pd.DataFrame | BaseAVG)

• meta (Mapping[str, Any] | None)

Return type:

ASTATIC

correct_static_shift(...)

Corrects for static shift using various spatial filters.

Parameters:

• reference_freq (float)

• filter_method (Literal['tma', 'flma', 'ama'])

• update_components (bool)

Return type:

DataFrame

correct_capacitive_coupling(...)

Remediates high-frequency distortions from capacitive coupling.

Parameters:

• contact_resistance (float | Series | str)

• setup_length (float | Series | str)

• wire_capacitance (float | Series | str)

• update_components (bool)

Return type:

DataFrame

Notes

The ASTATIC class is designed using a “composition over inheritance” approach. It is not a type of AVG file; rather, it is a tool that contains and operates on an AVG object.

Most processing methods, such as correct_static_shift, modify the underlying avg object’s DataFrame in place when the update_components parameter is set to True. This ensures that all data components are consistently updated after a processing step.

Examples

The typical workflow involves loading data with an AMTAVG object and then passing that object to the ASTATIC processor.

>>> from pycsamt.zonge import AMTAVG, ASTATIC
>>> # 1. Load the data
>>> avg = AMTAVG.from_file('data/avg/K2.avg')
>>>
>>> # 2. Create a processor and apply a correction
>>> processor = ASTATIC().read(avg)
>>> processor.correct_static_shift(
...     reference_freq=4096, filter_method='tma'
... )
>>>
>>> # 3. The original avg object is now updated and can be saved
>>> avg.to_modern('K2_corrected.avg')

References

[1]

Zonge International, Inc. (2014). ASTATIC v3.70 User Manual.

See also

pycsamt.zonge.avg.AMTAVG

The primary data container class.

pycsamt.zonge.proc_utils

The module containing the core filtering algorithms.

read(source, meta=None)

Load a data source into the processor.

This is the primary method for associating a dataset with the ASTATIC processor. It is designed to be flexible, accepting various input types and ensuring that the processor is initialized with a valid, fully-loaded AVG data object.

Parameters:

• source (str, Path, AVGFrame, pd.DataFrame, or BaseAVG) –

  The data source to load. This can be:

  • A string or pathlib.Path pointing to a Zonge AVG file. A new AMTAVG instance will be created internally to read the file.

  • A pandas.DataFrame. A new AMTAVG instance will be created to read the DataFrame.

  • A pre-existing, loaded object that inherits from BaseAVG (e.g., an AVG or AMTAVG instance).

• meta (mapping, optional) – An optional dictionary of metadata. This is only used when source is a pd.DataFrame.

Returns:

self – The method returns the instance of the class, allowing for convenient method chaining.

Return type:

ASTATIC

Raises:

• TypeError – If the source is of an unsupported type.

• NotReadError – If an AVG-like object is passed as the source but it has not been populated with data yet.

Notes

This method acts as a smart constructor for the processor. If the provided source is not already a loaded AVG object, the method takes on the responsibility of creating one. This ensures that the self.avg attribute is always a valid, ready-to-use data container.

Examples

>>> from pycsamt.zonge import AMTAVG, ASTATIC
>>> # --- Reading from a pre-loaded AVG object ---
>>> avg = AMTAVG.from_file('data/avg/K2.avg')
>>> processor = ASTATIC().read(avg)
>>>
>>> # --- Reading directly from a file path ---
>>> processor_from_file = ASTATIC().read('data/avg/K1.avg')

See also

pycsamt.zonge.avg.AVG.from_file

The primary factory for creating an AVG data object.

pycsamt.utils.validation.has_read

The underlying utility used to validate loaded data objects.

correct_capacitive_coupling(contact_resistance, setup_length, wire_capacitance=15.0, update_components=True)

Correct for capacitive coupling effects in E-field data.

This method remediates distortions in high-frequency data caused by capacitive coupling between receiver wires and the ground.

Parameters:

• contact_resistance (float, pd.Series, or str) – The contact resistance at the electrodes, in Ohms. Can be a single value for all measurements, a Series, or the name of a column in the dataset.

• setup_length (float, pd.Series, or str) – The length of the setup wire, in meters. This is often the distance from the GDP to the dipole center.

• wire_capacitance (float, pd.Series, or str, default 15.0) – The wire-to-ground capacitance in picofarads per meter (pF/m). This is often an empirical tuning parameter.

• update_components (bool, default True) – If True, the main DataFrame (self.avg.info.df) is updated in place with the corrected E-field values, and all dependent components (Z, rho, phase) are recalculated.

Returns:

A new DataFrame containing the corrected emag and ephz columns.

Return type:

pandas.DataFrame

Notes

The correction is based on a simple circuit model where the capacitive admittance (\(Y_c\)) shunts the true Earth impedance. The measured voltage is corrected to estimate the true voltage that would be measured without this effect.

The correction factor is given by:

\[E_{true} = \frac{E_{measured}}{1 + Z_c Y_c}\]

where \(Z_c\) is the contact impedance (resistance) and \(Y_c = i \omega C\) is the capacitive admittance.

correct_static_shift(reference_freq, *, filter_method='tma', update_components=True, **kwargs)

Correct for static shift using a spatial filter.

This method applies a spatial filter to the data at a single reference frequency to estimate and correct for static shift effects.

Parameters:

• reference_freq (float) – The frequency (in Hz) at which to perform the spatial filtering. This should typically be the highest frequency with clean data.

• filter_method ({'tma', 'flma', 'ama'}, default 'tma') – The filtering algorithm to use: - ‘tma’: Trimmed Moving Average (works on resistivity). - ‘flma’: Fixed-Length Moving Average (works on impedance). - ‘ama’: Adaptive Moving Average (works on impedance).

• update_components (bool, default True) – If True, the main DataFrame (self.avg.info.df) is updated in place with the static-shifted resistivity values, and all components are re-read.

• **kwargs – Additional keyword arguments to be passed to the chosen filtering function (e.g., window_size for tma, filter_width_dipoles for flma).

Returns:

A DataFrame containing the station, the original data profile, the smoothed profile, and the shift factor.

Return type:

pandas.DataFrame