obspy-noise-correlation

name

obspy-noise-correlation

description

Extract ambient seismic noise cross-correlation functions from continuous waveform data. Use when Codex needs to process continuous MiniSEED/SAC/ObsPy-readable seismic data for background-noise tomography or monitoring, including daily/hourly chunking, response removal, resampling, broad bandpass filtering, temporal normalization, spectral whitening, station-pair cross correlation, max-lag cutting, substacking, linear stacking, or preparing/using NoisePy-style workflows and stores.

ObsPy Noise Correlation

Scope

Use this skill for continuous ambient-noise workflows, not event-window earthquake processing. For ordinary event data preprocessing, use obspy-process-earthquake; for continuous data that will become noise correlation functions, use this skill and reuse the event-processing skill only for shared operations such as response removal, detrending, tapering, filtering, and resampling.

Workflow

1. Identify the continuous data layout:
   • local MiniSEED/SAC files or FDSN download target
   • station metadata: StationXML if response removal is requested
   • network/station/channel selections and component pairing
   • analysis time range and chunking, usually daily or hourly
2. Choose implementation scale:
   • Use NoisePy CLI/API for multi-day, many-station, production-scale work.
   • Use scripts/extract_noise_xcorr.py for small local MiniSEED/SAC tests, method development, or simple station-pair extraction.
3. Preprocess each channel consistently:
   • merge and trim to common windows
   • demean, detrend, taper
   • remove response when StationXML is available
   • resample/interpolate to a common sampling rate
   • broad bandpass before correlation
   • reject windows with spikes, gaps, NaN/Inf, or too little overlap
4. Apply ambient-noise normalization:
   • temporal normalization: one_bit, running mean absolute normalization, or none
   • spectral normalization: whitening or running-mean amplitude normalization
5. Compute correlations:
   • split data into cc_len windows with step overlap
   • FFT/correlate each station-channel pair
   • normalize by window energy
   • cut to maxlag
   • save substacks and linear stacks with metadata

NoisePy Pattern

NoisePy organizes the workflow as:

1. optional download into a raw data store
2. cross correlation into a CCF store
3. stacking into a stack store

For local MiniSEED, NoisePy uses MiniSeedDataStore, XMLStationChannelCatalog, ConfigParameters, and settings such as:

config.sampling_rate = 20
config.cc_len = 3600
config.step = 1800
config.freqmin, config.freqmax = 0.05, 2.0
config.time_norm = TimeNorm.ONE_BIT
config.freq_norm = FreqNorm.RMA
config.cc_method = CCMethod.XCORR
config.maxlag = 200

Read references/noise-correlation-guide.md before implementing a custom workflow or deciding between the bundled script and NoisePy.

Bundled Script

Use scripts/extract_noise_xcorr.py for local experiments:

python scripts/extract_noise_xcorr.py \
  --waveforms "continuous/*.mseed" \
  --output-dir CCF \
  --sampling-rate 20 \
  --freqmin 0.05 --freqmax 2.0 \
  --cc-len 3600 --step 1800 --maxlag 200 \
  --time-norm one_bit --freq-norm whiten

The script writes one .npz per station-channel pair with:

• lags: lag seconds
• stack: linear stack of all accepted windows
• substack: per-window correlations
• metadata: JSON string with parameters, pair id, and accepted window count

Defaults

• sampling rate: 20 Hz for broadband noise examples
• window length: 1 hour (cc_len=3600)
• step: 30 minutes (step=1800)
• bandpass: 0.05-2.0 Hz for many regional ambient-noise examples; adjust by interstation distance and target periods
• max lag: 200 s unless target interstation distances require more
• temporal normalization: one_bit for robust first-pass CCFs
• spectral normalization: whitening or running-mean spectral normalization
• stack: linear stack first; keep substacks for monitoring or later robust stacking

Quality Checks

• Confirm all traces in a correlation pair share sampling rate, start time coverage, and enough samples.
• Keep raw continuous data separate from processed CCF/STACK outputs.
• Record preprocessing parameters in every output.
• Inspect several daily CCFs before trusting long stacks.
• For tomography, verify station coordinates and interstation distances before interpreting group/phase velocities.

Sources

• NoisePy documentation: https://noisepy.github.io/NoisePy/README.html
• Local MiniSEED tutorial: https://noisepy.github.io/NoisePy/tutorial_local_mseed.html
• CLI tutorial: https://noisepy.github.io/NoisePy/tutorial_cli.html
• ObsPy preprocessing concepts are shared with obspy-process-earthquake.