SeisAug 0.2.0__py3-none-any.whl

seisaug/__init__.py

@@ -0,0 +1,25 @@
+from .noise import (
+    add_white_noise,
+    add_pink_noise,
+    add_monofrequency_noise,
+    add_bandpass_noise,
+    add_spikes,
+)
+from .signal import time_shift_zero_pad, convolve_with_sine, convolve_with_step
+from .io import read_waveform, read_stead_trace, write_stead_trace
+
+__all__ = [
+    "add_white_noise",
+    "add_pink_noise",
+    "add_monofrequency_noise",
+    "add_bandpass_noise",
+    "add_spikes",
+    "time_shift_zero_pad",
+    "convolve_with_sine",
+    "convolve_with_step",
+    "read_waveform",
+    "read_stead_trace",
+    "write_stead_trace",
+]
+
+__version__ = "1.2.0"

seisaug/__main__.py

@@ -0,0 +1,4 @@
+from .cli import batch_main
+
+if __name__ == "__main__":
+    batch_main()

seisaug/cli.py

@@ -0,0 +1,115 @@
+import argparse
+
+
+def batch_main(args):
+    from .pipeline import batch_augment
+
+    batch_augment(
+        input_hdf5=args.input_hdf5,
+        input_csv=args.input_csv,
+        output_hdf5=args.output_hdf5,
+        output_csv=args.output_csv,
+        config_path=args.config,
+    )
+    print(f"Augmented dataset written to: {args.output_hdf5}")
+    print(f"Metadata written to: {args.output_csv}")
+
+
+def validate_main(args):
+    from .validate import validate_stead_file
+
+    issues = validate_stead_file(args.input_hdf5, args.input_csv)
+
+    if issues:
+        print("Validation issues found:")
+        for item in issues:
+            print(f"- {item}")
+        raise SystemExit(1)
+
+    print("Validation passed.")
+
+
+def snr_main(args):
+    from .plotting import plot_snr_distribution
+
+    plot_snr_distribution(args.input_csv, outfile=args.output_png)
+    print(f"SNR distribution saved to: {args.output_png}")
+
+
+def grid_main(args):
+    from .io import read_stead_trace
+    from .plotting import plot_augmentation_grid
+
+    original, _ = read_stead_trace(args.input_hdf5, args.trace_name)
+
+    augmented = {}
+    for name in args.augmented_names:
+        augmented_data, _ = read_stead_trace(args.input_hdf5, name)
+        augmented[name] = augmented_data
+
+    plot_augmentation_grid(original, augmented, outfile=args.output_png)
+    print(f"Augmentation grid saved to: {args.output_png}")
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="seisaug",
+        description="SeisAug command-line tools for seismic augmentation, validation, and plotting.",
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    batch_parser = subparsers.add_parser(
+        "batch",
+        help="Batch augment a STEAD-format HDF5+CSV dataset",
+    )
+    batch_parser.add_argument("--input_hdf5", required=True, help="Input STEAD HDF5 file")
+    batch_parser.add_argument("--input_csv", required=True, help="Input STEAD metadata CSV")
+    batch_parser.add_argument("--output_hdf5", required=True, help="Output augmented HDF5 file")
+    batch_parser.add_argument("--output_csv", required=True, help="Output augmented CSV file")
+    batch_parser.add_argument("--config", required=True, help="YAML augmentation config file")
+    batch_parser.set_defaults(func=batch_main)
+
+    validate_parser = subparsers.add_parser(
+        "validate",
+        help="Validate a STEAD-format HDF5/CSV dataset",
+    )
+    validate_parser.add_argument("--input_hdf5", required=True, help="Input STEAD HDF5 file")
+    validate_parser.add_argument("--input_csv", default=None, help="Optional STEAD metadata CSV")
+    validate_parser.set_defaults(func=validate_main)
+
+    snr_parser = subparsers.add_parser(
+        "snr",
+        help="Plot SNR distribution from STEAD CSV metadata",
+    )
+    snr_parser.add_argument("--input_csv", required=True, help="Input STEAD metadata CSV")
+    snr_parser.add_argument("--output_png", required=True, help="Output PNG path")
+    snr_parser.set_defaults(func=snr_main)
+
+    grid_parser = subparsers.add_parser(
+        "grid",
+        help="Plot augmentation grid from original and augmented traces",
+    )
+    grid_parser.add_argument("--input_hdf5", required=True, help="Input STEAD HDF5 file")
+    grid_parser.add_argument("--trace_name", required=True, help="Original trace name")
+    grid_parser.add_argument(
+        "--augmented_names",
+        nargs="+",
+        required=True,
+        help="One or more augmented trace names",
+    )
+    grid_parser.add_argument("--output_png", required=True, help="Output PNG path")
+    grid_parser.set_defaults(func=grid_main)
+
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not hasattr(args, "func"):
+        parser.print_help()
+        raise SystemExit(0)
+
+    args.func(args)

