SalishSeaTools
API
This section documents the SalishSeaTools
API (Application Programming Interface).
These API docs provide function signatures and docstrings derived directly from the code modules.
bathy_tools
Module
A library of Python functions for viewing and manipulating netCDF bathymetry files.
- salishsea_tools.bathy_tools.argmax(depths)[source]
Return the indices of the maximum value in depths.
- Parameters:
depths (
netCDF4.Variable
) – netcdf variable object containing the depths- Returns:
Indices of the maximum value in depths
- Return type:
2-tuple
- salishsea_tools.bathy_tools.calc_norm_depth_diffs(depths, delta_lat, delta_lon)[source]
Calculate normalized depth differences between each depth and the depth delta_lat and delta_lon grid points away.
- Parameters:
depths (
netCDF4.Variable
) – netcdf variable object containing the depthsdelta_lat (int) – Number of grid point in the latitude direction to calculate the difference over
delta_lon (int) – Number of grid point in the longitude direction to calculate the difference over
- Returns:
Normalized depth difference field for the bathymetry
- Return type:
netCDF4.Variable
- salishsea_tools.bathy_tools.choose_steepest_cells(depths)[source]
Choose the grid cells with the greatest normalized depth differences in the latitude and longitude directions.
- Parameters:
depths (
netCDF4.Variable
) – netcdf variable object containing the depths- Returns:
Normalized depth difference field in the latitude direction, indices of the grid point with the greatest latitude direction difference, normalized depth difference field in the longitude direction, and indices of the grid point with the greatest longitude direction difference.
- Return type:
4-tuple
- salishsea_tools.bathy_tools.min_mid_max(var)[source]
Return the minimum, median, and maximum values of var as a tuple.
Especially useful when applied to latitude and longitude variables.
- Parameters:
dataset (
netCDF4.Variable
) – netcdf variable object
- salishsea_tools.bathy_tools.plot_colourmesh(dataset, title, fig_size=(9, 9), axis_limits=None, colour_map='winter_r', bins=15, land_colour='#edc9af')[source]
Create a colour-mesh plot of a bathymetry dataset on a longitude/latitude axis.
- Parameters:
dataset (
netCDF4.Dataset
) – netcdf dataset object containing the bathymetrytitle (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 namebins (int) – Number of level bins for the colour map
land_colour (str) – Colour to use for land regions; i.e. those which the depth is undefined in the dataset’s
Bathymetry
variable masked array
- Returns:
Figure object containing the plot
- Return type:
matplotlib.figure.Figure
- salishsea_tools.bathy_tools.plot_colourmesh_zoom(dataset, centre, half_width=5, fig_size=(9, 9), colour_map='copper_r', bins=15, land_colour='white')[source]
Create a colour-mesh plot of a bathymetry dataset on a grid point axis.
The plot extends half_width grid points in each direction from centre.
- Parameters:
dataset (
netCDF4.Dataset
) – netcdf dataset object containing the bathymetrycentre (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 namebins (int) – Number of level bins for the colour map
land_colour (str) – Colour to use for land regions; i.e. those which the depth is undefined in the dataset’s
Bathymetry
variable masked array
- salishsea_tools.bathy_tools.prep_colour_map(depths, limits=None, centre=None, half_width=5, colour_map='copper_r', bins=15)[source]
Returns cmap and norm elements of a colourmap for the netCDF depths variable.
If limits is None (the default) the limits are set to (0, max depth in centre +/- half_width).
- Parameters:
depths (
netCDF4.Variable
) – netcdf variable object containing the depthslimits (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 namebins (int) – Number of level bins for the colour map
- salishsea_tools.bathy_tools.set_aspect_ratio(lats)[source]
Set the plot axis aspect ratio based on the median latitude.
- Parameters:
lats (
netCDF4.Variable
) – netcdf variable object containing the latitudes
- salishsea_tools.bathy_tools.show_dimensions(dataset)[source]
Print the dimensions of the netCDF dataset.
Note
This function is deprecated. Use
nc_tools.show_dimensions()
instead.- Parameters:
dataset (
netCDF4.Dataset
) – netcdf dataset object
- salishsea_tools.bathy_tools.show_global_attrs(dataset)[source]
Print the global attributes of the netCDF dataset.
Note
This function is deprecated. Use
nc_tools.show_dataset_attrs()
instead.- Parameters:
dataset (
netCDF4.Dataset
) – netcdf dataset object
- salishsea_tools.bathy_tools.show_region_depths(depths, centre, half_width=5)[source]
Print the depths for a region extending half_width grid points from centre.
- Parameters:
depths (
netCDF4.Variable
) – netcdf variable object containing the depthscentre (2-tuple) – Grid point to centre the plot at
half_width (int) – Number of grid points from centre to the edge of the plot
- salishsea_tools.bathy_tools.show_variables(dataset)[source]
Print the variable names in the netCDF dataset as a list.
Note
This function is deprecated. Use
nc_tools.show_variables()
instead.- Parameters:
dataset (
netCDF4.Dataset
) – netcdf dataset object
- salishsea_tools.bathy_tools.smooth(depths, max_norm_depth_diff=0.8, smooth_factor=0.2)[source]
Smooth the bathymetry by successively adjusting depths that have the greatest normalized difference until all of those differences are below a max_norm_depth_diff.
- Parameters:
depths (
netCDF4.Variable
) – netcdf variable object containing the depthsmax_norm_depth_diff (float) – Threshold normalized depth difference to smooth to.
smooth_factor (float) – Fraction of the average depth to change the depths by
- Returns:
netcdf variable object containing the depths
- Return type:
netCDF4.Variable
- salishsea_tools.bathy_tools.smooth_neighbours(smooth_factor, depth1, depth2)[source]
Adjust a pair of depths by smooth_factor times their average.
- Parameters:
smooth_factor (float) – Fraction of the average depth to change the depths by
depth1 (float) – First depth to adjust
depth2 (float) – Second depth to adjust
- Returns:
Adjusted depths
- Return type:
2-tuple
- salishsea_tools.bathy_tools.zero_jervis_end(depths)[source]
Set the depths to zero in the area at the end of Jervis Inlet where the Cascadia bathymetry source data are deficient.
- Parameters:
depths (
netCDF4.Variable
) – netcdf variable object containing the depths- Returns:
netcdf variable object containing the depths
- Return type:
netCDF4.Variable
- salishsea_tools.bathy_tools.zero_toba_region(depths)[source]
Set the depths to zero in the Toba Inlet region where the Cascadia bathymetry source data are deficient.
- Parameters:
depths (
netCDF4.Variable
) – netcdf variable object containing the depths- Returns:
netcdf variable object containing the depths
- Return type:
netCDF4.Variable
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)[source]
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)[source]
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})[source]
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})[source]
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:
- salishsea_tools.data_tools.get_onc_data(endpoint, method, token, retry_args={'wait_exponential_max': 30000, 'wait_exponential_multiplier': 1000}, **query_params)[source]
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)[source]
Download a .mat file of ADCP data for 1 day from an Ocean Networks Canada (ONC) node in the Strait of Georgia.
This function relies on a soon-to-be-deprecated ONC web service. It is based on a Matlab script provided by Marlene Jefferies of ONC. It is primarily intended for use in an automation pipeline that also includes ADCP data processing Matlab scripts developed by Rich Pawlowicz of UBC EOAS.
- Parameters:
date (str) – Date for which to request the ADCP data.
node (str) – Strait of Georgia node for which to request the ONC data; must be a key in
salishsea_tools.onc_sog_adcps.deployments
(e.g. “Central node”).dest_path (str) – Path at which to store the downloaded .mat file.
userno (str) – User number with an ONC data.oceannetworks.ca account.
- Return type:
str
- salishsea_tools.data_tools.get_onc_sog_adcp_search_status(search_hdr_id, userid)[source]
Return a JSON blob containing information about the status of a search for ADCP data from an Ocean Networks Canada (ONC) node in the Strait of Georgia.
- Parameters:
search_hdr_id (int) – ONC search header id.
userid (str) – Email address associated with an ONC 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)[source]
Calculate the interpolated value of var at interp_depth using linear interpolation.
- Parameters:
var (
numpy.ndarray
) – Depth profile of a model variable or data quantity.var_depths (
numpy.ndarray
) – Depths at which the model variable or data quantity has values.interp_depths (
numpy.ndarray
or number) – Depth(s) at which to calculate the interpolated value of the model variable or data quantity.var_mask (
numpy.ndarray
or number) – Mask to use for the model variable or data quantity. For model results it is best to use the a 1D slice of the appropriate mesh mask array; e.g.tmask
for tracers. Masking the model variable or data quantity increases the accuracy of the interpolation. If var_mask is not provided the model variable or data quantity is zero-masked.var_depth_mask – Mask to use for the depths. For model results it is best to use the a 1D slice of the appropriate mesh mask array; e.g.
tmask
for tracers. Masking the depths array increases the accuracy of the interpolation. If var_depth_mask is not provided the depths array is zero-masked.
- Returns:
Value(s) of var linearly interpolated to interp_depths.
- Return type:
numpy.ndarray
or number
- salishsea_tools.data_tools.load_ADCP(daterange, station='central', adcp_data_dir='/ocean/dlatorne/MEOPAR/ONC_ADCP/')[source]
Returns the ONC ADCP velocity profiles at a given station over a specified datetime range.
This function uses the nearest neighbor to the specified datetime bounds. ONC ADCP data is returned at approximately 15 and 45 minutes past the hour, so choose datetime bounds accordingly.
- Parameters:
daterange (list or tuple of str) – start and end datetimes for the requested data range. (ex. [‘yyyy mmm dd HH:MM’, ‘yyyy mmm dd HH:MM’])
station (str) – Requested profile location (‘central’, ‘east’, or ‘ddl’)
adcp_data_dir (str) – ADCP file storage location
- Returns:
xarray.Dataset
of zonal u and meridional v velocity with time and depth dimensions.- Return type:
2-D, 2 element
xarray.Dataset
- salishsea_tools.data_tools.load_drifters(deployments=range(1, 10), filename='driftersPositions.geojson', drifterpath='/ocean/rcostanz/Drifters/data')[source]
Loads drifter coordinates and times from the ODL Drifters Project.
UBC Ocean Dynamics Laboratory Drifters Project 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)[source]
Iterate through nowcast results directory, return tracer data that matches request in pandas dataframe.
Example:
station_phy2 = load_nowcast_station_tracers( tracers = ["PHY2"], stations = {'BS1': (636, 126),'BS11': (605, 125)}, months = ['apr'], hours = [0,6,12,18], depth_indices = range(20), )
Returns pandas dataframe with this format:
STATION HOUR DEPTH PHY2 DATE MONTH 0 BS11 0 0.500000 3.903608 2016-04-06 4 1 BS11 0 1.500003 4.114840 2016-04-06 4 2 BS11 0 2.500011 5.080880 2016-04-06 4 3 BS11 0 3.500031 5.082539 2016-04-06 4 4 BS11 0 4.500071 5.076756 2016-04-06 4 5 BS11 0 5.500151 5.030882 2016-04-06 4 6 BS11 0 6.500310 4.975801 2016-04-06 4
- salishsea_tools.data_tools.onc_datetime(date_time, timezone='Canada/Pacific')[source]
Return a string representation of a date/time in the particular ISO-8601 extended format required by the Ocean Networks Canada (ONC) data web services API.
- Parameters:
date_time (str or
datetime.datetime
orarrow.Arrow
) – Date/time to transform into format required by ONC data web services API.timezone (str) – Timezone of date_time.
- Returns:
UTC date/time formatted as YYYY-MM-DDTHH:mm:ss.SSSZ
- Return type:
str
- salishsea_tools.data_tools.onc_json_to_dataset(onc_json, teos=True)[source]
Return an
xarray.Dataset
object containing the data and metadata obtained from an Ocean Networks Canada (ONC) data web service API request.- Parameters:
onc_json (dict) – Data structure returned from an ONC data web service API request. Typically produced by calling the
json()
method on theResponse
object produced by callingrequests.get()
.teos (boolean) – Convert salinity data from PSU (Practical Salinity Units) to TEOS-10 reference salinity in g/kg. Defaults to
True
.
- Returns:
Data structure containing data and metadata
- Return type:
xarray.Dataset
- salishsea_tools.data_tools.request_onc_sog_adcp(date, node, userid)[source]
Request a .mat file of ADCP data for 1 day from an Ocean Networks Canada (ONC) node in the Strait of Georgia.
This function relies on a soon-to-be-deprecated ONC web service. It is based on a Matlab script provided by Marlene Jefferies of ONC. It is primarily intended for use in an automation pipeline that also includes ADCP data processing Matlab scripts developed by Rich Pawlowicz of UBC EOAS.
- Parameters:
date (str) – Date for which to request the ADCP data.
node (str) – Strait of Georgia node for which to request the ONC data; must be a key in
salishsea_tools.onc_sog_adcps.deployments
(e.g. “Central node”).userid (str) – Email address associated with an ONC 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)[source]
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)[source]
Given a list of U filenames and a mesh mask, returns an array with the unscaled Courant numbers.
- Parameters:
files – list of U filenames
meshmask (
netCDF4.Dataset
) – mesh mask
- Returns:
Numpy MaskedArray with unscaled Courant numbers.
- Return type:
- py:class:
numpy.ma.core.MaskedArray
- salishsea_tools.diagnosis_tools.pcourantv(files, meshmask)[source]
Given a list of V filenames and a mesh mask, returns an array with the unscaled Courant numbers.
- Parameters:
files – list of V filenames
meshmask (
netCDF4.Dataset
) – mesh mask
- Returns:
Numpy MaskedArray with unscaled Courant numbers.
- Return type:
- py:class:
numpy.ma.core.MaskedArray
- salishsea_tools.diagnosis_tools.pcourantw(files, meshmask)[source]
Given a list of W filenames and a mesh mask, returns an array with the unscaled Courant numbers.
- Parameters:
files – list of W filenames
meshmask (
netCDF4.Dataset
) – mesh mask
- Returns:
Numpy MaskedArray with unscaled Courant numbers.
- Return type:
- py:class:
numpy.ma.core.MaskedArray
ellipse_tools
Module
A collection of tools for dealing with tidal ellipse calculations.
- salishsea_tools.ellipse.ellipse_files_nowcast(to, tf, iss, jss, path, depthrange='None', period='1h', station='None')[source]
This function loads all the data between the start and the end date that contains in the netCDF4 nowcast files in the specified depth range. This will make an area with all the indices indicated, the area must be continuous for unstaggering.
- Parameters:
to (datetime object) – The beginning of the date range of interest
tf (datetime object) – The end of the date range of interest
iss – x index.
jss – y index.
path (string) – Defines the path used(eg. nowcast)
depthrange (float, string or list.) – Depth values of interest in meters as a float for a single depth or a list for a range. A float will find the closest depth that is <= the value given. Default is ‘None’ for the whole water column (0-441m).
period (string - '1h' for hourly results or '15m' for 15 minute) – period of the results files
station (string 'None' if not applicable. 'ddl', 'east' or 'central') – station for analysis
- Returns:
u, v, time, dep.
- salishsea_tools.ellipse.ellipse_params(uamp, upha, vamp, vpha)[source]
Calculates ellipse parameters based on the amplitude and phase for a tidal constituent.
- Parameters:
uamp (
numpy.ndarray
) – u fitted amplitude of the chosen constituentupha (
numpy.ndarray
) – u fitted phase of the chosen constituentvamp (
numpy.ndarray
) – v fitted amplitude of the chosen constituentvpha (
numpy.ndarray
) – v fitted phase of the chosen constituent
- Returns:
CX, SX, CY, SY, ap, am, ep, em, major, minor, theta, phase The positively and negatively rotating amplitude and phase. As well as the major and minor axis and the axis tilt.
- salishsea_tools.ellipse.get_params(u, v, time, nconst, tidecorr={'K1': {'freq': 15.041069, 'ft': 0.891751, 'uvt': 262.636797}, 'K2': {'freq': 30.082138, 'ft': 0.763545, 'uvt': 344.740346}, 'M2': {'freq': 28.984106, 'ft': 1.03539, 'uvt': 346.11449}, 'N2': {'freq': 28.43973, 'ft': 1.03539, 'uvt': 310.920296}, 'O1': {'freq': 13.943036, 'ft': 0.822543, 'uvt': 81.47243}, 'P1': {'freq': 14.958932, 'ft': 1.0, 'uvt': 101.04216}, 'Q1': {'freq': 13.398661, 'ft': 0.822543, 'uvt': 46.278236}, 'S2': {'freq': 30.000002, 'ft': 1.0, 'uvt': 0.0}, 'reftime': datetime.datetime(2014, 9, 10, 0, 0, tzinfo=tzutc())})[source]
Calculates tidal ellipse parameters from the u and v time series. Maintains the shape of the velocities enters only loosing the time dimensions.
- Parameters:
u (:py:class:'np.ndarray') – One of the orthogonal tidal current velocities. Must be already prepared for the analysis.
v (:py:class:'np.ndarray') – One of the orthogonal tidal current velocities. Must be already prepared for the analysis.
time (:py:class:'np.ndarray') – Time over which the velocities were taken; in hours.
nconst (int) – The amount of tidal constituents used for the analysis. They added in pairs and by order of importance, M2, K1, S2, O1, N2, P1, K2, Q1.
tidecorr (dictionary) – Tidal corrections in aplitude and phase. Default is the nowcast values.
- Returns:
params a dictionary containing the tidal ellipse parameter of the chosen constituents
- salishsea_tools.ellipse.get_params_nowcast(to, tf, i, j, path, nconst, depthrange='None', depav=False, tidecorr={'K1': {'freq': 15.041069, 'ft': 0.891751, 'uvt': 262.636797}, 'K2': {'freq': 30.082138, 'ft': 0.763545, 'uvt': 344.740346}, 'M2': {'freq': 28.984106, 'ft': 1.03539, 'uvt': 346.11449}, 'N2': {'freq': 28.43973, 'ft': 1.03539, 'uvt': 310.920296}, 'O1': {'freq': 13.943036, 'ft': 0.822543, 'uvt': 81.47243}, 'P1': {'freq': 14.958932, 'ft': 1.0, 'uvt': 101.04216}, 'Q1': {'freq': 13.398661, 'ft': 0.822543, 'uvt': 46.278236}, 'S2': {'freq': 30.000002, 'ft': 1.0, 'uvt': 0.0}, 'reftime': datetime.datetime(2014, 9, 10, 0, 0, tzinfo=tzutc())})[source]
This function loads all the data between the start and the end date that contains hourly velocities in the netCDF4 nowcast files in the specified depth range. Then masks, rotates and unstaggers the time series. The unstaggering causes the shapes of the returned arrays to be 1 less than those of the input arrays in the y and x dimensions. Finally it calculates tidal ellipse parameters from the u and v time series. Maintains the shape of the velocities enters only loosing the time dimensions.
- Parameters:
to (datetime object) – The beginning of the date range of interest
tf (datetime object) – The end of the date range of interest
i (float or list) – x index, must have at least 2 values for unstaggering, will loose the first i during the unstaggering in prepare_vel.
j (float or list) – y index, must have at least 2 values for unstaggering, will loose the first j during the unstaggering in prepare_vel.
path (string) – Defines the path used(eg. nowcast)
depthrange – Depth values of interest in meters as a float for a single depth or a list for a range. A float will find the closest depth that is <= the value given. Default is ‘None’ for the whole water column (0-441m).
depav (boolean) – True will depth average over the whole depth profile given. Default is False.
depth (:py:class:'np.ndarray' or string) – depth vector corresponding to the depth of the velocities, only requiered if depav=True.
- Returns:
params, dep params is dictionary object of the ellipse parameters for each constituent dep is the depths of the ellipse paramters
- salishsea_tools.ellipse.get_params_nowcast_15(to, tf, station, path, nconst, depthrange='None', depav=False, tidecorr={'K1': {'freq': 15.041069, 'ft': 0.891751, 'uvt': 262.636797}, 'K2': {'freq': 30.082138, 'ft': 0.763545, 'uvt': 344.740346}, 'M2': {'freq': 28.984106, 'ft': 1.03539, 'uvt': 346.11449}, 'N2': {'freq': 28.43973, 'ft': 1.03539, 'uvt': 310.920296}, 'O1': {'freq': 13.943036, 'ft': 0.822543, 'uvt': 81.47243}, 'P1': {'freq': 14.958932, 'ft': 1.0, 'uvt': 101.04216}, 'Q1': {'freq': 13.398661, 'ft': 0.822543, 'uvt': 46.278236}, 'S2': {'freq': 30.000002, 'ft': 1.0, 'uvt': 0.0}, 'reftime': datetime.datetime(2014, 9, 10, 0, 0, tzinfo=tzutc())})[source]
This function loads all the data between the start and the end date that contains quater houlry velocities in the netCDF4 nowcast files in the depth range. Then masks, rotates and unstaggers the time series. The unstaggering causes the shapes of the returned arrays to be 1 less than those of the input arrays in the y and x dimensions. Finally it calculates tidal ellipse parameters from the u and v time series. Maintains the shape of the velocities enters only loosing the time dimensions.
- Parameters:
to (datetime object) – The beginning of the date range of interest
tf (datetime object) – The end of the date range of interest
station (string (East or Central)) – station name for the quater-hourly data
path (string) – Defines the path used(eg. nowcast)
depthrange – Depth values of interest in meters as a float for a single depth or a list for a range. A float will find the closest depth that is <= the value given. Default is ‘None’ for the whole water column (0-441m).
depav (boolean) – True will depth average over the whole depth profile given. Default is False.
depth (:py:class:'np.ndarray' or string) – depth vector corresponding to the depth of the velocities, only required if depav=True.
- Returns:
params, dep params is dictionary object of the ellipse parameters for each constituent dep is the depths of the ellipse paramters
- salishsea_tools.ellipse.prepare_vel(u, v, depav=False, depth='None')[source]
Preparing the time series of the orthogonal pair of velocities to get tidal ellipse parameters. This function masks, rotates and unstaggers the time series. The depth averaging does not work over masked values.
- Parameters:
u (:py:class:'np.ndarray') – One of the orthogonal components of the time series of tidal current velocities.
v (:py:class:'np.ndarray') – One of the orthogonal components of the time series of tidal current velocities.
depav – True will depth average over the whole depth profile given. Default is False.
depth (:py:class:'np.ndarray' or string) – depth vector corresponding to the depth of the velocities, only requiered if depav=True.
formatting_tools
Module
Functions for formatting data output from datasets.
- salishsea_tools.formatting_tools.STR_LATEX_MAPPING = {'degC': '$^\\circ$C', 'degrees_east': '$^\\circ$E', 'degrees_north': '$^\\circ$N', 'g kg-1': 'g / kg', 'g/kg': 'g / kg', 'm/s': 'm/s', 'm2/s': 'm$^2$ / s$', 'm2/s3': 'm$^2$ / s$^3$', 'mmol m-3': 'mmol / $m^{3}$', 'mmol/m3': 'mmol / $m^{3}$'}
String to LaTeX notation mapping for units
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}})[source]
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)[source]
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:
- 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)[source]
Returns the grid coordinates of the closest model point to a specified lon/lat. If land_mask is provided, returns the closest water point.
Example:
j, i = find_closest_model_point( -125.5,49.2,model_lons,model_lats,land_mask=bathy.mask)
where bathy, model_lons and model_lats are returned from
salishsea_tools.tidetools.get_bathy_data()
.j is the y-index(latitude), i is the x-index(longitude)
- Parameters:
lon (float) – longitude to find closest grid point to
lat (float) – latitude to find closest grid point to
model_lons (
numpy.ndarray
) – specified model longitude gridmodel_lats (
numpy.ndarray
) – specified model latitude gridgrid (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')[source]
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)[source]
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)[source]
Given a NEMO weights file and an operational surface forcing file, we assemble the weights into a sparse interpolation matrix that interpolates the surface forcing data from the operational grid to the NEMO grid. This function returns the matrix and the NEMO grid shape.
- Parameters:
weightsfile (str) – Path to NEMO weights file.
opsfile (str) – Path to an operational file.
- Returns:
Sparse interpolation matrix and NEMO grid shape
- Return type:
(
csr_matrix
,tuple
)
- salishsea_tools.grid_tools.calculate_H(e3t0, tmask)[source]
Calculate the initial water column thickness (H).
- Parameters:
e3t0 (
numpy.ndarray
) – initial vertical scale factors on T-grid. Dimensions: (depth, y, x).tmask (
numpy.ndarray
) – T-grid mask. Dimensions: (depth, y, x)
- Returns:
the initial water column thickness. Dimensions: (y, x)
- salishsea_tools.grid_tools.calculate_adjustment_factor(H, ssh)[source]
Calculate the time-dependent adjustment factor for variable volume in NEMO. adj = (1+ssh/H) and e3t_t = e3t_0*adj
- Parameters:
H (
numpy.array
) – Water column thickness. Dimension: (y, x)ssh (
numpy.ndarray
) – the model sea surface height. Dimensions: (time, y, x)
- Returns:
the adjustment factor with dimensions (time, y, x)
- salishsea_tools.grid_tools.calculate_time_dependent_grid(e3t0, tmask, ssh, input_vars)[source]
Calculate the time dependent vertical grids and scale factors for variable volume in NEMO.
- Parameters:
e3t0 (
numpy.ndarray
) – initial vertical scale factors on T-grid. Dimensions: (depth, y, x).tmask (
numpy.ndarray
) – T-grid mask. Dimensions: (depth, y, x)ssh (
numpy.ndarray
) – the model sea surface height. Dimensions: (time, y, x)input_vars – A dictionary of the initial grids/scale factors to be translated into time_dependent. Example keys can be ‘e3t_0’, ‘gdept_0’, ‘e3w_0’, ‘gdepw_0’. A dictionary with corresponding time-dependent grids is returned, where the keys are now ‘e3t_t’, ‘gdept_t’, ‘e3w_0’, ‘gdepw_0’.
- Typ input_vars:
dictionary
- Returns:
A dictionary containing the desired time dependent vertical scale factors on t and w grids and depths on t and w grids. Dimensions of each: (time, depth, y, x)
- salishsea_tools.grid_tools.time_dependent_grid_U(e3u0, e1u, e2u, e1t, e2t, umask, ssh, input_vars, return_ssh=False)[source]
Calculate time-dependent vertical grid spacing and depths on U-grid for variable volume in NEMO.
- Parameters:
e3u0 (
numpy.ndarray
) – initial vertical scale factors on U-grid. Dimensions: (depth, y, x).e1u (
numpy.ndarray
) – x-direction scale factors on U-grid. Dimensions: (y, x).e2u (
numpy.ndarray
) – y-direction scale factors on U-grid. Dimensions: (y, x).e1t (
numpy.ndarray
) – x-direction scale factors on T-grid. Dimensions: (y, x).e2t (
numpy.ndarray
) – y-direction scale factors on T-grid. Dimensions: (y, x).umask (
numpy.ndarray
) – U-grid mask. Dimensions: (depth, y, x)ssh (
numpy.ndarray
) – the model sea surface height on T-grid. Dimensions: (time, y, x)input_vars (dictionary) – A dictionary of the initial grids/scale factors to be translated into time-dependent. Example keys can be ‘e3u_0’, ‘gdepu_0’. A dictionary with corresponding time-dependent grids is returned, where the keys are now ‘e3u_t’, ‘gdepu_t’.
return_ssh (boolean) – Specifies whether the ssh interpolated to the U-grid should be returned (ssh_u)
- Returns:
A dictionary containing the desired time dependent vertical scale factors on depths on u grid. Dimensions of each: (time, depth, y, x). If returned, ssh_u has dimensions (time, y, x)
- salishsea_tools.grid_tools.time_dependent_grid_V(e3v0, e1v, e2v, e1t, e2t, vmask, ssh, input_vars, return_ssh=False)[source]
Calculate time-dependent vertical grid spacing and depths on V-grid for variable volume in NEMO.
- Parameters:
e3v0 (
numpy.ndarray
) – initial vertical scale factors on V-grid. Dimensions: (depth, y, x).e1v (
numpy.ndarray
) – x-direction scale factors on V-grid. Dimensions: (y, x).e2v (
numpy.ndarray
) – y-direction scale factors on V-grid. Dimensions: (y, x).e1t (
numpy.ndarray
) – x-direction scale factors on T-grid. Dimensions: (y, x).e2t (
numpy.ndarray
) – y-direction scale factors on T-grid. Dimensions: (y, x).vmask (
numpy.ndarray
) – V-grid mask. Dimensions: (depth, y, x)ssh (
numpy.ndarray
) – the model sea surface height on T-grid. Dimensions: (time, y, x)input_vars (dictionary) – A dictionary of the initial grids/scale factors to be translated into time_dependent. Example keys can be ‘e3v_0’, ‘gdepv_0’. A dictionary with corresponding time-dependent grids is returned, where the keys are now ‘e3v_t’, ‘gdepv_t’.
return_ssh (boolean) – Specifies whether the ssh interpolated to the V-grid should be returned (ssh_v)
- Returns:
A dictionary containing the desired time dependent vertical scale factors and depths on v grid. Dimensions of each: (time, depth, y, x). If returned, ssh_uvhas dimensions (time, y, x)
- salishsea_tools.grid_tools.use_matrix(opsfile, matrix, nemoshape, variable, time)[source]
Given an operational surface forcing file, an interpolation matrix and NEMO grid shape (produced by grid_tools.build_matrix), a variable name and a time index, we return the operational data interpolated onto the NEMO grid.
- Parameters:
opsfile (str) – Path to operational file to interpolate.
matrix (
csr_matrix
) – Interpolation matrix (from build_matrix)nemoshape (tuple) – NEMO grid shape (from build_matrix)
variable (str) – Specified variable in ops file.
index (time) – time index in ops file.
- Returns:
Operational data interpolated onto the NEMO grid
- Return type:
gsw_calls
Module
- salishsea_tools.gsw_calls.generic_gsw_caller(gsw_function_name, input_vars, matlab_gsw_dir='/ocean/rich/home/matlab/gsw3')[source]
A generic function for calling matlab gsw functions. Only works with gsw functions that have a single variable as output.
- Parameters:
gsw_function_name (str) – The name of the matlab gsw function. e.g. gsw_p_from_z.m
input_vars (list of numpy arrays) – A list of the input variables in the same order as expected from the gsw matlab function.
matlab_gsw_dir (str) – The directory where the matlab gsw scripts are stored.
- Returns:
A numpy array containing the output from call to gsw function.
hg_commands
Module
A library of Python functions for working with Mercurial via its command line interface. This is a utility library that is used by other Python packages and modules developed for the SalishSeaCast project.
- salishsea_tools.hg_commands.commit(logfile)[source]
Commit all changes in the repo with the contents of logfile as the commit message.
- Parameters:
logfile (str) – Name of the file containing the commit message.
- salishsea_tools.hg_commands.default_url(repo=None)[source]
Return the result of the hg paths default command.
If repo is given the hg -R repo paths default command is run. The repo argument must be the root directory of a Mercurial repository.
If the hg command fails
None
is returned.- Parameters:
repo (str) – Repository root directory.
- Returns:
Output of the command or
None
.
- salishsea_tools.hg_commands.heads(repo, revs=['.'])[source]
Return the result of the hg -R repo heads revs command.
- Parameters:
repo (str) – Repository root directory.
revs (list) – Revisions for which to show branch heads. The default . causes the head(s) of the currently checked out branch to be returned.
- Returns:
Output of the command.
- Return type:
str
- salishsea_tools.hg_commands.parents(repo=None, rev=None, file=None, verbose=False)[source]
Return the result of the hg parents command.
If repo is given the hg parents -R repo command is run. The repo argument must be the root directory of a Mercurial repository.
If rev is given the hg parents -r rev command is run. Only one rev may be given.
If file is given the hg parents file command is run. Only one file may be given.
If verbose is True the hg parents -v command is run.
Keyword argument can be used cumulatively; e.g. repo=foo, file=bar will result in the hg parents -R foo bar command being run.
- Parameters:
repo (str) – Repository root directory.
rev – Revision to get the parents of. May be either an integer or a hash string.
file (str) – File path and name to get the parents of.
verbose (Boolean) – Control verbosity of hg command; default to False meaning to run the command without the -v flag.
- Returns:
Output of the command.
- Return type:
str
Modules for Working with Live Ocean Model Products
- salishsea_tools.LiveOcean_BCs.calculate_Si_from_NO3(NO3, SA, a=6.46, b=1.35, c=0, sigma=1, tsa=29)[source]
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)[source]
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)[source]
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}})[source]
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)[source]
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)[source]
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)[source]
Interpolate variables in var_names from a Live Ocean dataset to NEMO depths. LiveOcean land points (including points lower than bathymetry) are set to np.nan and then masked.
- Parameters:
dataset (xarray Dataset) – Live Ocean dataset
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)[source]
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')[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
Gets grid, vertical coordinate, and time info from a ROMS NetCDF history file with full name ‘fn’
Input: the filename (with path if needed)
Output: dicts G, S, and T
Example calls: 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)[source]
Used to calculate the z position of fields in a ROMS history file. Only for rho levels
Input: arrays h (bathymetry depth) and zeta (sea surface height) which must be the same size, and dict S created by get_basic_info()
Output: 3-D arrays of z_rho
NOTE: one foible is that if you input arrays of h and zeta that are vectors of length VL, the output array (e.g. z_rho) will have size (N, VL) (i.e. it will never return an array with size (N, VL, 1), even if (VL, 1) was the input shape). This is a result of the initial and final squeeze calls.
loadDataFRP
Module
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)
nc_tools
Module
A library of Python functions for working with netCDF files.
Included are functions for:
exploring the attributes of netCDF files
managing those attributes during netCDF file creation and updating
obtaining variable values from netCDF files
creation of special purpose netCDF files
combining per-processor sub-domain output files fron NEMO into a single netCDF file
- salishsea_tools.nc_tools.check_dataset_attrs(dataset)[source]
Check that required dataset and variable attributes are present and that they are not empty.
- Parameters:
dataset (
netCDF4.Dataset
) – netcdf dataset object
- salishsea_tools.nc_tools.combine_subdomain(filenames, outfilename)[source]
Recombine per-processor subdomain files into one single file.
Note: filenames must be an array of files organized to reflect the subdomain decomposition. filenames[0,0] is bottom left, filenames[0,-1] is bottom right, filenames[-1,0] is top left, filenames[-1,-1] is top right. For example, filenames = [[sub_00.nc, sub_01.nc], [sub_02.nc, sub_03.nc]]. This can be improved. At some point it would be worthwhile to automatically build the filenames array. Also, we might want to add netcdf attributes like history, units, etc.
- Parameters:
filenames (numpy array (2D)) – An array containing the names of the files to be recombined.
outfilename (string) – The name of the file for saving output
- salishsea_tools.nc_tools.dataset_from_path(path, *args, **kwargs)[source]
Return a dataset constructed from the file given by path.
This is a shim that facilitates constructing a
netCDF4.Dataset
instance from a file that is identified by path/filename that is either a string or apathlib.Path
instance. ThenetCDF4.Dataset
constructor cannot handlepathlib.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 thenetCDF4.Dataset
constructor raises aRuntimeError
that indicates that the file or directory at path is not found.
- salishsea_tools.nc_tools.generate_pressure_file(filename, p_file, t_file, alt_file, day)[source]
Generates a file with CGRF pressure corrected to sea level.
- Parameters:
filename (string) – full path name where the corrected pressure should be saved
p_file (string) – full path name of the uncorrected CGRF pressure
t_file (string) – full path name of the corresponding CGRF temperature
alt_file (string) – full path name of the altitude of CGRF cells
day (arrow) – the date
- salishsea_tools.nc_tools.generate_pressure_file_ops(filename, p_file, t_file, alt_file, day)[source]
Generates a file with CGRF pressure corrected to sea level.
- Parameters:
filename (string) – full path name where the corrected pressure should be saved
p_file (string) – full path name of the uncorrected CGRF pressure
t_file (string) – full path name of the corresponding CGRF temperature
alt_file (string) – full path name of the altitude of CGRF cells
day (arrow) – the date
- salishsea_tools.nc_tools.get_GEM_path(date)[source]
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)[source]
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')[source]
Return the datetime array for a dataset
This is a wrapper around nc_tools.timestamp that automatically handles all timesteps and converts the arrow objects to a numpy datetime object array.
- Parameters:
dataset (
netCDF4.Dataset
) – netcdf dataset object.time_var (str) – name of time variable.
- Returns:
datetime values at each timestep in the dataset.
- Return type:
Numpy
array ofDatetime
instances
- salishsea_tools.nc_tools.get_hindcast_prefix(date, res='h', version='201905')[source]
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 recordres (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)[source]
Initialize the required global attributes of the netCDF dataset.
If an attribute with one of the required attribute names is already set on the dataset it will not be overwritten, instead a warning will be printed, unless quiet==True.
With quiet==False (the default) the dataset attributes and their values are printed.
- Parameters:
dataset (
netCDF4.Dataset
) – netcdf dataset objecttitle (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)[source]
Print the global attributes of the netCDF dataset.
- Parameters:
dataset (
netCDF4.Dataset
) – netcdf dataset object
- salishsea_tools.nc_tools.show_dimensions(dataset)[source]
Print the dimensions of the netCDF dataset.
- Parameters:
dataset (
netCDF4.Dataset
) – netcdf dataset object
- salishsea_tools.nc_tools.show_variable_attrs(dataset, *vars)[source]
Print the variable attributes of the netCDF dataset.
If variable instances are given as optional arguments, only those variable’s attributes are printed.
- Parameters:
dataset (
netCDF4.Dataset
) – netcdf dataset objectvars (
netCDF4.Variable1
) – Variables to print attributes for
- salishsea_tools.nc_tools.show_variables(dataset)[source]
Print the variable names in the netCDF dataset as a list.
- Parameters:
dataset (
netCDF4.Dataset
) – netcdf dataset object
- salishsea_tools.nc_tools.ssh_timeseries_at_point(grid_T, j, i, datetimes=False, time_var='time_counter', ssh_var='sossheig')[source]
Return the sea surface height and time counter values at a single grid point from a NEMO tracer results dataset.
- Parameters:
grid_T (
netCDF4.Dataset
) – Tracer results dataset from NEMO.j (int) – j-direction (longitude) index of grid point to get sea surface height at.
i (int) – i-direction (latitude) index of grid point to get sea surface height at.
datetimes (boolean) – Return time counter values as
datetime.datetime
objects ifTrue
, otherwise return them asarrow.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. Thessh
attribute holds the sea surface heights, and thetime
attribute holds the time counter values.- Return type:
collections.namedtuple
- salishsea_tools.nc_tools.time_origin(dataset, time_var='time_counter')[source]
Return the time_var.time_origin value.
- Parameters:
dataset (
netCDF4.Dataset
orxarray.Dataset
) – netcdf dataset objecttime_var (str) – name of time variable
- Returns:
Value of the time_origin attribute of the time_counter variable.
- Return type:
Arrow
instance
- salishsea_tools.nc_tools.timestamp(dataset, tindex, time_var='time_counter')[source]
Return the time stamp of the tindex time_counter value(s) in dataset.
The time stamp is calculated by adding the time_counter[tindex] value (in seconds) to the dataset’s time_counter.time_origin value.
- Parameters:
dataset (
netCDF4.Dataset
) – netcdf dataset objecttindex (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)[source]
Return the u and v wind components and time counter values at a single grid point from a weather forcing dataset.
- Parameters:
grid_weather (
netCDF4.Dataset
) – Weather forcing dataset, typically from anops_yYYYYmMMdDD.nc
file produced by thenowcast.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 ifTrue
, otherwise return them asarrow.Arrow
objects (the default).
- Returns:
2-tuple of 1-dimensional
numpy.ndarray
objects, Theu
attribute holds the u-direction wind component, Thev
attribute holds the v-direction wind component, and thetime
attribute holds the time counter values.- Return type:
collections.namedtuple
- salishsea_tools.nc_tools.xarraytime_to_datetime(xarraytime)[source]
Convert an xarray.DataArray of numpy.datetime64 times to a numpy.ndarray of datetime.datetime times
- Parameters:
xarraytime (
xarray.DataArray
ofnumpy.datetime64
) – DataArray of datetime64- Returns:
array of datetimes
- Return type:
numpy.ndarray
ofdatetime.datetime
- class salishsea_tools.nc_tools.scDataset(files)[source]
Simple Concatenated Dataset
scDataset is a partial implementation of MFDataset that automates the concatenation of netCDF variables split between multiple files. The aim is to provide a simple concatenated interface to variables where the first dimension is the unlimited dimension (usually “time_counter”).
Variables where the first dimension is not the unlimited time dimension (such as lon, lat, etc) are not concatenated. They are, however, made available in a “pass through” sense to the first dataset in the list. Thus, you can read those variables without opening another Dataset.
The other MFDataset features are not implemented: attributes, etc are ignored for the concatenated variables. It may be possible to add the those features but the goal here is simply automated concatenation.
Building this class was motivated by deficiencies in the other options for split-file concatenation:
xarray.open_mfdataset() appears to load the entire dataset into memory, which is both slow and memory intensive.
netCDF4.MFDataset refuses to open NETCDF4 format files
In the event that netCDF4.MFDataset is improved to work with NETCDF4 files, this will become obsolete.
- Parameters:
files (list) – list of netcdf filenames in chronological order
Example usage:
# Get the (concatenated) output times with scDataset(files) as ds: t = ds.variables['time_counter'][:]
# Get temperature at all times and all depths at one location with scDataset(files) as ds: temper = ds.variables['votemper'][:,:,100,100]
# Load surface salinity at each time in a loop for plotting/animation with scDataset(files) as ds: for ti in range(ds.variables['vosaline'].shape[0]): print("Loading time "+str(ti)) surfsal = ds.variables['vosaline'][ti,0,:,:] # make_a_plot(surfsal)
# Python indexing and slicing also works with scDataset(files) as ds: t1 = ds.variables['votemper'][29:33:-1,-10:-1,100:130] print(t1.shape)
places
Module
Salish Sea NEMO model geographic places information.
It is recommended that library code that uses the PLACES
data
structure from this module should use try...except to catch
KeyError
exceptions and produce an error message that is more
informative than the default, for example:
try:
max_tide_ssh = max(ttide.pred_all) + PLACES[site_name]['mean sea lvl']
max_historic_ssh = PLACES[site_name]['hist max sea lvl']
except KeyError as e:
raise KeyError(
'place name or info key not found in '
'salishsea_tools.places.PLACES: {}'.format(e))
- salishsea_tools.places.DispGeoLocs()[source]
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')[source]
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)
psu_tools
Module
Functions for converting temperature and salinity(psu) to density
- salishsea_tools.psu_tools.calculate_density(t, s)[source]
Calculates the density given temperature in deg C (t) and salinity in psu (s). The reference for this calculation is: Pond and Pickard, (1983). Introductory Dynamical Oceanography
- Parameters:
t (numpy array) – temperature array in deg C
s (numpy array) – salinity array in psu
- Returns:
the density as an array (rho) in kg/m^3
rivertools
Module
A collections of functions for working with river flow forcing data for the SalishSeaCast NEMO model.
- salishsea_tools.rivertools.check_sum(runoff_orig, runoff_new, flux, area)[source]
Check that the runoff adds up to what it should.
- salishsea_tools.rivertools.check_sum_monthly(runoff_orig, runoff_new, flux, area, numtimes=12)[source]
Check that the runoff adds up per month to what it should.
- salishsea_tools.rivertools.fill_runoff_array(flux, istart, di, jstart, dj, depth_of_flux, runoff, run_depth, area)[source]
Fill the runoff array.
- salishsea_tools.rivertools.fill_runoff_array_monthly(flux, istart, di, jstart, dj, depth_of_flux, runoff, run_depth, run_temp, area, numtimes=12)[source]
Fill the monthly runoff array.
- salishsea_tools.rivertools.get_bathy_cell_size(grid='../../../nemo-forcing/grid/coordinates_seagrid_SalishSea.nc')[source]
Get the bathymetry and size of each cell.
- salishsea_tools.rivertools.get_watershed_prop_dict(watershedname, Fraser_River='short')[source]
get the proportion that each river occupies in the watershed.
- salishsea_tools.rivertools.get_watershed_prop_dict_allArms_fraser(watershedname)[source]
get the proportion that each river occupies in the watershed.
- salishsea_tools.rivertools.get_watershed_prop_dict_long_fraser(watershedname)[source]
get the proportion that each river occupies in the watershed.
- salishsea_tools.rivertools.init_runoff3_array(bathy='/ocean/jieliu/research/meopar/river-treatment/bathy_meter_SalishSea3.nc')[source]
Initialise the runoff array.
- salishsea_tools.rivertools.init_runoff3_array_monthly(bathy='/ocean/jieliu/research/meopar/river-treatment/bathy_meter_SalishSea3.nc')[source]
Initialise the runoff array for each month.
- salishsea_tools.rivertools.init_runoff5_array(bathy='/ocean/jieliu/research/meopar/river-treatment/bathy_meter_SalishSea5.nc')[source]
Initialise the runoff array.
- salishsea_tools.rivertools.init_runoff5_array_monthly(bathy='/ocean/jieliu/research/meopar/river-treatment/bathy_meter_SalishSea5.nc')[source]
Initialise the runoff array for each month.
- salishsea_tools.rivertools.init_runoff_array(bathy='../../../nemo-forcing/grid/bathy_meter_SalishSea.nc', init_depth=-1, init_temp=-99)[source]
Initialise the runoff array.
If you want to use a different bathymetry set it in the call; e.g.:
init_runoff_array( bathy='/ocean/jieliu/research/meopar/river-treatment/bathy_meter_SalishSea6.nc')
- salishsea_tools.rivertools.init_runoff_array_monthly(bathy='../../../nemo-forcing/grid/bathy_meter_SalishSea.nc', init_depth=-1, init_temp=-99)[source]
Initialise the runoff array for each month.
- salishsea_tools.rivertools.put_watershed_into_runoff(rivertype, area, flux, runoff, run_depth, run_temp, pd)[source]
Fill the river file with the rivers of one watershed.
- Parameters:
rivertype (str) – ‘constant’ or ‘monthly’ flows
area (
numpy.ndarray
) – horizontal area of each grid cell in domain e1t*e2tflux (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)[source]
Fill the river file with the rivers of one watershed.
stormtools
Module
A collection of tools for storm surge results from the Salish Sea Model.
- salishsea_tools.stormtools.combine_data(data_list)[source]
This function combines output from a list of netcdf files into a dict objects of model fields. It is used for easy handling of output from thalweg and surge stations.
- Parameters:
data_list (dict object) – dict object that contains the netcdf handles for the files to be combined; e.g. {‘Thalweg1’: f1, ‘Thalweg2’: f2,…} where f1 = NC.Dataset(‘1h_Thalweg1.nc’,’r’)
- Returns:
dict objects us, vs, lats, lons, sals, tmps, sshs with the zonal velocity, meridional velocity, latitude, longitude, salinity, temperature, and sea surface height for each station. The keys are the same as those in data_list. For example, us[‘Thalweg1’] contains the zonal velocity from the Thalweg 1 station.
- salishsea_tools.stormtools.convert_date_hours(times, start)[source]
This function converts model output time in hours to datetime objects.
- Parameters:
times (int) – array of hours since the start date of a simulation. From time_counter in model output.
start (str) – string containing the start date of the simulation in format ‘01-Nov-2006’
- Returns:
array of datetime objects representing the time of model outputs.
- salishsea_tools.stormtools.convert_date_seconds(times, start)[source]
This function converts model output time in seconds to datetime objects. Note: Doug has a better version of this in nc_tools.timestamp
- Parameters:
times (int) – array of seconds since the start date of a simulation. From time_counter in model output.
start (str) – string containing the start date of the simulation in format ‘01-Nov-2006’
diff (str) – string indicating the time step in the times data E.g. months, seconds, days
- Returns:
array of datetime objects representing the time of model outputs.
- salishsea_tools.stormtools.correct_model(ssh, ttide, sdt, edt)[source]
Adjusts model output by correcting for error in using only 8 constituents
- Parameters:
ssh (array of numbers) – an array with model ssh data
ttide (struc with dimension time, pred_all, pred_8) – struc with tidal predictions. Assumes tidal predictions are on the the hour can model output is on the 1/2 hour.
sdt (datetime object) – datetime object representing start date of simulation
edt (datetime object) – datetime object representing end date of simulation
- Returns:
corr_model: the corrected model output
- salishsea_tools.stormtools.dateParserMeasured(s)[source]
converts string in %Y/%m/%d %H:%M format Pacific time to a datetime object UTC time.
- salishsea_tools.stormtools.get_CGRF_weather(start, end, grid)[source]
Returns the CGRF weather between the dates start and end at the grid point defined in grid.
- Parameters:
start (str) – string containing the start date of the CGRF collection in format ‘01-Nov-2006’
start – string containing the end date of the CGRF collection in format ‘01-Nov-2006’
grid – array of the CGRF grid coordinates for the point of interest eg. [244,245]
type – arr of ints
- Returns:
windspeed, winddir pressure and time array from CGRF data for the times indicated. windspeed is in m/s winddir direction wind is blowing to in degrees measured counterclockwise from East. pressure is in Pa.
- salishsea_tools.stormtools.get_EC_observations(station, start_day, end_day)[source]
Gather hourly Environment Canada (EC) weather observations for the station and dates indicated.
The hourly EC data is stored in monthly files, so only a single month can be downloaded at a time.
- Parameters:
station (str) – Station name (no spaces). e.g. ‘PointAtkinson’
start_day (str) – Start date in the format ‘01-Dec-2006’.
end_day (str) – End date in the format ‘01-Dec-2006’.
- Returns:
wind_speed, wind_dir, temperature, times, lat and lon: wind speed is in m/s wind_dir is direction wind is blowing to in degrees measured counterclockwise from East temperature is in Kelvin time is UTC Also returns latitude and longitude of the station.
- salishsea_tools.stormtools.get_NOAA_predictions(station_no, start_date, end_date)[source]
Download tide predictions from NOAA site for one NOAA station for specified period.
- Parameters:
station_no (int) – Station number e.g. 9443090.
start_date (str) – Start date; e.g. ‘01-JAN-2010’.
end_date (str) – End date; e.g. ‘31-JAN-2010’
- Returns:
Saves text file with predictions in meters at one station. Time zone is UTC
- salishsea_tools.stormtools.get_NOAA_wlev(station_no, start_date, end_date)[source]
Download water level data from NOAA site for one NOAA station for specified period.
- Parameters:
station_no (int) – Station number e.g. 9443090.
start_date (str) – Start date; e.g. ‘01-JAN-2010’.
end_date (str) – End date; e.g. ‘31-JAN-2010’
- Returns:
Saves text file with water level data in meters at one station. Time zone is UTC
- salishsea_tools.stormtools.get_SSH_forcing(boundary, date)[source]
A function that returns the ssh forcing for the month of the date and boundary indicated.
- Parameters:
boundary (str) – A string naming the boundary. e.g ‘north’ or ‘west’
date (str) – A string indicating the date of interest. e.g. ‘01-Dec-2006’. The day needs to be the first day of the month.
- Returns:
ssh_forc, time_ssh: arrays of the ssh forcing values and corresponding times
- salishsea_tools.stormtools.get_operational_weather(start, end, grid)[source]
Returns the operational weather between the dates start and end at the grid point defined in grid.
- Parameters:
start (str) – string containing the start date of the weather collection in format ‘01-Nov-2006’
start – string containing the end date of the weather collection in format ‘01-Nov-2006’
grid – array of the operational grid coordinates for the point of interest eg. [244,245]
type – arr of ints
- Returns:
windspeed, winddir pressure and time array from weather data for the times indicated wind speed is m/s winddir is direction wind is blowing in degrees counterclockwise from east pressure is kPa time is UTC
- salishsea_tools.stormtools.get_statistics(obs, model, t_obs, t_model, sdt, edt)[source]
Calculates several statistics, such as mean error, maximum value, etc. for model and observations in a given time period.
- Parameters:
obs (array) – observation data
model (array) – model data
t_obs (array) – observations time
t_model (array) – model time
sdt (datetime object) – datetime object representing start date of analysis period
edt (datetime object) – datetime object representing end date of analysis period
- Returns:
max_obs, max_model, tmax_obs, tmax_model, mean_error, mean_abs_error, rms_error, gamma2 (see Bernier Thompson 2006), correlation matrix, willmott score, mean_obs, mean_model, std_obs, std_model
- salishsea_tools.stormtools.get_variables(fU, fV, fT, timestamp, depth)[source]
Generates masked u,v,SSH,S,T from NETCDF handles fU,fV,fT at timestamp and depth.
- Parameters:
fU (netcdf handle) – netcdf handle for Ugrid model output
fV (netcdf handle) – netcdf handle for Vgrid model output
fT (netcdf handle) – netcdf handle for Tgrid model output
timestamp (int) – the timestamp for desired model output
depth (int) – the model z-level for desired output
- Returns:
masked arrays U,V,E,S,T with of zonal velocity, meridional velocity, sea surface height, salinity, and temperature at specified time and z-level.
- salishsea_tools.stormtools.interp_to_model_time(time_model, varp, tp)[source]
Interpolates a variable to model output times.
- Parameters:
model_time (array with datetimes) – array of model output times as datetime objects
varp (array) – array of variable to be interpolated
tp (array) – array of times associated with variable
- Returns:
varp_interp, the variable interpolated to model_times
- salishsea_tools.stormtools.load_observations(start, end, location)[source]
Loads tidal observations from the DFO website using tidetools function
- Parameters:
start (string in format %d-%b-%Y) – a string representing the starting date of the observations.
end (string in format %d-%b-%Y) – a string representing the end date of the observations.
location (a string from the following - PointAtkinson, Victoria, PatriciaBay, CampbellRiver) – a string representing the location for observations
- Returns:
wlev_meas: a dict object with the water level measurements reference to Chart Datum
- salishsea_tools.stormtools.load_tidal_predictions(filename)[source]
Load tidal prediction from a file.
- Parameters:
filename (str) – The path and file name of a CSV file that contains ttide tidal predictions generated by
get_ttide_8.m
.- Returns:
ttide: Tidal predictions and mean sea level, the mean component from the harmonic analysis.
- Return type:
- salishsea_tools.stormtools.modelled_anomaly(sshs, location)[source]
Calculates the modelled ssh anomaly by finding the difference between a simulation with all forcing and a simulation with tides only.
- Parameters:
sshs (struc with dimensions 'all_forcing' and 'tidesonly') – A struc object with ssh data from all_forcing and tidesonly model runs
location (string either "PointAtkinson", "Victoria", "PatriciaBay", "CampbellRiver") – string defining the desired location
- Returns:
anom: the difference between all_forcing and tidesonly
- salishsea_tools.stormtools.observed_anomaly(ttide, wlev_meas, msl)[source]
Calculates the observed anomaly (water level obs - tidal predictions).
- Parameters:
ttide (struc with dimensions time, pred_all, pred_8) – A struc object that contains tidal predictions from get_ttide_8.m
wlev_meas (sruc with dimensions time, slev) – A struc object with observations from DFO
msl (float) – The mean sea level from tidal predictions
- Returns:
ssanomaly: the ssh anomaly (wlev_meas.slev-(ttide.pred_all+msl))
- salishsea_tools.stormtools.rebase_obs(data, time)[source]
Rebases the observations so that they are given on the half hour instead of hour. Half hour outputs calculated by averaging between two hourly outputs.
- Parameters:
data (array) – data to be rebased
time (array) – time outputs associated with data
- Returns:
rebase_data, rebase_time, the data and times shifted by half an hour
- salishsea_tools.stormtools.storm_surge_risk_level(site_name, max_ssh, ttide)[source]
Calculate the storm surge risk level for site_name, a tide gauge station name.
Thresholds are:
Highest predicted tide
Half way between highest predicted tide and highest historical water level
Highest historical water level
Threshold levels are obtained from
salishsea_tools.places.PLACES
dict.- :arg str site_name` Name of a tide gauge station at which to
calculate the storm surge risk.
- Parameters:
max_ssh (float) – The maximum sea surface height predicted for site_name.
ttide (
pandas.DataFrame
) – Tidal predictions from ttide.
- Returns:
None
for no storm surge risk, moderate risk for water level between max tide level and the half-way threshold, and extreme risk for water level above the half-way threshold
- salishsea_tools.stormtools.surge_tide(ssh, ttide, sdt, edt)[source]
Calculates the sea surface height from the model run with surge only. That is, adds tidal prediction to modelled surge. :arg ssh: shh from surge only model run :type ssh: array of numbers
- Parameters:
ttide (struc with dimension time, pred_all, pred_8) – struc with tidal predictions
sdt (datetime object) – datetime object representing start date of simulation
edt (datetime object) – datetime object representing end date of simulation
- Returns:
surgetide: the surge only run with tides added (mean not included)
- salishsea_tools.stormtools.truncate(data, time, sdt, edt)[source]
Returns truncated array for the time period of interest :arg data: data to be truncated :type data: array
- Parameters:
time (array) – time output associated with data
sdt (datetime object) – datetime object representing start date of analysis period
edt (datetime object) – datetime object representing end date of analysis period
- Returns:
data_t, time_t, truncated data and time arrays
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)[source]
Convert salinity in practical salinity units (psu) to TEOS-10 reference salinity in g/kg.
- Parameters:
psu (float,
numpy.ndarray
, list, or tuple) – Practical salinity units (psu) value to convert.- Returns:
TEOS-10 reference salinity in g/kg.
- Return type:
float or
numpy.ndarray
- salishsea_tools.teos_tools.teos_psu(teos)[source]
Convert TEOS-10 reference salinity in g/kg to salinity in practical salinity units (psu).
- Parameters:
teos (float,
numpy.ndarray
, list, or tuple) – TEOS-10 reference salinity value [g/kg] to convert.- Returns:
Practical salinity units (psu) value.
- Return type:
float or
numpy.ndarray
tidetools
Module
A collection of tools for dealing with tidal results from the Salish Sea NEMO model
- salishsea_tools.tidetools.ap2ep(Au, PHIu, Av, PHIv)[source]
Convert amplitude and phase to ellipse parameters.
Based on MATLAB script by Zhigang Xu, available at https://woodshole.er.usgs.gov/operations/sea-mat/tidal_ellipse-html/ap2ep.m
- salishsea_tools.tidetools.calc_diffs_meas_mod(runname, loc, grid)[source]
Calculate differences between measured and modelled water level e.g. (meas_wl_harm, Am_M2_all, Ao_M2_all, gm_M2_all, go_M2_all, D_F95_M2_all, D_M04_M2_all,Am_K1_all, Ao_K1_all, gm_K1_all, go_K1_all, D_F95_K1_all, D_M04_K1_all = calc_diffs_meas_mod(’50s_13Sep-20Sep’)
- Parameters:
runname (str) – name of model run
- Returns:
meas_wl_harm, Am_M2_all, Ao_M2_all, gm_M2_all, go_M2_all, D_F95_M2_all, D_M04_M2_all,Am_K1_all, Ao_K1_all, gm_K1_all, go_K1_all, D_F95_K1_all, D_M04_K1_all
- salishsea_tools.tidetools.convention_pha_amp(fitted_amp, fitted_pha)[source]
- This function takes the fitted parameters given for phase and
amplitude of the tidal analysis and returns them following the tidal parameter convention; amplitude is positive and phase is between -180 and +180 degrees.
- Parameters:
fitted_amp (float) – The amplitude given by the fitting function.
fitted_pha (float) – The phase given by the fitting function.
- Return fitted_amp, fitted_pha:
The fitted parameters following the conventions.
- salishsea_tools.tidetools.convert_to_hours(time_model, reftime='None')[source]
- Interpolates the datetime values into an array of hours from a
determined starting point
- Parameters:
time_model (array with datetimes) – array of model output time as datetime objects
reftime (date time object) – Epoc value. Default ‘None’, uses time_model[0] as the epoc. Note: must add tzinfo = tzutc() in datetime.datetime object.
- :returns tp_wrt_epoch, times with respect to the
beginning of the input in seconds
- salishsea_tools.tidetools.dateParserMeasured(s)[source]
Function to make datetime object aware of time zone e.g. date_parser=dateParserMeasured(‘2014/05/31 11:42’)
- Parameters:
s (str) – string of date and time
- Returns:
datetime object that is timezone aware
- salishsea_tools.tidetools.double(x, M2amp, M2pha, K1amp, K1pha, mean)[source]
Function for the fit, assuming only M2 and K2 tidal constituents.
- Parameters:
x
M2amp – Tidal amplitude of the M2 constituent
M2pha – Phase lag of M2 constituent
K1amp – Tidal amplitude of the K1 constituent
K1pha – Phase lag of K1 constituent
- :returns:(mean + M2amp*np.cos(M2FREQ*x-M2pha*np.pi/180.)
+K1amp*np.cos(K1FREQ*x-K1pha*np.pi/180.))
- salishsea_tools.tidetools.filter_timeseries(record, winlen=39, method='box')[source]
Filter a timeseries.
Developed for wind and tidal filtering, but can be modified for use with a variety of timeseries data. The data record should be at least half a window length longer at either end than the period of interest to accommodate window length shrinking near the array edges.
This function can only operate along the 0 axis. Please modify to include an axis argument in the future.
Types of filters (please add to these): * box: simple running mean * doodson: Doodson bandpass filter (39 winlen required)
- Parameters:
record (
numpy.ndarray
,xarray.DataArray
, ornetCDF4.Variable
) – timeseries record to be filteredwinlen (integer) – window length
method (string) – type of filter (ex. ‘box’, ‘doodson’, etc.)
- Returns filtered:
filtered timeseries
- Return type:
same as record
- salishsea_tools.tidetools.find_closest_model_point(lon, lat, X, Y, bathy, lon_tol=0.0052, lat_tol=0.00189, allow_land=False)[source]
Returns the grid co-ordinates of the closest non-land model point to a specified lon/lat.
Note
This function is deprecated. Use
geo_tools.find_closest_model_point()
instead.
- salishsea_tools.tidetools.find_model_level(depth, model_depths, fractional=False)[source]
Returns the index of the model level closest to a specified depth. The model level can be fractional (ie between two grid points). If depth is between 0 and first model level the result is negative. If depth is greater than the max depth the lowest level is returned. A python index is returned (count starting at 0). Add 1 for Fortran.
- Parameters:
depth (float > 0) – The specified depth
model_depths (numpy array (one dimensional)) – array of model depths
fractional (boolean) – a flag that specifies if a fractional model level is desired
- Returns:
idx, the model level index
- salishsea_tools.tidetools.fittit(uaus, time, nconst)[source]
Function to find tidal components of a time series over the whole area given.
Can be done over depth, or an area. Time must be in axis one, depth in axis two if applicable then the y, x if an area. In order to calculate the tidal components of an area at a single depth the time series must only have 3 dimensions. For a depth profile it must only have 2 dimensions
- Parameters:
uaus (:py:class:'np.ndarray' or float) – The time series to be analyzed.
time (:py:class:'np.ndarray') – Time over which the time series is taken in hours.
nconst (int) – The amount of tidal constituents used for the analysis. They added in pairs and by order of importance, M2, K1, S2, O1, N2, P1, K2, Q1.
- Returns:
a dictionary object containing a phase an amplitude for each harmonic constituent, for each orthogonal velocity
- salishsea_tools.tidetools.get_SS2_bathy_data()[source]
Get the Salish Sea 2 bathymetry and grid data e.g. bathy, X, Y = get_SS2_bathy_data()
Note
This function is deprecated due to hard-coding of
/ocean/klesouef/
path. Usetidetools.get_bathy_data()
instead.- Returns:
bathy, X, Y
- salishsea_tools.tidetools.get_SS_bathy_data()[source]
Get the Salish Sea bathymetry and grid data e.g. bathy, X, Y = get_SS_bathy_data()
Note
This function is deprecated due to hard-coding of
/ocean/klesouef/
path. Usetidetools.get_bathy_data()
instead.- Returns:
bathy, X, Y
- salishsea_tools.tidetools.get_all_perm_dfo_wlev(start_date, end_date)[source]
Get water level data for all permanent DFO water level sites for specified period.
- Parameters:
start_date (str) – Start date; e.g. ‘01-JAN-2010’.
end_date (str) – End date; e.g. ‘31-JAN-2010’
- Returns:
Saves text files with water level data at each site
- salishsea_tools.tidetools.get_amp_phase_data(runname, loc)[source]
Get the amplitude and phase data for one or more model runs.
- Parameters:
runname (str or tuple) – Name of the model run to process; e.g. runname = ’50s_15Sep-21Sep’, or if you’d like the harmonics of more than one run to be combined into one picture, give a tuple of names; e.g. (‘40d’, ‘41d50d’, ‘51d60d’).
loc (str) – Location of results folder; e.g. /ocean/dlatorne/MEOPAR/SalishSea/results
- Returns:
mod_M2_amp, mod_K1_amp, mod_M2_pha, mod_K1_pha
- salishsea_tools.tidetools.get_bathy_data(grid)[source]
Get the Salish Sea bathymetry from specified grid NC.Dataset e.g. bathy, X, Y = get_bathy_data(grid)
- Parameters:
grid (netcdf dataset) – netcdf object of model grid
- Returns:
bathy, X, Y
- salishsea_tools.tidetools.get_composite_harms(runnames, loc)[source]
Combine the harmonics from the specified runs into a ‘composite’ run.
The runs to be ‘composed’ must all have the same model setup.
- Parameters:
runnames (tuple) – Names of the model runs to process; e.g. (‘40d’, ‘41d50d’, ‘51d60d’).
loc (str) – Location of results folder; e.g. /ocean/dlatorne/MEOPAR/SalishSea/results
- Returns:
mod_M2_amp, mod_K1_amp, mod_M2_pha, mod_K1_pha
- Rtypes:
4-tuple of numpy.ndarray instances
- salishsea_tools.tidetools.get_composite_harms2()[source]
Take the results of the following runs (which are all the same model setup) and combine the harmonics into one ‘composite’ run.
50s_15-21Sep 50s_22-25Sep 50s_26-29Sep 50s_30Sep-6Oct 50s_7-13Oct
- Returns:
mod_M2_amp, mod_K1_amp, mod_M2_pha, mod_K1_pha
- salishsea_tools.tidetools.get_composite_harms_uv(runname, loc)[source]
Take the results of the specified runs (which must all have the same model setup) and combine the harmonics into one ‘composite’ run.
- Parameters:
runname (str) – name of the model run to process; e.g. runname = ’50s_15Sep-21Sep’, or if you’d like the harmonics of more than one run to be combined into one picture, give a list of names e.g. ‘40d’,’41d50d’,’51d60d’
loc (str) – location of results folder; e.g. /ocean/dlatorne/MEOPAR/SalishSea/results
- Returns:
mod_M2_u_amp, mod_M2_u_pha, mod_M2_v_amp, mod_M2_v_pha, mod_K1_u_amp, mod_K1_u_pha, mod_K1_v_amp, mod_K1_v_pha
- salishsea_tools.tidetools.get_current_harms(runname, loc)[source]
Get harmonics of current at a specified lon, lat and depth.
- Parameters:
runname (str) – name of the model run to process; e.g. runname = ’50s_15Sep-21Sep’ (doesn’t deal with multiple runs)
loc (str) – location of results folder; e.g. /ocean/dlatorne/MEOPAR/SalishSea/results
- Returns:
mod_M2_u_amp, mod_M2_u_pha, mod_M2_v_amp, mod_M2_v_pha
- salishsea_tools.tidetools.get_dfo_wlev(station_no, start_date, end_date)[source]
Download water level data from DFO site for one DFO station for specified period.
- Parameters:
station_no (int) – Station number e.g. 7795.
start_date (str) – Start date; e.g. ‘01-JAN-2010’.
end_date (str) – End date; e.g. ‘31-JAN-2010’
- Returns:
Saves text file with water level data at one station
- salishsea_tools.tidetools.get_netcdf_amp_phase_data(loc)[source]
Calculate amplitude and phase from the results of a particular run of the Salish Sea model
- Parameters:
runname (str) – name of the model run to process e.g. ’50s_15Sep-21Sep’
- Returns:
model M2 amplitude, model K1 amplitude, model M2 phase, model K1 phase
- salishsea_tools.tidetools.get_netcdf_amp_phase_data_concepts110(loc)[source]
Calculate amplitude and phase from the results of the CONCEPTS110 model e.g. mod_M2_amp, mod_M2_pha = get_netcdf_amp_phase_data_concepts110()
- Returns:
model M2 amplitude, model M2 phase
- salishsea_tools.tidetools.get_netcdf_amp_phase_data_jpp72(loc)[source]
Calculate amplitude and phase from the results of the JPP72 model e.g. mod_M2_amp, mod_M2_pha = get_netcdf_amp_phase_data_jpp72()
- Returns:
model M2 amplitude, model M2 phase
- salishsea_tools.tidetools.get_run_length(runname, loc)[source]
Get the length, in days, of the run from the namelist file
- Parameters:
runname (str) – name of the model run to process; e.g. ’50s_15Sep-21Sep’
loc (str) – location of results folder; e.g. ‘/ocean/dlatorne/MEOPAR/SalishSea/results’
- Returns:
length of run in days
- salishsea_tools.tidetools.get_subdomain_bathy_data()[source]
Get the subdomain bathymetry and grid data e.g. bathy, X, Y = get_subdomain_bathy_data()
Note
This function is deprecated due to hard-coding of
/ocean/klesouef/
path. Usetidetools.get_bathy_data()
instead.- Returns:
bathy, X, Y
- salishsea_tools.tidetools.haversine(lon1, lat1, lon2, lat2)[source]
Calculate the great-circle distance between two points on a sphere from their longitudes and latitudes.
Note
This function is deprecated. Use
geo_tools.haversine()
instead.
- salishsea_tools.tidetools.octuple(x, M2amp, M2pha, K1amp, K1pha, S2amp, S2pha, O1amp, O1pha, N2amp, N2pha, P1amp, P1pha, K2amp, K2pha, Q1amp, Q1pha, mean)[source]
Function for the fit, for all the constituents: M2, K2, S1, O1, N2, P1, K2 and Q1.
- Parameters:
x – Independent variable, time.
*amp (float) – Tidal amplitude of the a constituent
*pha (float) – Phase lag of a constituent
- Returns:
function for fitting 8 frequencies
- salishsea_tools.tidetools.plot_amp_map(X, Y, grid, amp, constituent_name, figsize=(9, 9))[source]
Plot the amplitude of one constituent throughout the whole domain.
- Parameters:
X (numpy array) – specified model longitude
Y (numpy array) – specified model latitude
grid (netcdf dataset) – model grid netcdf
amp (numpy array) – amplitude
constituent_name (str) – Name of tidal constituent. Used as subplot title.
figsize (2-tuple) – Figure size, (width, height).
- Returns:
Figure containing plots of observed vs. modelled amplitude and phase of the tidal constituent.
- Return type:
Matplotlib figure
- salishsea_tools.tidetools.plot_amp_phase_maps(runname, loc, grid)[source]
Plot the amplitude and phase results for a model run e.g. plot_amp_phase_maps(’50s_15Sep-21Sep’)
- Parameters:
runname (str) – name of the model run to process; e.g. runname = ’50s_15Sep-21Sep’, or if you’d like the harmonics of more than one run to be combined into one picture, give a list of names; e.g. ‘40d’,’41d50d’,’51d60d’
loc (str) – location of results folder; e.g. /ocean/dlatorne/MEOPAR/SalishSea/results
grid (netcdf dataset) – netcdf file of grid data
- Returns:
plots the amplitude and phase
- salishsea_tools.tidetools.plot_coastline(grid)[source]
Plots a map of the coastline.
Note
This function is deprecated. Use
viz_tools.plot_coastline()
instead.- Parameters:
grid (netcdf dataset) – netcdf file of bathymetry
- Returns:
coastline map
- salishsea_tools.tidetools.plot_diffs_on_domain(diffs, meas_wl_harm, calc_method, constituent_name, grid, scale_fac=100, legend_scale=0.1, figsize=(9, 9))[source]
Plot differences as circles of varying radius on a map of the model domain.
- Parameters:
diffs (numpy array) – Differences calculated between measured and modelled values [m].
meas_wl_harm (numpy array) – Measured water level harmonics read in from csv.
calc_method (str) – Method for calculating differences (‘F95’ or ‘M04’)
constituent_name (str) – Name of tidal constituent. Used as subplot title.
grid (Netcdf dataset) – Netcdf file of grid data.
scale_fac (float) – Scale factor to make difference dots visible on map.
legend_scale – Size of legend sot; [cm].
figsize (2-tuple) – Figure size, (width, height).
- Returns:
Figure containing plots of observed vs. modelled amplitude and phase of the tidal constituent.
- Return type:
Matplotlib figure
- salishsea_tools.tidetools.plot_meas_mod_locations(measlon, measlat, modlon, modlat, X, Y, bathy)[source]
Plot two locations on a contour map of bathymetry, where bathy, X and Y are returned from get_bathy_data(grid); e.g. plot_meas_mod_locations(-124.0, 48.4, -124.2, 48.1,X,Y,bathy)
- Parameters:
measlon (float) – longitude of point 1
measlat (float) – latitude of point 1
modlon (float) – longitude of point 2
modlat (float) – latitude of point 2
X (numpy array) – specified model longitude
Y (numpy array) – specified model latitude
bathy (numpy array) – model bathymetry
- Returns:
plots contour plot with 2 points
- salishsea_tools.tidetools.plot_pha_map(X, Y, grid, pha, constituent_name, figsize=(9, 9))[source]
Plot the phase of one constituent throughout the whole domain.
- Parameters:
X (numpy array) – specified model longitude
Y (numpy array) – specified model latitude
pha (numpy array) – phase
constituent_name (str) – Name of tidal constituent. Used as subplot title.
figsize (2-tuple) – Figure size, (width, height).
- Returns:
Figure containing plots of observed vs. modelled amplitude and phase of the tidal constituent.
- Return type:
Matplotlib figure
- salishsea_tools.tidetools.plot_scatter_pha_amp(Am, Ao, gm, go, constituent_name, figsize=(12, 6), split1=0, split2=0, labels=['', '', ''])[source]
Plot scatter plot of observed vs. modelled phase and amplitude
- Parameters:
Am (Numpy array) – Modelled amplitude.
Ao (NumPy array) – Observed amplitude.
gm (NumPy array) – Modelled phase.
go (NumPy array) – Observed phase.
constituent_name (str) – Name of tidal constituent. Used as subplot title.
figsize (2-tuple) – Figure size, (width, height).
split1 (int) – Change colors at this point in array, if > 0
split2 (int) – Change colors at this point in array, if > 0
labels (list of strings) – Labels for three different splits
- Returns:
Figure containing plots of observed vs. modelled amplitude and phase of the tidal constituent.
- Return type:
Matplotlib figure
- salishsea_tools.tidetools.plot_wlev_const_transect(savename, statnums, runname, loc, grid, *args)[source]
Plot water level of the modelled M2 and K1 constituents and measured M2 and K1 constituents in a transect at specified stations e.g. plot_wlev_const_transect(‘40d’,’/ocean/klesouef/meopar/)
- Parameters:
savename (str) – tag for saving the pdf pics
statnums (numpy array) – array of station numbers
runname (str) – unique name of run
loc (str) – location of model results
grid (netcdf dataset) – netcdf dataset of model grid
args (str) – other runname and results location strings, in case you want to plot more than set of model results on the same figure
- Returns:
plots transect of M2 and K1 water level constituent
- salishsea_tools.tidetools.plot_wlev_transect_map(grid, stn_nums, stn_file='obs_tidal_wlev_const_all.csv', figsize=(9, 9))[source]
Plot a map of the coastline and the transect of water level stations, which are plotted in
plot_wlev_M2_const_transect()
.- Parameters:
grid (netcdf dataset) – Bathymetry file.
stn_nums (numpy array) – Station numbers to plot.
stn_file (str) – Name of file containing tidal observation station names, lats/lons, and tidal component amplitudes and phases.
figsize (2-tuple) – Figure size, (width, height).
- Returns:
Figure containing plots of observed vs. modelled amplitude and phase of the tidal constituent.
- Return type:
Matplotlib figure
- salishsea_tools.tidetools.quadruple(x, M2amp, M2pha, K1amp, K1pha, S2amp, S2pha, O1amp, O1pha, mean)[source]
- Function for the fit, assuming only 4 constituents of importance are:
M2, K2, S1 and O1.
- Parameters:
x – Independent variable, time.
*amp (float) – Tidal amplitude of the a constituent
*pha (float) – Phase lag of a constituent
- Returns:
function for fitting 4 frequencies
- salishsea_tools.tidetools.read_dfo_wlev_file(filename)[source]
Read in the data in the csv file downloaded from DFO website
- Parameters:
filename (str) – Filename to read.
- Returns:
measured time, measured water level, station name, station number, station lat, station long
- salishsea_tools.tidetools.sextuple(x, M2amp, M2pha, K1amp, K1pha, S2amp, S2pha, O1amp, O1pha, N2amp, N2pha, P1amp, P1pha, mean)[source]
Function for the fit, assuming 6 constituents of importance are: M2, K2, S1, O1, N2 and P1.
- Parameters:
x – Independent variable, time.
*amp (float) – Tidal amplitude of the a constituent
*pha (float) – Phase lag of a constituent
- Returns:
function for fitting 6 frequencies
timeseries_tools
Module
A library of Python functions for loading SalishSeaCast timeseries while conserving memory.
- salishsea_tools.timeseries_tools.make_filename_list(timerange, qty, model='nowcast', resolution='h', path='/results/SalishSea')[source]
Return a sequential list of Nowcast results filenames to be passed into xarray.open_mfdataset or timeseries_tools.load_NEMO_timeseries.
- Parameters:
timerange (list or tuple of str) – list or tuple of date strings (e.g., [‘2017 Jan 1 00:00’, ‘2017 Jan 31 23:00’])
qty (str) – quantity type (‘U’ for zonal velocity, ‘V’ for meridional velocity, ‘W’ for vertical velocity, ‘T’ for tracers)
model (str) – forecast type (e.g., ‘nowcast’, ‘nowcast-green’, ‘forecast’)
resolution (str) – time resolution (‘h’ for hourly, ‘d’, for daily)
path (str) – path to results archive
- Returns:
Sequential list of Nowcast results filenames
- Return type:
list of str
- salishsea_tools.timeseries_tools.reshape_coords(mask_in, dim_in, index=0, spacing=1)[source]
Prepare the mask and grid for the selected timeseries slice, and reshape into 1 spatial dimension
- salishsea_tools.timeseries_tools.reshape_to_grid(data_flat, coords, shape)[source]
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'))[source]
Convert a compass bearing to a heading.
- Parameters:
bearing (float) – The compass bearing to convert.
headings (sequence) – A sequence of headings to convert the bearing to. The default is the 16 compass points that divide the compass into 22.5° segments.
- Returns:
Compass heading.
- Return type:
str
- salishsea_tools.unit_conversions.humanize_time_of_day(date_time)[source]
Return a “humanized” time of day string like “early Monday afternoon” that corresponds to date_time.
We use the same terminology as is used in the Environment Canada weather forecasts: https://www.ec.gc.ca/meteo-weather/default.asp?lang=En&n=10220A6B-1#c4
- Parameters:
date_time (
arrow.Arrow
) – Date/time to humanize.- Returns:
Humanized time of day and day name; e.g. early Monday afternoon
- Return type:
str
- salishsea_tools.unit_conversions.mps_knots(m_per_s)[source]
Convert speed from m/s to knots.
m_per_s may be either a scalar number or a
numpy.ndarray
object, and the return value will be of the same type.- Parameters:
m_per_s – Speed in m/s to convert.
- Returns:
Speed in knots.
- salishsea_tools.unit_conversions.mps_kph(m_per_s)[source]
Convert speed from m/s to km/hr.
m_per_s may be either a scalar number or a
numpy.ndarray
object, and the return value will be of the same type.- Parameters:
m_per_s – Speed in m/s to convert.
- Returns:
Speed in km/hr.
- salishsea_tools.unit_conversions.psu_teos(psu)[source]
Convert salinity in practical salinity units (psu) to TEOS-10 reference salinity in g/kg.
- Parameters:
psu (float,
numpy.ndarray
, list, or tuple) – Practical salinity units (psu) value to convert.- Returns:
TEOS-10 reference salinity in g/kg.
- Return type:
float or
numpy.ndarray
- salishsea_tools.unit_conversions.teos_psu(teos)[source]
Convert TEOS-10 reference salinity in g/kg to salinity in practical salinity units (psu).
- Parameters:
teos (float,
numpy.ndarray
, list, or tuple) – TEOS-10 reference salinity value [g/kg] to convert.- Returns:
Practical salinity units (psu) value.
- Return type:
float or
numpy.ndarray
- salishsea_tools.unit_conversions.wind_to_from(wind_to)[source]
Convert wind bearing from “physics” compass “to” direction to “human”compass “from” direction.
“Physics” compass has zero at the east and bearing angles increase in the counter-clockwise direction.
“Human” compass has zero at the north and bearing angles increase in the clockwise direction.
Example: 0° on the physics compass indicates air flow to the east which is called a west (270°) wind on the human compass.
wind_to may be either a scalar number or a
numpy.ndarray
object, and the return value will be of the same type.- Parameters:
wind_to – Bearing on physics (to) compass to convert.
- Returns:
Bearing on human (from) compass.
utilities
Module
A library of basic utility Python functions
- salishsea_tools.utilities.findnamelist(namelist, year, month, day, pathname='/results/SalishSea/nowcast-green')[source]
Find the most recent namelist from a results file.
arg str namelist: name of the namelist you are looking for
arg int year: year
arg int month: month
arg int day: day
arg int pathname: pathname to the results directory
visualisations
Module
Functions for common model visualisations
- salishsea_tools.visualisations.contour_layer_grid(axes, data, mask, clevels=10, lat=None, lon=None, cmap=None, var_name=None, land_colour='burlywood', is_depth_avg=False, is_pcolmesh=False, title='', cbar_args=None)[source]
Contour 2d data at an arbitrary klevel on the model grid
- Parameters:
axes (
matplotlib.axes.Axes
) – Axes instance to plot thalweg contour on.data (
numpy.ndarray
) – 2D array to be contoured at level kklev (int) – Index of k-level along which to contour
mask (
numpy.ndarray
) – Mask array with same dimensions as dataclevels (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')[source]
Contour the data stored in var along the domain thalweg.
- Parameters:
axes (
matplotlib.axes.Axes
) – Axes instance to plot thalweg contour on.var (
numpy.ndarray
) – Salish Sea NEMO model results variable to be contouredbathy (
netCDF4.Dataset
) – Salish Sea NEMO model bathymetry datasetmesh_mask (
netCDF4.Dataset
) – Salish Sea NEMO model mesh_mask datasetclevels (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])[source]
Boilerplate figure code like coastline, aspect ratio, axis lims, etc.
Note
This function is deprecated. Call plot formatting functions individually instead.
- salishsea_tools.visualisations.load_thalweg(depths, var, lons, lats, thalweg_pts)[source]
Returns depths, cumulative distance and variable along thalweg.
- Parameters:
depths (
numpy.ndarray
) – depth array for variable. Can be 1D or 3D.var (
numpy.ndarray
) – 3D Salish Sea NEMO model results variablelons (
numpy.ndarray
) – Salish Sea NEMO model longitude grid datalats (
numpy.ndarray
) – Salish Sea NEMO model latitude grid datathalweg_pts (2D numpy array) – Salish Sea NEMO model grid indices along thalweg
- Returns:
dep_thal, xx_thal, var_thal, all the same shape (depth, thalweg length)
- salishsea_tools.visualisations.plot_drifters(ax, DATA, DRIFT_OBJS=None, color='red', cutoff=24, zorder=15)[source]
Plot a drifter track from ODL Drifter observations.
- Parameters:
time_ind (str or
datetime.datetime
) – Time index (current drifter position, track will be visible up until this point, ex. ‘YYYY-mmm-dd HH:MM:SS’, format is flexible)ax (
matplotlib.pyplot.axes
) – Axis objectDATA (
xarray.Dataset
) – Drifter track datasetcolor (str) – Drifter track color
cutoff (integer) – Time threshold for color plotting (hours)
zorder (integer) – Plotting layer specifier
- Returns:
Dictionary of line objects
- Return type:
dict >
matplotlib.lines.Line2D
- salishsea_tools.visualisations.plot_tracers(ax, qty, DATA, C=None, coords='map', clim=[0, 35, 1], cmap='jet', zorder=0)[source]
Plot a horizontal slice of NEMO tracers as filled contours.
Note
This function is deprecated. Plot NEMO results directly using matplotlib.pyplot.contourf or equivalent instead.
- salishsea_tools.visualisations.plot_velocity(ax, model, DATA, Q=None, coords='map', processed=False, spacing=5, mask=True, color='black', scale=20, headwidth=3, linewidth=0, zorder=5)[source]
Plot a horizontal slice of NEMO or GEM velocities as quiver objects. Accepts subsampled u and v fields via the processed keyword argument.
Note
This function is deprecated. Plot NEMO results directly using matplotlib.pyplot.quiver or equivalent instead.
viz_tools
Module
A collection of Python functions to do routine tasks associated with plotting and visualization.
- salishsea_tools.viz_tools.calc_abs_max(array)[source]
Return the maximum absolute value in the array.
- Parameters:
array (
numpy.ndarray
ornetCDF4.Dataset
) – Array to find the maximum absolute value of.- Returns:
Maximum absolute value
- Return type:
numpy.float32
- salishsea_tools.viz_tools.clear_contours(C)[source]
Clear contours from an existing plot.
- Parameters:
C (
matplotlib.contour.QuadContourSet
) – contour object handle
- salishsea_tools.viz_tools.plot_boundary(ax, grid, mask, dim='depth', index=0, coords='grid', color='burlywood', zorder=10)[source]
Plot the land boundary for a given NEMO domain slice.
- Parameters:
ax (
matplotlib.axes._subplots.AxesSubplot
) – axes object handlegrid (
xarray.DataSet
) – NEMO grid variablesmask (
xarray.DataSet
) – NEMO mask variablesdim (str) – dimension for slice (one of ‘depth’, ‘x’, or ‘y’)
index (int or float) – slice index (integer for ‘x’ or ‘y’, float for ‘depth’)
coords (str) – ‘map’ or ‘grid’
color (str) – land color
zorder (int) – desired vertical plot layer
- Returns:
land and coastline contour object handles
- Return type:
matplotlib.contour.QuadContourSet
- salishsea_tools.viz_tools.plot_coastline(axes, bathymetry, coords='grid', isobath=0, xslice=None, yslice=None, color='black', server='local', zorder=2)[source]
Plot the coastline contour line from bathymetry on the axes.
The bathymetry data may be specified either as a file path/name, or as a
netCDF4.Dataset
instance. If a file path/name is given it is opened and read into anetCDF4.Dataset
so, if this function is being called in a loop, it is best to provide it with a bathymetry dataset to avoid the overhead of repeated file reads.- Parameters:
axes (
matplotlib.axes.Axes
) – Axes instance to plot the coastline contour line on.bathymetry (str or
netCDF4.Dataset
) – File path/name of a netCDF bathymetry data file or a dataset object containing the bathymetry data.coords (str) – Type of plot coordinates to set the aspect ratio for; either grid (the default) or map.
isobath (float) – Depth to plot the contour at; defaults to 0.
xslice (
numpy.ndarray
) – X dimension slice to defined the region for which the contour is to be calculated; defaults to None which means the whole domain. If an xslice is given, a yslice value is also required.yslice (
numpy.ndarray
) – Y dimension slice to defined the region for which the contour is to be calculated; defaults to None which means the whole domain. If a yslice is given, an xslice value is also required.color (str, float, rgb or rgba tuple) – Matplotlib colour argument
zorder (integer) – Plotting layer specifier
- Returns:
Contour line set
- Return type:
matplotlib.contour.QuadContourSet
- salishsea_tools.viz_tools.plot_land_mask(axes, bathymetry, coords='grid', isobath=0, xslice=None, yslice=None, color='black', server='local', zorder=1)[source]
Plot land areas from bathymetry as solid colour polygons on the axes.
The bathymetry data may be specified either as a file path/name, or as a
netCDF4.Dataset
instance. If a file path/name is given it is opened and read into anetCDF4.Dataset
so, if this function is being called in a loop, it is best to provide it with a bathymetry dataset to avoid the overhead of repeated file reads.- Parameters:
axes (
matplotlib.axes.Axes
) – Axes instance to plot the land mask polygons on.bathymetry (str or
netCDF4.Dataset
) – File path/name of a netCDF bathymetry data file or a dataset object containing the bathymetry data.coords (str) – Type of plot coordinates to set the aspect ratio for; either grid (the default) or map.
isobath (float) – Depth to plot the land mask at; defaults to 0.
xslice (
numpy.ndarray
) – X dimension slice to defined the region for which the land mask is to be calculated; defaults to None which means the whole domain. If an xslice is given, a yslice value is also required.yslice (
numpy.ndarray
) – Y dimension slice to defined the region for which the land maks is to be calculated; defaults to None which means the whole domain. If a yslice is given, an xslice value is also required.color (str, float, rgb or rgba tuple) – Matplotlib colour argument
zorder (integer) – Plotting layer specifier
- Returns:
Contour polygon set
- Return type:
matplotlib.contour.QuadContourSet
- salishsea_tools.viz_tools.rotate_vel(u_in, v_in, origin='grid')[source]
Rotate u and v component values to either 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 valuesv_in (
numpy.ndarray
|xarray.DataArray
) – v velocity component valuesorigin (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:
- salishsea_tools.viz_tools.rotate_vel2(u_in, v_in, coords, origin='grid')[source]
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 valuesv_in (
numpy.ndarray
) – v velocity component valuescoords (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:
- salishsea_tools.viz_tools.rotate_vel_bybearing(u_in, v_in, coords, origin='grid')[source]
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 valuesv_in (
numpy.ndarray
) – v velocity component valuescoords (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:
- salishsea_tools.viz_tools.set_aspect(axes, aspect=1.1363636363636362, coords='grid', lats=None, adjustable='box')[source]
Set the aspect ratio for the axes.
This is a thin wrapper on the
matplotlib.axes.Axes.set_aspect()
method. Its primary purpose is to free the user from needing to remember the 5/4.4 nominal aspect ratio for the Salish Sea NEMO model grid, and the formula for the aspect ratio based on latitude for map coordinates. It also sets the axes aspect ratio withadjustable='box-forced'
so that the axes can be shared if desired.- Parameters:
axes (
matplotlib.axes.Axes
) – Axes instance to set the aspect ratio of.aspect (float) – Aspect ratio.
coords (str) – Type of plot coordinates to set the aspect ratio for; either grid (the default) or map.
lats (
numpy.ndarray
) – Array of latitude values to calculate the aspect ratio from; only required when coordinates='map'.adjustable (str) – How to adjust the axes box.
- Returns:
Aspect ratio.
- Return type:
float
Note
To explicitly set the aspect ratio for map coordinates (instead of calculating it from latitudes) set aspect to the aspect ratio, coords='map', and use the default lats=None.
- salishsea_tools.viz_tools.unstagger(ugrid, vgrid)[source]
Interpolate u and v component values to values at grid cell centres.
The shapes are the returned arrays are 1 less than those of the input arrays in the y and x dimensions.
- Parameters:
ugrid (
numpy.ndarray
) – u velocity component values with axes (…, y, x)vgrid (
numpy.ndarray
) – v velocity component values with axes (…, y, x)
- Returns u, v:
u and v component values at grid cell centres
- Return type:
2-tuple of
numpy.ndarray
- salishsea_tools.viz_tools.unstagger_xarray(qty, index)[source]
Interpolate u, v, or w component values to values at grid cell centres.
Named indexing requires that input arrays are XArray DataArrays.
- Parameters:
qty (
xarray.DataArray
) – u, v, or w component valuesindex (str) – index name along which to centre (generally one of ‘gridX’, ‘gridY’, or ‘depth’)
- Returns qty:
u, v, or w component values at grid cell centres
- Return type:
xarray.DataArray
wind_tools
Module
Functions for working with wind model results and wind observations data.
- salishsea_tools.wind_tools.bearing_heading(bearing, headings=('N', 'NNE', 'NE', 'ENE', 'E', 'ESE', 'SE', 'SSE', 'S', 'SSW', 'SW', 'WSW', 'W', 'WNW', 'NW', 'NNW', 'N'))[source]
Convert a compass bearing to a heading.
- Parameters:
bearing (float) – The compass bearing to convert.
headings (sequence) – A sequence of headings to convert the bearing to. The default is the 16 compass points that divide the compass into 22.5° segments.
- Returns:
Compass heading.
- Return type:
str
- salishsea_tools.wind_tools.calc_wind_avg_at_point(date_time, weather_path, windji, avg_hrs=-4)[source]
Calculate the average wind components for a time period at a single weather dataset grid point.
Note
The present implementation only supports averaging over a time period ending at:kbd:date_time and values for avg_hrs in the range [-24, 0].
- Parameters:
date_time (
arrow.arrow.Arrow
) – Date and time to use as base for the calculation.weather_path (str) – The directory where weather dataset files are stored.
windji (2-tuple) – Indices of weather dataset grid point to calculate the average at as (lon_index, lat_index).
avg_hrs (float) – Number of hours to calculate
- Returns:
2-tuple containing the averaged wind components. The
u
attribute holds the u-direction component, and thev
attribute holds the v-direction component.- Return type:
collections.namedtuple
- Raises:
IndexError
if avg_hrs is outside the range [-24, 0].
- salishsea_tools.wind_tools.mps_knots(m_per_s)[source]
Convert speed from m/s to knots.
m_per_s may be either a scalar number or a
numpy.ndarray
object, and the return value will be of the same type.- Parameters:
m_per_s – Speed in m/s to convert.
- Returns:
Speed in knots.
- salishsea_tools.wind_tools.mps_kph(m_per_s)[source]
Convert speed from m/s to km/hr.
m_per_s may be either a scalar number or a
numpy.ndarray
object, and the return value will be of the same type.- Parameters:
m_per_s – Speed in m/s to convert.
- Returns:
Speed in km/hr.
- salishsea_tools.wind_tools.wind_speed_dir(u_wind, v_wind)[source]
Calculate wind speed and direction from u and v wind components.
u_wind and v_wind may be either scalar numbers or
numpy.ndarray
objects, and the elements of the return value will be of the same type.- Parameters:
u_wind – u-direction component of wind vector.
v_wind – v-direction component of wind vector.
- Returns:
2-tuple containing the wind speed and direction. The
speed
attribute holds the wind speed(s), and thedir
attribute holds the wind direction(s).- Return type:
collections.namedtuple
- salishsea_tools.wind_tools.wind_to_from(wind_to)[source]
Convert wind bearing from “physics” compass “to” direction to “human”compass “from” direction.
“Physics” compass has zero at the east and bearing angles increase in the counter-clockwise direction.
“Human” compass has zero at the north and bearing angles increase in the clockwise direction.
Example: 0° on the physics compass indicates air flow to the east which is called a west (270°) wind on the human compass.
wind_to may be either a scalar number or a
numpy.ndarray
object, and the return value will be of the same type.- Parameters:
wind_to – Bearing on physics (to) compass to convert.
- Returns:
Bearing on human (from) compass.