Utils Module

The utils module includes helper functions. The module currently contains a single function to help users convert numeric indexes to datetime indexes. Additional helper functions could be added at a later date.

get_statistics	Calculate mean, max, min and stdev statistics of continuous data for a given statistical window.
unwrap_vector	Function used to unwrap vectors into 0-360 deg range
matlab_to_datetime	Convert MATLAB datenum format to Python datetime
excel_to_datetime	Convert Excel datenum format to Python datetime
index_to_datetime	Convert DataFrame index from int/float to datetime, rounds datetime to the nearest millisecond

mhkit.utils.get_statistics(data, freq, period=600, vector_channels=[])

Calculate mean, max, min and stdev statistics of continuous data for a given statistical window. Default length of statistical window (period) is based on IEC TS 62600-3:2020 ED1. Also allows calculation of statistics for multiple statistical windows of continuous data and accounts for vector/directional channels.

Parameters

• data (pandas DataFrame) – Data indexed by datetime with columns of data to be analyzed

• freq (float/int) – Sample rate of data [Hz]

• period (float/int) – Statistical window of interest [sec], default = 600

• vector_channels (string or list (optional)) – List of vector/directional channel names formatted in deg (0-360)

Returns

means,maxs,mins,stdevs (pandas DataFrame) – Calculated statistical values from the data, indexed by the first timestamp

mhkit.utils.vector_statistics(data)

Function used to calculate statistics for vector/directional channels based on routine from Campbell data logger and Yamartino algorithm

Parameters

data (pandas Series, numpy array, list) – Vector channel to calculate statistics on [deg, 0-360]

Returns

• vector_avg (numpy array) – Vector mean statistic

• vector_std (numpy array) – Vector standard deviation statistic

mhkit.utils.unwrap_vector(data)

Function used to unwrap vectors into 0-360 deg range

Parameters

data (pandas Series, numpy array, list) – Data points to be unwrapped [deg]

Returns

data (numpy array) – Data points unwrapped between 0-360 deg

mhkit.utils.matlab_to_datetime(matlab_datenum)

Convert MATLAB datenum format to Python datetime

Parameters

matlab_datenum (numpy array) – MATLAB datenum to be converted

Returns

time (DateTimeIndex) – Python datetime values

mhkit.utils.excel_to_datetime(excel_num)

Convert Excel datenum format to Python datetime

Parameters

excel_num (numpy array) – Excel datenums to be converted

Returns

time (DateTimeIndex) – Python datetime values

mhkit.utils.magnitude_phase(x, y, z=None)

Retuns magnitude and phase in two or three dimensions.

Parameters

• x (array_like) – x-component

• y (array_like) – y-component

• z (array_like) – z-component defined positive up. (Optional) Default None.

Returns

• mag (float or array) – magnitude of the vector

• theta (float or array) – radians from the x-axis

• phi (float or array) – radians from z-axis defined as positive up. Optional: only returned when z is passed.

mhkit.utils.unorm(x, y, z)

Calculates the root mean squared value given three arrays.

Parameters

• x (array) – One input for the root mean squared calculation.(eq. x velocity)

• y (array) – One input for the root mean squared calculation.(eq. y velocity)

• z (array) – One input for the root mean squared calculation.(eq. z velocity)

Returns

unorm (array) – The root mean squared of x, y, and z.

Example

If the inputs are [1,2,3], [4,5,6], and [7,8,9] the code take the cordinationg value from each array and calculates the root mean squared. The resulting output is [ 8.1240384, 9.64365076, 11.22497216].

mhkit.utils.index_to_datetime(index, unit='s', origin='unix')

Convert DataFrame index from int/float to datetime, rounds datetime to the nearest millisecond

Parameters

• index (pandas Index) – DataFrame index in int or float

• unit (str, optional) – Units of the original index

• origin (str) – Reference date used to define the starting time. If origin = ‘unix’, the start time is ‘1970-01-01 00:00:00’ The origin can also be defined using a datetime string in a similar format (i.e. ‘2019-05-17 16:05:45’)

Returns

pandas Index – DataFrame index in datetime