SalishSeaTools API

This section documents the SalishSeaTools API (Application Programming Interface). These API docs provide function signatures and docstrings derived directly from the code modules.

bathy_tools Module

A library of Python functions for viewing and manipulating netCDF bathymetry files.

salishsea_tools.bathy_tools.argmax(depths)[source]

Return the indices of the maximum value in depths.

Parameters:depths (netCDF4.Variable) – netcdf variable object containing the depths
Returns:Indices of the maximum value in depths
Return type:2-tuple
salishsea_tools.bathy_tools.calc_norm_depth_diffs(depths, delta_lat, delta_lon)[source]

Calculate normalized depth differences between each depth and the depth delta_lat and delta_lon grid points away.

Parameters:
  • depths (netCDF4.Variable) – netcdf variable object containing the depths
  • delta_lat (int) – Number of grid point in the latitude direction to calculate the difference over
  • delta_lon (int) – Number of grid point in the longitude direction to calculate the difference over
Returns:

Normalized depth difference field for the bathymetry

Return type:

netCDF4.Variable

salishsea_tools.bathy_tools.choose_steepest_cells(depths)[source]

Choose the grid cells with the greatest normalized depth differences in the latitude and longitude directions.

Parameters:depths (netCDF4.Variable) – netcdf variable object containing the depths
Returns:Normalized depth difference field in the latitude direction, indices of the grid point with the greatest latitude direction difference, normalized depth difference field in the longitude direction, and indices of the grid point with the greatest longitude direction difference.
Return type:4-tuple
salishsea_tools.bathy_tools.min_mid_max(var)[source]

Return the minimum, median, and maximum values of var as a tuple.

Especially useful when applied to latitude and longitude variables.

Parameters:dataset (netCDF4.Variable) – netcdf variable object
salishsea_tools.bathy_tools.plot_colourmesh(dataset, title, fig_size=(9, 9), axis_limits=None, colour_map='winter_r', bins=15, land_colour='#edc9af')[source]

Create a colour-mesh plot of a bathymetry dataset on a longitude/latitude axis.

Parameters:
  • dataset (netCDF4.Dataset) – netcdf dataset object containing the bathymetry
  • title (str) – Title for the plot
  • fig_size (2-tuple) – Size of the figure
  • axis_limits (4-tuple) – Axis limits for the plt (xmin, xmax, ymin, ymax); defaults to those calculated by matplotlib
  • colour_map (str) – matplotlib colour map name
  • bins (int) – Number of level bins for the colour map
  • land_colour (str) – Colour to use for land regions; i.e. those which the depth is undefined in the dataset’s Bathymetry variable masked array
Returns:

Figure object containing the plot

Return type:

matplotlib.figure.Figure

salishsea_tools.bathy_tools.plot_colourmesh_zoom(dataset, centre, half_width=5, fig_size=(9, 9), colour_map='copper_r', bins=15, land_colour='white')[source]

Create a colour-mesh plot of a bathymetry dataset on a grid point axis.

The plot extends half_width grid points in each direction from centre.

Parameters:
  • dataset (netCDF4.Dataset) – netcdf dataset object containing the bathymetry
  • centre (2-tuple) – Grid point to centre the plot at
  • half_width (int) – Number of grid points from centre to the edge of the plot
  • fig_size (2-tuple) – Size of the figure
  • colour_map (str) – matplotlib colour map name
  • bins (int) – Number of level bins for the colour map
  • land_colour (str) – Colour to use for land regions; i.e. those which the depth is undefined in the dataset’s Bathymetry variable masked array
salishsea_tools.bathy_tools.prep_colour_map(depths, limits=None, centre=None, half_width=5, colour_map='copper_r', bins=15)[source]

Returns cmap and norm elements of a colourmap for the netCDF depths variable.

If limits is None (the default) the limits are set to (0, max depth in centre +/- half_width).

Parameters:
  • depths (netCDF4.Variable) – netcdf variable object containing the depths
  • limits (2-tuple) – Minimum and maximum depths for colour map
  • centre (2-tuple) – Grid point to centre the plot at
  • half_width (int) – Number of grid points from centre to the edge of the plot
  • colour_map (str) – matplotlib colour map name
  • bins (int) – Number of level bins for the colour map
salishsea_tools.bathy_tools.set_aspect_ratio(lats)[source]

Set the plot axis aspect ratio based on the median latitude.

Parameters:lats (netCDF4.Variable) – netcdf variable object containing the latitudes
salishsea_tools.bathy_tools.show_dimensions(dataset)[source]

Print the dimensions of the netCDF dataset.

Note

This function is deprecated. Use nc_tools.show_dimensions() instead.

Parameters:dataset (netCDF4.Dataset) – netcdf dataset object
salishsea_tools.bathy_tools.show_global_attrs(dataset)[source]

Print the global attributes of the netCDF dataset.

Note

This function is deprecated. Use nc_tools.show_dataset_attrs() instead.

Parameters:dataset (netCDF4.Dataset) – netcdf dataset object
salishsea_tools.bathy_tools.show_region_depths(depths, centre, half_width=5)[source]

Print the depths for a region extending half_width grid points from centre.

Parameters:
  • depths (netCDF4.Variable) – netcdf variable object containing the depths
  • centre (2-tuple) – Grid point to centre the plot at
  • half_width (int) – Number of grid points from centre to the edge of the plot
salishsea_tools.bathy_tools.show_variables(dataset)[source]

Print the variable names in the netCDF dataset as a list.

Note

This function is deprecated. Use nc_tools.show_variables() instead.

Parameters:dataset (netCDF4.Dataset) – netcdf dataset object
salishsea_tools.bathy_tools.smooth(depths, max_norm_depth_diff=0.8, smooth_factor=0.2)[source]

Smooth the bathymetry by successively adjusting depths that have the greatest normalized difference until all of those differences are below a max_norm_depth_diff.

Parameters:
  • depths (netCDF4.Variable) – netcdf variable object containing the depths
  • max_norm_depth_diff (float) – Threshold normalized depth difference to smooth to.
  • smooth_factor (float) – Fraction of the average depth to change the depths by
Returns:

netcdf variable object containing the depths

Return type:

netCDF4.Variable

salishsea_tools.bathy_tools.smooth_neighbours(smooth_factor, depth1, depth2)[source]

Adjust a pair of depths by smooth_factor times their average.

Parameters:
  • smooth_factor (float) – Fraction of the average depth to change the depths by
  • depth1 (float) – First depth to adjust
  • depth2 (float) – Second depth to adjust
Returns:

Adjusted depths

Return type:

2-tuple

salishsea_tools.bathy_tools.zero_jervis_end(depths)[source]

Set the depths to zero in the area at the end of Jervis Inlet where the Cascadia bathymetry source data are deficient.

Parameters:depths (netCDF4.Variable) – netcdf variable object containing the depths
Returns:netcdf variable object containing the depths
Return type:netCDF4.Variable
salishsea_tools.bathy_tools.zero_toba_region(depths)[source]

Set the depths to zero in the Toba Inlet region where the Cascadia bathymetry source data are deficient.

Parameters:depths (netCDF4.Variable) – netcdf variable object containing the depths
Returns:netcdf variable object containing the depths
Return type:netCDF4.Variable

data_tools Module

Functions for loading and processing observational data

salishsea_tools.data_tools.get_onc_data(endpoint, method, token, retry_args={'wait_exponential_multiplier': 1000, 'wait_exponential_max': 30000}, **query_params)[source]

Request data from one of the Ocean Networks Canada (ONC) web services.

See https://wiki.oceannetworks.ca/display/help/API for documentation of the ONC data web services API. See the ONC-DataWebServices notebook for example of use of the API and of this function.

Parameters:
  • retry_args (dict) – Key/value pair arguments to control how the request is retried should it fail the first time. The defaults provide a 2^x * 1 second exponential back-off between each retry, up to 30 seconds, then 30 seconds afterwards See https://pypi.python.org/pypi/retrying for a full discussion of the parameters available to control retrying.
  • endpoint (str) – ONC web service end-point; e.g. scalardata. See https://wiki.oceannetworks.ca/display/help/API for available web service end-points.
  • method (str) – ONC web service method; e.g. getByStation. See https://wiki.oceannetworks.ca/display/help/API and the pages linked from it for the method available on each of the web service end-points.
  • token (str) – ONC web services API token generated on the Web Services API tab of http://dmas.uvic.ca/Profile
  • query_params (dict) – Query parameters expressed as key/value pairs.
Returns:

Mapping created from the JSON content of the response from the data web service

Return type:

dict

salishsea_tools.data_tools.get_onc_sog_adcp_mat(date, search_info, dest_path, userno)[source]

Download a .mat file of ADCP data for 1 day from an Ocean Networks Canada (ONC) node in the Strait of Georgia.

This function relies on a soon-to-be-deprecated ONC web service. It is based on a Matlab script provided by Marlene Jefferies of ONC. It is primarily intended for use in an automation pipeline that also includes ADCP data processing Matlab scripts developed by Rich Pawlowicz of UBC EOAS.

Parameters:
  • date (str) – Date for which to request the ADCP data.
  • node (str) – Strait of Georgia node for which to request the ONC data; must be a key in salishsea_tools.onc_sog_adcps.deployments (e.g. “Central node”).
  • dest_path (str) – Path at which to store the downloaded .mat file.
  • userno (str) – User number with an ONC dmas.uvic.ca account.
Return type:

str

salishsea_tools.data_tools.get_onc_sog_adcp_search_status(search_hdr_id, userid)[source]

Return a JSON blob containing information about the status of a search for ADCP data from an Ocean Networks Canada (ONC) node in the Strait of Georgia.

Parameters:
  • search_hdr_id (int) – ONC search header id.
  • userid (str) – Email address associated with an ONC dmas.uvic.ca account.

This function relies on a soon-to-be-deprecated ONC web service. It is based on a Matlab script provided by Marlene Jefferies of ONC. It is primarily intended for debugging requests produced by get_onc_sog_adcp_mat().

salishsea_tools.data_tools.interpolate_to_depth(var, var_depths, interp_depths, var_mask=0, var_depth_mask=0)[source]

Calculate the interpolated value of var at interp_depth using linear interpolation.

Parameters:
  • var (numpy.ndarray) – Depth profile of a model variable or data quantity.
  • var_depths (numpy.ndarray) – Depths at which the model variable or data quantity has values.
  • interp_depths (numpy.ndarray or number) – Depth(s) at which to calculate the interpolated value of the model variable or data quantity.
  • var_mask (numpy.ndarray or number) – Mask to use for the model variable or data quantity. For model results it is best to use the a 1D slice of the appropriate mesh mask array; e.g. tmask for tracers. Masking the model variable or data quantity increases the accuracy of the interpolation. If var_mask is not provided the model variable or data quantity is zero-masked.
  • var_depth_mask – Mask to use for the depths. For model results it is best to use the a 1D slice of the appropriate mesh mask array; e.g. tmask for tracers. Masking the depths array increases the accuracy of the interpolation. If var_depth_mask is not provided the depths array is zero-masked.
Returns:

Value(s) of var linearly interpolated to interp_depths.

Return type:

numpy.ndarray or number

salishsea_tools.data_tools.load_ADCP(daterange, station='central', adcp_data_dir='/ocean/dlatorne/MEOPAR/ONC_ADCP/')[source]

Returns the ONC ADCP velocity profiles at a given station over a specified datetime range.

This function uses the nearest neighbor to the specified datetime bounds. ONC ADCP data is returned at approximately 15 and 45 minutes past the hour, so choose datetime bounds accordingly.

Parameters:
  • daterange (list or tuple of str) – start and end datetimes for the requested data range. (ex. [‘yyyy mmm dd HH:MM’, ‘yyyy mmm dd HH:MM’])
  • station (str) – Requested profile location (‘central’, ‘east’, or ‘ddl’)
  • adcp_data_dir (str) – ADCP file storage location
Returns:

xarray.Dataset of zonal u and meridional v velocity with time and depth dimensions.

Return type:

2-D, 2 element xarray.Dataset

salishsea_tools.data_tools.load_drifters(deployments=range(1, 10), filename='driftersPositions.geojson', drifterpath='/ocean/rcostanz/Drifters/data')[source]

Loads drifter coordinates and times from the ODL Drifters Project.

UBC Ocean Dynamics Laboratory Drifters Project http://drifters.eoas.ubc.ca/ Contact Rich Pawlowicz: rich@eos.ubc.ca Contact Romain Costanz: rcostanz@eos.ubc.ca

Parameters:
  • deployments (python iterable of integers) – python iterable containing requested deployment numbers (ex. [1, 2, 5], range(1, 9), etc…)
  • filename (str) – Filename
  • drifterpath (str) – Drifter data storage directory
Returns:

Nested ordered dictionaries of xarray dataset objects.

Return type:

collections.OrderedDict > collections.OrderedDict > xarray.Dataset

salishsea_tools.data_tools.load_nowcast_station_tracers(tracers, stations, months, hours, depth_indices, file_ending='ptrc_T.nc', nowcast_dir='/results/SalishSea/nowcast-green/', save_path=None, verbose=True)[source]

Iterate through nowcast results directory, return tracer data that matches request in pandas dataframe.

Example:

station_phy2 = load_nowcast_station_tracers(
    tracers = ["PHY2"],
    stations = {'BS1': (636, 126),'BS11': (605, 125)},
    months = ['apr'],
    hours = [0,6,12,18],
    depth_indices = range(20),
)

Returns pandas dataframe with this format:

STATION  HOUR      DEPTH      PHY2       DATE  MONTH
0      BS11     0   0.500000  3.903608 2016-04-06      4
1      BS11     0   1.500003  4.114840 2016-04-06      4
2      BS11     0   2.500011  5.080880 2016-04-06      4
3      BS11     0   3.500031  5.082539 2016-04-06      4
4      BS11     0   4.500071  5.076756 2016-04-06      4
5      BS11     0   5.500151  5.030882 2016-04-06      4
6      BS11     0   6.500310  4.975801 2016-04-06      4
salishsea_tools.data_tools.onc_datetime(date_time, timezone='Canada/Pacific')[source]

Return a string representation of a date/time in the particular ISO-8601 extended format required by the Ocean Networks Canada (ONC) data web services API.

Parameters:
  • date_time (str or datetime.datetime or arrow.Arrow) – Date/time to transform into format required by ONC data web services API.
  • timezone (str) – Timezone of date_time.
Returns:

UTC date/time formatted as YYYY-MM-DDTHH:mm:ss.SSSZ

Return type:

str

salishsea_tools.data_tools.onc_json_to_dataset(onc_json, teos=True)[source]

Return an xarray.Dataset object containing the data and metadata obtained from an Ocean Networks Canada (ONC) data web service API request.

