Metadata-Version: 2.4
Name: SeisDeepFilter
Version: 0.1.1
Summary: Interactive deep-learning seismic filtering and wavefield separation
Author: Myrto Papadopoulou
Author-email: Yang Cui <yang.cui@geo.uu.se>
License-Expression: Apache-2.0
Keywords: seismic,deep learning,denoising,wavefield separation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.7
Requires-Dist: torch>=2.1
Requires-Dist: PyQt5>=5.15
Requires-Dist: obspy>=1.4
Requires-Dist: segyio>=1.9
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Dynamic: license-file

<div align="center">
  <img src="./deepfilter-logo.png" alt="SeisDeepFilter logo" width="500">
</div>

<h1 align="center">SeisDeepFilter: An Interactive Deep-Learning Platform for Seismic Wavefield Separation and Denoising</h1>

<div align="center">
  <a href="https://github.com/cuiyang512">Yang Cui<sup>1</sup></a>
  &emsp;
  <a href="https://www.uu.se/en/contact-and-organisation/staff?query=N21-2074">Myrto Papadopoulou<sup>1</sup></a>
</div>

<div align="center">
  <sup>1</sup>Department of Earth Sciences, Uppsala University
</div>

<br>

<div align="center">
  <img src="https://img.shields.io/github/stars/cuiyang512/SeisDeepFilter" alt="GitHub stars">
  <img src="https://img.shields.io/github/forks/cuiyang512/SeisDeepFilter" alt="GitHub forks">
  <img src="https://img.shields.io/github/last-commit/cuiyang512/SeisDeepFilter" alt="Last commit">
  <img src="https://img.shields.io/badge/Python-3.10%2B-3572A5" alt="Python 3.10 or newer">
  <img src="https://img.shields.io/badge/compute-CPU%20%7C%20CUDA-35aaa3" alt="CPU and CUDA support">
</div>

## Overview

SeisDeepFilter is an interactive deep-learning platform for general-purpose seismic filtering and wavefield separation. A user draws a polygon mask in a selected transform domain and identifies the energy to preserve or remove. A lightweight U-Net is then optimized directly on the input gather, without labelled examples, clean reference data, or a pretrained model.

This per-gather training strategy reduces dependence on the ability of a pretrained network to generalize to new acquisition geometries and noise conditions. The neural network acts as an implicit reconstruction model and provides an alternative to applying a hard inverse-transform mask directly. This can reduce mask-edge artefacts, although the result still depends on the selected transform, polygon, preprocessing, and optimization settings.

SeisDeepFilter currently supports 2-D seismic gathers and produces two complementary outputs:

```text
input = kept + removed
```

The framework has been applied to seismic denoising, ground-roll removal, surface-wave processing, and upgoing/downgoing wavefield separation. The examples below illustrate the workflow on field data; they are not intended as a universal performance benchmark.

## Key features

- Interactive polygon selection in **F-K**, **linear Radon (τ-p)**, **frequency–velocity (F-V)**, and **time-frequency** domains.
- User-defined **Keep selected energy** and **Remove selected energy** tasks.
- Per-gather optimization without training labels or clean targets.
- Full-size 2-D input processing without silently cropping the gather.
- Lightweight residual U-Net with several selectable model sizes.
- Automatic CUDA use when available, with CPU fallback.
- Optional detrending, RMS AGC, tapering, band-pass filtering, and time muting.
- Support for SEG-Y, MATLAB, NPY, and NPZ input and output.
- Automatic recovery of sampling and receiver geometry from valid SEG-Y headers.
- Output QC for the input, kept component, removed component, and their corresponding transform spectra.
- Reproducible masks, training recipes, model checkpoints, and reconstruction reports.

## Supported transforms

| Transform | Typical application | Notes |
|---|---|---|
| F-K | Linear noise and directional wavefield separation | Uses the full gather aperture |
| Linear Radon | Approximately linear events defined by intercept time and slowness | Uses an automatically calculated τ range and runs on the CPU |
| F-V | Dispersive surface-wave energy | Uses a user-defined receiver window |
| Time-frequency | Transient and frequency-localized noise | Uses a short-time Fourier transform with adjustable window and hop lengths |

The transforms share the same training workflow but use different loss representations. F-K and Radon constrain the full gather. F-V currently applies its constraint to a selected receiver window.

## Installation

SeisDeepFilter requires Python 3.10 or newer. After the package is published on PyPI, install the complete application with:

```bash
pip install SeisDeepFilter
```

To install directly from a cloned repository:

```bash
git clone https://github.com/cuiyang512/SeisDeepFilter.git
cd SeisDeepFilter
pip install .
```

Launch the GUI with:

```bash
seisdeepfilter-gui
```

The legacy command `deepfilter-gui` is also available. CUDA is selected automatically when supported by the installed PyTorch build; otherwise training runs on the CPU.

## Workflow

1. Open a 2-D seismic gather.
2. Apply optional preprocessing and time muting.
3. Select and calculate a transform.
4. Draw or load a polygon mask.
5. Choose whether the selected energy should be kept or removed.
6. Start filtering.
7. Inspect the input, kept component, removed component, and their spectra in Output QC.
8. Save the separated data, model, processing recipe, report, and QC figure.

Input arrays use `[time sample, receiver]` layout. SeisDeepFilter preserves the input format when writing the kept, removed, and optional preprocessed gathers.

<div align="center">
  <img src="./fig/interface.png" alt="Seismic denoising example" width="850">
</div>

## Results

### Seismic denoising

<div align="center">
  <img src="./fig/denoising.png" alt="Seismic denoising example" width="750">
</div>

### Upgoing and downgoing wavefield separation

<div align="center">
  <img src="./fig/up_and_down_sep.png" alt="Upgoing and downgoing wavefield separation" width="750">
</div>

### Ground-roll removal

The following South African field-data example targets strong surface-wave contamination in a reflection gather. The picked F-K mask follows the coherent linear and surface-wave energy selected for removal.

<div align="center">
  <img src="./fig/south_africa_surface_wave_removal.png" alt="Ground-roll removal example" width="850">
</div>

## Important considerations

- The polygon mask is a user-defined prior rather than ground truth.
- Components that overlap strongly in the selected transform domain may not be uniquely separable.
- Results depend on the transform parameters, polygon boundary, preprocessing, model size, and optimization length.
- RMS AGC changes relative amplitudes and can reduce phase coherence in F-V spectra.
- F-V currently uses one receiver window and therefore does not constrain every receiver position equally in a large shot gather.
- Linear Radon runs on the CPU and is generally slower than F-K.

## Citation

If SeisDeepFilter contributes to your research, please cite the associated paper once its final bibliographic information is available:

> Yang Cui and Myrto Papadopoulou. “SeisDeepFilter: An Interactive Deep-Learning Platform for Seismic Wavefield Separation and Denoising.” 2026. Manuscript in preparation.

```bibtex
@article{cui2026seisdeepfilter,
  title   = {SeisDeepFilter: An Interactive Deep-Learning Platform for Seismic Wavefield Separation and Denoising},
  author  = {Cui, Yang and Papadopoulou, Myrto},
  journal = {To be determined},
  year    = {2026}
}
```

## Contributing

    Contributions, bug reports, and suggestions are welcome. When reporting a processing issue, please include the input format, array dimensions, sampling rate, receiver spacing, selected transform, preprocessing settings, and complete error message.

## Contact

For questions, bug reports, development, or collaboration, contact:

**Yang Cui**  
[yang.cui512@gmail.com](mailto:yang.cui512@gmail.com)  
[yang.cui@geo.uu.se](mailto:yang.cui@geo.uu.se)
