Feat/trajectory complexity example

[Vadim3377]

Description

What is this PR
Addition of a new feature

Why is this PR needed?

movement currently provides low-level kinematic quantities such as velocity, speed, and path length, but there is not yet an example showing how these can be used to analyse noisy, irregularly sampled trajectories in a realistic scientific setting.

This PR is needed to provide a concrete, research-motivated example that demonstrates trajectory analysis with movement and motivates higher-level trajectory complexity metrics such as straightness index and tortuosity.

What does this PR do?

This PR adds a new example based on synthetic intracellular particle tracking data.

Specifically, it:

• simulates 2D particle trajectories with different motion regimes (directed, diffusive, and mixed)
• introduces realistic challenges such as localisation noise, missing observations, and irregular sampling
• converts the simulated data into a movement-compatible xarray dataset
• demonstrates the use of movement.kinematics functions such as compute_velocity, compute_speed, and compute_path_length
• includes prototype trajectory-level summary metrics, including straightness index and tortuosity, to illustrate possible future extensions of movement.kinematics
• visualises both spatial trajectories and temporal speed profiles

References

Relates to #517.

How has this PR been tested?

The example was run locally from start to finish to confirm that:

• the synthetic dataset is created successfully
• the movement.kinematics functions execute correctly on the generated data
• the trajectory summary metrics return sensible values for the three motion regimes
• the plots render correctly without errors

I also checked that the example uses the current public movement.kinematics API (compute_velocity, compute_speed, compute_path_length) rather than non-existent helper names.

Since this PR adds a new example and does not modify existing library functionality, existing behaviour should be unchanged.

Is this a breaking change?

No. This PR only adds a new example and does not change existing functionality or APIs.

Does this PR require an update to the documentation?

Yes.

This PR adds a new example demonstrating trajectory analysis for noisy and irregularly sampled intracellular particle trajectories. It is intended as example/gallery-style documentation showing how to use existing movement functionality in a realistic scientific context.

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud