Last updated on May 12, 2026.

netsse.tools.misc_func#

Miscellaneous functions for NetSSE.

Copyright (C) 2023-2026 Technical University of Denmark, R.E.G. Mounet

This code is part of the NetSSE software.

NetSSE is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

NetSSE is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

To credit the author, users are encouraged to use below reference:

Mounet, R. E. G., & Nielsen, U. D. NetSSE: An open-source Python package
for network-based sea state estimation from ships, buoys, and other
observation platforms (version 2.2). Technical University of Denmark,
GitLab. February 2026. https://doi.org/10.11583/DTU.26379811.

Last updated on 20-02-2026 by R.E.G. Mounet

Functions#

ang_diff(alpha, beta[, unit])

Calculates the signed difference between two angles.

ang_interp(x, alpha, xq[, axis, unit, datetime])

Interpolates angular data.

ang_mean(angles[, unit])

Calculates the mean angle from an array of angular data.

ang_std(angles[, unit])

Calculates the circular standard deviation of an array of

areSame_mat(A, B)

Checks whether two matrices are identical, element-wise.

areSame_vec(a, b)

Checks whether two vectors are identical, element-wise.

find_nearest_gridpoint(lat_wps, lon_wps, lat_grid, ...)

Finds the nearest neighbours to a series of waypoints within a grid

id_generator([size, chars])

Randomly generates a cryptographically secure string of a given size.

knots2ms(U_kn)

Converts a speed from knots to meters per second.

ms2knots(U_ms)

Converts a speed from meters per second to knots.

pad(U[, axis, add])

Adds zeros to an array along one of its dimensions.

re_range(theta[, start, unit])

Converts angles to a new range (of extent 360 degrees).

weighted_quantile(x, q, w[, a, b, axis])

Computes the q-th quantiles of weighted data.

weighted_std(a, w[, axis, ddof])

Computes the weighted standard deviation of some data.

wrap(U[, axis, add])

Wraps an array around one of its dimensions.

Module Contents#

netsse.tools.misc_func.ang_diff(alpha, beta, unit='deg')[source]#

Calculates the signed difference between two angles.

Parameters:

  • alpha (float or array_like) – Input angle as a scalar value or as an array of angles.

  • beta (float or array_like) – Input angle as a scalar value or as an array of angles.

  • unit ({'deg','rad'}, optional) – Specifies the unit of the angles as 'rad' or 'deg'. The default is 'deg'.

Returns:

delta – The output difference between alpha and beta in the range [-180,180] degrees.

Note

This function subtracts alpha from beta, i.e., computes the signed difference beta-alpha, taking into account the circularity at 360 degrees.

Return type:

float or array_like

See also

re_range

Converts angles to a new range of values.

ang_mean

Calculates the mean angle from an array of angular data.

ang_std

Calculates the circular standard deviation for an array of angular data.

Example

>>> delta = ang_diff(alpha, beta, unit='deg')
netsse.tools.misc_func.ang_interp(x, alpha, xq, axis=0, unit='deg', datetime=False)[source]#

Interpolates angular data.

This function properly handles the circularity of angles at 360 degrees.

Parameters:

  • x (array_like) – Array of independent variable where the angles alpha are defined.

  • alpha (array_like) – Array of angles to be interpolated.

  • xq (array_like) – Array of independent variable where the angles alpha must be interpolated.

  • axis ({0,1}, optional) – If alpha is a 2d-array, the axis of alpha along which to interpolate. The default is 0.

  • unit ({'deg','rad'}, optional) – Specifies the unit of the angles as 'rad' or 'deg'. The default is 'deg'.

  • datetime (bool, default False) – If True, then x and xq are assumed to be arrays of datetime objects.

Returns:

alpha_q – Interpolated angles at xq.

Return type:

array_like

See also

ang_diff

Calculates the signed difference between two angles.

ang_mean

Calculates the mean angle from an array of angular data.

ang_std

Calculates the circular standard deviation for an array of angular data.

Example

>>> alpha_q = ang_interp(x,alpha,xq,axis=0,unit='deg')
netsse.tools.misc_func.ang_mean(angles, unit='deg')[source]#

Calculates the mean angle from an array of angular data.

This function properly handles the circularity of angles at 360 degrees.

Parameters:

  • angles (array_like) – Array of angles.

  • unit ({'deg','rad'}, optional) – Specifies the unit of the angles as 'rad' or 'deg'. The default is 'deg'.

Returns:

mean_a – Mean angle in the range [-180,180) degrees.

Return type:

float

See also

ang_diff

Calculates the signed difference between two angles.

ang_std

Calculates the circular standard deviation of an array of angular data.

Example

>>> mean_angle = ang_mean(angles, unit='deg')
netsse.tools.misc_func.ang_std(angles, unit='deg')[source]#

Calculates the circular standard deviation of an array of angular data.