seisaug/io.py

@@ -0,0 +1,35 @@
+import h5py
+import numpy as np
+import pandas as pd
+from obspy import read
+
+
+def read_waveform(path):
+    return read(str(path))
+
+
+def read_stead_trace(hdf5_path, trace_name):
+    with h5py.File(hdf5_path, "r") as f:
+        ds = f[f"data/{trace_name}"]
+        data = np.array(ds)
+        attrs = {k: ds.attrs[k] for k in ds.attrs.keys()}
+    return data, attrs
+
+
+def read_stead_metadata(csv_path):
+    return pd.read_csv(csv_path)
+
+
+def write_stead_trace(hdf5_path, trace_name, data, attrs=None, compression="gzip"):
+    attrs = attrs or {}
+    with h5py.File(hdf5_path, "a") as f:
+        grp = f.require_group("data")
+        if trace_name in grp:
+            del grp[trace_name]
+        ds = grp.create_dataset(trace_name, data=np.asarray(data, dtype=np.float32), compression=compression)
+        for k, v in attrs.items():
+            ds.attrs[k] = v
+
+
+def write_stead_metadata(csv_path, rows):
+    pd.DataFrame(rows).to_csv(csv_path, index=False)

seisaug/noise.py

@@ -0,0 +1,60 @@
+import numpy as np
+from scipy import signal
+
+
+def _db_to_amplitude_ratio(noise_level_db: float) -> float:
+    return 10 ** (noise_level_db / 20.0)
+
+
+def add_white_noise(data, noise_level_db):
+    data = np.asarray(data, dtype=np.float32)
+    ratio = _db_to_amplitude_ratio(noise_level_db)
+    noise = np.random.normal(size=data.shape).astype(np.float32)
+    noise_std = np.std(noise) or 1.0
+    return data + ratio * (noise / noise_std)
+
+
+def add_pink_noise(data, noise_level_db):
+    data = np.asarray(data, dtype=np.float32)
+    ratio = _db_to_amplitude_ratio(noise_level_db)
+    n = len(data)
+    freqs = np.fft.rfftfreq(n)
+    freqs[0] = 1.0
+    white = np.fft.rfft(np.random.normal(size=n))
+    pink = white / np.sqrt(freqs)
+    noise = np.fft.irfft(pink, n=n).astype(np.float32)
+    noise_std = np.std(noise) or 1.0
+    return data + ratio * (noise / noise_std)
+
+
+def add_monofrequency_noise(data, noise_level_db, fs, freq):
+    data = np.asarray(data, dtype=np.float32)
+    ratio = _db_to_amplitude_ratio(noise_level_db)
+    t = np.arange(data.shape[0], dtype=np.float32) / float(fs)
+    noise = np.sin(2 * np.pi * float(freq) * t).astype(np.float32)
+    noise_std = np.std(noise) or 1.0
+    return data + ratio * (noise / noise_std)
+
+
+def add_bandpass_noise(data, noise_level_db, fs, low_freq, high_freq, order=6):
+    data = np.asarray(data, dtype=np.float32)
+    ratio = _db_to_amplitude_ratio(noise_level_db)
+    white = np.random.normal(size=data.shape).astype(np.float32)
+    white_std = np.std(white) or 1.0
+    white = white / white_std
+    sos = signal.butter(order, [low_freq, high_freq], btype="band", fs=fs, output="sos")
+    filtered = signal.sosfilt(sos, white).astype(np.float32)
+    filt_std = np.std(filtered) or 1.0
+    return data + ratio * (filtered / filt_std)
+
+
+def add_spikes(data, num_spikes=10, spike_amp_ratio=0.3, seed=None):
+    data = np.asarray(data, dtype=np.float32).copy()
+    rng = np.random.default_rng(seed)
+    if len(data) == 0:
+        return data
+    max_amp = np.max(np.abs(data)) or 1.0
+    idx = rng.integers(0, len(data), size=int(num_spikes))
+    signs = rng.choice([-1.0, 1.0], size=int(num_spikes))
+    data[idx] += signs * float(spike_amp_ratio) * max_amp
+    return data