Parameters:
  • onc_json (dict) – Data structure returned from an ONC data web service API request. Typically produces by calling the json() method on the Response object produced by calling requests.get().
  • teos (boolean) – Convert salinity data from PSU (Practical Salinity Units) to TEOS-10 reference salinity in g/kg. Defaults to True.
Returns:

Data structure containing data and metadata

Return type:

xarray.Dataset

salishsea_tools.data_tools.request_onc_sog_adcp(date, node, userid)[source]

Request a .mat file of ADCP data for 1 day from an Ocean Networks Canada (ONC) node in the Strait of Georgia.

This function relies on a soon-to-be-deprecated ONC web service. It is based on a Matlab script provided by Marlene Jefferies of ONC. It is primarily intended for use in an automation pipeline that also includes ADCP data processing Matlab scripts developed by Rich Pawlowicz of UBC EOAS.

Parameters:
  • date (str) – Date for which to request the ADCP data.
  • node (str) – Strait of Georgia node for which to request the ONC data; must be a key in salishsea_tools.onc_sog_adcps.deployments (e.g. “Central node”).
  • userid (str) – Email address associated with an ONC dmas.uvic.ca account.
Returns:

Search info data provided by the ONC data service; contains search header id.

Return type:

dict

diagnosis_tools Module

salishsea_tools.diagnosis_tools.pcourantu(files, meshmask)[source]

Given a list of U filenames and a mesh mask, returns an array with the unscaled Courant numbers.

Parameters:
  • files – list of U filenames
  • meshmask (netCDF4.Dataset) – mesh mask
Returns:

Numpy MaskedArray with unscaled Courant numbers.

Return type:

:py:class: numpy.ma.core.MaskedArray

salishsea_tools.diagnosis_tools.pcourantv(files, meshmask)[source]

Given a list of V filenames and a mesh mask, returns an array with the unscaled Courant numbers.

Parameters:
  • files – list of V filenames
  • meshmask (netCDF4.Dataset) – mesh mask
Returns:

Numpy MaskedArray with unscaled Courant numbers.

Return type:

:py:class: numpy.ma.core.MaskedArray

salishsea_tools.diagnosis_tools.pcourantw(files, meshmask)[source]

Given a list of W filenames and a mesh mask, returns an array with the unscaled Courant numbers.

Parameters:
  • files – list of W filenames
  • meshmask (netCDF4.Dataset) – mesh mask
Returns:

Numpy MaskedArray with unscaled Courant numbers.

Return type:

:py:class: numpy.ma.core.MaskedArray

formatting_tools Module

Functions for formatting data output from datasets.

salishsea_tools.formatting_tools.STR_LATEX_MAPPING = {'mmol m-3': 'mmol / $m^{3}$', 'mmol/m3': 'mmol / $m^{3}$', 'm2/s3': 'm$^2$ / s$^3$', 'm/s': 'm/s', 'm2/s': 'm$^2$ / s$', 'g/kg': 'g / kg', 'degrees_east': '$^\\circ$E', 'degC': '$^\\circ$C', 'degrees_north': '$^\\circ$N', 'g kg-1': 'g / kg'}

String to LaTeX notation mapping for units

salishsea_tools.formatting_tools.format_units(units)[source]

Convert unit string to LaTeX notation.

Parameters:units (str) – Unit to convert.
Returns:Units in LaTeX notation.
Return type:str

geo_tools Module

Functions for working with geographical data and model results.

salishsea_tools.geo_tools.distance_along_curve(lons, lats)[source]

Calculate cumulative distance in km between points in lons, lats

Parameters:
Returns:

Cumulative point-by-point distance along track in km.

Return type:

numpy.ndarray

salishsea_tools.geo_tools.find_closest_model_point(lon, lat, model_lons, model_lats, grid='NEMO', land_mask=None, tols={'NEMO': {'tol_lat': 0.00388, 'tol_lon': 0.0104}, 'GEM2.5': {'tol_lat': 0.012, 'tol_lon': 0.016}})[source]

Returns the grid coordinates of the closest model point to a specified lon/lat. If land_mask is provided, returns the closest water point.

Example:

j, i = find_closest_model_point(
           -125.5,49.2,model_lons,model_lats,land_mask=bathy.mask)

where bathy, model_lons and model_lats are returned from salishsea_tools.tidetools.get_bathy_data().

j is the y-index(latitude), i is the x-index(longitude)

Parameters:
  • lon (float) – longitude to find closest grid point to
  • lat (float) – latitude to find closest grid point to
  • model_lons (numpy.ndarray) – specified model longitude grid
  • model_lats (numpy.ndarray) – specified model latitude grid
  • grid (string) – specify which default lon/lat tolerances
  • land_mask (numpy array) – describes which grid coordinates are land
  • tols (dict) – stored default tols for different grid types
Returns:

yind, xind

salishsea_tools.geo_tools.haversine(lon1, lat1, lon2, lat2)[source]

Calculate the great-circle distance in kilometers between two points on a sphere from their longitudes and latitudes.

Reference: http://www.movable-type.co.uk/scripts/latlong.html

Parameters:
Returns:

Great-circle distance between two points in km

Return type:

float or numpy.ndarray

grid_tools Module

Functions for calculating time-dependent scale factors and depth.

Functions developed/tested in this notebook: http://nbviewer.jupyter.org/urls/bitbucket.org/salishsea/analysis-nancy/raw/tip/notebooks/energy_flux/Time-dependent%20depth%20and%20scale%20factors%20-%20development.ipynb

Examples of plotting with output: http://nbviewer.jupyter.org/urls/bitbucket.org/salishsea/analysis-nancy/raw/tip/notebooks/energy_flux/Plotting%20with%20time%20dependent%20depths.ipynb

NKS nsoontie@eos.ubc.ca 08-2016

salishsea_tools.grid_tools.calculate_H(e3t0, tmask)[source]

Calculate the initial water column thickness (H).

Parameters:
  • e3t0 (numpy.ndarray) – initial vertical scale factors on T-grid. Dimensions: (depth, y, x).
  • tmask (numpy.ndarray) – T-grid mask. Dimensions: (depth, y, x)
Returns:

the initial water column thickness. Dimensions: (y, x)

salishsea_tools.grid_tools.calculate_adjustment_factor(H, ssh)[source]

Calculate the time-dependent adjustment factor for variable volume in NEMO. adj = (1+ssh/H) and e3t_t = e3t_0*adj

Parameters:
  • H (numpy.array) – Water column thickness. Dimension: (y, x)
  • ssh (numpy.ndarray) – the model sea surface height. Dimensions: (time, y, x)
Returns:

the adjustment factor with dimensions (time, y, x)

salishsea_tools.grid_tools.calculate_time_dependent_grid(e3t0, tmask, ssh, input_vars)[source]

Calculate the time dependent vertical grids and scale factors for variable volume in NEMO.

Parameters:
  • e3t0 (numpy.ndarray) – initial vertical scale factors on T-grid. Dimensions: (depth, y, x).
  • tmask (numpy.ndarray) – T-grid mask. Dimensions: (depth, y, x)
  • ssh (numpy.ndarray) – the model sea surface height. Dimensions: (time, y, x)
  • input_vars – A dictionary of the initial grids/scale factors to be translated into time_dependent. Example keys can be ‘e3t_0’, ‘gdept_0’, ‘e3w_0’, ‘gdepw_0’. A dictionary with corresponding time-dependent grids is returned, where the keys are now ‘e3t_t’, ‘gdept_t’, ‘e3w_0’, ‘gdepw_0’.
Typ input_vars:

dictionary

Returns:

A dictionary containing the desired time dependent vertical scale factors on t and w grids and depths on t and w grids. Dimensions of each: (time, depth, y, x)

salishsea_tools.grid_tools.time_dependent_grid_U(e3u0, e1u, e2u, e1t, e2t, umask, ssh, input_vars, return_ssh=False)[source]

Calculate time-dependent vertical grid spacing and depths on U-grid for variable volume in NEMO.

Parameters:
  • e3u0 (numpy.ndarray) – initial vertical scale factors on U-grid. Dimensions: (depth, y, x).
  • e1u (numpy.ndarray) – x-direction scale factors on U-grid. Dimensions: (y, x).
  • e2u (numpy.ndarray) – y-direction scale factors on U-grid. Dimensions: (y, x).
  • e1t (numpy.ndarray) – x-direction scale factors on T-grid. Dimensions: (y, x).
  • e2t (numpy.ndarray) – y-direction scale factors on T-grid. Dimensions: (y, x).
  • umask (numpy.ndarray) – U-grid mask. Dimensions: (depth, y, x)
  • ssh (numpy.ndarray) – the model sea surface height on T-grid. Dimensions: (time, y, x)
  • input_vars (dictionary) – A dictionary of the initial grids/scale factors to be translated into time-dependent. Example keys can be ‘e3u_0’, ‘gdepu_0’. A dictionary with corresponding time-dependent grids is returned, where the keys are now ‘e3u_t’, ‘gdepu_t’.
  • return_ssh (boolean) – Specifies whether the ssh interpolated to the U-grid should be returned (ssh_u)
Returns:

A dictionary containing the desired time dependent vertical scale factors on depths on u grid. Dimensions of each: (time, depth, y, x). If returned, ssh_u has dimensions (time, y, x)

salishsea_tools.grid_tools.time_dependent_grid_V(e3v0, e1v, e2v, e1t, e2t, vmask, ssh, input_vars, return_ssh=False)[source]

Calculate time-dependent vertical grid spacing and depths on V-grid for variable volume in NEMO.

Parameters:
  • e3v0 (numpy.ndarray) – initial vertical scale factors on V-grid. Dimensions: (depth, y, x).
  • e1v (numpy.ndarray) – x-direction scale factors on V-grid. Dimensions: (y, x).
  • e2v (numpy.ndarray) – y-direction scale factors on V-grid. Dimensions: (y, x).
  • e1t (numpy.ndarray) – x-direction scale factors on T-grid. Dimensions: (y, x).
  • e2t (numpy.ndarray) – y-direction scale factors on T-grid. Dimensions: (y, x).
  • vmask (numpy.ndarray) – V-grid mask. Dimensions: (depth, y, x)
  • ssh (numpy.ndarray) – the model sea surface height on T-grid. Dimensions: (time, y, x)
  • input_vars (dictionary) – A dictionary of the initial grids/scale factors to be translated into time_dependent. Example keys can be ‘e3v_0’, ‘gdepv_0’. A dictionary with corresponding time-dependent grids is returned, where the keys are now ‘e3v_t’, ‘gdepv_t’.
  • return_ssh (boolean) – Specifies whether the ssh interpolated to the V-grid should be returned (ssh_v)
Returns:

A dictionary containing the desired time dependent vertical scale factors and depths on v grid. Dimensions of each: (time, depth, y, x). If returned, ssh_uvhas dimensions (time, y, x)

salishsea_tools.grid_tools.build_GEM_mask(grid_GEM, grid_NEMO, mask_NEMO)[source]
salishsea_tools.grid_tools.build_matrix(weightsfile, opsfile)[source]

Given a NEMO weights file and an operational surface forcing file, we assemble the weights into a sparse interpolation matrix that interpolates the surface forcing data from the operational grid to the NEMO grid. This function returns the matrix and the NEMO grid shape.

Parameters:
  • weightsfile (str) – Path to NEMO weights file.
  • opsfile (str) – Path to an operational file.
Returns:

Sparse interpolation matrix and NEMO grid shape

Return type:

(csr_matrix, tuple)

salishsea_tools.grid_tools.use_matrix(opsfile, matrix, nemoshape, variable, time)[source]

Given an operational surface forcing file, an interpolation matrix and NEMO grid shape (produced by grid_tools.build_matrix), a variable name and a time index, we return the operational data interpolated onto the NEMO grid.

Parameters:
  • opsfile (str) – Path to operational file to interpolate.
  • matrix (csr_matrix) – Interpolation matrix (from build_matrix)
  • nemoshape (tuple) – NEMO grid shape (from build_matrix)
  • variable (str) – Specified variable in ops file.
  • index (time) – time index in ops file.
Returns:

Operational data interpolated onto the NEMO grid

Return type:

ndarray

gsw_calls Module

salishsea_tools.gsw_calls.generic_gsw_caller(gsw_function_name, input_vars, matlab_gsw_dir='/ocean/rich/home/matlab/gsw3')[source]

A generic function for calling matlab gsw functions. Only works with gsw functions that have a single variable as output.

Parameters:
  • gsw_function_name (str) – The name of the matlab gsw function. e.g. gsw_p_from_z.m
  • input_vars (list of numpy arrays) – A list of the input variables in the same order as expected from the gsw matlab function.
  • matlab_gsw_dir (str) – The directory where the matlab gsw scripts are stored.
Returns:

A numpy array containing the output from call to gsw function.

hg_commands Module

A library of Python functions for working with Mercurial via its command line interface. This is a utility library that is used by other Python packages and modules developed for the Salish Sea MEOPAR project.

salishsea_tools.hg_commands.commit(logfile)[source]

Commit all changes in the repo with the contents of logfile as the commit message.

Parameters:logfile (str) – Name of the file containing the commit message.
salishsea_tools.hg_commands.default_url(repo=None)[source]

Return the result of the hg paths default command.

If repo is given the hg -R repo paths default command is run. The repo argument must be the root directory of a Mercurial repository.

If the hg command fails None is returned.

Parameters:repo (str) – Repository root directory.
Returns:Output of the command or None.
salishsea_tools.hg_commands.heads(repo, revs=['.'])[source]

Return the result of the hg -R repo heads revs command.

Parameters:
  • repo (str) – Repository root directory.
  • revs (list) – Revisions for which to show branch heads. The default . causes the head(s) of the currently checked out branch to be returned.
Returns:

Output of the command.

Return type:

str

salishsea_tools.hg_commands.parents(repo=None, rev=None, file=None, verbose=False)[source]

Return the result of the hg parents command.

If repo is given the hg parents -R repo command is run. The repo argument must be the root directory of a Mercurial repository.

If rev is given the hg parents -r rev command is run. Only one rev may be given.

If file is given the hg parents file command is run. Only one file may be given.

If verbose is True the hg parents -v command is run.

Keyword argument can be used cumulatively; e.g. repo=foo, file=bar will result in the hg parents -R foo bar command being run.

Parameters:
  • repo (str) – Repository root directory.
  • rev – Revision to get the parents of. May be either an integer or a hash string.
  • file (str) – File path and name to get the parents of.
  • verbose (Boolean) – Control verbosity of hg command; default to False meaning to run the command without the -v flag.
Returns:

Output of the command.

Return type:

str

Modules for Working with Live Ocean Model Products

