2.13.2.6. pycsamt.stratagem.survey#

stratagem.survey#

End-to-end Stratagem AMT survey processing pipeline.

StratagemSurvey replaces the legacy watex-based stratagem_edi_process_script.py with a single composable class that covers the full post-acquisition workflow:

WinGLink EDI directory
  ↓  EDIBatch              load & natural-sort
  ↓  CoordinateInjector    inject GPS coords from CSV / XLS / XLSX
  ↓  QualityController     per-station QC report (optional)
  ↓  StaticShiftCorrector  AMA static-shift removal
  ↓  FrequencyFilter       band select + incoherent-freq masking
  ↓  NoiseRemover          powerline notch + Hampel + smoothing
  ↓  export()              write corrected EDIs
  ↓  rename()              standardise filenames (T2.000.edi …)

Every processing step is optional and chainable. The pipeline stores intermediate objects as attributes so individual results are always accessible.

Usage example#

Replicate the old stratagem_edi_process_script.py in four lines:

>>> from pycsamt.stratagem import StratagemSurvey
>>> sv = StratagemSurvey(
...     edi_dir="2/2EDI",
...     coord_file="2.csv",
...     raw_dir="原始数据/2HX",
...     epsg=32649,
... ).fit()
>>> sv.remove_static_shift().remove_noises().drop_frequencies(fmin=10.0)
>>> sv.export("2/2EDIP").rename(basename="T2.", dst_path="2/renamedEDIs")

Module Attributes

EdiSource