seisaug/plotting.py

@@ -0,0 +1,63 @@
+import ast
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+
+
+def plot_trace(data, title="Waveform", outfile=None):
+    data = np.asarray(data)
+    fig, axes = plt.subplots(3, 1, figsize=(10, 6), sharex=True)
+    labels = ["E", "N", "Z"]
+    for i, ax in enumerate(axes):
+        ax.plot(data[:, i], lw=0.8, color="k")
+        ax.set_ylabel(labels[i])
+    axes[-1].set_xlabel("Sample")
+    fig.suptitle(title)
+    fig.tight_layout()
+    if outfile:
+        fig.savefig(outfile, dpi=200, bbox_inches="tight")
+    return fig
+
+
+def plot_augmentation_grid(original, augmented_dict, outfile=None):
+    n = 1 + len(augmented_dict)
+    fig, axes = plt.subplots(n, 3, figsize=(14, 3 * n), sharex=True)
+    labels = ["E", "N", "Z"]
+    rows = [("original", original)] + list(augmented_dict.items())
+    for r, (name, arr) in enumerate(rows):
+        arr = np.asarray(arr)
+        for c in range(3):
+            ax = axes[r, c] if n > 1 else axes[c]
+            ax.plot(arr[:, c], lw=0.7, color="k")
+            ax.set_title(f"{name} - {labels[c]}")
+            if r == n - 1:
+                ax.set_xlabel("Sample")
+    fig.tight_layout()
+    if outfile:
+        fig.savefig(outfile, dpi=200, bbox_inches="tight")
+    return fig
+
+
+def plot_snr_distribution(csv_path, outfile=None):
+    df = pd.read_csv(csv_path)
+
+    def parse_snr(x):
+        try:
+            vals = ast.literal_eval(str(x))
+            vals = np.asarray(vals, dtype=float)
+            vals = vals[np.isfinite(vals)]
+            vals = vals[vals > -900]
+            return float(np.mean(vals)) if len(vals) else np.nan
+        except Exception:
+            return np.nan
+
+    df["snr_mean_db"] = df["snr_db"].apply(parse_snr)
+    fig, ax = plt.subplots(figsize=(8, 5))
+    ax.hist(df["snr_mean_db"].dropna(), bins=40, color="steelblue", alpha=0.8)
+    ax.set_xlabel("Mean SNR (dB)")
+    ax.set_ylabel("Count")
+    ax.set_title("SNR Distribution")
+    fig.tight_layout()
+    if outfile:
+        fig.savefig(outfile, dpi=200, bbox_inches="tight")
+    return fig

seisaug/signal.py

@@ -0,0 +1,36 @@
+import numpy as np
+
+
+def time_shift_zero_pad(data, shift_samples):
+    data = np.asarray(data, dtype=np.float32)
+    shift_samples = int(shift_samples)
+    out = np.zeros_like(data)
+    if shift_samples == 0:
+        return data.copy()
+    if abs(shift_samples) >= len(data):
+        return out
+    if shift_samples > 0:
+        out[shift_samples:] = data[:-shift_samples]
+    else:
+        out[:shift_samples] = data[-shift_samples:]
+    return out
+
+
+def convolve_with_sine(data, fs, freq=1.0):
+    data = np.asarray(data, dtype=np.float32)
+    t = np.arange(len(data), dtype=np.float32) / float(fs)
+    sig = np.sin(2 * np.pi * float(freq) * t).astype(np.float32)
+    out = np.convolve(sig, data, mode="same").astype(np.float32)
+    norm = np.max(np.abs(out)) or 1.0
+    return out / norm
+
+
+def convolve_with_step(data, fs, num_steps=10):
+    data = np.asarray(data, dtype=np.float32)
+    sig = np.zeros(len(data), dtype=np.float32)
+    edges = np.linspace(0, len(data), int(num_steps) + 1).astype(int)
+    for i in range(len(edges) - 1):
+        sig[edges[i]:edges[i + 1]] = i % 2
+    out = np.convolve(sig, data, mode="same").astype(np.float32)
+    norm = np.max(np.abs(out)) or 1.0
+    return out / norm