salishsea_tools.LiveOcean_BCs.create_LiveOcean_TS_BCs(start, end, avg_period, file_frequency, nowcast=False, teos_10=True, basename='LO', single_nowcast=False, bc_dir='/results/forcing/LiveOcean/boundary_condtions/', LO_dir='/results/forcing/LiveOcean/downloaded/', NEMO_BC='/data/nsoontie/MEOPAR/NEMO-forcing/open_boundaries/west/SalishSea_west_TEOS10.nc')[source]

Create a series of Live Ocean boundary condition files in date range [start, end] for use in the NEMO model.

Parameters:
  • start (str) – start date in format ‘yyyy-mm-dd’
  • end (str) – end date in format ‘yyyy-mm-dd
  • avg_period (str) – The averaging period for the forcing files. options are ‘1H’ for hourly, ‘1D’ for daily, ‘7D’ for weekly’, ‘1M’ for monthly
  • file_frequency (str) –

    The frequency by which the files will be saved. Options are:

    • ’yearly’ files that contain a year of data and look like *_yYYYY.nc
    • ’monthly’ for files that contain a month of data and look like *_yYYYYmMM.nc
    • ’daily’ for files that contain a day of data and look like *_yYYYYmMMdDD.nc

    where * is the basename.

  • nowcast (boolean) – Specifies that the boundary data is to be generated for the nowcast framework. If true, the files are from a single 72 hour run beginning on start, in which case, the argument end is ignored. If both this and single_nowcst are false, a set of time series files is produced.
  • single_nowcast – Specifies that the boundary data is to be generated for the nowcast framework. If true, the files are from a single tidally averaged value centered at 12 noon on day specified by start, in this case, the argument end is ignored. If both this and nowcast are false, a set of time series files is produced.
  • teos_10 (boolean) – specifies that temperature and salinity are saved in teos-10 variables if true. If false, temperature is Potential Temperature and Salinity is Practical Salinity
  • basename (str) – the base name of the saved files. Eg. basename=’LO’, file_frequency=’daily’ saves files as ‘LO_yYYYYmMMdDD.nc’
  • bc_dir (str) – the directory in which to save the results.
  • LO_dir (str) – the directory in which Live Ocean results are stored.
  • NEMO_BC (str) – path to an example NEMO boundary condition file for loading boundary info.
Returns:

Boundary conditions files that were created.

Return type:

list

salishsea_tools.LiveOcean_BCs.create_LiveOcean_bio_BCs_fromTS(TSfile, strdate=None, TSdir='/results/forcing/LiveOcean/boundary_conditions', outFile='bioLOTS_{:y%Ym%md%d}.nc', outDir='/results/forcing/LiveOcean/boundary_conditions/bio', nFitFilePath='/results/forcing/LiveOcean/boundary_conditions/bio/fits/bioOBCfit_NTS.csv', siFitFilePath='/results/forcing/LiveOcean/boundary_conditions/bio/fits/bioOBCfit_SiTS.csv', nClimFilePath='/results/forcing/LiveOcean/boundary_conditions/bio/fits/nmat.csv', siClimFilePath='/results/forcing/LiveOcean/boundary_conditions/bio/fits/simat.csv', recalcFits=False)[source]

create BC files from LiveOcean-based TS BC files using linear fit of N and Si to T and S

Parameters:
  • TSfile (str) – name of LiveOcean-based TS Bc file
  • strdate (str) – the LiveOcean rundate in format yyyy-mm-dd. If not provided, it will be inferred from TSfile if possible.
  • TSdir (str) – path to directory where TSfile is located
  • outFile (str) – file name or nowcast-style filename template for output file
  • outDir (str) – path where outFile should be created
  • nFitFilePath (str) – path and filename from which to load N to T,S fit coefficients
  • siFitFilePath (str) – path and filename from which to load Si to T,S fit coefficients
  • nClimFilePath (str) – path and filename from which to load N upper water column climatology
  • siClimFilePath (str) – path and filename from which to load Si upper water column climatology
  • recalcFits (Boolean) – if true, recalculate the T,S fits and store them in the paths they would otherwise be loaded from. Constant variable BC file will also be recalculated and overwritten at default path.
Returns:

Filepath of nutrients boundary conditions file that was created

Return type:

str

salishsea_tools.LiveOcean_BCs.create_files_for_nowcast(date, teos_10=True)[source]

Create boundary files from Live Ocean results for use in nowcast, forecast and forecast2.

Parameters:
  • date (str) – the LiveOcean rundate in format yyyy-mm-dd
  • teos_10 (boolean) – specifies that temperature and salinity are saved in teos-10 variables if true. If true, temperature is saved as Conservative Temperature and salinity is Reference Salinity. If false, temperature is saved as Potential Temperature and salinity is Practical Salinity
salishsea_tools.LiveOcean_BCs.fill_NaNs_with_nearest_neighbour(data, lons, lats)[source]

At each depth level and time, fill in NaN values with nearest lateral neighbour. If the entire depth level is NaN, fill with values from level above. The last two dimensions of data are the lateral dimensions. lons.shape and lats.shape = (data.shape[-2], data.shape[-1])

Parameters:
  • data (4D numpy array) – the data to be filled
  • lons (2D numpy array) – longitude points
  • lats (2D numpy array) – latitude points
Returns:

a 4D numpy array

salishsea_tools.LiveOcean_BCs.interpolate_to_NEMO_depths(dataset, NEMO_depths, var_names)[source]

Interpolate variables in var_names from a Live Ocean dataset to NEMO depths. LiveOcean land points (including points lower than bathymetry) are set to np.nan and then masked.

Parameters:
  • dataset (xarray Dataset) – Live Ocean dataset
  • NEMO_depths (1D numpy array) – NEMO model depths
  • var_names (list of str) – list of Live Ocean variable names to be interpolated, e.g [‘salt’, ‘temp’]
Returns:

dictionary containing interpolated numpy arrays for each variable

salishsea_tools.LiveOcean_BCs.interpolate_to_NEMO_lateral(var_arrays, dataset, NEMOlon, NEMOlat, shape)[source]

Interpolates arrays in var_arrays laterally to NEMO grid. Assumes these arrays have already been interpolated vertically. NaN values are set to nearest lateral neighbour. If a vertical level is entirely NaNs, it is set equal to the level above.

Parameters:
  • var_arrays – dictionary of 4D numpy arrays. Key represents the variable name.
  • dataset (xarray Dataset) – LiveOcean results. Used to look up lateral grid.
  • NEMOlon (1D numpy array) – array of NEMO boundary longitudes
  • NEMOlat (1D numpy array) – array of NEMO boundary longitudes
  • shape (2-tuple) – the lateral shape of NEMO boundary area.
Returns:

a dictionary, like var_arrays, but with arrays replaced with interpolated values

salishsea_tools.LiveOcean_BCs.load_LiveOcean(files, resample_interval='1H')[source]

Load a time series of Live Ocean results represented by a list of files. Time series is resampled by averaging over resample_interval. Default is 1 hour.

Parameters:
  • files (list of strings) – Live Ocean filenames
  • resample_interval (str) – interval for resampling based on pandas values. e.g. 1H is one hour, 7D is seven days, etc
Returns:

xarray dataset of Live Ocean results

salishsea_tools.LiveOcean_BCs.load_SalishSea_boundary_grid(fname='/data/nsoontie/MEOPAR/NEMO-forcing/open_boundaries/west/SalishSea_west_TEOS10.nc')[source]

Load the Salish Sea NEMO model boundary depth, latitudes and longitudes.

Parameters:str (fname) – name of boundary file
Returns:numpy arrays depth, lon, lat and a tuple shape
salishsea_tools.LiveOcean_BCs.recalcBioTSFits(TSfile, TSdir='/results/forcing/LiveOcean/boundary_conditions', nFitFilePath='/results/forcing/LiveOcean/boundary_conditions/bio/fits/bioOBCfit_NTS.csv', siFitFilePath='/results/forcing/LiveOcean/boundary_conditions/bio/fits/bioOBCfit_SiTS.csv', nClimFilePath='/results/forcing/LiveOcean/boundary_conditions/bio/fits/nmat.csv', siClimFilePath='/results/forcing/LiveOcean/boundary_conditions/bio/fits/simat.csv', constFile='/ocean/eolson/MEOPAR/NEMO-3.6-inputs/boundary_conditions/bioOBC_constTest.nc')[source]

Recalculate TS fits and also create new boundary file for constant variables.

Parameters:
  • TSfile (str) – the name of a TS boundary file to use as a template for dimensions
  • TSdir (str) – path to the specified TSfile
  • nFitFilePath (str) – path and filename where N to T,S fit coefficients will be saved
  • siFitFilePath (str) – path and filename where Si to T,S fit coefficients will be saved
  • nClimFilePath (str) – path and filename where N upper water column climatology will be saved
  • siClimFilePath (str) – path and filename where Si upper water column climatology will be saved
  • constFile (str) – path and filename where constant BC variables will be stored
salishsea_tools.LiveOcean_grid.get_basic_info(fn, getG=True, getS=True, getT=True)[source]

Gets grid, vertical coordinate, and time info from a ROMS NetCDF history file with full name ‘fn’

Input: the filename (with path if needed)

Output: dicts G, S, and T

Example calls:

for more than one the dout list is unpacked automatically G, S, T = zfun.get_basic_info(fn)

for getting just one use [] to just get the dict [T] = zfun.get_basic_info(fn, getG=False, getS=False)

salishsea_tools.LiveOcean_grid.get_z(h, zeta, S)[source]

Used to calculate the z position of fields in a ROMS history file. Only for rho levels

Input: arrays h (bathymetry depth) and zeta (sea surface height) which must be the same size, and dict S created by get_basic_info()

Output: 3-D arrays of z_rho

NOTE: one foible is that if you input arrays of h and zeta that are vectors of length VL, the output array (e.g. z_rho) will have size (N, VL) (i.e. it will never return an array with size (N, VL, 1), even if (VL, 1) was the input shape). This is a result of the initial and final squeeze calls.

salishsea_tools.UBC_subdomain.get_UBC_subdomain(f_list)[source]

Create subdomain files for all netCDF files in f_list

namelist Module

Fortran namelist parser. Converts namelists to Python dictionaries.

Based on https://gist.github.com/krischer/4943658.

Should be fairly robust. Cannot be used for verifying fortran namelists as it is rather forgiving.

Error messages during parsing are kind of messy right now.

Usage

>>> from namelist import namelist2dict
>>> namelist_dict = namelist2dict("fortran_list.txt")

Can deal with filenames, open files and file-like object (StringIO).

Works with Python 2.7 and has not further dependencies.