a WinGLink export directory (uses Stratagem's own natural 3-digit sort), or anything the conventional pycsamt.emtools/pycsamt.site stack already understands (a Sites, a list of EDIFile, or an EDICollection).

Classes

StratagemSurvey(edi_dir, coord_file, *[, ...])

End-to-end Stratagem AMT survey processing pipeline.

class pycsamt.stratagem.survey.StratagemSurvey(edi_dir, coord_file, *, raw_dir=None, epsg=32649, utm_zone='49N', coordinate_system='utm', order='auto', drop_stations=None, easting_col=None, northing_col=None, elev_col='elev', station_col='stations', read_kwargs=None, verbose=0)[source]

Bases: PyCSAMTObject, MetadataMixin

End-to-end Stratagem AMT survey processing pipeline.

Parameters:

edi_dir (path-like, Sites, or sequence of EDIFile) – Directory of WinGLink-exported EDI files (uses Stratagem’s own natural 3-digit sort via EDIBatch), or an already-loaded Sites / EDICollection / list of EDIFile — normalised through ensure_sites(), the same entry point the rest of pycsamt.emtools uses. In the latter case batch_ stays None (there’s no directory to report) and ordering is whatever the source already has.
coord_file (path-like) – GPS coordinate table (CSV / XLS / XLSX).
raw_dir (path-like, optional) – Directory of raw Stratagem hardware files (X*.NNN, …). When supplied, hardware SNR masks are used in QC and frequency filtering.
epsg (int, default 32649) – EPSG code of the projected CRS of coord_file. Use 32649 (UTM Zone 49N WGS84) for the standard south-China survey area.
utm_zone (str, default '49N') – UTM zone string for project_point_utm2ll when epsg is not sufficient.
coordinate_system (str, default 'utm')
order (str, default 'auto') – Station-to-GPS row ordering for StationLocator.
drop_stations (list of int, optional) – 0-based indices into the loaded EDIBatch to exclude before coordinate injection — e.g. a calibration/test shot that isn’t a real profile position and has no matching row in coord_file.
easting_col (str, optional) – Column names in coord_file for the projected E-W / N-S coordinates. Forwarded to fit(). Required whenever coord_file has more than two numeric columns besides elev_col — auto-detection raises rather than guessing in that case (see pycsamt.stratagem.gis_correct).
northing_col (str, optional) – Column names in coord_file for the projected E-W / N-S coordinates. Forwarded to fit(). Required whenever coord_file has more than two numeric columns besides elev_col — auto-detection raises rather than guessing in that case (see pycsamt.stratagem.gis_correct).
elev_col (str, default 'elev')
station_col (str, default 'stations')
read_kwargs (dict, optional) – Extra keyword arguments forwarded to the coord_file reader.
verbose (int, default 0)

Variables:

batch (EDIBatch or None) – Loaded EDI collection when edi_dir was a directory path; None when edi_dir was already a Sites/list of EDIFile.
raw_reader (StratagemRawReader or None) – Hardware file reader (None when raw_dir not supplied).
injector (CoordinateInjector) – Coordinate-injected EDI wrapper.
qc (QualityController or None) – QC report (populated after run_qc()).
edi_objects (list of EDIFile) – Current working set of EDI objects. Modified in-place by each processing step.

Examples

Full pipeline, one fluent expression:

>>> sv = (
...     StratagemSurvey(
...         edi_dir="2/2EDI",
...         coord_file="2.csv",
...         raw_dir="原始数据/2HX",
...         epsg=32649,
...     )
...     .fit()
...     .run_qc()
...     .remove_static_shift()
...     .drop_frequencies(fmin=10.0)
...     .remove_noises()
...     .export("2/2EDIP")
...     .rename(basename="T2.", dst_path="2/renamedEDIs")
... )
>>> print(sv.qc_.summary())

fit()[source]

Load EDIs, optional raw files, and inject GPS coordinates.

This is the only mandatory step. All processing methods (remove_static_shift(), drop_frequencies(), etc.) must be called after fit().

Return type:: self

run_qc(*, min_frac_ok=0.6, min_snr_med=2.0, max_skew_med=6.0, include_skew=True)[source]

Run the station-level QC report.

Results stored in qc_. Does not modify Z data.

Return type:

self

Parameters:

min_frac_ok (float)
min_snr_med (float)
max_skew_med (float)
include_skew (bool)

remove_static_shift(*, sort_by='lon', half_window=3, weights='tri', pband=None, max_skew=6.0)[source]

Apply AMA static-shift correction.

Important

Call this before drop_frequencies() to ensure the full frequency range is available for spatial averaging.

Return type:

self

Parameters:

sort_by (str)
half_window (int)
weights (str)
pband (tuple | None)
max_skew (float | None)

drop_frequencies(*, fmin=None, fmax=None, snr_thresh=2.5, min_frac=0.4, use_hardware_mask=True)[source]

Filter frequency bands and mask incoherent bins.

Parameters:

fmin (float, optional) – Frequency band limits in Hz.
fmax (float, optional) – Frequency band limits in Hz.
snr_thresh (float) – Per-station SNR threshold for incoherence masking.
min_frac (float) – Minimum fraction of stations that must pass snr_thresh.
use_hardware_mask (bool) – Apply hardware SNR mask when raw files were loaded.

Return type:

self

remove_noises(*, mains_hz=50.0, n_harm=30, tol_hz=0.08, notch_mode='interp', hampel_win=3, hampel_nsig=3.0, smooth=False, smooth_win=3)[source]

Apply powerline notch + Hampel outlier + optional smoothing.

Return type:

self

Parameters:

mains_hz (float)
n_harm (int)
tol_hz (float)
notch_mode (str)
hampel_win (int)
hampel_nsig (float)
smooth (bool)
smooth_win (int)

export(savepath, *, dataid_prefix=None, overwrite=False)[source]

Write the current edi_objects_ to savepath.

Parameters:

savepath (path-like) – Output directory (created if absent).
dataid_prefix (str, optional) – When given, >HEAD.DATAID is standardised to {dataid_prefix}{i:03d} before writing.
overwrite (bool, default False)

Return type:

self

rename(basename, dst_path, *, zero_pad=3, trailer='', overwrite=False, source=None)[source]

Rename EDI files with a standardised basename.

Parameters:

basename (str) – Filename prefix, e.g. 'T2.' → T2.000.edi.
dst_path (path-like) – Output directory for renamed files.
zero_pad (int, default 3)
trailer (str, default '')
overwrite (bool, default False)
source (path-like, optional) – Source directory or list. Defaults to the directory written by the most recent export() call; falls back to the current edi_objects_.

Return type:

self

summary()[source]

Return a human-readable pipeline status summary.

Return type:: str

property coordinate_frame[source]: DataFrame of WGS84 coordinates (requires fit()).

property sites_: Sites[source]

Current edi_objects_ wrapped as a Sites.

A fresh view built on every access, so it always reflects the current pipeline state (post-QC, post-static-shift, etc.). This is the interop point with the conventional pycsamt.emtools / pycsamt.site stack — e.g. use sv.sites_.write(outdir) for the generic {station}.edi writer instead of Stratagem’s own export()/rename() (which additionally handle DATAID prefixing and Stratagem’s zero-padded naming convention).

Examples

>>> sv.sites_.write("out_dir", exist_ok=True)