Author: He XingChen

Last Updated: 2026-03-21

Welcome to SeisPolarity

SeisPolarity is a comprehensive seismic first-motion polarity picking framework.

SeisPolarity provides a unified API for applying deep learning models to seismic waveforms for polarity classification, supporting multiple datasets and models.

Features

Unified Data Interface: Support for SCSN, Txed, DiTing, Instance, PNW datasets with automatic downloading
Multiple Models: Ross, Eqpolarity, APP, DiTingMotion, CFM, RPNet, PolarCAP with pretrained weights
Flexible Data Loading: RAM/disk streaming support for datasets of any scale
Advanced Inference: Predictor class with automatic pretrained model downloading from Hugging Face/ModelScope
Data Augmentation: Balanced sampling with various augmentation techniques
Unified Training: Checkpoint saving and early stopping mechanisms
Cross-platform Support: Linux, macOS, and Windows

Quick Start

Installation

pip install seispolarity

git clone https://github.com/Chuan1937/SeisPolarity.git
cd SeisPolarity
pip install -e .

Inference

from seispolarity.inference import Predictor
import numpy as np

predictor = Predictor("ROSS_SCSN")  
waveforms = np.random.randn(10, 400)  # (Batch, Length)
predictions = predictor.predict(waveforms)

Data Loading

from seispolarity.data import WaveformDataset

# Use disk streaming for large datasets
dataset = WaveformDataset(path="data.hdf5", name="SCSN", preload=False)
loader = dataset.get_dataloader(batch_size=1024, num_workers=4)

# Use RAM preloading for small datasets
dataset_ram = WaveformDataset(path="data.hdf5", name="SCSN", preload=True)

Automatic Dataset Download

from seispolarity.data import PNW
from pathlib import Path

output_dir = Path('datasets/PNW')
processor = PNW(
    csv_path=str(output_dir / 'PNW.csv'),
    hdf5_path=str(output_dir / 'PNW.hdf5'),
    output_polarity=str(output_dir),
    auto_download=True,  # Automatically download missing data
    use_hf=False,         # Use ModelScope instead of Hugging Face
    component='Z',        # Extract vertical component
    sampling_rate=100     # Target sampling rate (Hz)
)
processor.process()

Training

from seispolarity.models.scsn import SCSN
from seispolarity.training import Trainer, TrainingConfig

model = SCSN(num_fm_classes=3)
config = TrainingConfig(
    batch_size=256,
    epochs=50,
    learning_rate=1e-4,
    device='cuda'  # or 'cpu'
)
trainer = Trainer(model=model, dataset=dataset, config=config)
trainer.train()

Data Augmentation

from seispolarity.generate import GenericGenerator
from seispolarity.generate.augmentation import (
    Demean, Normalize, RandomTimeShift, 
    BandpassFilter, PolarityInversion
)

generator = GenericGenerator(dataset)
generator.add_augmentations([
    Demean(),
    Normalize(amp_norm_type="peak"),
    RandomTimeShift(max_shift=10),
    BandpassFilter(freqmin=1, freqmax=20),
    PolarityInversion(prob=0.5)
])
loader = generator.get_dataloader(batch_size=256)

Supported Datasets

Dataset	Description	Samples	Auto Download
SCSN	Southern California Seismic Network	100k+	Yes
Txed	Texas Earthquake Dataset	50k+	Yes
DiTing	China Earthquake Networks Center	80k+	No (request required)
Instance	Instance-based Dataset	30k+	Yes
PNW	Pacific Northwest	20k+	Yes

Supported Models

Model	Input Length	Classes
Ross (SCSN)	400	3 (U/D/N)
Eqpolarity	600	2 (U/D)
DiTingMotion	128	3 (U/D/N)
CFM	160	2 (U/D)
RPNet	400	2 (U/D)
PolarCAP	64	2 (U/D)
APP	400	3 (U/D/N)

Documentation

Documentation Contents

Examples

See complete examples in the examples/ directory:

Dataset API Usage - Dataset loading and usage examples
Prediction API Usage - Model inference examples
Model API Usage - Model architecture and initialization
Training API Usage - Training workflow examples

Citation

The paper will be published subsequently, please stay tuned.

Contact

For questions and support, please submit an issue on GitHub or contact: [chuanjun1978@gmail.com]