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)

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)

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)

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)

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')

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')

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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

bio_tools Module

Functions for working with geographical data and model results.

salishsea_tools.bio_tools.calc_p_limiters(I, NO, NH, Si, tmask, nampisprod)

Calculate limiting factor: I, Si, or N based on SMELT output

Parameters:

• I – np.array slice of PAR from dia file

• NO – “ nitrate

• NH – “ ammonia

• Si – “ silicate

• tmask – np.array containing appropriate tmask sliced to same size

• nampisprod – namelist dict loaded using load_nml_bio with argument nampisprod

salishsea_tools.bio_tools.load_nml_bio(resDir, nmlname, bioRefName='namelist_smelt_ref', bioCfgName='namelist_smelt_cfg', namRefDir=None)

extract parameter values from smelt namelists for nampisbio :arg str resDir: directory containing namelists associated with run; usually results diri :arg str nmlname name of namelist to load: eg, ‘nampisprod’ :arg str bioRefName: name of bio reference namelist (optional) :arg str bioCfgName: name of bio config namelist (optional) :arg str namRefDir: dir to get ref namelist from if not in results dir (optional)

data_tools Module

Functions for loading and processing observational data

salishsea_tools.data_tools.get_chs_tide_stn_id(stn, api_server='https://api-iwls.dfo-mpo.gc.ca', api_version='v1', retry_args={'stop_max_delay': 36000, 'wait_exponential_max': 30000, 'wait_exponential_multiplier': 1000})

Get a CHS tide gauge station id corresponding to a station number or name.

Station names are resolved to station codes by resolve_chs_tide_stn(). Station codes are resolved to station ids by requests to the CHS Integrated Water Level System API stations endpoint.

API docs: https://api-iwls.dfo-mpo.gc.ca/v3/api-docs/v1

The station id returned is a UUID hash string for use in other API requests.

Parameters:

• stn (int or str) – Tide gauge station number or name.

• api_server (str) – API server URL.

• api_version (str) – API version identifier.

• 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, to a maximum of 10 minutes of retrying. See https://pypi.python.org/pypi/retrying for a full discussion of the parameters available to control retrying.

Returns:

Station id, or none if station name cannot be resolved.

Return type:

str or None

salishsea_tools.data_tools.get_chs_tides(data_type, stn, begin, end, api_server='https://api-iwls.dfo-mpo.gc.ca', api_version='v1', retry_args={'stop_max_delay': 36000, 'wait_exponential_max': 30000, 'wait_exponential_multiplier': 1000})

Retrieve a time series of observed or predicted water levels for a CHS recording tide gauge station from the Integrated Water Level System API web service for the date/time range given by begin and end.

API docs: https://api-iwls.dfo-mpo.gc.ca/v3/api-docs/v1

The values of begin and end, and the returned time series date/time index are all UTC.

Water levels are relative to chart datum for the station requested.

The time series is returned as a pandas.Series object.

Parameters:

• data_type (str) – Type of data to retrieve; obs or pred.

• stn (int or str) – Tide gauge station number or name. Names use PLACES to look up the station number.

• begin (str or arrow.Arrow) – UTC beginning date or date/time for data request. If a date only is used the time defaults to 00:00:00.

• end (str or arrow.Arrow) – UTC end date or date/time for data request. If a date only is used the time defaults to 00:00:00.

• api_server (str) – API server URL.

• api_version (str) – API version identifier.

• 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, to a maximum of 10 minutes of retrying. See https://pypi.python.org/pypi/retrying for a full discussion of the parameters available to control retrying.

Returns:

Water level time series.

Return type:

pandas.Series

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

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

See https://wiki.oceannetworks.ca/display/O2A/Oceans+3.0+API+Home 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/O2A/Oceans+3.0+API+Home for available web service end-points.

• method (str) – ONC web service method; e.g. getByStation. See https://wiki.oceannetworks.ca/display/O2A/Oceans+3.0+API+Home 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 https://data.oceannetworks.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)

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 data.oceannetworks.ca account.

Return type:

str

salishsea_tools.data_tools.get_onc_sog_adcp_search_status(search_hdr_id, userid)

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 data.oceannetworks.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)

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/')

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')

Loads drifter coordinates and times from the ODL Drifters Project.

UBC Ocean Dynamics Laboratory Drifters Project https://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)

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')

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)

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 produced 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)

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 data.oceannetworks.ca account.

Returns:

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

Return type:

dict

salishsea_tools.data_tools.resolve_chs_tide_stn(stn)

Resolve a CHS tide gauge station number or name to a station code for use in API requests.

Station names are resolved by lookup in PLACES.

Parameters:

stn (int or str) – Tide gauge station number or name.

Returns:

Station code formatted for API requests, or none if station name cannot be resolved.

Return type:

str or None

diagnosis_tools Module

salishsea_tools.diagnosis_tools.pcourantu(files, meshmask)

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)

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)

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

ellipse_tools Module

A collection of tools for dealing with tidal ellipse calculations.

salishsea_tools.ellipse.ellipse_files_nowcast(to, tf, iss, jss, path, depthrange='None', period='1h', station='None')

This function loads all the data between the start and the end date that contains in the netCDF4 nowcast files in the specified depth range. This will make an area with all the indices indicated, the area must be continuous for unstaggering.

Parameters:

• to (datetime object) – The beginning of the date range of interest

• tf (datetime object) – The end of the date range of interest

• iss – x index.

• jss – y index.

• path (string) – Defines the path used(eg. nowcast)

• depthrange (float, string or list.) – Depth values of interest in meters as a float for a single depth or a list for a range. A float will find the closest depth that is <= the value given. Default is ‘None’ for the whole water column (0-441m).

• period (string - '1h' for hourly results or '15m' for 15 minute) – period of the results files

• station (string 'None' if not applicable. 'ddl', 'east' or 'central') – station for analysis

Returns:

u, v, time, dep.

