SeisAug 0.2.0__tar.gz

seisaug-0.2.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include pyproject.toml

seisaug-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,171 @@
+# 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/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "SeisAug"
+version = "0.2.0"
+description = "Seismic waveform augmentation, STEAD-format I/O, plotting, and batch processing utilities"
+dynamic = ["readme"]
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+  {name = "Pragnath"}
+]
+keywords = ["seismology", "augmentation", "obspy", "earthquake", "STEAD", "machine-learning"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: Scientific/Engineering :: Physics"
+]
+dependencies = [
+  "numpy>=1.23",
+  "scipy>=1.10",
+  "matplotlib>=3.6",
+  "obspy>=1.4",
+  "pandas>=1.5",
+  "h5py>=3.8",
+  "ipywidgets>=8.0",
+  "tqdm>=4.65",
+  "pyyaml>=6.0"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "build>=1.2.1",
+  "twine>=5.1.1"
+]
+
+[project.urls]
+Homepage = "https://github.com/Pragnath/SeisAug"
+Repository = "https://github.com/Pragnath/SeisAug"
+Issues = "https://github.com/Pragnath/SeisAug/issues"
+
+[project.scripts]
+seisaug = "seisaug.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+readme = {file = ["README.md"], content-type = "text/markdown"}

seisaug-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

seisaug-0.2.0/src/SeisAug.egg-info/PKG-INFO

@@ -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/src/SeisAug.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+MANIFEST.in
+README.md
+pyproject.toml
+src/SeisAug.egg-info/PKG-INFO
+src/SeisAug.egg-info/SOURCES.txt
+src/SeisAug.egg-info/dependency_links.txt
+src/SeisAug.egg-info/entry_points.txt
+src/SeisAug.egg-info/requires.txt
+src/SeisAug.egg-info/top_level.txt
+src/seisaug/__init__.py
+src/seisaug/__main__.py
+src/seisaug/cli.py
+src/seisaug/io.py
+src/seisaug/noise.py
+src/seisaug/plotting.py
+src/seisaug/signal.py
+src/seisaug/validate.py
+tests/test_noise.py
+tests/test_signal.py
+tests/test_validate.py

seisaug-0.2.0/src/SeisAug.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

seisaug-0.2.0/src/SeisAug.egg-info/entry_points.txt

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

seisaug-0.2.0/src/SeisAug.egg-info/requires.txt

@@ -0,0 +1,14 @@
+numpy>=1.23
+scipy>=1.10
+matplotlib>=3.6
+obspy>=1.4
+pandas>=1.5
+h5py>=3.8
+ipywidgets>=8.0
+tqdm>=4.65
+pyyaml>=6.0
+
+[dev]
+pytest>=7.0
+build>=1.2.1
+twine>=5.1.1

seisaug-0.2.0/src/SeisAug.egg-info/top_level.txt

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

seisaug-0.2.0/src/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-0.2.0/src/seisaug/__main__.py

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

seisaug-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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/tests/test_noise.py

@@ -0,0 +1,23 @@
+import numpy as np
+
+from seisaug.noise import add_white_noise, add_pink_noise, add_spikes
+
+
+def test_add_white_noise_preserves_shape():
+    x = np.zeros(1000, dtype=np.float32)
+    y = add_white_noise(x, noise_level_db=10)
+    assert y.shape == x.shape
+
+
+def test_add_pink_noise_returns_finite_values():
+    x = np.zeros(2000, dtype=np.float32)
+    y = add_pink_noise(x, noise_level_db=8)
+    assert y.shape == x.shape
+    assert np.isfinite(y).all()
+
+
+def test_add_spikes_preserves_shape_and_changes_samples():
+    x = np.ones(1000, dtype=np.float32)
+    y = add_spikes(x, num_spikes=5, spike_amp_ratio=0.5, seed=42)
+    assert y.shape == x.shape
+    assert not np.allclose(x, y)

seisaug-0.2.0/tests/test_signal.py

@@ -0,0 +1,29 @@
+import numpy as np
+
+from seisaug.signal import time_shift_zero_pad, convolve_with_sine, convolve_with_step
+
+
+def test_time_shift_zero_pad_positive_shift():
+    x = np.array([1, 2, 3, 4], dtype=np.float32)
+    y = time_shift_zero_pad(x, 2)
+    assert np.allclose(y, [0, 0, 1, 2])
+
+
+def test_time_shift_zero_pad_negative_shift():
+    x = np.array([1, 2, 3, 4], dtype=np.float32)
+    y = time_shift_zero_pad(x, -2)
+    assert np.allclose(y, [3, 4, 0, 0])
+
+
+def test_convolve_with_sine_shape():
+    x = np.random.randn(1000).astype(np.float32)
+    y = convolve_with_sine(x, fs=100.0, freq=2.0)
+    assert y.shape == x.shape
+    assert np.isfinite(y).all()
+
+
+def test_convolve_with_step_shape():
+    x = np.random.randn(1000).astype(np.float32)
+    y = convolve_with_step(x, fs=100.0, num_steps=8)
+    assert y.shape == x.shape
+    assert np.isfinite(y).all()

seisaug-0.2.0/tests/test_validate.py

@@ -0,0 +1,37 @@
+import tempfile
+from pathlib import Path
+
+import h5py
+import numpy as np
+import pandas as pd
+
+from seisaug.validate import validate_stead_file
+
+
+def test_validate_stead_file_passes_for_minimal_valid_input():
+    with tempfile.TemporaryDirectory() as tmpdir:
+        h5_path = Path(tmpdir) / "test.hdf5"
+        csv_path = Path(tmpdir) / "test.csv"
+
+        with h5py.File(h5_path, "w") as f:
+            grp = f.create_group("data")
+            ds = grp.create_dataset("trace_1", data=np.zeros((100, 3), dtype=np.float32))
+            ds.attrs["network_code"] = "XX"
+            ds.attrs["receiver_code"] = "STAT"
+            ds.attrs["receiver_type"] = "HH"
+            ds.attrs["trace_name"] = "trace_1"
+            ds.attrs["trace_category"] = "earthquake_local"
+
+        pd.DataFrame([{"trace_name": "trace_1"}]).to_csv(csv_path, index=False)
+
+        issues = validate_stead_file(h5_path, csv_path)
+        assert issues == []
+
+
+def test_validate_stead_file_flags_missing_data_group():
+    with tempfile.TemporaryDirectory() as tmpdir:
+        h5_path = Path(tmpdir) / "bad.hdf5"
+        with h5py.File(h5_path, "w"):
+            pass
+        issues = validate_stead_file(h5_path)
+        assert any("Missing /data group" in item for item in issues)