This function properly handles the circularity of angles at 360 degrees. The standard “two-pass” computation is implemented.

Parameters:

  • angles (array_like) – Array of angles.

  • unit ({'deg','rad'}, optional) – Specifies the unit of the angles as 'rad' or 'deg'. The default is 'deg'.

Returns:

std_a – Circular standard deviation.

Return type:

float

See also

ang_diff

Calculates the signed difference between two angles.

ang_mean

Calculates the mean angle from an array of angular data.

Example

>>> std_angle = ang_std(angles, unit='deg')
netsse.tools.misc_func.areSame_mat(A, B)[source]#

Checks whether two matrices are identical, element-wise.

Parameters:

  • A (2d-array) – Input matrix.

  • B (2d-array) – Input matrix.

Returns:

False for A!=B, True for A=B.

Return type:

bool

Note

If A and B do not have the same shape, then False is returned.

See also

areSame_vec

Checks whether two vectors are identical, element-wise.

Example

>>> areSame_mat(A,B)
netsse.tools.misc_func.areSame_vec(a, b)[source]#

Checks whether two vectors are identical, element-wise.

Parameters:

  • a (1d-array) – Input vector.

  • b (1d-array) – Input vector.

Returns:

False for a!=b, True for a=b.

Return type:

bool

Note

If a and b do not have the same shape, then False is returned.

See also

areSame_mat

Checks whether two matrices are identical, element-wise.

Example

>>> areSame_vec(a,b)
netsse.tools.misc_func.find_nearest_gridpoint(lat_wps, lon_wps, lat_grid, lon_grid, interv=0.01)[source]#

Finds the nearest neighbours to a series of waypoints within a grid of points.

Note

The grid points do not need to be uniformly spaced in any direction. The grid can also have been rotated of any angle about the vertical direction (e.g., to be aligned with some shoreline).

For a given waypoint at (lat_wp,lon_wp), the nearest-neighbour candidates are first selected within the gridpoints that fall in the geographical area delimited by lat_wp*[1-interv,1+interv] in latitude and lon_wp*[1-interv,1+interv] in longitude. Then, the distance between the waypoint and the nearest-neighbour candidates is computed. The output neighbour is found as the candidate that minimises this distance.

Parameters:

  • lat_wps (float, or 1d-array of shape (Nwp,)) – Vector of waypoint latitudes [deg].

  • lon_wps (float, or 1d-array of shape (Nwp,)) – Vector of waypoint longitudes [deg].

  • lat_grid (2d-array) – Matrix defining the latitudes of the grid points [deg].

  • lon_grid (2d-array) – Matrix defining the longitudes of the grid points [deg].

  • interv (float, default 0.01) – Half-width [-] of the interval band fraction in latitude and longitude, used for screening the potential nearest-neighbour candidates.

Returns:

  • index_nearest (numpy.array of shape (Nwp,2)) – The coordinates in (latitude,longitude) of the nearest gridpoints to the waypoints [deg].

  • dist_nearest (numpy.array of shape (Nwp,)) – The distance between the nearest gridpoints and the waypoints [km].

Example

>>> index_nearest, dist_nearest =
...     find_nearest_gridpoint(lat_wps, lon_wps, lat_grid, lon_grid, interv=0.01)
netsse.tools.misc_func.id_generator(size=6, chars=string.ascii_uppercase + string.digits)[source]#

Randomly generates a cryptographically secure string of a given size.