salishsea_tools.ellipse.ellipse_params(uamp, upha, vamp, vpha)

Calculates ellipse parameters based on the amplitude and phase for a tidal constituent.

Parameters:

• uamp (numpy.ndarray) – u fitted amplitude of the chosen constituent

• upha (numpy.ndarray) – u fitted phase of the chosen constituent

• vamp (numpy.ndarray) – v fitted amplitude of the chosen constituent

• vpha (numpy.ndarray) – v fitted phase of the chosen constituent

Returns:

CX, SX, CY, SY, ap, am, ep, em, major, minor, theta, phase The positively and negatively rotating amplitude and phase. As well as the major and minor axis and the axis tilt.

salishsea_tools.ellipse.get_params(u, v, time, nconst, tidecorr={'K1': {'freq': 15.041069, 'ft': 0.891751, 'uvt': 262.636797}, 'K2': {'freq': 30.082138, 'ft': 0.763545, 'uvt': 344.740346}, 'M2': {'freq': 28.984106, 'ft': 1.03539, 'uvt': 346.11449}, 'N2': {'freq': 28.43973, 'ft': 1.03539, 'uvt': 310.920296}, 'O1': {'freq': 13.943036, 'ft': 0.822543, 'uvt': 81.47243}, 'P1': {'freq': 14.958932, 'ft': 1.0, 'uvt': 101.04216}, 'Q1': {'freq': 13.398661, 'ft': 0.822543, 'uvt': 46.278236}, 'S2': {'freq': 30.000002, 'ft': 1.0, 'uvt': 0.0}, 'reftime': datetime.datetime(2014, 9, 10, 0, 0, tzinfo=tzutc())})

Calculates tidal ellipse parameters from the u and v time series. Maintains the shape of the velocities enters only loosing the time dimensions.

Parameters:

• u (:py:class:'np.ndarray') – One of the orthogonal tidal current velocities. Must be already prepared for the analysis.

• v (:py:class:'np.ndarray') – One of the orthogonal tidal current velocities. Must be already prepared for the analysis.

• time (:py:class:'np.ndarray') – Time over which the velocities were 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.

• tidecorr (dictionary) – Tidal corrections in aplitude and phase. Default is the nowcast values.

Returns:

params a dictionary containing the tidal ellipse parameter of the chosen constituents

salishsea_tools.ellipse.get_params_nowcast(to, tf, i, j, path, nconst, depthrange='None', depav=False, tidecorr={'K1': {'freq': 15.041069, 'ft': 0.891751, 'uvt': 262.636797}, 'K2': {'freq': 30.082138, 'ft': 0.763545, 'uvt': 344.740346}, 'M2': {'freq': 28.984106, 'ft': 1.03539, 'uvt': 346.11449}, 'N2': {'freq': 28.43973, 'ft': 1.03539, 'uvt': 310.920296}, 'O1': {'freq': 13.943036, 'ft': 0.822543, 'uvt': 81.47243}, 'P1': {'freq': 14.958932, 'ft': 1.0, 'uvt': 101.04216}, 'Q1': {'freq': 13.398661, 'ft': 0.822543, 'uvt': 46.278236}, 'S2': {'freq': 30.000002, 'ft': 1.0, 'uvt': 0.0}, 'reftime': datetime.datetime(2014, 9, 10, 0, 0, tzinfo=tzutc())})

This function loads all the data between the start and the end date that contains hourly velocities in the netCDF4 nowcast files in the specified depth range. Then masks, rotates and unstaggers the time series. The unstaggering causes the shapes of the returned arrays to be 1 less than those of the input arrays in the y and x dimensions. Finally it calculates tidal ellipse parameters from the u and v time series. Maintains the shape of the velocities enters only loosing the time dimensions.

Parameters:

• to (datetime object) – The beginning of the date range of interest

• tf (datetime object) – The end of the date range of interest

• i (float or list) – x index, must have at least 2 values for unstaggering, will loose the first i during the unstaggering in prepare_vel.

• j (float or list) – y index, must have at least 2 values for unstaggering, will loose the first j during the unstaggering in prepare_vel.

• path (string) – Defines the path used(eg. nowcast)

• depthrange – Depth values of interest in meters as a float for a single depth or a list for a range. A float will find the closest depth that is <= the value given. Default is ‘None’ for the whole water column (0-441m).

• depav (boolean) – True will depth average over the whole depth profile given. Default is False.

• depth (:py:class:'np.ndarray' or string) – depth vector corresponding to the depth of the velocities, only requiered if depav=True.

Returns:

params, dep params is dictionary object of the ellipse parameters for each constituent dep is the depths of the ellipse paramters

salishsea_tools.ellipse.get_params_nowcast_15(to, tf, station, path, nconst, depthrange='None', depav=False, tidecorr={'K1': {'freq': 15.041069, 'ft': 0.891751, 'uvt': 262.636797}, 'K2': {'freq': 30.082138, 'ft': 0.763545, 'uvt': 344.740346}, 'M2': {'freq': 28.984106, 'ft': 1.03539, 'uvt': 346.11449}, 'N2': {'freq': 28.43973, 'ft': 1.03539, 'uvt': 310.920296}, 'O1': {'freq': 13.943036, 'ft': 0.822543, 'uvt': 81.47243}, 'P1': {'freq': 14.958932, 'ft': 1.0, 'uvt': 101.04216}, 'Q1': {'freq': 13.398661, 'ft': 0.822543, 'uvt': 46.278236}, 'S2': {'freq': 30.000002, 'ft': 1.0, 'uvt': 0.0}, 'reftime': datetime.datetime(2014, 9, 10, 0, 0, tzinfo=tzutc())})

This function loads all the data between the start and the end date that contains quater houlry velocities in the netCDF4 nowcast files in the depth range. Then masks, rotates and unstaggers the time series. The unstaggering causes the shapes of the returned arrays to be 1 less than those of the input arrays in the y and x dimensions. Finally it calculates tidal ellipse parameters from the u and v time series. Maintains the shape of the velocities enters only loosing the time dimensions.

