Functions#

flock measures#

Diagnostics.Functions.flock_measures.absolute_dispersion(X, Y, X0=None, Y0=None)[source]#

see equation (2) in [Ha08]

Parameters:

  • X (numpy.ndarray, size=(m,n), unit={degrees,meters}) – m: id, n: time

  • Y (numpy.ndarray, size=(m,n), unit={degrees,meters}) – m: id, n: time

  • X0 ({float, numpy.ndarray}) – initial coordinate(s) at the start

  • Y0 ({float, numpy.ndarray}) – initial coordinate(s) at the start

References

[Ha08]

Haza, et al. “Relative dispersion from a high-resolution coastal model of the Adriatic Sea” Ocean Modelling, vol.22(1) pp.48-65, 2008.

Diagnostics.Functions.flock_measures.center_of_mass_displacement(X, Y, X0=None, Y0=None)[source]#

see equation (1) in [La08].

Parameters:

  • X (numpy.ndarray, size=(m,n), unit={degrees,meters}) – m: id, n: time

  • Y (numpy.ndarray, size=(m,n), unit={degrees,meters}) – m: id, n: time

  • X0 ({float, numpy.ndarray}) – initial coordinate(s) at the start

  • Y0 ({float, numpy.ndarray}) – initial coordinate(s) at the start

Returns:

M_x,M_y – displacement of the center of mass over time for the different axis

Return type:

np.ndarray, size=(n,), unit={degrees,meters}

See also

center_of_mass_spread

References

[La08]

LaCasce, “Statistics from Lagrangian observations”, Progress in Oceanography, vol.77(1) pp.1-29, 2008.

Diagnostics.Functions.flock_measures.center_of_mass_spread(X, Y, X0=None, Y0=None, M_x=None, M_y=None)[source]#

see equation (2) in [La08].

Parameters:

  • X (numpy.ndarray, size=(m,n), unit={degrees,meters}) – m: id, n: time

  • Y (numpy.ndarray, size=(m,n), unit={degrees,meters}) – m: id, n: time

  • X0 ({float, numpy.ndarray}) – initial coordinate(s) at the start

  • Y0 ({float, numpy.ndarray}) – initial coordinate(s) at the start

  • Mx (numpy.ndarray, size=(n,)) – first moment of the flock

  • My (numpy.ndarray, size=(n,)) – first moment of the flock

Returns:

D_x,D_y – spread of the center of mass over time for the different spatial axis

Return type:

numpy.ndarray, size=(n,), unit={degrees,meters}

See also

center_of_mass_displacement

References

[La08]

LaCasce, “Statistics from Lagrangian observations”, Progress in Oceanography, vol.77(1) pp.1-29, 2008.

Diagnostics.Functions.flock_measures.cumulative_incremental_trajectory_error(X, Y, dX=None, dY=None, X_ref=None, Y_ref=None, leader_id=None, spherical=True)[source]#

see equation (3) in [Ri06].

References

[Ri06]

Riddle, et al. “Trajectory model validation using newly developed altitude-controlled balloons during the international consortium for atmospheric research on transport and transformations 2004 campaign” Journal of geophysical research - atmospheres vol.111 pp.D23, 2006.

Diagnostics.Functions.flock_measures.frechet_dist(X, Y, spherical=True)[source]#

Fréchet distance, typically it is defined for polygons or polylines. The distance is typically explained as a “dog on a leash” measure. Where, the geometry is traverse, and the longest separation distance is taken. However, in this case the data is ordered along time, see also [LN13]. Hence, here the separation distance at each time step is analysed and the maximum distance is kept.

Parameters:

  • X (np.ndarray, size=(m,n), unit={degrees,meters}) – m: id, n: time

  • Y (np.ndarray, size=(m,n), unit={degrees,meters}) – m: id, n: time

Returns:

maximum separation distance for each time step

Return type:

np.ndarray, size=(n,), unit=meters

References

[LN13]

Long & Nelson, “A review of quantitative methods for movement data” International journal of geographic information science, vol.23(2) pp.292-318, 2013.

Diagnostics.Functions.flock_measures.mean_cumulative_separation_distance(X, Y, X_ref=None, Y_ref=None, leader_id=None, spherical=True)[source]#

see equation (5) in [Mh20].

Parameters:

  • X (numpy.ndarray, size=(m,n), unit={degrees,meters}) – trajectery stack with m: id, n: time

  • Y (numpy.ndarray, size=(m,n), unit={degrees,meters}) – trajectery stack with m: id, n: time

  • X_ref (numpy.ndarray, size=(n,)) – reference or leader trajectory

  • Y_ref (numpy.ndarray, size=(n,)) – reference or leader trajectory

  • leader_id (integer, range=0...m) – index of the leader within the trajectery stack {X,Y}

  • spherical (bool) – when True, then spherical coordinates are given otherwise metric plane coordinates are assumed

Returns:

spatial-temporal mean of the separation within the flock

Return type:

float, unit=meters

References

[Mh20]

van der Mheen, et al. “Depth-dependent correction for wind-driven drift current in particle tracking applications.” Frontiers in marine science vol.7 pp.305, 2020.

Diagnostics.Functions.flock_measures.mediod(X, Y, spherical=False, robust=True)[source]#

