pycsamt.ai.training.augment#

Data augmentation for EM training datasets.

Augmenters are callable objects that accept (X, y) numpy pairs and return modified copies. They are designed to be composed with Compose and used inside a training loop or as a preprocessing step on EMDataset.

Available augmenters#

AugmentNoise

Additive log-Gaussian noise on feature amplitudes.

AugmentStaticShift

Random static shift — multiply all log-amplitude features by a site-specific constant drawn from a log-uniform distribution.

AugmentFreqDrop

Randomly zero-out a fraction of frequency channels.

AugmentMixup

Convex combination of two training samples (Zhang et al. 2018).

Compose

Sequential chain of augmenters.

RandomApply

Apply an augmenter with probability p.

Classes

AugmentFreqDrop([drop_rate, contiguous, ...])

Randomly zero-out a fraction of frequency channels.

AugmentMixup([alpha])

Mixup augmentation (Zhang et al. 2018).

AugmentNoise([sigma, phase_sigma, clip])

Add multiplicative log-Gaussian noise to feature amplitudes.

AugmentStaticShift([shift_range, ...])

Apply a random static shift to amplitude features.

Compose(augmenters[, seed])

Sequentially apply a list of augmenters.

RandomApply(augmenter[, p, seed])

Apply an augmenter with probability p.
class pycsamt.ai.training.augment.AugmentNoise(sigma=0.05, phase_sigma=None, clip=3.0)[source]#

Bases: _BaseAugmenter

Add multiplicative log-Gaussian noise to feature amplitudes.

For each sample a noise vector

\[\boldsymbol{\varepsilon} \sim \mathcal{N}(\mathbf{0},\, \sigma^2 \mathbf{I})\]

is added to the feature vector. If phase_sigma is given a separate (typically smaller) noise level is used on phase features (assumed to occupy the second half of the feature vector when include_phase=True).

Parameters:

  • sigma (float, default 0.05) – Noise standard deviation applied to all features.

  • phase_sigma (float or None) – Separate noise level for phase features. None → use sigma.

  • clip (float or None) – Clip noise magnitude to [-clip, +clip] standard deviations.

class pycsamt.ai.training.augment.AugmentStaticShift(shift_range=(0.3, 3.0), n_amp_features=None, per_sample=True)[source]#

Bases: _BaseAugmenter

Apply a random static shift to amplitude features.

Static shift is a common MT artefact: all apparent-resistivity values at one site are scaled by a constant factor due to local near-surface heterogeneity. This augmenter simulates the effect by multiplying the first n_amp_features feature columns by a site-specific log-uniform random factor.

Parameters:

  • shift_range ((lo, hi), default (0.3, 3.0)) – Range of the multiplicative factor in linear scale.

  • n_amp_features (int or None) – Number of amplitude columns at the start of the feature vector. None → shift all features (use when features are log₁₀ amplitude only, without phase).

  • per_sample (bool) – If True draw an independent shift for each sample; otherwise draw one shift per batch.

class pycsamt.ai.training.augment.AugmentFreqDrop(drop_rate=0.1, contiguous=False, fill_value=0.0)[source]#

Bases: _BaseAugmenter

Randomly zero-out a fraction of frequency channels.

Simulates missing data at individual frequencies (bad data periods, cultural noise bursts, dead-band contamination).

Parameters:

  • drop_rate (float, default 0.1) – Fraction of feature columns to zero-out per sample.

  • contiguous (bool, default False) – When True drop a contiguous block of channels (simulates a dead band in frequency).

  • fill_value (float, default 0.0) – Replacement value for dropped channels.

class pycsamt.ai.training.augment.AugmentMixup(alpha=0.2)[source]#

Bases: _BaseAugmenter

Mixup augmentation (Zhang et al. 2018).

Randomly pairs samples within the batch and creates convex combinations:

\[\tilde{\mathbf{x}} = \lambda \mathbf{x}_i + (1-\lambda) \mathbf{x}_j, \quad \tilde{\mathbf{y}} = \lambda \mathbf{y}_i + (1-\lambda) \mathbf{y}_j\]

where \(\lambda \sim \mathrm{Beta}(\alpha, \alpha)\).

Parameters:

alpha (float, default 0.2) – Beta distribution shape parameter. Small values (≈0.1) produce near-original samples; alpha=1.0 is uniform mixing.

class pycsamt.ai.training.augment.Compose(augmenters, seed=None)[source]#

Bases: object

Sequentially apply a list of augmenters.

Parameters:

  • augmenters (list of _BaseAugmenter) – Applied in order.

  • seed (int or None) – Seed for the shared random generator.

Examples

>>> aug = Compose([
...     AugmentStaticShift(shift_range=(0.5, 2.0)),
...     AugmentNoise(sigma=0.03),
...     AugmentFreqDrop(drop_rate=0.05),
... ])
>>> X_aug, y_aug = aug(X_train, y_train)
class pycsamt.ai.training.augment.RandomApply(augmenter, p=0.5, seed=None)[source]#

Bases: object

Apply an augmenter with probability p.

Parameters:

  • augmenter (_BaseAugmenter)

  • p (float, default 0.5)

  • seed (int or None)

Examples

>>> aug = RandomApply(AugmentMixup(alpha=0.3), p=0.4)
>>> X_aug, y_aug = aug(X_train, y_train)