Parameters:

• to (datetime object) – The beginning of the date range of interest

• tf (datetime object) – The end of the date range of interest

• station (string (East or Central)) – station name for the quater-hourly data

• path (string) – Defines the path used(eg. nowcast)

• depthrange – Depth values of interest in meters as a float for a single depth or a list for a range. A float will find the closest depth that is <= the value given. Default is ‘None’ for the whole water column (0-441m).

• depav (boolean) – True will depth average over the whole depth profile given. Default is False.

• depth (:py:class:'np.ndarray' or string) – depth vector corresponding to the depth of the velocities, only required if depav=True.

Returns:

params, dep params is dictionary object of the ellipse parameters for each constituent dep is the depths of the ellipse paramters

salishsea_tools.ellipse.prepare_vel(u, v, depav=False, depth='None')

Preparing the time series of the orthogonal pair of velocities to get tidal ellipse parameters. This function masks, rotates and unstaggers the time series. The depth averaging does not work over masked values.

Parameters:

• u (:py:class:'np.ndarray') – One of the orthogonal components of the time series of tidal current velocities.

• v (:py:class:'np.ndarray') – One of the orthogonal components of the time series of tidal current velocities.

• depav – True will depth average over the whole depth profile given. Default is False.

• depth (:py:class:'np.ndarray' or string) – depth vector corresponding to the depth of the velocities, only requiered if depav=True.

formatting_tools Module

Functions for formatting data output from datasets.

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

String to LaTeX notation mapping for units

salishsea_tools.formatting_tools.format_units(units)

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.closestPointArray(lons, lats, model_lons, model_lats, tol2=1, grid='NEMO', land_mask=None, tols={'GEM2.5': {'tol_lat': 0.012, 'tol_lon': 0.016}, 'NEMO': {'tol_lat': 0.00388, 'tol_lon': 0.0104}})

Wrapper on find_closest_model_point that is faster if you have many points to locate AND you expect the points to be ordered such that each point is likely close to the point ahead (eg ship track). Returns the grid coordinates of the closest model points as numpy arrays of lons and lats. See find_closest_model_point for more details. For a list of 5000 points on ONC ferry path, speed up was ~95%.

Additional/changed input: :arg float lons: numpy array of longitudes to find closest grid point to

Parameters:

• lats (float) – numpy array of latitudes to find closest grid point to

• tol2: (int) – expected distance in grid cells between one point and the next

Returns:

yinds, xinds: numpy arrays of same shape as input lons

salishsea_tools.geo_tools.distance_along_curve(lons, lats)

Calculate cumulative distance in km between points in lons, lats

Parameters:

• lons (numpy.ndarray) – 1D array of longitude points.

• lats (numpy.ndarray) – 1D array of latitude points.

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={'GEM2.5': {'tol_lat': 0.013, 'tol_lon': 0.018}, 'NEMO': {'tol_lat': 0.004, 'tol_lon': 0.007}, 'continental2.5': {'tol_lat': 0.013, 'tol_lon': 0.018}}, checkTol=False, raiseOutOfBounds=False)

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

• checkTol – optionally check that nearest ocean point is not outside specified tolerances in case that spiral search is called Note: NEMO tols may not be appropriate for warped Fraser R area

• raiseOutOfBounds – optionally raise exception when no point found, but default to previous behaviour (return NaN)

Returns:

yind, xind

salishsea_tools.geo_tools.get_ij_coordinates(lat, lon, grid_loc='~/MEOPAR/grid/grid_from_lat_lon_mask999.nc')

Finds the closest ii and jj model coordinates by matching Latitude and Longitude to the new grid_from_lat_lon_mask999.nc file

Parameters:

• lat (float) – The Latitude of the point in question in decimal degrees.

• lon (float) – The Longitude of the point in question in decimal degrees.

• grid_loc (str) – The location of the grid_from_lat_lon nc file on your system.

salishsea_tools.geo_tools.haversine(lon1, lat1, lon2, lat2)

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

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

Parameters:

• lon1 (float or numpy.ndarray) – Longitude of point 1.

• lat1 (float or numpy.ndarray) – Latitude of point 1.

• lon2 (float or numpy.ndarray) – Longitude of point 2.

• lat2 (float or numpy.ndarray) – Latitude of point 2.

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: https://nbviewer.org/github/SalishSeaCast/analysis-nancy/blob/master/notebooks/energy_flux/Time-dependent%20depth%20and%20scale%20factors%20-%20development.ipynb

Examples of plotting with output: https://nbviewer.org/github/SalishSeaCast/analysis-nancy/blob/master/notebooks/energy_flux/Plotting%20with%20time%20dependent%20depths.ipynb

NKS nsoontie@eos.ubc.ca 08-2016

salishsea_tools.grid_tools.build_matrix(weightsfile, opsfile)

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.calculate_H(e3t0, tmask)

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)

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)

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)

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)

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.use_matrix(opsfile, matrix, nemoshape, variable, time)

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')

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 SalishSeaCast project.

salishsea_tools.hg_commands.commit(logfile)

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)

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=['.'])

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)

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.calculate_Si_from_NO3(NO3, SA, a=6.46, b=1.35, c=0, sigma=1, tsa=29)

Use a simple fit to calculate Si from NO3

Parameters:

• NO3 (array) – 3-D array of nitate values

• SA (array) – 3-D array of absolute salinities

• a (float) – constant in Si from NO3 fit units uM

• b (float) – linear term in Si form NO3 fit units none

• c (float) – magnitude for salinity additional impact units uM

• sigma (float) – 1/width of tanh for salinity impact units /(g/kg)

• tsa (float) – centre of salnity correction units g/kg

Returns:

a 3-D array of silicon values

salishsea_tools.LiveOcean_BCs.convect(sigma, interps)

Convect interps based on density (sigma). Ignores variations in cell depths and convects vertically

