Skip to content

Aligning with ICCS

The process

ICCS alignment is inherently exploratory. There is no fixed sequence of steps that works for every dataset — it is a feedback loop between adjusting parameters, running the algorithm, and examining the results. The goal is a stack that is coherent across the array and correlation coefficients that are high across most of the array.

Parameters interact: a filter that sharpens the waveform may allow a narrower time window, which in turn changes which seismograms align well. It is generally best to change one thing at a time and observe the effect before making further adjustments.

Running ICCS

aimbat align iccs <ID>                          # basic run
aimbat align iccs <ID> --autoflip               # flip inverted polarity automatically
aimbat align iccs <ID> --autoselect             # deselect poor-quality seismograms automatically
aimbat align iccs <ID> --autoflip --autoselect  # both

align iccs                          # basic run
align iccs --autoflip               # flip inverted polarity automatically
align iccs --autoselect             # deselect poor-quality seismograms automatically
align iccs --autoflip --autoselect  # both

Press a to open the alignment menu and choose ICCS. Before running, toggle Autoflip (f) and Autoselect (s) as needed.

Use the Run ICCS button in the Processing tab. Autoflip and autoselect can be toggled before running.

After each run, inspect the stack and matrix image to assess alignment quality before deciding what to change next.

Parameters

All parameters are per-event and can be adjusted at any time. Changes take effect on the next ICCS run.

Time window

window_pre and window_post define how much of the seismogram — before and after the pick — is used in the cross-correlation. Since the pick aims to sit at the onset of the target phase (the first coherent ground motion), the window effectively starts a little before the onset and extends through the arrival. Keeping window_pre short and placing the onset near the beginning of the window tends to work well, as it limits how much noise before the arrival is included. The window should be narrow enough that it is dominated by the target phase rather than noise or later arrivals.

A good starting point is a window that visually frames the onset in the stack plot. Narrowing it once initial alignment is reasonable often improves precision.

Bandpass filter

bandpass_apply, bandpass_fmin, and bandpass_fmax control an optional bandpass filter applied before cross-correlation. Filtering can dramatically improve alignment on noisy data by suppressing frequencies where the signal is weak, but the right frequency range depends on the event and the array.

Filtering is off by default. When enabled, the same filter is applied to both the seismograms and the stack, so the cross-correlation is always comparing like with like.

The phase pick (t1)

t1 is the per-seismogram pick that ICCS refines during each run — every seismogram gets its own value, reflecting how much it needs to be shifted relative to the stack. When adjusted interactively from the stack plot, however, the same shift is applied to all seismograms simultaneously. This makes interactive picking a coarse, global adjustment — useful for moving the entire array onto the onset — while ICCS handles the fine, per-seismogram refinement.

Minimum CC norm

min_cc is the threshold used by autoselect to deselect seismograms automatically. It does not affect the cross-correlation itself — only which seismograms are excluded from contributing to the stack in subsequent iterations.

Setting this too high early on may exclude seismograms that would align well once the stack improves. It is usually more effective to start with a permissive threshold and tighten it as alignment converges. The threshold can be adjusted interactively with aimbat tool cc.

Interactive adjustment

In addition to setting parameters directly, four interactive tools let you adjust values by interacting with the plot — clicking or scrolling in a waveform display rather than typing numbers. They are the most convenient way to explore parameters, but the same values can also be set directly via CLI arguments or the Python API.

aimbat tool phase <ID>    # adjust t1 by clicking on the stack
aimbat tool window <ID>   # set window_pre / window_post by clicking
aimbat tool cc <ID>       # set min_cc by scrolling the matrix image
aimbat tool bandpass <ID> # adjust bandpass filter settings interactively

tool phase    # adjust t1 by clicking on the stack
tool window   # set window_pre / window_post by clicking
tool cc       # set min_cc by scrolling the matrix image
tool bandpass # adjust bandpass filter settings interactively

Each command opens a matplotlib window. Click (or scroll) to set the value, then close the window to save it.

All four accept --no-context and --all (include deselected seismograms).

Press t to open the Tools menu, then choose from:

  • Phase arrival (t1) — click in the stack to shift all picks globally
  • Time window — click to place the window boundaries
  • Min CC — scroll the matrix image to set the threshold
  • Bandpass filter — toggle the filter and adjust frequency bounds

Before launching, toggle Context (c) and All seismograms (a) as needed. The TUI suspends while the matplotlib window is open and resumes when you close it.

The phase, window, and bandpass tools open the stack view; cc opens the matrix image. The behaviour of each is described in The ICCS Stack.

Running modes

Basic

Running without autoflip or autoselect leaves all decisions about which seismograms to include and whether to flip them up to the user. The stack and matrix views show the full result, and you can manually toggle select and flip on individual seismograms from the seismogram list.

Autoflip

Depending on the focal mechanism and a station's azimuth and take-off angle, some stations may record the target phase with opposite polarity to the rest of the array. These seismograms contribute destructively to the stack, degrading alignment for everything else. The flip flag multiplies a seismogram's data by −1 before it enters the stack and cross-correlation, correcting for this. With autoflip enabled, ICCS detects seismograms whose maximum absolute cross-correlation with the stack is negative and automatically toggles their flip parameter.

Autoflip can be run once early on to correct polarity issues, or left enabled throughout. It is safe to run repeatedly.

Autoselect

With autoselect enabled, seismograms whose CC norm falls below min_cc are automatically set to select = False and excluded from the stack in subsequent iterations. Importantly, they are still cross-correlated against the stack — so if parameters improve and they start to align better, they can be re-selected automatically in a later run.

This means autoselect is not permanent. A seismogram deselected at an early stage may recover as parameters improve — and narrowing the time window tends to increase CC norms across the board, which can bring previously deselected seismograms back above the threshold even without any change in alignment quality. This is worth keeping in mind when interpreting CC norms after a window adjustment.

Convergence

Within a single run, ICCS iterates — rebuilding the stack and re-correlating after each pass — until the stack stops changing meaningfully between iterations or a maximum number of iterations is reached. Convergence is assessed by comparing the current stack to the previous one: either by their correlation coefficient, or by the normalised change in stack shape. This happens automatically; there is no need to monitor it. Running ICCS again from AIMBAT's interface always starts a fresh run from the current picks.

What matters is the convergence of the overall process: across multiple runs with adjusted parameters, do the stack and correlation coefficients keep improving, or have they plateaued? When further adjustments produce no visible improvement in the stack, the data is ready — either for direct export, or as input to MCCC for formal timing uncertainties.

Knowing when to stop

There is no objective criterion for when ICCS alignment is "done". Practical signals that the dataset is ready:

  • The stack is visually coherent — individual traces closely follow its shape
  • Correlation coefficients are high across most of the array
  • The time window highlights a clean, well-defined arrival
  • Running ICCS again with or without autoflip/autoselect produces no meaningful change

At this point the ICCS picks can be exported directly from a snapshot — see Exporting Results. If formal per-station timing standard errors are needed (for example, as input to tomographic inversion), continue to MCCC alignment before taking the final snapshot. Either way, it is worth taking a snapshot now before making any further changes.

Tips

  • Change one parameter at a time. It is easy to lose track of what caused an improvement or regression if multiple things change at once.
  • Take snapshots liberally. They are lightweight and make it easy to backtrack to a promising state.
  • ICCS picks are directly usable. For workflows that do not require formal timing uncertainties, ICCS picks exported from a snapshot are suitable for further analysis as-is. MCCC adds formal standard errors and a more rigorous pairwise solution — run it when those are needed, but there is no obligation to do so.
  • Outlier seismograms. If a seismogram consistently has a poor CC norm across many runs and parameter combinations, it may be worth deleting it from the project rather than letting it drag down the stack.