copyright:Lion Krischer (krischer@geophysik.uni-muenchen.de), 2013
license:GNU Lesser General Public License, Version 3 (http://www.gnu.org/copyleft/lesser.html)
salishsea_tools.namelist.namelist2dict(file_or_file_object)[source]

Thin wrapper to be able to deal with file-like objects and filenames.

nc_tools Module

A library of Python functions for working with netCDF files.

Included are functions for:

  • exploring the attributes of netCDF files
  • managing those attributes during netCDF file creation and updating
  • obtaining variable values from netCDF files
  • creation of special purpose netCDF files
  • combining per-processor sub-domain output files fron NEMO into a single netCDF file
salishsea_tools.nc_tools.check_dataset_attrs(dataset)[source]

Check that required dataset and variable attributes are present and that they are not empty.

Parameters:dataset (netCDF4.Dataset) – netcdf dataset object
salishsea_tools.nc_tools.combine_subdomain(filenames, outfilename)[source]

Recombine per-processor subdomain files into one single file.

Note: filenames must be an array of files organized to reflect the subdomain decomposition. filenames[0,0] is bottom left, filenames[0,-1] is bottom right, filenames[-1,0] is top left, filenames[-1,-1] is top right. For example, filenames = [[sub_00.nc, sub_01.nc], [sub_02.nc, sub_03.nc]]. This can be improved. At some point it would be worthwhile to automatically build the filenames array. Also, we might want to add netcdf attributes like history, units, etc.

Parameters:
  • filenames (numpy array (2D)) – An array containing the names of the files to be recombined.
  • outfilename (string) – The name of the file for saving output
salishsea_tools.nc_tools.dataset_from_path(path, *args, **kwargs)[source]

Return a dataset constructed from the file given by path.

This is a shim that facilitates constructing a netCDF4.Dataset instance from a file that is identified by path/filename that is either a string or a pathlib.Path instance. The netCDF4.Dataset constructor cannot handle pathlib.Path instances.

Parameters:
  • path (pathlib.Path or :py:class`str`) – Path/filename to construct the dataset from.
  • args (list) – Positional arguments to pass through to the netCDF4.Dataset constructor.
  • kwargs (dict) – Keyword arguments to pass through to the netCDF4.Dataset constructor.
Returns:

Dataset from file at path.

Return type:

netCDF4.Dataset

Raises:

IOError if there the netCDF4.Dataset constructor raises a RuntimeError that indicates that the file or directory at path is not found.

salishsea_tools.nc_tools.generate_pressure_file(filename, p_file, t_file, alt_file, day)[source]

Generates a file with CGRF pressure corrected to sea level.

Parameters:
  • filename (string) – full path name where the corrected pressure should be saved
  • p_file (string) – full path name of the uncorrected CGRF pressure
  • t_file (string) – full path name of the corresponding CGRF temperature
  • alt_file (string) – full path name of the altitude of CGRF cells
  • day (arrow) – the date
salishsea_tools.nc_tools.generate_pressure_file_ops(filename, p_file, t_file, alt_file, day)[source]

Generates a file with CGRF pressure corrected to sea level.

Parameters:
  • filename (string) – full path name where the corrected pressure should be saved
  • p_file (string) – full path name of the uncorrected CGRF pressure
  • t_file (string) – full path name of the corresponding CGRF temperature
  • alt_file (string) – full path name of the altitude of CGRF cells
  • day (arrow) – the date
salishsea_tools.nc_tools.get_datetimes(dataset, time_var='time_counter')[source]

Return the datetime array for a dataset

This is a wrapper around nc_tools.timestamp that automatically handles all timesteps and converts the arrow objects to a numpy datetime object array.

Parameters:
  • dataset (netCDF4.Dataset) – netcdf dataset object.
  • time_var (str) – name of time variable.
Returns:

datetime values at each timestep in the dataset.

Return type:

Numpy array of Datetime instances

salishsea_tools.nc_tools.init_dataset_attrs(dataset, title, notebook_name, nc_filepath, comment='', quiet=False)[source]

Initialize the required global attributes of the netCDF dataset.

If an attribute with one of the required attribute names is already set on the dataset it will not be overwritten, instead a warning will be printed, unless quiet==True.

With quiet==False (the default) the dataset attributes and their values are printed.

Parameters:
  • dataset (netCDF4.Dataset) – netcdf dataset object
  • title (str) – Title for the dataset
  • notebook_name (str) – Name of the IPython Notebook being used to create or update the dataset. If empty the source attribute value will be set to REQUIRED and must therefore be handled in a subsequent operation.
  • nc_filepath (str) – Relative path and filename of the netCDF file being created or updated. If empty the references attribute value will be set to REQUIRED and must therefore be handled in a subsequent operation.
  • comment (str) – Comment(s) for the dataset
  • quiet (Boolean) – Suppress printed output when True; defaults to False
salishsea_tools.nc_tools.load_GEM_from_erddap(timerange, window=[None, None, None, None], fields=['u_wind', 'v_wind'], gridpath='https://salishsea.eos.ubc.ca/erddap/griddap/ubcSSaAtmosphereGridV1', datapath='https://salishsea.eos.ubc.ca/erddap/griddap/ubcSSaSurfaceAtmosphereFieldsV1')[source]

Returns surface atmospheric variables from the Environment Canada GEM 2.5 km HRDPS atmospheric model, accessed through the ERDDAP server.

Note

This function is deprecated. Load HRDPS results directly from the ERDDAP server instead.

salishsea_tools.nc_tools.load_GEM_from_path(timerange, window=[None, None, None, None], fields=['u_wind', 'v_wind'], model='operational', path='/results/forcing/atmospheric/GEM2.5')[source]

Returns surface atmospheric variables from the Environment Canada GEM 2.5 km HRDPS atmospheric model, accessed through the local filesystem.

Note

This function is deprecated. Load HRDPS results directly from the filesystem on Skookum instead.

salishsea_tools.nc_tools.load_NEMO_from_erddap(timerange, depth=[None, None], window=[None, None, None, None], fields=['salinity', 'temperature', 'u_vel', 'v_vel'], path='https://salishsea.eos.ubc.ca/erddap/griddap', bathy_dataset='ubcSSnBathymetry2V1')[source]

Returns vector and tracer variables from the Salish Sea NEMO model, accessed through the ERDDAP server.

Note

This function is deprecated. Load NEMO results directly from the ERDDAP server instead, or use timeseries_tools.load_NEMO_timeseries.

salishsea_tools.nc_tools.load_NEMO_from_path(timerange, depth=[None, None], window=[None, None, None, None], model='nowcast', resolution='h', path='/results/SalishSea', bathy_meter='/results/SalishSea/nowcast/01aug16/bathy_meter.nc', fields=['salinity', 'temperature', 'u_vel', 'v_vel'])[source]

Returns vector and tracer variables from the Salish Sea NEMO model, accessed through the local filesystem.

Note

This function is deprecated. Load NEMO results directly from the filesystem on Skookum instead, or use timeseries_tools.load_NEMO_timeseries.

salishsea_tools.nc_tools.make_filename_list(timerange, qty, model='nowcast', resolution='h', path='/results/SalishSea')[source]

Return a sequential list of Nowcast results filenames to be passed into xarray.open_mfdataset or timeseries_tools.load_NEMO_timeseries.

Note

This function has migrated to timeseries_tools.make_filename_list.

Parameters:
  • timerange (list or tuple of str) – list or tuple of date strings (e.g., [‘2017 Jan 1 00:00’, ‘2017 Jan 31 23:00’])
  • qty (str) – quantity type (‘U’ for zonal velocity, ‘V’ for meridional velocity, ‘W’ for vertical velocity, ‘T’ for tracers)
  • model (str) – forecast type (e.g., ‘nowcast’, ‘nowcast-green’, ‘forecast’)
  • resolution (str) – time resolution (‘h’ for hourly, ‘d’, for daily)
  • path (str) – path to results archive
Returns:

Sequential list of Nowcast results filenames

Return type:

list of str

salishsea_tools.nc_tools.show_dataset_attrs(dataset)[source]

Print the global attributes of the netCDF dataset.

Parameters:dataset (netCDF4.Dataset) – netcdf dataset object
salishsea_tools.nc_tools.show_dimensions(dataset)[source]

Print the dimensions of the netCDF dataset.

Parameters:dataset (netCDF4.Dataset) – netcdf dataset object
salishsea_tools.nc_tools.show_variable_attrs(dataset, *vars)[source]

Print the variable attributes of the netCDF dataset.

If variable instances are given as optional arguments, only those variable’s attributes are printed.

Parameters:
  • dataset (netCDF4.Dataset) – netcdf dataset object
  • vars (netCDF4.Variable1) – Variables to print attributes for
salishsea_tools.nc_tools.show_variables(dataset)[source]

Print the variable names in the netCDF dataset as a list.

Parameters:dataset (netCDF4.Dataset) – netcdf dataset object
salishsea_tools.nc_tools.ssh_timeseries_at_point(grid_T, j, i, datetimes=False)[source]

Return the sea surface height and time counter values at a single grid point from a NEMO tracer results dataset.

Parameters:
  • grid_T (netCDF4.Dataset) – Tracer results dataset from NEMO.
  • j (int) – j-direction (longitude) index of grid point to get sea surface height at.
  • i (int) – i-direction (latitude) index of grid point to get sea surface height at.
  • datetimes (boolean) – Return time counter values as datetime.datetime objects if True, otherwise return them as arrow.Arrow objects (the default).
Returns:

2-tuple of 1-dimensional numpy.ndarray objects. The ssh attribute holds the sea surface heights, and the time attribute holds the time counter values.

Return type:

collections.namedtuple

salishsea_tools.nc_tools.time_origin(dataset, time_var='time_counter')[source]

Return the time_var.time_origin value.

Parameters:
  • dataset (netCDF4.Dataset) – netcdf dataset object
  • time_var (str) – name of time variable
Returns:

Value of the time_origin attribute of the time_counter variable.

Return type:

Arrow instance

salishsea_tools.nc_tools.timestamp(dataset, tindex, time_var='time_counter')[source]

Return the time stamp of the tindex time_counter value(s) in dataset.

The time stamp is calculated by adding the time_counter[tindex] value (in seconds) to the dataset’s time_counter.time_origin value.

Parameters:
  • dataset (netCDF4.Dataset) – netcdf dataset object
  • tindex (int or list) – time_counter variable index.
  • time_var (str) – name of the time variable
Returns:

Time stamp value(s) at tindex in the dataset.

Return type:

Arrow instance or list of instances

salishsea_tools.nc_tools.uv_wind_timeseries_at_point(grid_weather, j, i, datetimes=False)[source]

Return the u and v wind components and time counter values at a single grid point from a weather forcing dataset.

Parameters:
  • grid_weather (netCDF4.Dataset) – Weather forcing dataset, typically from an ops_yYYYYmMMdDD.nc file produced by the nowcast.workers.grid_to_netcdf worker.
  • j (int) – j-direction (longitude) index of grid point to get wind components at.
  • i (int) – i-direction (latitude) index of grid point to get wind components at.
  • datetimes (boolean) – Return time counter values as datetime.datetime objects if True, otherwise return them as arrow.Arrow objects (the default).
Returns:

2-tuple of 1-dimensional numpy.ndarray objects, The u attribute holds the u-direction wind component, The v attribute holds the v-direction wind component, and the time attribute holds the time counter values.

Return type:

collections.namedtuple

salishsea_tools.nc_tools.xarraytime_to_datetime(xarraytime)[source]

Convert an xarray.DataArray numpy.datetime64 object to a datetime.datetime object.

Parameters:xarraytime (xarray.DataArray of numpy.datetime64) – xarray time object
Returns:datetime time object
Return type:datetime.datetime
class salishsea_tools.nc_tools.scDataset(files)[source]

Simple Concatenated Dataset

scDataset is a partial implementation of MFDataset that automates the concatenation of netCDF variables split between multiple files. The aim is to provide a simple concatenated interface to variables where the first dimension is the unlimited dimension (usually “time_counter”).

Variables where the first dimension is not the unlimited time dimension (such as lon, lat, etc) are not concatenated. They are, however, made available in a “pass through” sense to the first dataset in the list. Thus, you can read those variables without opening another Dataset.

The other MFDataset features are not implemented: attributes, etc are ignored for the concatenated variables. It may be possible to add the those features but the goal here is simply automated concatenation.

Building this class was motivated by deficiencies in the other options for split-file concatenation:

  • xarray.open_mfdataset() appears to load the entire dataset into memory, which is both slow and memory intensive.
  • netCDF4.MFDataset refuses to open NETCDF4 format files

In the event that netCDF4.MFDataset is improved to work with NETCDF4 files, this will become obsolete.

Parameters:files (list) – list of netcdf filenames in chronological order

Example usage:

# Get the (concatenated) output times
with scDataset(files) as ds:
    t = ds.variables['time_counter'][:]
# Get temperature at all times and all depths at one location
with scDataset(files) as ds:
    temper = ds.variables['votemper'][:,:,100,100]
# Load surface salinity at each time in a loop for plotting/animation
with scDataset(files) as ds:
    for ti in range(ds.variables['vosaline'].shape[0]):
        print("Loading time "+str(ti))
        surfsal = ds.variables['vosaline'][ti,0,:,:]
        # make_a_plot(surfsal)
# Python indexing and slicing also works
with scDataset(files) as ds:
    t1 = ds.variables['votemper'][29:33:-1,-10:-1,100:130]
    print(t1.shape)

places Module

Salish Sea NEMO model geographic places information.

It is recommended that library code that uses the PLACES data structure from this module should use try...except to catch KeyError exceptions and produce an error message that is more informative than the default, for example:

try:
    max_tide_ssh = max(ttide.pred_all) + PLACES[site_name]['mean sea lvl']
    max_historic_ssh = PLACES[site_name]['hist max sea lvl']
except KeyError as e:
    raise KeyError(
        'place name or info key not found in '
        'salishsea_tools.places.PLACES: {}'.format(e))
salishsea_tools.places.PLACES = {'Cluster_8': {'lon lat': (49.726, -124.679), 'Vector Stn': '12', 'NEMO grid ji': (646, 168)}, 'East node': {'lon lat': (-123.316836666, 49.04316), 'depth': 164, 'ONC stationCode': 'SEVIP', 'NEMO grid ji': (417, 283)}, 'Sandheads': {'lon lat': (-123.3, 49.1), 'NEMO grid ji': (426, 292)}, 'Halibut Bank': {'lon lat': (-123.72, 49.34), 'GEM2.5 grid ji': (149, 141), 'EC buoy number': 46146, 'NEMO grid ji': (503, 261)}, 'Duke Pt.': {'lon lat': (-123.89095676900132, 49.16340592936349), 'in berth radius': 0.002}, 'Central node': {'lon lat': (-123.425825, 49.040066666), 'depth': 294, 'ONC stationCode': 'SCVIP', 'NEMO grid ji': (424, 266)}, 'Cluster_1': {'lon lat': (48.215, -123.099), 'Vector Stn': '64', 'NEMO grid ji': (241, 212)}, 'Tsawwassen': {'lon lat': (-123.132722, 49.006165), 'in berth radius': 0.0015}, 'Juan de Fuca Strait': {'lon lat': (-124.7, 48.47)}, 'Strait of Georgia': {'lon lat': (-123.8, 49.3)}, 'Cluster_3': {'lon lat': (48.899, -123.138), 'Vector Stn': '45', 'NEMO grid ji': (376, 291)}, 'S3': {'lon lat': (-123.558, 49.125), 'NEMO grid ji': (450, 258)}, 'Sentry Shoal': {'lon lat': (-125.0, 49.92), 'GEM2.5 grid ji': (183, 107), 'EC buoy number': 46131, 'NEMO grid ji': (707, 145)}, 'Cluster_6': {'lon lat': (48.249, -124.11), 'Vector Stn': '73', 'NEMO grid ji': (320, 68)}, 'Cluster_4': {'lon lat': (48.555, -122.75), 'Vector Stn': '53', 'NEMO grid ji': (282, 305)}, 'Vancouver': {'lon lat': (-123.1207, 49.2827)}, 'Horseshoe Bay': {'lon lat': (-123.2728, 49.3742)}, 'Delta DDL node': {'lon lat': (-123.32972, 49.08495), 'depth': 107, 'ONC stationCode': 'USDDL', 'NEMO grid ji': (426, 286)}, 'Cherry Point': {'lon lat': (-122.766667, 48.866667), 'hist max sea lvl': 5.846, 'stn number': 9449424, 'wind grid ji': (122, 166), 'NEMO grid ji': (343, 341), 'ww3 grid ji': (193, 462), 'mean sea lvl': 3.543}, 'Nanaimo': {'lon lat': (-123.93, 49.16), 'hist max sea lvl': 5.47, 'wind grid ji': (142, 133), 'NEMO grid ji': (484, 208), 'ww3 grid ji': (258, 296), 'mean sea lvl': 3.08}, 'Washington State': {'lon lat': (-123.8, 47.8)}, 'Delta BBL node': {'lon lat': (-123.339633, 49.074766), 'depth': 143, 'ONC stationCode': 'LSBBL', 'NEMO grid ji': (424, 283)}, 'Cluster_7': {'lon lat': (49.317, -123.801), 'Vector Stn': '27', 'NEMO grid ji': (504, 246)}, 'Cluster_2': {'lon lat': (48.261, -123.717), 'Vector Stn': '69', 'NEMO grid ji': (294, 127)}, 'Victoria': {'lon lat': (-123.36, 48.41), 'hist max sea lvl': 3.76, 'stn number': 7120, 'wind grid ji': (104, 144), 'NEMO grid ji': (297, 197), 'ww3 grid ji': (91, 377), 'mean sea lvl': 1.881}, 'Puget Sound': {'lon lat': (-122.67, 48)}, 'Cluster_9': {'lon lat': (49.101, -123.249), 'NEMO grid ji': (423, 300)}, 'British Columbia': {'lon lat': (-123.6, 49.9)}, 'Point Atkinson': {'lon lat': (-123.25, 49.33), 'hist max sea lvl': 5.61, 'stn number': 7795, 'wind grid ji': (146, 155), 'NEMO grid ji': (468, 329), 'ww3 grid ji': (296, 393), 'mean sea lvl': 3.09}, 'Pacific Ocean': {'lon lat': (-125.6, 48.1)}, 'Departure Bay': {'lon lat': (-123.8909, 49.1632)}, 'Cluster_5': {'lon lat': (48.735, -123.135), 'Vector Stn': '57', 'NEMO grid ji': (344, 271)}, 'Swartz Bay': {'lon lat': (-123.4102, 48.6882)}, 'Campbell River': {'lon lat': (-125.24, 50.04), 'hist max sea lvl': 5.35, 'stn number': 8074, 'wind grid ji': (190, 102), 'NEMO grid ji': (747, 125), 'ww3 grid ji': (453, 109), 'mean sea lvl': 2.916}}

Information about geographic places used in the analysis and presentation of Salish Sea NEMO model results.

salishsea_tools.places.TIDE_GAUGE_SITES = ('Victoria', 'Cherry Point', 'Point Atkinson', 'Nanaimo', 'Campbell River')

Names of tide gauge sites, ordered from south and west to north and east. These names are keys of the PLACES dict.

psu_tools Module

Functions for converting temperature and salinity(psu) to density

salishsea_tools.psu_tools.calculate_density(t, s)[source]

Calculates the density given temperature in deg C (t) and salinity in psu (s). The reference for this calculation is: Pond and Pickard, (1983). Introductory Dynamical Oceanography

Parameters:
  • t (numpy array) – temperature array in deg C
  • s (numpy array) – salinity array in psu
Returns:

the density as an array (rho) in kg/m^3

rivertools Module

A collections of functions for working with river flow forcing data for the Salish Sea NEMO model.

salishsea_tools.rivertools.check_sum(runoff_orig, runoff_new, flux, area)[source]

Check that the runoff adds up to what it should.

salishsea_tools.rivertools.check_sum_monthly(runoff_orig, runoff_new, flux, area)[source]

Check that the runoff adds up per month to what it should.

salishsea_tools.rivertools.fill_runoff_array(flux, istart, di, jstart, dj, depth_of_flux, runoff, run_depth, area)[source]

Fill the runoff array.

salishsea_tools.rivertools.fill_runoff_array_monthly(flux, istart, di, jstart, dj, depth_of_flux, runoff, run_depth, run_temp, area)[source]

Fill the monthly runoff array.

salishsea_tools.rivertools.get_bathy_cell_size(grid='../../../nemo-forcing/grid/coordinates_seagrid_SalishSea.nc')[source]

Get the bathymetry and size of each cell.

salishsea_tools.rivertools.get_watershed_prop_dict(watershedname, Fraser_River='short')[source]

get the proportion that each river occupies in the watershed.

salishsea_tools.rivertools.get_watershed_prop_dict_allArms_fraser(watershedname)[source]

get the proportion that each river occupies in the watershed.

salishsea_tools.rivertools.get_watershed_prop_dict_long_fraser(watershedname)[source]

get the proportion that each river occupies in the watershed.

salishsea_tools.rivertools.init_runoff3_array(bathy='/ocean/jieliu/research/meopar/river-treatment/bathy_meter_SalishSea3.nc')[source]

Initialise the runoff array.

salishsea_tools.rivertools.init_runoff3_array_monthly(bathy='/ocean/jieliu/research/meopar/river-treatment/bathy_meter_SalishSea3.nc')[source]

Initialise the runoff array for each month.

salishsea_tools.rivertools.init_runoff5_array(bathy='/ocean/jieliu/research/meopar/river-treatment/bathy_meter_SalishSea5.nc')[source]

Initialise the runoff array.

salishsea_tools.rivertools.init_runoff5_array_monthly(bathy='/ocean/jieliu/research/meopar/river-treatment/bathy_meter_SalishSea5.nc')[source]

Initialise the runoff array for each month.

salishsea_tools.rivertools.init_runoff_array(bathy='../../../nemo-forcing/grid/bathy_meter_SalishSea.nc', init_depth=-1, init_temp=-99)[source]

Initialise the runoff array.

If you want to use a different bathymetry set it in the call; e.g.:

init_runoff_array(
    bathy='/ocean/jieliu/research/meopar/river-treatment/bathy_meter_SalishSea6.nc')
salishsea_tools.rivertools.init_runoff_array_monthly(bathy='../../../nemo-forcing/grid/bathy_meter_SalishSea.nc', init_depth=-1, init_temp=-99)[source]

Initialise the runoff array for each month.

salishsea_tools.rivertools.put_watershed_into_runoff(rivertype, area, flux, runoff, run_depth, run_temp, pd)[source]

Fill the river file with the rivers of one watershed.

Parameters:
  • rivertype (str) – ‘constant’ or ‘monthly’ flows
  • area (array) – horizontal area of each grid cell in domain e1t*e2t
  • flux (float) – amount of flow into watershed
  • runoff (array) – runoff array we are filling
  • run_depth (array) – depth array we are filling
  • run_temp (array) – temperature array we are filling
  • pd (dict) – property dictionary for the watershed

Note: this function now needs pd sent in, it does not go and get it as it did previously

salishsea_tools.rivertools.put_watershed_into_runoff3(rivertype, watershedname, flux, runoff, run_depth, run_temp)[source]

Fill the river file with the rivers of one watershed.

salishsea_tools.rivertools.rivertemp(month)[source]

River temperature, based on Fraser River, see Allen and Wolfe (2013).

Temperature in NEMO is in Celsius.

stormtools Module

A collection of tools for storm surge results from the Salish Sea Model.

salishsea_tools.stormtools.combine_data(data_list)[source]

This function combines output from a list of netcdf files into a dict objects of model fields. It is used for easy handling of output from thalweg and surge stations.

Parameters:data_list (dict object) – dict object that contains the netcdf handles for the files to be combined; e.g. {‘Thalweg1’: f1, ‘Thalweg2’: f2,…} where f1 = NC.Dataset(‘1h_Thalweg1.nc’,’r’)
Returns:dict objects us, vs, lats, lons, sals, tmps, sshs with the zonal velocity, meridional velocity, latitude, longitude, salinity, temperature, and sea surface height for each station. The keys are the same as those in data_list. For example, us[‘Thalweg1’] contains the zonal velocity from the Thalweg 1 station.
salishsea_tools.stormtools.convert_date_hours(times, start)[source]

This function converts model output time in hours to datetime objects.

Parameters:
  • times (int) – array of hours since the start date of a simulation. From time_counter in model output.
  • start (str) – string containing the start date of the simulation in format ‘01-Nov-2006’
Returns:

array of datetime objects representing the time of model outputs.

salishsea_tools.stormtools.convert_date_seconds(times, start)[source]

This function converts model output time in seconds to datetime objects. Note: Doug has a better version of this in nc_tools.timestamp

Parameters:
  • times (int) – array of seconds since the start date of a simulation. From time_counter in model output.
  • start (str) – string containing the start date of the simulation in format ‘01-Nov-2006’
  • diff (str) – string indicating the time step in the times data E.g. months, seconds, days
Returns:

array of datetime objects representing the time of model outputs.

salishsea_tools.stormtools.correct_model(ssh, ttide, sdt, edt)[source]

Adjusts model output by correcting for error in using only 8 constituents

Parameters:
  • ssh (array of numbers) – an array with model ssh data
  • ttide (struc with dimension time, pred_all, pred_8) – struc with tidal predictions. Assumes tidal predictions are on the the hour can model output is on the 1/2 hour.
  • sdt (datetime object) – datetime object representing start date of simulation
  • edt (datetime object) – datetime object representing end date of simulation
Returns:

corr_model: the corrected model output

salishsea_tools.stormtools.dateParserMeasured(s)[source]

converts string in %Y/%m/%d %H:%M format Pacific time to a datetime object UTC time.

salishsea_tools.stormtools.dateParserMeasured2(s)[source]

converts string in %d-%b-%Y %H:%M:%S format Pacific time to a datetime object UTC time.

salishsea_tools.stormtools.get_CGRF_weather(start, end, grid)[source]

Returns the CGRF weather between the dates start and end at the grid point defined in grid.

Parameters:
  • start (str) – string containing the start date of the CGRF collection in format ‘01-Nov-2006’
  • start – string containing the end date of the CGRF collection in format ‘01-Nov-2006’
  • grid – array of the CGRF grid coordinates for the point of interest eg. [244,245]
  • type – arr of ints
Returns:

windspeed, winddir pressure and time array from CGRF data for the times indicated. windspeed is in m/s winddir direction wind is blowing to in degrees measured counterclockwise from East. pressure is in Pa.

salishsea_tools.stormtools.get_EC_observations(station, start_day, end_day)[source]

Gather hourly Environment Canada (EC) weather observations for the station and dates indicated.

The hourly EC data is stored in monthly files, so only a single month can be downloaded at a time.

Parameters:
  • station (str) – Station name (no spaces). e.g. ‘PointAtkinson’
  • start_day (str) – Start date in the format ‘01-Dec-2006’.
  • end_day (str) – End date in the format ‘01-Dec-2006’.
Returns:

wind_speed, wind_dir, temperature, times, lat and lon: wind speed is in m/s wind_dir is direction wind is blowing to in degrees measured counterclockwise from East temperature is in Kelvin time is UTC Also returns latitude and longitude of the station.

salishsea_tools.stormtools.get_NOAA_predictions(station_no, start_date, end_date)[source]

Download tide predictions from NOAA site for one NOAA station for specified period.

Parameters:
  • station_no (int) – Station number e.g. 9443090.
  • start_date (str) – Start date; e.g. ‘01-JAN-2010’.
  • end_date (str) – End date; e.g. ‘31-JAN-2010’
Returns:

Saves text file with predictions in meters at one station. Time zone is UTC

salishsea_tools.stormtools.get_NOAA_wlev(station_no, start_date, end_date)[source]

Download water level data from NOAA site for one NOAA station for specified period.

Parameters:
  • station_no (int) – Station number e.g. 9443090.
  • start_date (str) – Start date; e.g. ‘01-JAN-2010’.
  • end_date (str) – End date; e.g. ‘31-JAN-2010’
Returns:

Saves text file with water level data in meters at one station. Time zone is UTC

salishsea_tools.stormtools.get_SSH_forcing(boundary, date)[source]

A function that returns the ssh forcing for the month of the date and boundary indicated.

Parameters:
  • boundary (str) – A string naming the boundary. e.g ‘north’ or ‘west’
  • date (str) – A string indicating the date of interest. e.g. ‘01-Dec-2006’. The day needs to be the first day of the month.
Returns:

ssh_forc, time_ssh: arrays of the ssh forcing values and corresponding times

salishsea_tools.stormtools.get_operational_weather(start, end, grid)[source]

Returns the operational weather between the dates start and end at the grid point defined in grid.

Parameters:
  • start (str) – string containing the start date of the weather collection in format ‘01-Nov-2006’
  • start – string containing the end date of the weather collection in format ‘01-Nov-2006’
  • grid – array of the operational grid coordinates for the point of interest eg. [244,245]
  • type – arr of ints
Returns:

windspeed, winddir pressure and time array from weather data for the times indicated wind speed is m/s winddir is direction wind is blowing in degrees counterclockwise from east pressure is kPa time is UTC

salishsea_tools.stormtools.get_statistics(obs, model, t_obs, t_model, sdt, edt)[source]

Calculates several statistics, such as mean error, maximum value, etc. for model and observations in a given time period.

Parameters:
  • obs (array) – observation data
  • model (array) – model data
  • t_obs (array) – observations time
  • t_model (array) – model time
  • sdt (datetime object) – datetime object representing start date of analysis period
  • edt (datetime object) – datetime object representing end date of analysis period
Returns:

max_obs, max_model, tmax_obs, tmax_model, mean_error, mean_abs_error, rms_error, gamma2 (see Bernier Thompson 2006), correlation matrix, willmott score, mean_obs, mean_model, std_obs, std_model

salishsea_tools.stormtools.get_variables(fU, fV, fT, timestamp, depth)[source]

Generates masked u,v,SSH,S,T from NETCDF handles fU,fV,fT at timestamp and depth.

Parameters:
  • fU (netcdf handle) – netcdf handle for Ugrid model output
  • fV (netcdf handle) – netcdf handle for Vgrid model output
  • fT (netcdf handle) – netcdf handle for Tgrid model output
  • timestamp (int) – the timestamp for desired model output
  • depth (int) – the model z-level for desired output
Returns:

masked arrays U,V,E,S,T with of zonal velocity, meridional velocity, sea surface height, salinity, and temperature at specified time and z-level.

salishsea_tools.stormtools.interp_to_model_time(time_model, varp, tp)[source]

Interpolates a variable to model output times.

Parameters:
  • model_time (array with datetimes) – array of model output times as datetime objects
  • varp (array) – array of variable to be interpolated
  • tp (array) – array of times associated with variable
Returns:

varp_interp, the variable interpolated to model_times

salishsea_tools.stormtools.load_observations(start, end, location)[source]

Loads tidal observations from the DFO website using tidetools function

Parameters:
  • start (string in format %d-%b-%Y) – a string representing the starting date of the observations.
  • end (string in format %d-%b-%Y) – a string representing the end date of the observations.
  • location (a string from the following - PointAtkinson, Victoria, PatriciaBay, CampbellRiver) – a string representing the location for observations
Returns:

wlev_meas: a dict object with the water level measurements reference to Chart Datum

salishsea_tools.stormtools.load_tidal_predictions(filename)[source]

Load tidal prediction from a file.

Parameters:filename (str) – The path and file name of a CSV file that contains ttide tidal predictions generated by get_ttide_8.m.
Returns:ttide: Tidal predictions and mean sea level, the mean component from the harmonic analysis.
Return type:pandas.DataFrame
salishsea_tools.stormtools.modelled_anomaly(sshs, location)[source]

Calculates the modelled ssh anomaly by finding the difference between a simulation with all forcing and a simulation with tides only.

Parameters:
  • sshs (struc with dimensions 'all_forcing' and 'tidesonly') – A struc object with ssh data from all_forcing and tidesonly model runs
  • location (string either "PointAtkinson", "Victoria", "PatriciaBay", "CampbellRiver") – string defining the desired location
Returns:

anom: the difference between all_forcing and tidesonly

salishsea_tools.stormtools.observed_anomaly(ttide, wlev_meas, msl)[source]

Calculates the observed anomaly (water level obs - tidal predictions).

Parameters:
  • ttide (struc with dimensions time, pred_all, pred_8) – A struc object that contains tidal predictions from get_ttide_8.m
  • wlev_meas (sruc with dimensions time, slev) – A struc object with observations from DFO
  • msl (float) – The mean sea level from tidal predictions
Returns:

ssanomaly: the ssh anomaly (wlev_meas.slev-(ttide.pred_all+msl))

salishsea_tools.stormtools.rebase_obs(data, time)[source]

Rebases the observations so that they are given on the half hour instead of hour. Half hour outputs calculated by averaging between two hourly outputs.

Parameters:
  • data (array) – data to be rebased
  • time (array) – time outputs associated with data
Returns:

rebase_data, rebase_time, the data and times shifted by half an hour

salishsea_tools.stormtools.storm_surge_risk_level(site_name, max_ssh, ttide)[source]

Calculate the storm surge risk level for site_name, a tide gauge station name.

Thresholds are:

  • Highest predicted tide
  • Half way between highest predicted tide and highest historical water level
  • Highest historical water level

Threshold levels are obtained from salishsea_tools.places.PLACES dict.

:arg str site_name` Name of a tide gauge station at which to
calculate the storm surge risk.
Parameters:
  • max_ssh (float) – The maximum sea surface height predicted for site_name.
  • ttide (pandas.DataFrame) – Tidal predictions from ttide.
Returns:

None for no storm surge risk, moderate risk for water level between max tide level and the half-way threshold, and extreme risk for water level above the half-way threshold

salishsea_tools.stormtools.surge_tide(ssh, ttide, sdt, edt)[source]

Calculates the sea surface height from the model run with surge only. That is, adds tidal prediction to modelled surge. :arg ssh: shh from surge only model run :type ssh: array of numbers

Parameters:
  • ttide (struc with dimension time, pred_all, pred_8) – struc with tidal predictions
  • sdt (datetime object) – datetime object representing start date of simulation
  • edt (datetime object) – datetime object representing end date of simulation
Returns:

surgetide: the surge only run with tides added (mean not included)

salishsea_tools.stormtools.truncate(data, time, sdt, edt)[source]

Returns truncated array for the time period of interest :arg data: data to be truncated :type data: array

Parameters:
  • time (array) – time output associated with data
  • sdt (datetime object) – datetime object representing start date of analysis period
  • edt (datetime object) – datetime object representing end date of analysis period
Returns:

data_t, time_t, truncated data and time arrays

salishsea_tools.stormtools.willmott_skill(obs, model)[source]

Calculates the Willmott skill score of the model. See Willmott 1982. :arg obs: observations data :type obs: array

Parameters:model (array) – model data
Returns:ws, the Willmott skill score

teos_tools Module

Constants and functions for working with TEOS-10 salinity in the Salish Sea NEMO model.

TEOS-10 is the Thermodynamic Equation of Seawater (2010). See http://www.teos-10.org/.

salishsea_tools.teos_tools.PSU_TEOS = 1.0047154285714286

Conversion factor from practical salinity units (psu) to TEOS-10 reference salinity

salishsea_tools.teos_tools.TEOS_PSU = 0.995306702338459

Conversion factor from TEOS-10 reference salinity to practical salinity units (psu)

salishsea_tools.teos_tools.psu_teos(psu)[source]

Convert salinity in practical salinity units (psu) to TEOS-10 reference salinity in g/kg.

Parameters:psu (float, numpy.ndarray, list, or tuple) – Practical salinity units (psu) value to convert.
Returns:TEOS-10 reference salinity in g/kg.
Return type:float or numpy.ndarray
salishsea_tools.teos_tools.teos_psu(teos)[source]

Convert TEOS-10 reference salinity in g/kg to salinity in practical salinity units (psu).

Parameters:teos (float, numpy.ndarray, list, or tuple) – TEOS-10 reference salinity value [g/kg] to convert.
Returns:Practical salinity units (psu) value.
Return type:float or numpy.ndarray

tidetools Module

A collection of tools for dealing with tidal results from the Salish Sea NEMO model

salishsea_tools.tidetools.ap2ep(Au, PHIu, Av, PHIv)[source]

Convert amplitude and phase to ellipse parameters.

Based on MATLAB script by Zhigang Xu, available at http://woodshole.er.usgs.gov/operations/sea-mat/tidal_ellipse-html/ap2ep.m

salishsea_tools.tidetools.calc_diffs_meas_mod(runname, loc, grid)[source]

Calculate differences between measured and modelled water level e.g. (meas_wl_harm, Am_M2_all, Ao_M2_all, gm_M2_all, go_M2_all, D_F95_M2_all, D_M04_M2_all,Am_K1_all, Ao_K1_all, gm_K1_all, go_K1_all, D_F95_K1_all, D_M04_K1_all = calc_diffs_meas_mod(’50s_13Sep-20Sep’)

Parameters:runname (str) – name of model run
Returns:meas_wl_harm, Am_M2_all, Ao_M2_all, gm_M2_all, go_M2_all, D_F95_M2_all, D_M04_M2_all,Am_K1_all, Ao_K1_all, gm_K1_all, go_K1_all, D_F95_K1_all, D_M04_K1_all
salishsea_tools.tidetools.convention_pha_amp(fitted_amp, fitted_pha)[source]
This function takes the fitted parameters given for phase and
amplitude of the tidal analysis and returns them following the tidal parameter convention; amplitude is positive and phase is between -180 and +180 degrees.
Parameters:
  • fitted_amp (float) – The amplitude given by the fitting function.
  • fitted_pha (float) – The phase given by the fitting function.
Return fitted_amp, fitted_pha:
 

The fitted parameters following the conventions.

salishsea_tools.tidetools.convert_to_hours(time_model, reftime='None')[source]
Interpolates the datetime values into an array of hours from a
determined starting point
Parameters:
  • time_model (array with datetimes) – array of model output time as datetime objects
  • reftime (date time object) – Epoc value. Default ‘None’, uses time_model[0] as the epoc. Note: must add tzinfo = tzutc() in datetime.datetime object.
:returns tp_wrt_epoch, times with respect to the
beginning of the input in seconds
salishsea_tools.tidetools.dateParserMeasured(s)[source]

Function to make datetime object aware of time zone e.g. date_parser=dateParserMeasured(‘2014/05/31 11:42’)

Parameters:s (str) – string of date and time
Returns:datetime object that is timezone aware
salishsea_tools.tidetools.double(x, M2amp, M2pha, K1amp, K1pha, mean)[source]

Function for the fit, assuming only M2 and K2 tidal constituents.

Parameters:
  • x
  • M2amp – Tidal amplitude of the M2 constituent
  • M2pha – Phase lag of M2 constituent
  • K1amp – Tidal amplitude of the K1 constituent
  • K1pha – Phase lag of K1 constituent
:returns:(mean + M2amp*np.cos(M2FREQ*x-M2pha*np.pi/180.)
+K1amp*np.cos(K1FREQ*x-K1pha*np.pi/180.))
salishsea_tools.tidetools.filter_timeseries(record, winlen=39, method='box')[source]

Filter a timeseries.

Developed for wind and tidal filtering, but can be modified for use with a variety of timeseries data. The data record should be at least half a window length longer at either end than the period of interest to accommodate window length shrinking near the array edges.

This function can only operate along the 0 axis. Please modify to include an axis argument in the future.

Types of filters (please add to these): * box: simple running mean * doodson: Doodson bandpass filter (39 winlen required)

Parameters:
  • record (numpy.ndarray, xarray.DataArray, or netCDF4.Variable) – timeseries record to be filtered
  • winlen (integer) – window length
  • method (string) – type of filter (ex. ‘box’, ‘doodson’, etc.)
Returns filtered:
 

filtered timeseries

Return type:

same as record

salishsea_tools.tidetools.find_closest_model_point(lon, lat, X, Y, bathy, lon_tol=0.0052, lat_tol=0.00189, allow_land=False)[source]

Returns the grid co-ordinates of the closest non-land model point to a specified lon/lat.

Note

This function is deprecated. Use geo_tools.find_closest_model_point() instead.

salishsea_tools.tidetools.find_model_level(depth, model_depths, fractional=False)[source]

Returns the index of the model level closest to a specified depth. The model level can be fractional (ie between two grid points). If depth is between 0 and first model level the result is negative. If depth is greater than the max depth the lowest level is returned. A python index is returned (count starting at 0). Add 1 for Fortran.

Parameters:
  • depth (float > 0) – The specified depth
  • model_depths (numpy array (one dimensional)) – array of model depths
  • fractional (boolean) – a flag that specifies if a fractional model level is desired
Returns:

idx, the model level index

salishsea_tools.tidetools.fittit(uaus, time, nconst)[source]

Function to find tidal components of a time series over the whole area given.

Can be done over depth, or an area. Time must be in axis one, depth in axis two if applicable then the y, x if an area. In order to calculate the tidal components of an area at a single depth the time series must only have 3 dimensions. For a depth profile it must only have 2 dimensions

Parameters:
  • uaus (:py:class:'np.ndarray' or float) – The time series to be analyzed.
  • time (:py:class:'np.ndarray') – Time over which the time series is taken in hours.
  • nconst (int) – The amount of tidal constituents used for the analysis. They added in pairs and by order of importance, M2, K1, S2, O1, N2, P1, K2, Q1.
Returns:

a dictionary object containing a phase an amplitude for each harmonic constituent, for each orthogonal velocity

salishsea_tools.tidetools.get_SS2_bathy_data()[source]

Get the Salish Sea 2 bathymetry and grid data e.g. bathy, X, Y = get_SS2_bathy_data()

Note

This function is deprecated due to hard-coding of /ocean/klesouef/ path. Use tidetools.get_bathy_data() instead.

Returns:bathy, X, Y
salishsea_tools.tidetools.get_SS_bathy_data()[source]

Get the Salish Sea bathymetry and grid data e.g. bathy, X, Y = get_SS_bathy_data()

Note

This function is deprecated due to hard-coding of /ocean/klesouef/ path. Use tidetools.get_bathy_data() instead.

Returns:bathy, X, Y
salishsea_tools.tidetools.get_all_perm_dfo_wlev(start_date, end_date)[source]

Get water level data for all permanent DFO water level sites for specified period.

Parameters:
  • start_date (str) – Start date; e.g. ‘01-JAN-2010’.
  • end_date (str) – End date; e.g. ‘31-JAN-2010’
Returns:

Saves text files with water level data at each site

salishsea_tools.tidetools.get_amp_phase_data(runname, loc)[source]

Get the amplitude and phase data for one or more model runs.

Parameters:
  • runname (str or tuple) – Name of the model run to process; e.g. runname = ’50s_15Sep-21Sep’, or if you’d like the harmonics of more than one run to be combined into one picture, give a tuple of names; e.g. (‘40d’, ‘41d50d’, ‘51d60d’).
  • loc (str) – Location of results folder; e.g. /ocean/dlatorne/MEOPAR/SalishSea/results
Returns:

mod_M2_amp, mod_K1_amp, mod_M2_pha, mod_K1_pha

salishsea_tools.tidetools.get_bathy_data(grid)[source]

Get the Salish Sea bathymetry from specified grid NC.Dataset e.g. bathy, X, Y = get_bathy_data(grid)

Parameters:grid (netcdf dataset) – netcdf object of model grid
Returns:bathy, X, Y
salishsea_tools.tidetools.get_composite_harms(runnames, loc)[source]

Combine the harmonics from the specified runs into a ‘composite’ run.

The runs to be ‘composed’ must all have the same model setup.

Parameters:
  • runnames (tuple) – Names of the model runs to process; e.g. (‘40d’, ‘41d50d’, ‘51d60d’).
  • loc (str) – Location of results folder; e.g. /ocean/dlatorne/MEOPAR/SalishSea/results
Returns:

mod_M2_amp, mod_K1_amp, mod_M2_pha, mod_K1_pha

Rtypes:

4-tuple of numpy.ndarray instances

salishsea_tools.tidetools.get_composite_harms2()[source]

Take the results of the following runs (which are all the same model setup) and combine the harmonics into one ‘composite’ run.

50s_15-21Sep 50s_22-25Sep 50s_26-29Sep 50s_30Sep-6Oct 50s_7-13Oct

Returns:mod_M2_amp, mod_K1_amp, mod_M2_pha, mod_K1_pha
salishsea_tools.tidetools.get_composite_harms_uv(runname, loc)[source]

Take the results of the specified runs (which must all have the same model setup) and combine the harmonics into one ‘composite’ run.

Parameters:
  • runname (str) – name of the model run to process; e.g. runname = ’50s_15Sep-21Sep’, or if you’d like the harmonics of more than one run to be combined into one picture, give a list of names e.g. ‘40d’,‘41d50d’,‘51d60d’
  • loc (str) – location of results folder; e.g. /ocean/dlatorne/MEOPAR/SalishSea/results
Returns:

mod_M2_u_amp, mod_M2_u_pha, mod_M2_v_amp, mod_M2_v_pha, mod_K1_u_amp, mod_K1_u_pha, mod_K1_v_amp, mod_K1_v_pha

salishsea_tools.tidetools.get_current_harms(runname, loc)[source]

Get harmonics of current at a specified lon, lat and depth.

Parameters:
  • runname (str) – name of the model run to process; e.g. runname = ’50s_15Sep-21Sep’ (doesn’t deal with multiple runs)
  • loc (str) – location of results folder; e.g. /ocean/dlatorne/MEOPAR/SalishSea/results
Returns:

mod_M2_u_amp, mod_M2_u_pha, mod_M2_v_amp, mod_M2_v_pha

salishsea_tools.tidetools.get_dfo_wlev(station_no, start_date, end_date)[source]

Download water level data from DFO site for one DFO station for specified period.

Parameters:
  • station_no (int) – Station number e.g. 7795.
  • start_date (str) – Start date; e.g. ‘01-JAN-2010’.
  • end_date (str) – End date; e.g. ‘31-JAN-2010’
Returns:

Saves text file with water level data at one station

salishsea_tools.tidetools.get_netcdf_amp_phase_data(loc)[source]

Calculate amplitude and phase from the results of a particular run of the Salish Sea model

Parameters:runname (str) – name of the model run to process e.g. ’50s_15Sep-21Sep’
Returns:model M2 amplitude, model K1 amplitude, model M2 phase, model K1 phase
salishsea_tools.tidetools.get_netcdf_amp_phase_data_concepts110(loc)[source]

Calculate amplitude and phase from the results of the CONCEPTS110 model e.g. mod_M2_amp, mod_M2_pha = get_netcdf_amp_phase_data_concepts110()

Returns:model M2 amplitude, model M2 phase
salishsea_tools.tidetools.get_netcdf_amp_phase_data_jpp72(loc)[source]

Calculate amplitude and phase from the results of the JPP72 model e.g. mod_M2_amp, mod_M2_pha = get_netcdf_amp_phase_data_jpp72()

Returns:model M2 amplitude, model M2 phase
salishsea_tools.tidetools.get_run_length(runname, loc)[source]

Get the length of the run in days from the namelist file

Parameters:
  • runname (str) – name of the model run to process; e.g. ’50s_15Sep-21Sep’
  • loc (str) – location of results folder; e.g. ‘/ocean/dlatorne/MEOPAR/SalishSea/results’
Returns:

length of run in days

salishsea_tools.tidetools.get_subdomain_bathy_data()[source]

Get the subdomain bathymetry and grid data e.g. bathy, X, Y = get_subdomain_bathy_data()

Note

This function is deprecated due to hard-coding of /ocean/klesouef/ path. Use tidetools.get_bathy_data() instead.

Returns:bathy, X, Y
salishsea_tools.tidetools.haversine(lon1, lat1, lon2, lat2)[source]

Calculate the great-circle distance between two points on a sphere from their longitudes and latitudes.

Note

This function is deprecated. Use geo_tools.haversine() instead.

salishsea_tools.tidetools.octuple(x, M2amp, M2pha, K1amp, K1pha, S2amp, S2pha, O1amp, O1pha, N2amp, N2pha, P1amp, P1pha, K2amp, K2pha, Q1amp, Q1pha, mean)[source]

Function for the fit, for all the constituents: M2, K2, S1, O1, N2, P1, K2 and Q1.

Parameters:
  • x – Independent variable, time.
  • *amp (float) – Tidal amplitude of the a constituent
  • *pha (float) – Phase lag of a constituent
Returns:

function for fitting 8 frequencies

salishsea_tools.tidetools.plot_amp_map(X, Y, grid, amp, constituent_name, figsize=(9, 9))[source]

Plot the amplitude of one constituent throughout the whole domain.

Parameters:
  • X (numpy array) – specified model longitude
  • Y (numpy array) – specified model latitude
  • grid (netcdf dataset) – model grid netcdf
  • amp (numpy array) – amplitude
  • constituent_name (str) – Name of tidal constituent. Used as subplot title.
  • figsize (2-tuple) – Figure size, (width, height).
Returns:

Figure containing plots of observed vs. modelled amplitude and phase of the tidal constituent.

Return type:

Matplotlib figure

salishsea_tools.tidetools.plot_amp_phase_maps(runname, loc, grid)[source]

Plot the amplitude and phase results for a model run e.g. plot_amp_phase_maps(’50s_15Sep-21Sep’)

Parameters:
  • runname (str) – name of the model run to process; e.g. runname = ’50s_15Sep-21Sep’, or if you’d like the harmonics of more than one run to be combined into one picture, give a list of names; e.g. ‘40d’,‘41d50d’,‘51d60d’
  • loc (str) – location of results folder; e.g. /ocean/dlatorne/MEOPAR/SalishSea/results
  • grid (netcdf dataset) – netcdf file of grid data
Returns:

plots the amplitude and phase

salishsea_tools.tidetools.plot_coastline(grid)[source]

Plots a map of the coastline.

Note

This function is deprecated. Use viz_tools.plot_coastline() instead.

Parameters:grid (netcdf dataset) – netcdf file of bathymetry
Returns:coastline map
salishsea_tools.tidetools.plot_diffs_on_domain(diffs, meas_wl_harm, calc_method, constituent_name, grid, scale_fac=100, legend_scale=0.1, figsize=(9, 9))[source]

Plot differences as circles of varying radius on a map of the model domain.

Parameters:
  • diffs (numpy array) – Differences calculated between measured and modelled values [m].
  • meas_wl_harm (numpy array) – Measured water level harmonics read in from csv.
  • calc_method (str) – Method for calculating differences (‘F95’ or ‘M04’)
  • constituent_name (str) – Name of tidal constituent. Used as subplot title.
  • grid (Netcdf dataset) – Netcdf file of grid data.
  • scale_fac (float) – Scale factor to make difference dots visible on map.
  • legend_scale – Size of legend sot; [cm].
  • figsize (2-tuple) – Figure size, (width, height).
Returns:

Figure containing plots of observed vs. modelled amplitude and phase of the tidal constituent.

Return type:

Matplotlib figure

salishsea_tools.tidetools.plot_meas_mod_locations(measlon, measlat, modlon, modlat, X, Y, bathy)[source]

Plot two locations on a contour map of bathymetry, where bathy, X and Y are returned from get_bathy_data(grid); e.g. plot_meas_mod_locations(-124.0, 48.4, -124.2, 48.1,X,Y,bathy)

Parameters:
  • measlon (float) – longitude of point 1
  • measlat (float) – latitude of point 1
  • modlon (float) – longitude of point 2
  • modlat (float) – latitude of point 2
  • X (numpy array) – specified model longitude
  • Y (numpy array) – specified model latitude
  • bathy (numpy array) – model bathymetry
Returns:

plots contour plot with 2 points

salishsea_tools.tidetools.plot_pha_map(X, Y, grid, pha, constituent_name, figsize=(9, 9))[source]

Plot the phase of one constituent throughout the whole domain.

Parameters:
  • X (numpy array) – specified model longitude
  • Y (numpy array) – specified model latitude
  • pha (numpy array) – phase
  • constituent_name (str) – Name of tidal constituent. Used as subplot title.
  • figsize (2-tuple) – Figure size, (width, height).
Returns:

Figure containing plots of observed vs. modelled amplitude and phase of the tidal constituent.

Return type:

Matplotlib figure

salishsea_tools.tidetools.plot_scatter_pha_amp(Am, Ao, gm, go, constituent_name, figsize=(12, 6), split1=0, split2=0, labels=['', '', ''])[source]

Plot scatter plot of observed vs. modelled phase and amplitude

Parameters:
  • Am (Numpy array) – Modelled amplitude.
  • Ao (NumPy array) – Observed amplitude.
  • gm (NumPy array) – Modelled phase.
  • go (NumPy array) – Observed phase.
  • constituent_name (str) – Name of tidal constituent. Used as subplot title.
  • figsize (2-tuple) – Figure size, (width, height).
  • split1 (int) – Change colors at this point in array, if > 0
  • split2 (int) – Change colors at this point in array, if > 0
  • labels (list of strings) – Labels for three different splits
Returns:

Figure containing plots of observed vs. modelled amplitude and phase of the tidal constituent.

Return type:

Matplotlib figure

salishsea_tools.tidetools.plot_wlev_const_transect(savename, statnums, runname, loc, grid, *args)[source]

Plot water level of the modelled M2 and K1 constituents and measured M2 and K1 constituents in a transect at specified stations e.g. plot_wlev_const_transect(‘40d’,’/ocean/klesouef/meopar/)

Parameters:
  • savename (str) – tag for saving the pdf pics
  • statnums (numpy array) – array of station numbers
  • runname (str) – unique name of run
  • loc (str) – location of model results
  • grid (netcdf dataset) – netcdf dataset of model grid
  • args (str) – other runname and results location strings, in case you want to plot more than set of model results on the same figure
Returns:

plots transect of M2 and K1 water level constituent

salishsea_tools.tidetools.plot_wlev_transect_map(grid, stn_nums, stn_file='obs_tidal_wlev_const_all.csv', figsize=(9, 9))[source]

Plot a map of the coastline and the transect of water level stations, which are plotted in plot_wlev_M2_const_transect().

Parameters:
  • grid (netcdf dataset) – Bathymetry file.
  • stn_nums (numpy array) – Station numbers to plot.
  • stn_file (str) – Name of file containing tidal observation station names, lats/lons, and tidal component amplitudes and phases.
  • figsize (2-tuple) – Figure size, (width, height).
Returns:

Figure containing plots of observed vs. modelled amplitude and phase of the tidal constituent.

Return type:

Matplotlib figure

salishsea_tools.tidetools.quadruple(x, M2amp, M2pha, K1amp, K1pha, S2amp, S2pha, O1amp, O1pha, mean)[source]
Function for the fit, assuming only 4 constituents of importance are:
M2, K2, S1 and O1.
Parameters:
  • x – Independent variable, time.
  • *amp (float) – Tidal amplitude of the a constituent
  • *pha (float) – Phase lag of a constituent
Returns:

function for fitting 4 frequencies

salishsea_tools.tidetools.read_dfo_wlev_file(filename)[source]

Read in the data in the csv file downloaded from DFO website

Parameters:filename (str) – Filename to read.
Returns:measured time, measured water level, station name, station number, station lat, station long
salishsea_tools.tidetools.sextuple(x, M2amp, M2pha, K1amp, K1pha, S2amp, S2pha, O1amp, O1pha, N2amp, N2pha, P1amp, P1pha, mean)[source]

Function for the fit, assuming 6 constituents of importance are: M2, K2, S1, O1, N2 and P1.

Parameters:
  • x – Independent variable, time.
  • *amp (float) – Tidal amplitude of the a constituent
  • *pha (float) – Phase lag of a constituent
Returns:

function for fitting 6 frequencies

timeseries_tools Module

A library of Python functions for loading SalishSeaCast timeseries while conserving memory.

salishsea_tools.timeseries_tools.load_NEMO_timeseries(filenames, mask, field, dim, index=0, spacing=1, shape='grid', unstagger_dim=None)[source]
salishsea_tools.timeseries_tools.make_filename_list(timerange, qty, model='nowcast', resolution='h', path='/results/SalishSea')[source]

Return a sequential list of Nowcast results filenames to be passed into xarray.open_mfdataset or timeseries_tools.load_NEMO_timeseries.

Parameters:
  • timerange (list or tuple of str) – list or tuple of date strings (e.g., [‘2017 Jan 1 00:00’, ‘2017 Jan 31 23:00’])
  • qty (str) – quantity type (‘U’ for zonal velocity, ‘V’ for meridional velocity, ‘W’ for vertical velocity, ‘T’ for tracers)
  • model (str) – forecast type (e.g., ‘nowcast’, ‘nowcast-green’, ‘forecast’)
  • resolution (str) – time resolution (‘h’ for hourly, ‘d’, for daily)
  • path (str) – path to results archive
Returns:

Sequential list of Nowcast results filenames

Return type:

list of str

salishsea_tools.timeseries_tools.reshape_coords(mask_in, dim_in, index=0, spacing=1)[source]

Prepare the mask and grid for the selected timeseries slice, and reshape into 1 spatial dimension

salishsea_tools.timeseries_tools.reshape_coords_GEM(grid, mask_in)[source]
salishsea_tools.timeseries_tools.reshape_to_grid(data_flat, coords, shape)[source]
salishsea_tools.timeseries_tools.reshape_to_ts(data_grid, mask, ngrid, ngrid_water, spacing=1)[source]

unit_conversions Module

Salish Sea NEMO model unit conversion functions and constants.

salishsea_tools.unit_conversions.psu_teos(psu)[source]

Convert salinity in practical salinity units (psu) to TEOS-10 reference salinity in g/kg.

Parameters:psu (float, numpy.ndarray, list, or tuple) – Practical salinity units (psu) value to convert.
Returns:TEOS-10 reference salinity in g/kg.
Return type:float or numpy.ndarray
salishsea_tools.unit_conversions.teos_psu(teos)[source]

Convert TEOS-10 reference salinity in g/kg to salinity in practical salinity units (psu).

Parameters:teos (float, numpy.ndarray, list, or tuple) – TEOS-10 reference salinity value [g/kg] to convert.
Returns:Practical salinity units (psu) value.
Return type:float or numpy.ndarray
salishsea_tools.unit_conversions.M_PER_S__KM_PER_HR = 3.6

Conversion factor from m/s to km/hr

salishsea_tools.unit_conversions.M_PER_S__KNOTS = 1.9438444924406046

Conversion factor from m/s to knots

salishsea_tools.unit_conversions.mps_kph(m_per_s)[source]

Convert speed from m/s to km/hr.

m_per_s may be either a scalar number or a numpy.ndarray object, and the return value will be of the same type.

Parameters:m_per_s – Speed in m/s to convert.
Returns:Speed in km/hr.
salishsea_tools.unit_conversions.mps_knots(m_per_s)[source]

Convert speed from m/s to knots.

m_per_s may be either a scalar number or a numpy.ndarray object, and the return value will be of the same type.

Parameters:m_per_s – Speed in m/s to convert.
Returns:Speed in knots.
salishsea_tools.unit_conversions.wind_to_from(wind_to)[source]

Convert wind bearing from “physics” compass “to” direction to “human”compass “from” direction.

“Physics” compass has zero at the east and bearing angles increase in the counter-clockwise direction.

“Human” compass has zero at the north and bearing angles increase in the clockwise direction.

Example: 0° on the physics compass indicates air flow to the east which is called a west (270°) wind on the human compass.

wind_to may be either a scalar number or a numpy.ndarray object, and the return value will be of the same type.

Parameters:wind_to – Bearing on physics (to) compass to convert.
Returns:Bearing on human (from) compass.
salishsea_tools.unit_conversions.bearing_heading(bearing, headings=('N', 'NNE', 'NE', 'ENE', 'E', 'ESE', 'SE', 'SSE', 'S', 'SSW', 'SW', 'WSW', 'W', 'WNW', 'NW', 'NNW', 'N'))[source]

Convert a compass bearing to a heading.

Parameters:
  • bearing (float) – The compass bearing to convert.
  • headings (sequence) – A sequence of headings to convert the bearing to. The default is the 16 compass points that divide the compass into 22.5° segments.
Returns:

Compass heading.

Return type:

str

salishsea_tools.unit_conversions.humanize_time_of_day(date_time)[source]

Return a “humanized” time of day string like “early Monday afternoon” that corresponds to date_time.

We use the same terminology as is used in the Environment Canada weather forecasts: https://www.ec.gc.ca/meteo-weather/default.asp?lang=En&n=10220A6B-1#c4

Parameters:date_time (arrow.Arrow) – Date/time to humanize.
Returns:Humanized time of day and day name; e.g. early Monday afternoon
Return type:str

utilities Module

A library of basic utility Python functions

salishsea_tools.utilities.findnamelist(namelist, year, month, day, pathname='/results/SalishSea/nowcast-green')[source]

Find the most recent namelist from a results file.

arg str namelist: name of the namelist you are looking for

arg int year: year

arg int month: month

arg int day: day

arg int pathname: pathname to the results directory

salishsea_tools.utilities.statusbar(message, width=None, maxval=None)[source]

visualisations Module

Functions for common model visualisations

salishsea_tools.visualisations.contour_layer_grid(axes, data, mask, clevels=10, lat=None, lon=None, cmap=None, var_name=None, land_colour='burlywood', is_depth_avg=False, is_pcolmesh=False, title='', cbar_args=None)[source]

Contour 2d data at an arbitrary klevel on the model grid

Parameters:
  • axes (matplotlib.axes.Axes) – Axes instance to plot thalweg contour on.
  • data (numpy.ndarray) – 2D array to be contoured at level k
  • klev (int) – Index of k-level along which to contour
  • mask (numpy.ndarray) – Mask array with same dimensions as data
  • clevels (str or int or iterable) – argument for determining contour levels. Choices are 1. an integer N, for N automatically determined levels. 2. a sequence V of contour levels, which must be in increasing order.
  • lon (numpy.ndarray) – Array of longitudes with same length as x dimension of data.
  • lat (numpy.ndarray) – Array of longitudes with same length as x dimension of data.
  • cmap (str) – matplotlib colormap
  • var_name (str) – Name of variable to plot. Necesssary if cmap=None.
  • land_colour (str) – matplotlib colour for land
  • is_depth_avg (boolean) – True if data is a depth averaged field (default is False).
  • is_pcolmesh (boolean) – plot a pcolormesh (True) instead of a contourf (default).
  • title (str) – Title string
  • cbar_args (dict) – Additional arguments to be passed to the cbar function (fraction, pad, etc.)
Returns:

matplotlib colorbar object

salishsea_tools.visualisations.contour_thalweg(axes, var, bathy, mesh_mask, clevels=None, mesh_mask_depth_var='gdept_0', cmap='hsv', land_colour='burlywood', xcoord_distance=True, thalweg_file='/data/nsoontie/MEOPAR/tools/bathymetry/thalweg_working.txt', cbar_args=None, mesh_args=None, method='contourf')[source]

Contour the data stored in var along the domain thalweg.

Parameters:
  • axes (matplotlib.axes.Axes) – Axes instance to plot thalweg contour on.
  • var (numpy.ndarray) – Salish Sea NEMO model results variable to be contoured
  • bathy (netCDF4.Dataset) – Salish Sea NEMO model bathymetry dataset
  • mesh_mask (netCDF4.Dataset) – Salish Sea NEMO model mesh_mask dataset
  • clevels (str or int or iterable) – argument for determining contour levels. Choices are 1. ‘salinity’ or ‘temperature’ for pre-determined levels used in nowcast. 2. an integer N, for N automatically determined levels. 3. a sequence V of contour levels, which must be in increasing order.
  • mesh_mask_depth_var (str) – name of depth variable in mesh_mask that is appropriate for var; defaults to gdept_0 for NEMO-3.6 tracer variables.
  • cmap (str) – matplotlib colormap
  • land_colour (str) – matplotlib colour for land
  • xcoord_distance (boolean) – plot along thalweg distance (True) or index (False)
  • thalweg_pts_file (str) – Path and file name to read the array of thalweg grid points from.
  • cbar_args (dict) – Additional arguments to be passed to the cbar function (fraction, pad, etc.)
  • mesh_args (dict) – Additional arguments to be passed to the contourf or pcolormesh function
: arg string method: method to use for data display: defaults to
‘contourf’ but ‘pcolormesh’ is also accepted
Returns:matplotlib colorbar object
salishsea_tools.visualisations.create_figure(ax, DATA, coords='map', window=[-125, -122.5, 48, 50])[source]

Boilerplate figure code like coastline, aspect ratio, axis lims, etc.

Note

This function is deprecated. Call plot formatting functions individually instead.

salishsea_tools.visualisations.load_thalweg(depths, var, lons, lats, thalweg_pts)[source]

Returns depths, cumulative distance and variable along thalweg.

Parameters:
  • depths (numpy.ndarray) – depth array for variable. Can be 1D or 3D.
  • var (numpy.ndarray) – 3D Salish Sea NEMO model results variable
  • lons (numpy.ndarray) – Salish Sea NEMO model longitude grid data
  • lats (numpy.ndarray) – Salish Sea NEMO model latitude grid data
  • thalweg_pts (2D numpy array) – Salish Sea NEMO model grid indices along thalweg
Returns:

dep_thal, xx_thal, var_thal, all the same shape (depth, thalweg length)

salishsea_tools.visualisations.plot_drifters(ax, DATA, DRIFT_OBJS=None, color='red', cutoff=24, zorder=15)[source]

Plot a drifter track from ODL Drifter observations.

Parameters:
  • time_ind (str or datetime.datetime) – Time index (current drifter position, track will be visible up until this point, ex. ‘YYYY-mmm-dd HH:MM:SS’, format is flexible)
  • ax (matplotlib.pyplot.axes) – Axis object
  • DATA (xarray.Dataset) – Drifter track dataset
  • color (str) – Drifter track color
  • cutoff (integer) – Time threshold for color plotting (hours)
  • zorder (integer) – Plotting layer specifier
Returns:

Dictionary of line objects

Return type:

dict > matplotlib.lines.Line2D

salishsea_tools.visualisations.plot_tracers(ax, qty, DATA, C=None, coords='map', clim=[0, 35, 1], cmap='jet', zorder=0)[source]

Plot a horizontal slice of NEMO tracers as filled contours.

Note

This function is deprecated. Plot NEMO results directly using matplotlib.pyplot.contourf or equivalent instead.

salishsea_tools.visualisations.plot_velocity(ax, model, DATA, Q=None, coords='map', processed=False, spacing=5, mask=True, color='black', scale=20, headwidth=3, linewidth=0, zorder=5)[source]

Plot a horizontal slice of NEMO or GEM velocities as quiver objects. Accepts subsampled u and v fields via the processed keyword argument.

Note

This function is deprecated. Plot NEMO results directly using matplotlib.pyplot.quiver or equivalent instead.

salishsea_tools.visualisations.retrieve_cmap(varname, deep_bool)[source]

takes 2 args: string varname - name of a variable from nowcast-green output boolean deep_bool - indicates whether the variable is depth-integrated or not returns 2 ints(min and max value of range), and string identifying cmap

viz_tools Module

A collection of Python functions to do routine tasks associated with plotting and visualization.

salishsea_tools.viz_tools.calc_abs_max(array)[source]

Return the maximum absolute value in the array.

Parameters:array (numpy.ndarray or netCDF4.Dataset) – Array to find the maximum absolute value of.
Returns:Maximum absolute value
Return type:numpy.float32
salishsea_tools.viz_tools.clear_contours(C)[source]

Clear contours from an existing plot.

Parameters:C (matplotlib.contour.QuadContourSet) – contour object handle
salishsea_tools.viz_tools.plot_boundary(ax, grid, mask, dim='depth', index=0, coords='grid', color='burlywood', zorder=10)[source]

Plot the land boundary for a given NEMO domain slice.

Parameters:
  • ax (matplotlib.axes._subplots.AxesSubplot) – axes object handle
  • grid (xarray.DataSet) – NEMO grid variables
  • mask (xarray.DataSet) – NEMO mask variables
  • dim (str) – dimension for slice (one of ‘depth’, ‘x’, or ‘y’)
  • index (int or float) – slice index (integer for ‘x’ or ‘y’, float for ‘depth’)
  • coords (str) – ‘map’ or ‘grid’
  • color (str) – land color
  • zorder (int) – desired vertical plot layer
Returns:

land and coastline contour object handles

Return type:

matplotlib.contour.QuadContourSet

salishsea_tools.viz_tools.plot_coastline(axes, bathymetry, coords='grid', isobath=0, xslice=None, yslice=None, color='black', server='local', zorder=2)[source]

Plot the coastline contour line from bathymetry on the axes.

The bathymetry data may be specified either as a file path/name, or as a netCDF4.Dataset instance. If a file path/name is given it is opened and read into a netCDF4.Dataset so, if this function is being called in a loop, it is best to provide it with a bathymetry dataset to avoid the overhead of repeated file reads.

Parameters:
  • axes (matplotlib.axes.Axes) – Axes instance to plot the coastline contour line on.
  • bathymetry (str or netCDF4.Dataset) – File path/name of a netCDF bathymetry data file or a dataset object containing the bathymetry data.
  • coords (str) – Type of plot coordinates to set the aspect ratio for; either grid (the default) or map.
  • isobath (float) – Depth to plot the contour at; defaults to 0.
  • xslice (numpy.ndarray) – X dimension slice to defined the region for which the contour is to be calculated; defaults to None which means the whole domain. If an xslice is given, a yslice value is also required.
  • yslice (numpy.ndarray) – Y dimension slice to defined the region for which the contour is to be calculated; defaults to None which means the whole domain. If a yslice is given, an xslice value is also required.
  • color (str, float, rgb or rgba tuple) – Matplotlib colour argument
  • zorder (integer) – Plotting layer specifier
Returns:

Contour line set

Return type:

matplotlib.contour.QuadContourSet

salishsea_tools.viz_tools.plot_land_mask(axes, bathymetry, coords='grid', isobath=0, xslice=None, yslice=None, color='black', server='local', zorder=1)[source]

Plot land areas from bathymetry as solid colour polygons on the axes.

The bathymetry data may be specified either as a file path/name, or as a netCDF4.Dataset instance. If a file path/name is given it is opened and read into a netCDF4.Dataset so, if this function is being called in a loop, it is best to provide it with a bathymetry dataset to avoid the overhead of repeated file reads.

Parameters:
  • axes (matplotlib.axes.Axes) – Axes instance to plot the land mask polygons on.
  • bathymetry (str or netCDF4.Dataset) – File path/name of a netCDF bathymetry data file or a dataset object containing the bathymetry data.
  • coords (str) – Type of plot coordinates to set the aspect ratio for; either grid (the default) or map.
  • isobath (float) – Depth to plot the land mask at; defaults to 0.
  • xslice (numpy.ndarray) – X dimension slice to defined the region for which the land mask is to be calculated; defaults to None which means the whole domain. If an xslice is given, a yslice value is also required.
  • yslice (numpy.ndarray) – Y dimension slice to defined the region for which the land maks is to be calculated; defaults to None which means the whole domain. If a yslice is given, an xslice value is also required.
  • color (str, float, rgb or rgba tuple) – Matplotlib colour argument
  • zorder (integer) – Plotting layer specifier
Returns:

Contour polygon set

Return type:

matplotlib.contour.QuadContourSet

salishsea_tools.viz_tools.rotate_vel(u_in, v_in, origin='grid')[source]

Rotate u and v component values to either N-S or model grid.

The origin argument sets the input coordinates (‘grid’ or ‘map’)

Parameters:
  • u_in (numpy.ndarray) – u velocity component values
  • v_in (numpy.ndarray) – v velocity component values
  • origin (str) – Input coordinate system (either ‘grid’ or ‘map’, output will be the other)
Returns u_out, v_out:
 

rotated u and v component values

Return type:

numpy.ndarray

salishsea_tools.viz_tools.set_aspect(axes, aspect=1.1363636363636362, coords='grid', lats=None, adjustable='box-forced')[source]

Set the aspect ratio for the axes.

This is a thin wrapper on the matplotlib.axes.Axes.set_aspect() method. Its primary purpose is to free the user from needing to remember the 5/4.4 nominal aspect ratio for the Salish Sea NEMO model grid, and the formula for the aspect ratio based on latitude for map coordinates. It also sets the axes aspect ratio with adjustable='box-forced' so that the axes can be shared if desired.

Parameters:
  • axes (matplotlib.axes.Axes) – Axes instance to set the aspect ratio of.
  • aspect (float) – Aspect ratio.
  • coords (str) – Type of plot coordinates to set the aspect ratio for; either grid (the default) or map.
  • lats (numpy.ndarray) – Array of latitude values to calculate the aspect ratio from; only required when coordinates='map'.
  • adjustable (str) – How to adjust the axes box.
Returns:

Aspect ratio.

Return type:

float

Note

To explicitly set the aspect ratio for map coordinates (instead of calculating it from latitudes) set aspect to the aspect ratio, coords='map', and use the default lats=None.

salishsea_tools.viz_tools.unstagger(ugrid, vgrid)[source]

Interpolate u and v component values to values at grid cell centres.

The shapes are the returned arrays are 1 less than those of the input arrays in the y and x dimensions.

Parameters:
  • ugrid (numpy.ndarray) – u velocity component values with axes (…, y, x)
  • vgrid (numpy.ndarray) – v velocity component values with axes (…, y, x)
Returns u, v:

u and v component values at grid cell centres

Return type:

2-tuple of numpy.ndarray

salishsea_tools.viz_tools.unstagger_xarray(qty, index)[source]

Interpolate u, v, or w component values to values at grid cell centres.

Named indexing requires that input arrays are XArray DataArrays.

Parameters:
  • qty (xarray.DataArray) – u, v, or w component values
  • index (str) – index name along which to centre (generally one of ‘gridX’, ‘gridY’, or ‘depth’)
Returns qty:

u, v, or w component values at grid cell centres

Return type:

xarray.DataArray

wind_tools Module

Functions for working with wind model results and wind observations data.

salishsea_tools.wind_tools.calc_wind_avg_at_point(date_time, weather_path, windji, avg_hrs=-4)[source]

Calculate the average wind components for a time period at a single weather dataset grid point.

Note

The present implementation only supports averaging over a time period ending at:kbd:date_time and values for avg_hrs in the range [-24, 0].

Parameters:
  • date_time (arrow.arrow.Arrow) – Date and time to use as base for the calculation.
  • weather_path (str) – The directory where weather dataset files are stored.
  • windji (2-tuple) – Indices of weather dataset grid point to calculate the average at as (lon_index, lat_index).
  • avg_hrs (float) – Number of hours to calculate
Returns:

2-tuple containing the averaged wind components. The u attribute holds the u-direction component, and the v attribute holds the v-direction component.

Return type:

collections.namedtuple

Raises:

IndexError if avg_hrs is outside the range [-24, 0].

salishsea_tools.wind_tools.mps_kph(m_per_s)[source]

Convert speed from m/s to km/hr.

m_per_s may be either a scalar number or a numpy.ndarray object, and the return value will be of the same type.

Parameters:m_per_s – Speed in m/s to convert.
Returns:Speed in km/hr.
salishsea_tools.wind_tools.mps_knots(m_per_s)[source]

Convert speed from m/s to knots.

m_per_s may be either a scalar number or a numpy.ndarray object, and the return value will be of the same type.

Parameters:m_per_s – Speed in m/s to convert.
Returns:Speed in knots.
salishsea_tools.wind_tools.wind_to_from(wind_to)[source]

Convert wind bearing from “physics” compass “to” direction to “human”compass “from” direction.

“Physics” compass has zero at the east and bearing angles increase in the counter-clockwise direction.

“Human” compass has zero at the north and bearing angles increase in the clockwise direction.

Example: 0° on the physics compass indicates air flow to the east which is called a west (270°) wind on the human compass.

wind_to may be either a scalar number or a numpy.ndarray object, and the return value will be of the same type.

Parameters:wind_to – Bearing on physics (to) compass to convert.
Returns:Bearing on human (from) compass.
salishsea_tools.wind_tools.bearing_heading(bearing, headings=('N', 'NNE', 'NE', 'ENE', 'E', 'ESE', 'SE', 'SSE', 'S', 'SSW', 'SW', 'WSW', 'W', 'WNW', 'NW', 'NNW', 'N'))[source]

Convert a compass bearing to a heading.

Parameters:
  • bearing (float) – The compass bearing to convert.
  • headings (sequence) – A sequence of headings to convert the bearing to. The default is the 16 compass points that divide the compass into 22.5° segments.
Returns:

Compass heading.

Return type:

str

salishsea_tools.wind_tools.wind_speed_dir(u_wind, v_wind)[source]

Calculate wind speed and direction from u and v wind components.

u_wind and v_wind may be either scalar numbers or numpy.ndarray objects, and the elements of the return value will be of the same type.

Parameters:
  • u_wind – u-direction component of wind vector.
  • v_wind – v-direction component of wind vector.
Returns:

2-tuple containing the wind speed and direction. The speed attribute holds the wind speed(s), and the dir attribute holds the wind direction(s).

Return type:

collections.namedtuple