Parameters:

• interps (dictionary) – dictionary of 3D numpy arrays. Key represents the variable name.

• sigma (numpy array) – sigma-t, density, 3D array

:returns sigma, interps stabilized

salishsea_tools.LiveOcean_BCs.correct_high_NO3(NO3, smax=100, nmax=120)

Correct LiveOcean nitrates that are higher than smax, so that the largest nitrate is nmax. Defaults cause no correction.

Parameters:

• NO3 (array) – 3-D array of nitrate values

• smax (float) – highest nitrate value corrected

• nmax (float) – maximum nitrate value allowed

Returns:

a 3-D array of corrected nitrate values

salishsea_tools.LiveOcean_BCs.create_LiveOcean_TS_BCs(date, file_template='LiveOcean_v201712_{:y%Ym%md%d}.nc', meshfilename='/results/nowcast-sys/grid/mesh_mask201702.nc', bc_dir='/results/forcing/LiveOcean/boundary_conditions/', LO_dir='/results/forcing/LiveOcean/downloaded/', LO_to_SSC_parameters={'NO3': {'nmax': 120.0, 'smax': 100.0}, 'Si': {'a': 6.46, 'b': 1.35, 'c': 0.0, 'sigma': 1.0, 'tsa': 29}})

Create a Live Ocean boundary condition file for date for use in the NEMO model.

Parameters:

• date (str) – date in format ‘yyyy-mm-dd’

• file_template (str) – filename template for the saved files; it will be formatted with a datetime.

• bc_dir (str) – the directory in which to save the results.

• LO_dir (str) – the directory in which Live Ocean results are stored.

• LO_to_SSC_parameters (dict) – a dictionary of parameters to convert Live Ocean values to Salish Sea Cast

Returns:

Boundary conditions files that were created.

Return type:

list

salishsea_tools.LiveOcean_BCs.extend_to_depth(interps, maxk=35)

Fill all values below level with LiveOcean data with data from above start at maxk

Parameters:

• interps (dictionary) – dictionary of 3D numpy arrays. Key represents the variable name.

• maxk (int) – maximum Live Ocean depth with data

:returns interps extended to depth

salishsea_tools.LiveOcean_BCs.fill_box(interps, maxk=35)

Fill all NaN in the LiveOcean with nearest points (constant depth), go as far down as maxk

Parameters:

• interps (dictionary) – dictionary of 3D numpy arrays. Key represents the variable name.

• maxk (int) – maximum Live Ocean depth with data

:returns interps with filled values

salishsea_tools.LiveOcean_BCs.interpolate_to_NEMO_depths(dataset, depBC, var_names)

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

• depBC (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(interps, dataset, NEMOlon, NEMOlat, shape)

Interpolates arrays in interps laterally to NEMO grid. Assumes these arrays have already been interpolated vertically. Note that by this point interps should be a full array

Parameters:

• interps (dictionary) – 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(date, LO_dir='/results/forcing/LiveOcean/downloaded/', LO_file='low_passed_UBC.nc')

Load a time series of Live Ocean results represented by a date, location and filename

Parameters:

• date (str) – date as yyyy-mm-dd

• LO_dir (str) – directory of Live Ocean file

• LO_file (str) – Live Ocean filename

Returns:

xarray dataset of Live Ocean results

salishsea_tools.LiveOcean_BCs.load_SalishSea_boundary_grid(imin, imax, rim, meshfilename)

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

Parameters:

• int (rim) – first grid point of western boundary

• int – one past last grid point of western boundary

• int – rim width, note rim starts at second grid point

• str (fname) – name of boundary file

Returns:

numpy arrays depth, lon, lat and a tuple shape

salishsea_tools.LiveOcean_BCs.prepare_dataset(interpl, var_meta, LO_to_NEMO_var_map, depBC, time)

Prepare xarray dataset for Live Ocean file

Parameters:

• interpl (dictionary SSS) – dictionary of 4D numpy arrays. Key represents the variable name.

• var_meta (a dictionary of dictionaries with key-value pairs of metadata) – metadata for each variable in var_arrays. Keys are NEMO variable names.

• LO_to_NEMO_var_map (a dictionary with string key-value pairs) – a dictionary mapping between LO variable names (keys) and NEMO variable names (values)

• depBC (1D numpy array) – NEMO model depths

• time (float) – time from Live Ocean dataset

returns dataset

salishsea_tools.LiveOcean_BCs.remove_south_of_Tatoosh(interps, imask=6, jmask=17)

Removes points south of Tatoosh point because the water masses there are different”

Parameters:

• interps – dictionary of 3D numpy arrays. Key represents the variable name.

• imask (int) – longitude points to be removed

• jmask (int) – latitude points to be removed

Returns:

interps with values south-west of Tatoosh set to Nan.

salishsea_tools.LiveOcean_BCs.stabilize(sigma, interps)

Add a little salt to stabilize marginally stable cells

Parameters:

• interps (dictionary) – dictionary of 3D numpy arrays. Key represents the variable name.

• sigma (numpy array) – sigma-t, density, 3D array

:returns interps stabilized

salishsea_tools.LiveOcean_BCs.write_out_file(ds, date, file_template, bc_dir)

Write out the Live Ocean Data File

Parameters:

• ds (xarray dataset) – xarray dataset containing data

• date (str) – date for file

• file_template (str) – filename template for the saved files; it will be formatted with a datetime.

• bc_dir (str) – directory for boundary condition file

salishsea_tools.LiveOcean_grid.get_basic_info(fn, only_G=False, only_S=False, only_T=False)

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: G, S, T = zfun.get_basic_info(fn) T = zfun.get_basic_info(fn, only_T=True)

salishsea_tools.LiveOcean_grid.get_z(h, zeta, S)

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)

Create subdomain files for all netCDF files in f_list

loadDataFRP Module

salishsea_tools.loadDataFRP.fmtVarName(strx)

transform string into one that meets python naming conventions

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 (https://www.gnu.org/copyleft/lesser.html)

salishsea_tools.namelist.namelist2dict(file_or_file_object)

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)

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)

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)

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)

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)

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_GEM_path(date)

Construct GEM results path given the date e.g., /results/forcing/atmospheric/GEM2.5/operational/ops_yYYYYmMMdDD.nc

Parameters:

date (datetime.datetime) – date of GEM record

Returns:

GEM path

Return type:

str

salishsea_tools.nc_tools.get_WW3_path(date)

Construct WW3 results path given the date e.g., /opp/wwatch3/nowcast/SoG_ww3_fields_YYYYMMDD_YYYYMMDD.nc

Parameters:

date (datetime.datetime) – date of WW3 record

Returns:

WW3 path

Return type:

str

salishsea_tools.nc_tools.get_datetimes(dataset, time_var='time_counter')

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.get_hindcast_prefix(date, res='h', version='201905')

Construct hindcast results prefix given the date, resolution and version e.g., /results/SalishSea/nowcast-green.201905/ddmmmyy/SalishSea_1h_YYYYMMDD_YYYYMMDD

Parameters:

• date (datetime.datetime) – date of hindcast record

• res (str) – time resolution (h=hourly, d=daily)

• version (str) – hindcast version (e.g., 201905)

Returns:

hindcast prefix

Return type:

str

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

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.show_dataset_attrs(dataset)

Print the global attributes of the netCDF dataset.

Parameters:

dataset (netCDF4.Dataset) – netcdf dataset object

salishsea_tools.nc_tools.show_dimensions(dataset)

Print the dimensions of the netCDF dataset.

Parameters:

dataset (netCDF4.Dataset) – netcdf dataset object

salishsea_tools.nc_tools.show_variable_attrs(dataset, *vars)

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)

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, time_var='time_counter', ssh_var='sossheig')

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).

• time_var (str) – Name of time variable.

• ssh_var – Name of sea surface height variable.

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')

Return the time_var.time_origin value.

Parameters:

• dataset (netCDF4.Dataset or xarray.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')

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 iterable) – 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)

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)

Convert an xarray.DataArray of numpy.datetime64 times to a numpy.ndarray of datetime.datetime times

Parameters:

xarraytime (xarray.DataArray of numpy.datetime64) – DataArray of datetime64

Returns:

array of datetimes

Return type:

numpy.ndarray of datetime.datetime

class salishsea_tools.nc_tools.scDataset(files)

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.DispGeoLocs()

Display locations in map coordinates

Returns:

figure handle

Return type:

matplotlib.figure.Figure

salishsea_tools.places.DispGridLocs(mesh_mask='/ocean/eolson/MEOPAR/NEMO-forcing/grid/mesh_mask201702_noLPE.nc')

Display locations in NEMO model grid coordinates

Parameters:

mesh_mask (str) – string with path to the meshmask you would like to plot; 201702 default

Returns:

figure handle

Return type:

matplotlib.figure.Figure

salishsea_tools.places.PLACES = {'2nd Narrows Rail Bridge': {'NEMO grid ji': None, 'lon lat': (-123.0247222, 49.2938889), 'mean sea lvl': None, 'stn number': 3160171, 'wind grid ji': (143, 161), 'ww3 grid ji': None}, 'Ballenas Islands': {'NEMO grid ji': (536, 197), 'lon lat': (-124.16, 49.35), 'wind grid ji': (152, 127)}, 'Baynes Sound': {'NEMO grid ji': (635, 126), 'lon lat': (-124.86022, 49.60356)}, 'Boundary Bay': {'NEMO grid ji': (380, 335), 'hist max sea lvl': 5.61, 'lon lat': (-122.925, 49.0), 'mean sea lvl': 3.09, 'stn number': None, 'wind grid ji': (129, 162), 'ww3 grid ji': (222, 439)}, 'British Columbia': {'lon lat': (-123.6, 49.9)}, 'Calamity Point': {'NEMO grid ji': None, 'lon lat': (-123.1276, 49.31262), 'mean sea lvl': 3.001, 'stn number': 7724, 'wind grid ji': (456, 344), 'ww3 grid ji': None}, 'Campbell River': {'NEMO grid ji': (747, 125), 'hist max sea lvl': 5.35, 'lon lat': (-125.24, 50.04), 'mean sea lvl': 2.916, 'stn number': 8074, 'wind grid ji': (190, 102), 'ww3 grid ji': (453, 109)}, 'CarrInlet': {'NEMO grid ji': (34, 152), 'lon lat': (-122.73, 47.28)}, 'Central SJDF': {'GEM2.5 grid ji': (101, 124), 'NEMO grid ji': (315, 95), 'lon lat': (-123.9534, 48.281677)}, 'Central node': {'NEMO grid ji': (424, 266), 'NEMO grid k': 34, 'ONC stationCode': 'SCVIP', 'depth': 294, 'lon lat': (-123.425825, 49.040066666), 'wind grid ji': (133, 147)}, 'Cherry Point': {'NEMO grid ji': (343, 342), 'hist max sea lvl': 5.846, 'lon lat': (-122.766667, 48.866667), 'mean sea lvl': 3.543, 'stn number': 9449424, 'wind grid ji': (122, 166), 'ww3 grid ji': (193, 462)}, 'Cluster_1': {'NEMO grid ji': (241, 212), 'Vector Stn': '64', 'lon lat': (48.215, -123.099)}, 'Cluster_2': {'NEMO grid ji': (294, 127), 'Vector Stn': '69', 'lon lat': (48.261, -123.717)}, 'Cluster_3': {'NEMO grid ji': (376, 291), 'Vector Stn': '45', 'lon lat': (48.899, -123.138)}, 'Cluster_4': {'NEMO grid ji': (282, 305), 'Vector Stn': '53', 'lon lat': (48.555, -122.75)}, 'Cluster_5': {'NEMO grid ji': (344, 271), 'Vector Stn': '57', 'lon lat': (48.735, -123.135)}, 'Cluster_6': {'NEMO grid ji': (320, 68), 'Vector Stn': '73', 'lon lat': (48.249, -124.11)}, 'Cluster_7': {'NEMO grid ji': (504, 246), 'Vector Stn': '27', 'lon lat': (49.317, -123.801)}, 'Cluster_8': {'NEMO grid ji': (646, 168), 'Vector Stn': '12', 'lon lat': (49.726, -124.679)}, 'Cluster_9': {'NEMO grid ji': (423, 300), 'lon lat': (49.101, -123.249)}, 'Comox Airport': {'NEMO grid ji': (660, 134), 'lon lat': (-124.9, 49.717), 'wind grid ji': (173, 108)}, 'DabobBay': {'NEMO grid ji': (141, 205), 'lon lat': (-122.8029, 47.8031)}, 'Delta BBL node': {'NEMO grid ji': (424, 283), 'NEMO grid k': 28, 'ONC stationCode': 'LSBBL', 'depth': 143, 'lon lat': (-123.339633, 49.074766), 'wind grid ji': (134, 150)}, 'Delta DDL node': {'NEMO grid ji': (426, 286), 'NEMO grid k': 27, 'ONC stationCode': 'USDDL', 'depth': 107, 'lon lat': (-123.32972, 49.08495), 'wind grid ji': (135, 150)}, 'Departure Bay': {'NEMO grid ji': (481, 213), 'lon lat': (-123.8909, 49.1632), 'mean sea lvl': None, 'stn number': None, 'wind grid ji': (142, 134), 'ww3 grid ji': None}, 'Discovery Island': {'NEMO grid ji': (291, 219), 'lon lat': (-123.226, 48.425), 'wind grid ji': (104, 148)}, 'Dockton': {'NEMO grid ji': (34, 204), 'lon lat': (-122.45722, 47.37611)}, 'Duke Pt.': {'NEMO grid ji': (481, 213), 'in berth radius': 0.002, 'lon lat': (-123.89095676900132, 49.16340592936349), 'mean sea lvl': None, 'stn number': None, 'wind grid ji': (142, 134), 'ww3 grid ji': None}, 'East node': {'NEMO grid ji': (417, 283), 'NEMO grid k': 29, 'ONC stationCode': 'SEVIP', 'depth': 164, 'lon lat': (-123.316836666, 49.04316), 'wind grid ji': (133, 150)}, 'Egmont': {'NEMO grid ji': (598, 282), 'lon lat': (-123.93, 49.75)}, 'Entrance Island': {'NEMO grid ji': (484, 231), 'lon lat': (-123.811, 49.209), 'wind grid ji': (143, 137)}, 'Esquimalt': {'NEMO grid ji': (307, 189), 'lon lat': (-123.439, 48.432), 'wind grid ji': (105, 141)}, 'Friday Harbor': {'NEMO grid ji': (300, 267), 'hist max sea lvl': 4.572, 'lon lat': (-123.016667, 48.55), 'mean sea lvl': 2.561, 'stn number': 9449880, 'wind grid ji': (108, 155), 'ww3 grid ji': (124, 427)}, 'Halfmoon Bay': {'NEMO grid ji': (549, 254), 'hist max sea lvl': 5.61, 'lon lat': (-123.912, 49.511), 'mean sea lvl': 3.14, 'stn number': None, 'wind grid ji': (158, 136), 'ww3 grid ji': (331, 297)}, 'Halibut Bank': {'EC buoy number': 46146, 'GEM2.5 grid ji': (149, 141), 'NEMO grid ji': (503, 261), 'lon lat': (-123.72, 49.34), 'wind grid ji': (149, 141)}, 'Hansville': {'NEMO grid ji': (148, 243), 'lon lat': (-122.627, 47.90733)}, 'Hoodsport': {'NEMO grid ji': (89, 114), 'lon lat': (-123.1126, 47.4218)}, 'Hope': {'lon lat': (-121.4419, 49.3858)}, 'Horseshoe Bay': {'NEMO grid ji': (478, 331), 'lon lat': (-123.2728, 49.3742), 'mean sea lvl': None, 'stn number': None, 'wind grid ji': (148, 154), 'ww3 grid ji': None}, 'Indian Arm Head': {'NEMO grid ji': None, 'lon lat': (-122.8864, 49.4615), 'mean sea lvl': 3.052, 'stn number': 7774, 'wind grid ji': (150, 167), 'ww3 grid ji': None}, 'Juan de Fuca Strait': {'lon lat': (-124.7, 48.47)}, 'Nanaimo': {'NEMO grid ji': (484, 208), 'hist max sea lvl': 5.47, 'lon lat': (-123.93, 49.16), 'mean sea lvl': 3.08, 'stn number': 7917, 'wind grid ji': (142, 133), 'ww3 grid ji': (261, 298)}, 'Neah Bay': {'NEMO grid ji': (384, 15), 'hist max sea lvl': 4.359, 'lon lat': (-124.6, 48.4), 'mean sea lvl': 1.925, 'stn number': 9443090, 'wind grid ji': (111, 105), 'ww3 grid ji': (89, 200)}, 'New Westminster': {'NEMO grid ji': (423, 363), 'hist max sea lvl': 4.66, 'lon lat': (-122.90535, 49.203683), 'mean sea lvl': 1.3, 'stn number': 7654, 'wind grid ji': (138, 164)}, 'Pacific Ocean': {'lon lat': (-125.6, 48.1)}, 'Pam Rocks': {'NEMO grid ji': (502, 341), 'lon lat': (-123.299, 49.488), 'wind grid ji': (153, 154)}, 'Patricia Bay': {'NEMO grid ji': (351, 214), 'hist max sea lvl': 4.38, 'lon lat': (-123.4515, 48.6536), 'mean sea lvl': 2.256, 'stn number': 7277, 'wind grid ji': (115, 143), 'ww3 grid ji': (145, 363)}, 'Point Atkinson': {'NEMO grid ji': (468, 329), 'hist max sea lvl': 5.61, 'lon lat': (-123.25, 49.33), 'mean sea lvl': 3.09, 'stn number': 7795, 'wind grid ji': (146, 155), 'ww3 grid ji': (296, 393)}, 'PointWells': {'NEMO grid ji': (104, 259), 'lon lat': (-122.3972, 47.7612)}, 'PointWilliams': {'NEMO grid ji': (62, 231), 'lon lat': (-122.40612, 47.53716)}, 'Port Moody': {'NEMO grid ji': None, 'lon lat': (-122.8658, 49.28814), 'mean sea lvl': 3.143, 'stn number': 7755, 'wind grid ji': (142, 166), 'ww3 grid ji': None}, 'Port Renfrew': {'NEMO grid ji': (401, 61), 'hist max sea lvl': 4.359, 'lon lat': (-124.421, 48.555), 'mean sea lvl': 1.937, 'stn number': 8525, 'wind grid ji': (117, 112), 'ww3 grid ji': (123, 226)}, 'Puget Sound': {'lon lat': (-122.67, 48)}, 'QU39': {'GEM2.5 grid ji': (189, 106), 'NEMO grid ji': (736, 144), 'lon lat': (-125.0992, 50.0307)}, 'Race Rocks': {'NEMO grid ji': (288, 159), 'lon lat': (-123.531, 48.298), 'wind grid ji': (99, 137)}, 'S3': {'GEM2.5 grid ji': (138, 144), 'NEMO grid ji': (450, 258), 'lon lat': (-123.558, 49.125)}, 'SJDF': {'GEM2.5 grid ji': (103, 121), 'NEMO grid ji': (329, 81), 'lon lat': (-124.07, 48.31)}, 'Sand Heads': {'GEM2.5 grid ji': (135, 151), 'NEMO grid ji': (426, 293), 'hist max sea lvl': 5.3950000000000005, 'lon lat': (-123.3, 49.1), 'mean sea lvl': 2.875, 'stn number': 7594, 'wind grid ji': (135, 151), 'ww3 grid ji': (246, 385)}, 'Sandheads': {'GEM2.5 grid ji': (135, 151), 'NEMO grid ji': (426, 293), 'hist max sea lvl': 5.3950000000000005, 'lon lat': (-123.3, 49.1), 'mean sea lvl': 2.875, 'stn number': 7594, 'wind grid ji': (135, 151), 'ww3 grid ji': (246, 385)}, 'Sandy Cove': {'NEMO grid ji': (468, 333), 'hist max sea lvl': 5.61, 'lon lat': (-123.23, 49.34), 'mean sea lvl': 3.1, 'stn number': 7786, 'wind grid ji': (146, 155), 'ww3 grid ji': (294, 396)}, 'Saturna Island': {'NEMO grid ji': (347, 290), 'lon lat': (-123.045, 48.784), 'wind grid ji': (119, 156)}, 'Sentry Shoal': {'EC buoy number': 46131, 'GEM2.5 grid ji': (183, 107), 'NEMO grid ji': (707, 145), 'lon lat': (-125.0, 49.92), 'wind grid ji': (183, 107)}, 'Sisters Islet': {'GEM2.5 grid ji': (160, 120), 'NEMO grid ji': (582, 175), 'lon lat': (-124.43, 49.49), 'wind grid ji': (160, 120)}, 'Squamish': {'NEMO grid ji': (532, 389), 'hist max sea lvl': 5.61, 'lon lat': (-123.155, 49.694), 'mean sea lvl': 3.14, 'stn number': None, 'wind grid ji': (162, 160), 'ww3 grid ji': (370, 404)}, 'Squamish Airport': {'lon lat': (-123.161, 49.783), 'wind grid ji': (166, 161)}, 'Strait of Georgia': {'lon lat': (-123.8, 49.3)}, 'Swartz Bay': {'NEMO grid ji': (354, 225), 'lon lat': (-123.4102, 48.6882), 'mean sea lvl': None, 'stn number': None, 'wind grid ji': (117, 144), 'ww3 grid ji': None}, 'Tsawwassen': {'NEMO grid ji': (396, 305), 'in berth radius': 0.0015, 'lon lat': (-123.132722, 49.006165), 'mean sea lvl': None, 'stn number': None, 'wind grid ji': (130, 155), 'ww3 grid ji': None}, 'Twanoh': {'NEMO grid ji': (72, 123), 'lon lat': (-123.0083, 47.375)}, 'Vancouver': {'lon lat': (-123.1207, 49.2827)}, 'Vancouver Harbour': {'NEMO grid ji': None, 'lon lat': (-123.1069, 49.28937), 'mean sea lvl': 3.001, 'stn number': 7735, 'wind grid ji': (143, 159), 'ww3 grid ji': None}, 'Victoria': {'NEMO grid ji': (302, 196), 'hist max sea lvl': 3.76, 'lon lat': (-123.3707, 48.424666), 'mean sea lvl': 1.881, 'stn number': 7120, 'wind grid ji': (104, 144), 'ww3 grid ji': (90, 374)}, 'Washington State': {'lon lat': (-123.8, 47.8)}, 'Woodwards Landing': {'NEMO grid ji': (414, 329), 'hist max sea lvl': 4.66, 'lon lat': (-123.0754, 49.1251), 'mean sea lvl': 1.84, 'stn number': 7610, 'wind grid ji': (135, 138)}, 'YVR': {'GEM2.5 grid ji': (139, 155), 'lon lat': (-123.184, 49.195), 'wind grid ji': (139, 155)}}

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

salishsea_tools.places.SUPP_TIDE_SITES = ('Friday Harbor', 'Halfmoon Bay', 'Patricia Bay', 'Port Renfrew', 'Squamish', 'Boundary Bay', 'Sand Heads')

Other tide sites, no wind data at these (just to keep the number of arrows under control)

salishsea_tools.places.TIDE_GAUGE_SITES = ('Neah Bay', '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)

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 SalishSeaCast NEMO model.

salishsea_tools.rivertools.check_sum(runoff_orig, runoff_new, flux, area)

Check that the runoff adds up to what it should.

salishsea_tools.rivertools.check_sum_monthly(runoff_orig, runoff_new, flux, area, numtimes=12)

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)

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, numtimes=12)

Fill the monthly runoff array.

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

Get the bathymetry and size of each cell.

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

get the proportion that each river occupies in the watershed.

salishsea_tools.rivertools.get_watershed_prop_dict_allArms_fraser(watershedname)

get the proportion that each river occupies in the watershed.

salishsea_tools.rivertools.get_watershed_prop_dict_long_fraser(watershedname)

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')

Initialise the runoff array.

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

Initialise the runoff array for each month.

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

Initialise the runoff array.

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

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)

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)

Initialise the runoff array for each month.

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

Fill the river file with the rivers of one watershed.

Parameters:

• rivertype (str) – ‘constant’ or ‘monthly’ flows

• area (numpy.ndarray) – horizontal area of each grid cell in domain e1t*e2t

• flux (float) – amount of flow into watershed

• runoff – runoff array we are filling

• run_depth – depth array we are filling

• run_temp – 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)

Fill the river file with the rivers of one watershed.

salishsea_tools.rivertools.rivertemp(month)

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

Temperature in NEMO is in Celsius.

salishsea_tools.rivertools.rivertemp_yday(yearday)

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)

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)

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)

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)

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)

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

salishsea_tools.stormtools.get_CGRF_weather(start, end, grid)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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 https://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)

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)

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)

Convert amplitude and phase to ellipse parameters.

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

salishsea_tools.tidetools.calc_diffs_meas_mod(runname, loc, grid)

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)

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')

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)

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)

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')

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)

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)

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)

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()

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()

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)

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)

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)

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)

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()

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)

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)

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)

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)

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)

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)

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)

Get the length, in days, of the run 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()

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)

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)

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))

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)

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)

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))

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)

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))

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=['', '', ''])

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)

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))

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)

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)

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)

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.make_filename_list(timerange, qty, model='nowcast', resolution='h', path='/results/SalishSea')

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)

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

salishsea_tools.timeseries_tools.reshape_to_grid(data_flat, coords, shape)

Given a flattened array of data with the corresponding Y and X coordinates and the desired grid shape, return the grid of desired shape with the data given. Assumes flattened array has a time dimension as first dimension.

Parameters:

• data_flat – 2d array of data. First dimension is assumed to be time.

• coords – List of form [Ycoords, Xcoords] for each data point given.

• shape – 2d tuple corresponding to desired grid shape. For Salish Sea model, shape would be (898,398).

Returns:

Array of with dimensions corresponding to shape given with data in coordinates given.

unit_conversions Module

Salish Sea NEMO model unit conversion functions and constants.

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.bearing_heading(bearing, headings=('N', 'NNE', 'NE', 'ENE', 'E', 'ESE', 'SE', 'SSE', 'S', 'SSW', 'SW', 'WSW', 'W', 'WNW', 'NW', 'NNW', 'N'))

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)

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

salishsea_tools.unit_conversions.mps_knots(m_per_s)

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.mps_kph(m_per_s)

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.psu_teos(psu)

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)

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.wind_to_from(wind_to)

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.

utilities Module

A library of basic utility Python functions

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

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

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)

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='/home/sallen/MEOPAR/Tools/bathymetry/thalweg_working.txt', cbar_args=None, mesh_args=None, method='contourf')

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_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])

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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')

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

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

Parameters:

• u_in (numpy.ndarray | xarray.DataArray) – u velocity component values

• v_in (numpy.ndarray | xarray.DataArray) – 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.rotate_vel2(u_in, v_in, coords, origin='grid')

Rotate u and v component values to either E-N or model grid. The origin argument sets the input coordinates (‘grid’ or ‘map’).

This function is an evolution of rotate_vel that uses spherical trig to compute the rotation angle at T points rather than assuming 29 degrees applies uniformly. For most of the Salish Sea domain the 29 degree approximation is reasonable, but it does not work in the compressed Fraser River region, hence the need for a per-point angle calculation. The u_in and v_in arguments should be unstaggered velocities at T points from viz_tools.unstagger() which exclude the first row and column.

Parameters:

• u_in (numpy.ndarray) – u velocity component values

• v_in (numpy.ndarray) – v velocity component values

• coords (str or netCDF4.Dataset) – File path/name to netCDF coordinates file or a dataset object containing the U-point coordinates.

• 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.rotate_vel_bybearing(u_in, v_in, coords, origin='grid')

Rotate u and v component values to either E-N or model grid. The origin argument sets the input coordinates (‘grid’ or ‘map’).

This function is an evolution of rotate_vel that uses a bearing calculation based on the coordinates to compute the rotation angle based on https://www.movable-type.co.uk/scripts/latlong.html see Bearing The u_in and v_in arguments should be on the grid passed in as a dictionary in coords

Parameters:

• u_in (numpy.ndarray) – u velocity component values

• v_in (numpy.ndarray) – v velocity component values

• coords (dict) – dict of latitudes and longitudes

• 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')

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)

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)

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.bearing_heading(bearing, headings=('N', 'NNE', 'NE', 'ENE', 'E', 'ESE', 'SE', 'SSE', 'S', 'SSW', 'SW', 'WSW', 'W', 'WNW', 'NW', 'NNW', 'N'))

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.calc_wind_avg_at_point(date_time, weather_path, windji, avg_hrs=-4)

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_knots(m_per_s)

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.mps_kph(m_per_s)

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.wind_speed_dir(u_wind, v_wind)

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

salishsea_tools.wind_tools.wind_to_from(wind_to)

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.