Parameters:

  • size (int, default 6) – String size

  • chars (str, default 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789') – List of allowed characters

Returns:

Output random string

Return type:

str

Example

>>> id_generator(size=6, chars=string.ascii_uppercase+string.digits)
netsse.tools.misc_func.knots2ms(U_kn)[source]#

Converts a speed from knots to meters per second.

Parameters:

U_kn (float or array_like) – Speed in knots [kn].

Returns:

U_ms – Speed in meters per second [m/s].

Return type:

float or array_like

See also

ms2knots

Converts a speed from meters per second to knots.

Example

>>> U_ms = knots2ms(U_kn)
netsse.tools.misc_func.ms2knots(U_ms)[source]#

Converts a speed from meters per second to knots.

Parameters:

U_ms (float or array_like) – Speed in meters per second [m/s].

Returns:

U_kn – Speed in knots [kn].

Return type:

float or array_like

See also

knots2ms

Converts a speed from knots to meters per second.

Example

>>> U_kn = ms2knots(U_ms)
netsse.tools.misc_func.pad(U, axis=1, add=0)[source]#

Adds zeros to an array along one of its dimensions.

Parameters:

  • U (array_like of shape (n,m) or (n,)) – Input array to be padded with zeros at the beginning.

  • axis ({1,0}, optional) – If U is a 2d-array, the axis of U along which to pad. The default is 1.

  • add (float or array_like, default 0) – Term that is added to the concatenated zeros.

Returns:

U_pad – Extended array, where U has been padded with a first column (respectively, row) of zeros (plus an optional added term).

Note

  • If U is a 2d-array, then the output array U_pad has a new shape of (n+1*(axis==0),m+1*(axis==1)).

  • If U is a 1d-array, then the output array U_pad has a new shape of (n+1,). A zero element has been added at the beginning.

Return type:

array_like

See also

wrap

Wraps an array around one of its dimensions.

Example

>>> U_wrap = pad(U,axis=1,add=0)
netsse.tools.misc_func.re_range(theta, start=0, unit='deg')[source]#

Converts angles to a new range (of extent 360 degrees).

Parameters:

  • theta (array_like) – Array of angles to be rearranged.

  • start (float, default 0) – Lower boundary of the range that should contain the new values of theta. The upper boundary will be set automatically to start + 360 degrees.

  • unit ({'deg','rad'}, optional) – Specifies the unit of theta and start as 'rad' or 'deg'. The default is 'deg'.

Returns:

theta_rerange – Array of angles where the elements of theta have been converted to the new range [start, start+360) degrees.

Return type:

array_like

See also

ang_diff

Calculates the signed difference between two angles.

Example

>>> theta_rerange = re_range(theta,start=0,unit='deg')
netsse.tools.misc_func.weighted_quantile(x, q, w, a=0.5, b=0.5, axis=-1)[source]#

Computes the q-th quantiles of weighted data.

The quantiles are computed along one of the axes of the input array x.

Parameters:

  • x (array_like) – Input data array for which the quantiles must be computed.

  • q (1d-array of shape (Nq,)) – Sequence of quantiles to compute, which must be between 0 and 1.

  • w (array_like) – Array of weights. The arrays x and w must be broadcastable.

  • a (floats, default 0.5) – User-defined constant used in the computation of the quantiles. The default is 0.5 to minimize biases (Rogers, 2003).

  • b (floats, default 0.5) – User-defined constant used in the computation of the quantiles. The default is 0.5 to minimize biases (Rogers, 2003).

  • axis (integer, default -1) – Axis of x along which the q-quantiles are computed.

Returns:

v – Values of the q-quantiles computed along the specified axis of the input array x with weights w.

Return type:

array_like

See also

weighted_std

Computes the weighted standard deviation of some data.

References

Rogers, J.W., 2003. Estimating the variance of percentiles using replicate weights, in: Proc. of the Joint Statistical Meetings, Survey Research Methods Section, American Statistical Association. pp. 3525–3532. URL: http://www.asasrms.org/Proceedings/y2003/Files/JSM2003-000742.pdf

Example

>>> v = weighted_quantile(x, q, w, a=0.5, b=0.5, axis=-1)
netsse.tools.misc_func.weighted_std(a, w, axis=None, ddof=1)[source]#

Computes the weighted standard deviation of some data.

The weighted standard deviation is a measure of the spread of a distribution of the array elements from the mean, where some of the elements are more significant than others. The weighted standard deviation is calculated based on the weighted mean and it attaches more importance to data that have more weight than to data with less weight (National Institute of Standards and Technology, 1996).

Parameters:

  • a (array_like) – Variable for which the weighted std. must be computed.

  • w (array_like) – Array of weights. All elements must be positive. The array w must broadcastable with the array a.

  • axis (None or int, optional) – Axis or axes along which the standard deviation is computed. The default is to compute the weighted standard deviation of the flattened array.

  • ddof (int, default 0) – Delta Degrees of Freedom. The divisor used in the calculations is (N_nz - ddof)/N_nz, where N_nz represents the number of non-zero weights.

Returns:

std – Weighted standard deviation of the data.

Return type:

array_like

See also

weighted_quantile

Computes the q-th quantiles of weighted data.

References

National Institute of Standards and Technology, 1996. Formula for the weighted standard deviation. Available at: https://www.itl.nist.gov/div898/software/dataplot/refman2/ch2/weightsd.pdf (Consulted on 06-08-2023).

Example

>>> std = weighted_std(a,w,axis=None,ddof=1)
netsse.tools.misc_func.wrap(U, axis=1, add=0)[source]#

Wraps an array around one of its dimensions.

Parameters:

  • U (array_like of shape (n,m) or (n,)) – Input array to be wrapped around.

  • axis ({1,0}, optional) – If U is a 2d-array, the axis of U along which to wrap. The default is 1.

  • add (float or array_like, default 0) – Term that is added to the repeated part of U before concatenation.

Returns:

U_wrap – Extended array, where the first column (respectively, row) of U has been repeated by concatenation at the end of U.

Note

  • If U is a 2d-array, then the output array has a shape of (n+1*(axis==0),m+1*(axis==1)).

  • If U is a 1d-array, then the output array has a shape of (n+1,). The first element of U has been repeated at the end.

Return type:

array_like

See also

pad

Adds zeros to an array along one of its dimensions.

Example

>>> U_wrap = wrap(U,axis=1,add=0)