seisaug/validate.py

@@ -0,0 +1,41 @@
+import h5py
+import numpy as np
+import pandas as pd
+
+
+REQUIRED_ATTRS = [
+    "network_code",
+    "receiver_code",
+    "receiver_type",
+    "trace_name",
+    "trace_category",
+]
+
+
+def validate_stead_file(hdf5_path, csv_path=None):
+    issues = []
+
+    with h5py.File(hdf5_path, "r") as f:
+        if "data" not in f:
+            issues.append("Missing /data group")
+            return issues
+
+        for trace_name, ds in f["data"].items():
+            arr = np.array(ds)
+
+            if arr.ndim != 2 or arr.shape[1] != 3:
+                issues.append(f"{trace_name}: expected shape (N, 3), got {arr.shape}")
+
+            if not np.all(np.isfinite(arr)):
+                issues.append(f"{trace_name}: contains NaN/Inf")
+
+            for attr in REQUIRED_ATTRS:
+                if attr not in ds.attrs:
+                    issues.append(f"{trace_name}: missing attr {attr}")
+
+    if csv_path:
+        df = pd.read_csv(csv_path)
+        if "trace_name" not in df.columns:
+            issues.append("CSV missing trace_name column")
+
+    return issues

seisaug-0.2.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: SeisAug
+Version: 0.2.0
+Summary: Seismic waveform augmentation, STEAD-format I/O, plotting, and batch processing utilities
+Author: Pragnath
+License: MIT
+Project-URL: Homepage, https://github.com/Pragnath/SeisAug
+Project-URL: Repository, https://github.com/Pragnath/SeisAug
+Project-URL: Issues, https://github.com/Pragnath/SeisAug/issues
+Keywords: seismology,augmentation,obspy,earthquake,STEAD,machine-learning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.10
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: obspy>=1.4
+Requires-Dist: pandas>=1.5
+Requires-Dist: h5py>=3.8
+Requires-Dist: ipywidgets>=8.0
+Requires-Dist: tqdm>=4.65
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=1.2.1; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+
+# SeisAug
+
+SeisAug is a Python package for **seismic waveform augmentation**, **STEAD-format data handling**, **validation**, and **basic visualization** for earthquake machine-learning workflows.
+
+It is designed for researchers working with waveform datasets such as STEAD and for users building training pipelines for phase picking, event detection, and waveform classification.
+
+## Features
+
+- Add seismic waveform augmentations such as noise injection, spikes, and time shifts
+- Validate STEAD-format HDF5 and CSV datasets
+- Read and process three-component waveform traces
+- Plot SNR distributions from STEAD metadata
+- Build batch augmentation pipelines from YAML configuration files
+- Use a command-line interface for augmentation, validation, and plotting
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install SeisAug
+```
+
+For development:
+
+```bash
+git clone https://github.com/Pragnath/SeisAug.git
+cd SeisAug
+pip install -e .[dev]
+```
+
+## Command-Line Usage
+
+After installation, the `seisaug` command is available.
+
+### Show help
+
+```bash
+seisaug --help
+```
+
+### Batch augment a dataset
+
+```bash
+seisaug batch \
+  --input_hdf5 data/input.hdf5 \
+  --input_csv data/input.csv \
+  --output_hdf5 data/output_aug.hdf5 \
+  --output_csv data/output_aug.csv \
+  --config examples/augment_config.yaml
+```
+
+### Validate a STEAD-format dataset
+
+```bash
+seisaug validate \
+  --input_hdf5 data/output_aug.hdf5 \
+  --input_csv data/output_aug.csv
+```
+
+### Plot SNR distribution
+
+```bash
+seisaug snr \
+  --input_csv data/output_aug.csv \
+  --output_png snr_distribution.png
+```
+
+### Plot an augmentation grid
+
+```bash
+seisaug grid \
+  --input_hdf5 data/output_aug.hdf5 \
+  --trace_name trace_001 \
+  --augmented_names trace_001_aug1 trace_001_aug2 \
+  --output_png augmentation_grid.png
+```
+
+## Python Usage
+
+### Validate a dataset
+
+```python
+from seisaug.validate import validate_stead_file
+
+issues = validate_stead_file("data/input.hdf5", "data/input.csv")
+
+if issues:
+    for issue in issues:
+        print(issue)
+else:
+    print("Validation passed.")
+```
+
+### Apply a simple augmentation
+
+```python
+import numpy as np
+from seisaug.noise import add_spikes
+
+x = np.ones(1000, dtype=np.float32)
+y = add_spikes(x, num_spikes=5, spike_amp_ratio=0.5, seed=42)
+```
+
+## Project Structure
+
+```text
+SeisAug/
+├── src/seisaug/
+│   ├── __main__.py
+│   ├── cli.py
+│   ├── noise.py
+│   ├── signal.py
+│   ├── validate.py
+│   └── ...
+├── tests/
+├── examples/
+├── pyproject.toml
+└── README.md
+```
+
+## Development
+
+Run tests with:
+
+```bash
+pytest -q
+```
+
+Build the package with:
+
+```bash
+python -m build
+```
+
+Check package metadata and README rendering with:
+
+```bash
+python -m twine check dist/*
+```
+
+## Use Cases
+
+SeisAug is useful for:
+
+- Earthquake phase-picking model training
+- Data augmentation for seismic ML experiments
+- STEAD-format dataset validation and preprocessing
+- Quick CLI-based augmentation and visualization workflows
+
+## Requirements
+
+- Python 3.9+
+- NumPy
+- SciPy
+- Matplotlib
+- ObsPy
+- pandas
+- h5py
+- PyYAML
+
+## License
+
+MIT License
+
+## Repository
+
+Source code, issues, and updates:
+
+- Repository: https://github.com/Pragnath/SeisAug
+- Issues: https://github.com/Pragnath/SeisAug/issues

seisaug-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+seisaug/__init__.py,sha256=_GevYlF9bIzaRlpLg9pNAR-IHSHt0X9JzA-zzhPQL6U,587
+seisaug/__main__.py,sha256=vgNTG4XkVDD6utXg2Kp2CdepypyQLEXBMilr7LHepR4,73
+seisaug/cli.py,sha256=iVSif32UbMAjb7FduwOlz-5x4ZbXuH0hKemtaYz2Ry0,3822
+seisaug/io.py,sha256=s8WNkN2IduJCS-o7BN7I_v6dema_7YIAPvnz8_IVbRs,953
+seisaug/noise.py,sha256=z_34g9mjIeCGa-h_pz1DWeBF9YaLX6d1aTkA6OP35KA,2227
+seisaug/plotting.py,sha256=lceFIWmFmgPJsI5OAHv5mCxcoZ2_XRl-bqkuctTSVnI,2041
+seisaug/signal.py,sha256=soLMV5JpEXte6A6VD-7FhwI0Rt2AhGwUbahgXVNXs9M,1209
+seisaug/validate.py,sha256=rBPpxXYYSvHjntKhmmwDEdjPoz9yyzOQQGVt1ABLjM4,1049
+seisaug-0.2.0.dist-info/METADATA,sha256=xpFYO4u0RhEEE6EaAYh1f3VvJtU81f-BB43vGZCxFXU,4629
+seisaug-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+seisaug-0.2.0.dist-info/entry_points.txt,sha256=WPrAWS-lJKBHec59BFqcbIi_Lt6vLbbGEpt0iCl5_BU,45
+seisaug-0.2.0.dist-info/top_level.txt,sha256=P8A9qrnvmoKhA8_bxSIU0wtW162qNhuw3tGM8irrPBE,8
+seisaug-0.2.0.dist-info/RECORD,,

seisaug-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

seisaug-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+seisaug = seisaug.cli:main

seisaug-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+seisaug