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

evaltools Module

Observation Loader Functions

Model/Observations Matching Function

datetime Conversion Functions

formatting_tools Module

Functions for formatting data output from datasets.

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

Load CTD cast data from Fraser River plume region that Elise Olson collected to ground-truth her turbidity model.

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

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

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