Metadata-Version: 2.4
Name: SeisAug
Version: 1.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
