Handling near-zero steps in `compute_turning_angle`: alternatives to the current default

[niksirbi]

In PR #833 we added a compute_turning_angle function (see API docs).

That function accepts an optional min_step_length=0.0 argument:

The minimum step length to consider for computing the turning angle. Any turning angle involving an incoming or outgoing step shorter than or equal to this value is set to NaN. The default 0.0 only masks steps with exactly zero length, which means steps with near-zero lengths may still produce spurious angles. See Note 2 below.

The aforementioned Note 2:

1. Positional jitter and small steps: Tracking data often contains positional jitter, meaning a stationary animal may appear to make microscopic movements. With default parameters (min_step_length=0.0), these tiny, noisy movements will produce spurious, meaningless turning angles. It is highly recommended to set min_step_length to an appropriate threshold based on the tracking resolution and the animal's size in the scene. The value should be in the same units as the input position data (e.g. pixels, mm, etc.). Pre-smoothing the trajectory can also help reduce positional jitter.

I've kept the default as 0.0, even though it's not a good choice in most cases (as documented in the docstring). The problem is that any small positive value would be entirely arbitrary: we ultimately can't know what step length is small enough to render a computed heading meaningless, since that's domain-specific — it depends on video resolution, data units (pixels, mm, etc.), animal size in the scene, tracking quality, use of smoothing, and so on.

I merged #833 despite these reservations, since the implementation is sound, well-documented, and tested. This issue is a place to discuss alternatives to the current approach.

Some alternatives:

• Make min_step_length a required argument. This forces users to make a conscious choice, but may deter newcomers and makes the function harder to use out of the box. There's also a design question: trajectory complexity metric functions are planned to call compute_turning_angle internally—should the requirement propagate up to those functions too?
• Keep min_step_length optional, but change the default to 'auto', which would trigger heuristic-based threshold estimation—for example, something derived from the distribution of step lengths. The open question is whether a reliable heuristic exists that generalises well across use cases.

Note

Other ideas welcome. This is a discussion issue, not a call for PRs; at least not until we've converged on a workable approach.

[isha822]

@niksirbi I've been thinking about this since the PR merged, so wanted to share my current understanding and where I land on the alternatives.

The core issue with 'auto' as a default is that min_step_length encodes physical reality, camera resolution, spatial units, animal size, assay design. No heuristic inside compute_turning_angle has access to any of that. The function would be making a domain-specific decision the library has no basis to make silently.

The statistical approach (Otsu, GMM) is mathematically sound if the step length distribution is bimodal, a clear noise cluster near zero and a real movement cluster above it. But that bimodality only exists if the animal has stationary periods in the recording. Many experimental designs don't guarantee that: treadmill assays, Morris water maze, or temporally cropped recordings where researchers clip specifically to the behaviour of interest. If you apply a bimodal solver to unimodal data, it forces a split anyway and silently discards the lower half of real movement as noise. That failure mode is hard to detect and the user has no indication it happened.

So 'auto' fails not because the idea is wrong but because the parameter is too sensitive to the experimental context for any default estimation to be safe.

This leaves two honest options as I see it:

Making it required. Forces the user to make a conscious, informed decision based on their setup. Scientifically strict. The prop drilling cost is real, any higher-level function that calls compute_turning_angle internally would need to surface this parameter too. But I'd argue that's correct behaviour: if sinuosity or any trajectory complexity metric depends on this threshold, the user should be aware of it at every level of the pipeline.

A standalone utility like estimate_noise_threshold(data, method='otsu'). For users who genuinely don't know their threshold, a principled estimation function they can call explicitly, inspect, and override before passing the value in. This separates estimation from execution, keeps compute_turning_angle clean, and makes the assumption transparent rather than hidden.

I lean toward making it required, with the utility as a companion for accessibility. The required parameter guarantees the user has thought about their data. The utility gives them a starting point if they haven't.

One thing worth discussing, do typical movement datasets in standard assays reliably include rest periods? That determines whether bimodal estimation is viable as a default method in the utility, or whether it needs a fallback. Open to exploring this further if there are typical dataset patterns I should factor into utility design.

[niksirbi]

The statistical approach (Otsu, GMM) is mathematically sound if the step length distribution is bimodal, a clear noise cluster near zero and a real movement cluster above it. But that bimodality only exists if the animal has stationary periods in the recording. Many experimental designs don't guarantee that: treadmill assays, Morris water maze, or temporally cropped recordings where researchers clip specifically to the behaviour of interest. If you apply a bimodal solver to unimodal data, it forces a split anyway and silently discards the lower half of real movement as noise. That failure mode is hard to detect and the user has no indication it happened.

I agree this is the key difficulty with any automatic heuristic, we can't assume bimodality.

One thing worth discussing, do typical movement datasets in standard assays reliably include rest periods?

Often, but not always, we can't assume data will contain rest periods.

Thanks for your input @isha822, you make a good case for making it a required argument, but let's wait for others' input before committing to any path.