Utils Module

The utils module contains the essential utility functions for data conversion, statistical analysis, caching, and event detection for the MHKiT library.

Note

The names of the functions below are of the convention path.path.function. Only the function name is used when calling the function in MATLAB. For example, to call on mhkit.wave.io.read_NDBC_file simply use read_NDBC_file.

Functions	Description
`get_statistics`	Calculate mean, max, min and stdev statistics of continuous data for a given statistical window.
`excel_to_datetime`	Convert Excel datenum format to Python datetime.
`magnitude_phase`	Calculates magnitude and phase in two or three dimensions of the supplied vector.
`bplot`	This function will create a nice boxplot from a set of data.
`cached_webread`	Perform webread with caching to avoid redundant downloads.
`check_name`	Check if a given string is a valid field name for MATLAB struct.
`convert_numeric_dataframe_to_struct`	Converts a numeric pandas DataFrame to a MATLAB struct.
`convert_numeric_struct_to_dataframe`	Converts a MATLAB struct to a numeric pandas DataFrame.
`nc_file_precheck`	Check NetCDF filename before working on it
`nc_get_var_info`	Append NetCDF variable data and info to an existing structure (res).
`read_nc_file`	Read NetCDF data into a MATLAB struct().
`read_nc_file_group`	Read NetCDF data into a MATLAB struct().
`read_nc_file_var`	Read NetCDF data structure.
`reloadPy`	Reloads Python for use after Python code change.
`toggleToolbox`	Utility to enable/disable MATLAB toolboxes.
`uninstall_all_toolboxes`	Uninstall all currently installed toolboxes

mhkit.utils.excel_to_datetime(excel_num)

Convert excel datenum format to datetime

Parameters:: excel_num (vector) – vector of excel datenums to be converted
Returns:: time (DateTimeIndex) – vector of corresponding python datetime values

mhkit.utils.blues_colormap(m): Colormap similar to matplotlib blues

mhkit.utils.convert_numeric_dataframe_to_struct(df)

Converts a numeric pandas DataFrame to a MATLAB struct.

Parameters:: df (DataFrame) – A numeric pandas DataFrame.
Returns:: result_struct (struct) – A MATLAB struct containing the data from the DataFrame.

mhkit.utils.read_nc_file_group(fname, varargin)

Read NetCDF data into a MATLAB struct().

Parameters:

filename (string) – Filename of NetCDF file to read.
vnms (cell array of characters (optional)) –
Variable names to read. Read all variables if vnms not given. Otherwise, read specified variables by calling read_nc_file_var(fname,vnms,opt_out=0), which returns a structure (ds) with fields ds.(vname) as described below. If the variable is in a group, make sure to include group name, i.e., {‘GROUP_NAME1/VAR_NAME1’,

’GROUP_NAME2/SUBGROUP_NAME2/VAR_NAME2’,…}
extracted (Note 1. Variables in root group ('/') can be) – directly by ‘VARNAME’.
variable (Note 2. To find the group info of a) – the provided user manual of the corresponding NetCDF data product, one can use ncdisp(filename) in MATLAB which shows variable info for all groups and subgroups.
reading (other than) – the provided user manual of the corresponding NetCDF data product, one can use ncdisp(filename) in MATLAB which shows variable info for all groups and subgroups.
be (An example ncdisp(filename.nc) output can)
... –
/GrpName/SubGrpName/ Variables:

… VAR_I_Need

Size: … Dimensions: … …
filename.nc (To get VAR_I_Need from) –

ds = read_nc_file_group(‘filename.nc’,…
{‘/GrpName/SubGrpName/VAR_I_Need’});
as (one can run this function) –

ds = read_nc_file_group(‘filename.nc’,…
{‘/GrpName/SubGrpName/VAR_I_Need’});
Group (Note 3. If needs to read all variables within a) – ginfo = ncinfo(‘filename.nc’,’/GrpName/SubGrpName/’); vnms = {ginfo.Variables.Name}; vnms = strcat(‘GrpName/SubGrpName/’,vnms); ds = read_nc_file_group(‘filename.nc’,vnms);
ncinfo() (one can use) – ginfo = ncinfo(‘filename.nc’,’/GrpName/SubGrpName/’); vnms = {ginfo.Variables.Name}; vnms = strcat(‘GrpName/SubGrpName/’,vnms); ds = read_nc_file_group(‘filename.nc’,vnms);