calculate which trajectory with least disagreement with all others

Parameters:

  • X (np.ndarray, size=(m,n), unit={degrees,meters}) – m: individual entity, n: time

  • Y (np.ndarray, size=(m,n), unit={degrees,meters}) – m: individual entity, n: time

  • spherical (bool) – when True, then spherical coordinates are given otherwise metric plane coordinates are assumed

  • robust (bool) – when True, robust statistics are used in the form of the median otherwise the mean is used instead

Returns:

index of the trajectory with the least sepration distance between all other trajectories

Return type:

integer, range=0…m

Diagnostics.Functions.flock_measures.normalized_cumulative_lagrangian_separation(X, Y, X_ref=None, Y_ref=None, leader_id=None, spherical=True)[source]#

eq. (3) in [LW11]

Parameters:

  • X (numpy.ndarray, size=(m,n), unit={degrees,meters}) – trajectery stack with m: id, n: time

  • Y (numpy.ndarray, size=(m,n), unit={degrees,meters}) – trajectery stack with m: id, n: time

  • X_ref (numpy.ndarray, size=(n,)) – reference or leader trajectory

  • Y_ref (numpy.ndarray, size=(n,)) – reference or leader trajectory

  • leader_id (integer, range=0...m) – index of the leader within the trajectery stack {X,Y}

  • spherical (bool) – when True, then spherical coordinates are given otherwise metric plane coordinates are assumed

Returns:

skill score for the different tracks in respect to the leader/reference

Return type:

numpy.ndarray, size=(m,), unit=meters

References

[LW11]

Liu & Weisberg, “Evaluation of trajectory modeling in different dynamic regions using normalized cumulative Lagrangian separation” Journal of geophysical research, vol.116 pp.C09013, 2011.

Diagnostics.Functions.flock_measures.relative_dispersion(X, Y, X_ref=None, Y_ref=None, leader_id=None, spherical=True)[source]#

see equation (3) in [Ha08], also known as, the absolute horizontal transport deviation (AHTD) [Ku85] in atmospheric sciences.

Parameters:

  • X (numpy.ndarray, size=(m,n), unit={degrees,meters}) – trajectery stack with m: id, n: time

  • Y (numpy.ndarray, size=(m,n), unit={degrees,meters}) – trajectery stack with m: id, n: time

  • X_ref (numpy.ndarray, size=(n,)) – reference or leader trajectory

  • Y_ref (numpy.ndarray, size=(n,)) – reference or leader trajectory

  • leader_id (integer, range=0...m) – index of the leader within the trajectery stack {X,Y}

  • spherical (bool) – when True, then spherical coordinates are given otherwise metric plane coordinates are assumed

Returns:

temporal evolution of the relative dispersion

Return type:

numpy.ndarray, size=(n,), unit=meters

References

[Ha08]

Haza, et al. “Relative dispersion from a high-resolution coastal model of the Adriatic Sea” Ocean Modelling, vol.22(1) pp.48-65, 2008.

[Ku85]

Kuo, et al. “The accuracy of trajectory models as revealed by the observing system simulation experiments” Monthly weather review, vol.113 pp.1852—1867, 1985.

Diagnostics.Functions.flock_measures.relative_horizontal_transport_deviation(X, Y, X_ref=None, Y_ref=None, leader_id=None, spherical=True)[source]#

see also [SW85]

Parameters:

  • X (numpy.ndarray, size=(m,n), unit={degrees,meters}) – trajectery stack with m: id, n: time

  • Y (numpy.ndarray, size=(m,n), unit={degrees,meters}) – trajectery stack with m: id, n: time

  • X_ref (numpy.ndarray, size=(n,)) – reference or leader trajectory

  • Y_ref (numpy.ndarray, size=(n,)) – reference or leader trajectory

  • leader_id (integer, range=0...m) – index of the leader within the trajectery stack {X,Y}

  • spherical (bool) – when True, then spherical coordinates are given otherwise metric plane coordinates are assumed

Returns:

temporal evolution of the relative dispersion

Return type:

numpy.ndarray, size=(n,), unit=meters

References

[SW85]

Stohl & Wotawa, “A method for computing single trajectories representing boundary layer transport” Atmospheric environment, vol.29 pp.3235—3239, 1995.

mapping functions#

Diagnostics.Functions.mapping_functions.Haversine_displacement(inlon1, inlon2, inlat1, inlat2)[source]#

_summary_

Parameters:

  • inlon1 (_type_) – _description_

  • inlon2 (_type_) – _description_

  • inlat1 (_type_) – _description_

  • inlat2 (_type_) – _description_

Returns:

_description_

Return type:

_type_

Diagnostics.Functions.mapping_functions.dist_meter(lon_1, lon_2, lat_1, lat_2, radius=None)[source]#

calculate the distance between two locations

Diagnostics.Functions.mapping_functions.haversine(Δlat, Δlon, lat, radius=None)[source]#

calculate the distance along a great-circle

Parameters:

  • Δlat (float, unit=degrees) – step size or angle difference

  • Δlon (float, unit=degrees) – step size or angle difference

  • lat (float, unit=degrees) – (mean) latitude where angles are situated

  • radius (float, unit=meters) – estimate of the radius of the earth

Returns:

distance

Return type:

float, unit=meters