slope_filter open bounds, signed velocities, and slowness-based bounds

[alanfbaird]

I’d like to discuss the Patch.slope_filter API from a user perspective, especially around directional filters, open bounds, and whether slowness should be supported as an alternative to velocity.

Currently slope_filter takes a sorted length-4 filt=[va, vb, vc, vd]. With directional=False, these appear to behave like apparent velocity magnitudes. With directional=True, the sign of the values indicates propagation direction, so a negative-velocity filter must be sorted numerically. For example, instead of simply negating [va, vb, vc, vd] to [-va, -vb, -vc, -vd], the valid signed order appears to be [-vd, -vc, -vb, -va].

This is technically consistent with filtering on signed slope values, but it is unintuitive to me as a user because I tend to think of “high velocity” and “low velocity” by absolute value, with direction as a separate concept.

One case I’d find useful is open symmetric magnitude bounds when directional=False, similar to pass_filter allowing ... for open frequency bounds. For example:

• Low apparent velocity pass, symmetric about zero: patch.slope_filter(filt=(..., ..., vc, vd))
• High apparent velocity pass: patch.slope_filter(filt=(va, vb, ..., ...))

Conceptually, these could map onto the existing signed directional representation:

• Low velocity pass: filt=(-vd, -vc, vc, vd), directional=True
• High velocity pass: filt=(-vb, -va, va, vb), directional=True, invert=True

The invert=True part for the high-velocity pass is also slightly unintuitive. In the symmetric/magnitude mental model, (va, vb, ..., ...) reads like “pass above this lower bound.” But in the signed representation, (-vb, -va, va, vb) describes the central low-velocity band, so getting the high-velocity pass requires inverting it. In other words, what feels like a lower bound in the symmetric API becomes the edge of a central low-velocity notch/pass region internally. That mapping works, but it is easy to trip over.

More generally, I wonder if slowness bounds should be supported as an alternative to velocity bounds. For many seismic/DAS use cases, arrivals are naturally bounded in slowness by the medium, e.g. p = +/- 1 / v. This makes filters around broadside or near-zero-slowness arrivals easier to express. A “high velocity pass” is equivalent to a near-zero slowness pass, which is conceptually continuous in slowness but awkward in velocity because velocity tends toward +/- infinity at zero slowness.

Questions

1. Should open bounds be allowed for directional=False symmetric velocity filters?
2. Should signed directional velocity filters continue to require numerically sorted signed velocities?
3. Should the docs explicitly explain the negative-velocity ordering?
4. Should slowness bounds be supported as an alternative to velocity bounds?
5. Would names like velocity= / slowness= or a separate direction= argument make this clearer long-term?

[d-chambers]

Hey @alanfbaird,

Thanks for raising the issue. I am doing field work this week, but I will think about and write more next week.

In the meantime, maybe @Shihao-Yuan has some ideas? I think he did the orignal slope filter implementation.

[alanfbaird]

My current feeling is that a small improvement would be to allow the upper or lower bound to be omitted in the directional=False case, similar to how pass_filter supports open bounds. I think symmetric low/high apparent-velocity filters are likely to be common enough that it would be nice to express them directly, rather than having to manually construct the equivalent signed filter then try to figure out if invert should be True or False.

Then maybe keep the directional=True behavour as-is, but expand the documentation to explain it more explicitly.

[Shihao-Yuan]

Hi @alanfbaird, thanks for the feedback.

At the moment, slope_filter requires a sorted length-4 filt=[a, b, c, d], regardless of whether the values are interpreted as velocity or slowness. For directional=True, the filter is applied to signed slope values, so negative-velocity filters must indeed be numerically sorted (e.g., [-vd, -vc, -vb, -va] rather than simply negating [va, vb, vc, vd]). This is consistent with the underlying implementation, although I agree it is not necessarily obvious from a user's perspective and should probably be documented more explicitly.

Open bounds are currently not supported. The filter specification always requires four finite values. Your examples using ... makes sense to me, particularly for symmetric magnitude-based filtering when directional=False. I can see how expressions such as (..., ..., vc, vd) or (va, vb, ..., ...) would be more intuitive than constructing the equivalent signed directional filters manually. I will generalize the parameterization for open bounds in the following days.