Returns:

ds (struct)

If vnms not specified, ds has fields:
groups: struct that contains names of child groups as fields LongName: path to current group Attributes: Attributes of current group Variables: struct that contains each variable as a struct and

a list of all variables within this group. e.g., Variables.(varname1), Variables.(varname2), …

Variables.(varname) includes fields:
Name: full name of the variable Data: metadata Dims: dimension names FillValue: V.FillValue or V.Attributes{‘_FillValue’} if

the former is not given.

Attrs: V.Attributes except for V.Attributes{‘_FillValue’}
If vnms specified, ds has fields: ds.(varname).
Each ds.(varname) contains fields same as Variables.(varname) described above.

precheck:

mhkit.utils.cmocean(ColormapName, varargin)

cmocean returns perceptually-uniform colormaps created by Kristen Thyng.

Syntax

cmocean cmap = cmocean(‘ColormapName’) cmap = cmocean(‘-ColormapName’) cmap = cmocean(…,NLevels) cmap = cmocean(…,’pivot’,PivotValue) cmap = cmocean(…,’negative’) cmocean(…)

Description

cmocean without any inputs displays the options for colormaps.

cmap = cmocean(‘ColormapName’) returns a 256x3 colormap. ColormapName can be any of of the following:

SEQUENTIAL: DIVERGING: ‘thermal’ ‘balance’ ‘haline’ ‘delta’ ‘solar’ ‘curl’ ‘ice’ ‘diff’ ‘gray’ ‘tarn’ ‘oxy’ ‘deep’ CONSTANT LIGHTNESS: ‘dense’ ‘phase’ ‘algae’ ‘matter’ OTHER: ‘turbid’ ‘topo’ ‘speed’ ‘amp’ ‘tempo’ ‘rain’

cmap = cmocean(‘-ColormapName’) a minus sign preceeding any ColormapName flips the order of the colormap.

cmap = cmocean(…,NLevels) specifies a number of levels in the colormap. Default value is 256.

cmap = cmocean(…,’pivot’,PivotValue) centers a diverging colormap such that white corresponds to a given value and maximum extents are set using current caxis limits. If no PivotValue is set, 0 is assumed. Early versions of this function used ‘zero’ as the syntax for ‘pivot’,0 and the old syntax is still supported.

cmap = cmocean(…,’negative’) inverts the lightness profile of the colormap. This can be useful particularly for divergent colormaps if the default white point of divergence gets lost in a white background.

cmocean(…) without any outputs sets the current colormap to the current axes.

Examples Using this sample plot:

imagesc(peaks(1000)+1) colorbar

Set the colormap to ‘algae’:

cmocean(‘algae’)

Same as above, but with an inverted algae colormap:

cmocean(‘-algae’)

Set the colormap to a 12-level ‘solar’:

cmocean(‘solar’,12)

Get the RGB values of a 5-level thermal colormap:

RGB = cmocean(‘thermal’,5)

Some of those values are below zero and others are above. If this dataset represents anomalies, perhaps a diverging colormap is more appropriate:

cmocean(‘balance’)

It’s unlikely that 1.7776 is an interesting value about which the data values diverge. If you want to center the colormap on zero using the current color axis limits, simply include the ‘pivot’ option:

cmocean(‘balance’,’pivot’,0)

Author Info This function was written by Chad A. Greene of the Institute for Geophysics at the University of Texas at Austin (UTIG), June 2016, using colormaps created by Kristen Thyng of Texas A&M University, Department of Oceanography. More information on the cmocean project can be found at http://matplotlib.org/cmocean/.

Citing this colormap: If you find an occasion to cite these colormaps for any reason, or if you just want some nice beach reading, check out the following paper from the journal Oceanography:

Thyng, K.M., C.A. Greene, R.D. Hetland, H.M. Zimmerle, and S.F. DiMarco. 2016. True colors of oceanography: Guidelines for effective and accurate colormap selection. Oceanography 29(3):9?13, http://dx.doi.org/10.5670/oceanog.2016.66.

Utils Module

Initialize