Utils Module

utils.CORDEX_boundary(domain_name)
Parameters:domain_name (:mod:'string') – CORDEX domain name (http://www.cordex.org/)
utils.calc_area_weighted_spatial_average(dataset, area_weight=False)

Calculate area weighted average of the values in OCW dataset

Parameters:dataset (dataset.Dataset) – Dataset object
Returns:time series for the dataset of shape (nT)
utils.calc_climatology_monthly(dataset)

Calculate monthly mean values for a dataset. Follow COARDS climo stats calculation, the year can be given as 0 but the min year allowed in Python is 1 http://www.cgd.ucar.edu/cms/eaton/netcdf/CF-20010629.htm#climatology

Parameters:dataset (dataset.Dataset) – Monthly binned Dataset object with the number of months divisible by 12
Returns:Mean values for each month of the year of shape (12, num_lats, num_lons) and times array of datetime objects of length 12
Raises:ValueError – If the number of monthly bins is not divisible by 12
utils.calc_climatology_year(dataset)

Calculate climatology of dataset’s values for each year

Parameters:dataset (dataset.Dataset) – Monthly binned Dataset object with an evenly divisible number of months.
Returns:Mean values for each year (annual_mean) and mean values for all years (total_mean)
Raises:ValueError – If the number of monthly bins is not evenly divisible by 12.
utils.calc_subregion_area_mean_and_std(dataset_array, subregions)

Calculate area mean and standard deviation values for a given subregions using datasets on common grid points

Parameters:
  • dataset_array – An array of OCW Dataset Objects :type list: :mod:’list’
  • subregions – list of subregions :type subregions: numpy.ma.array
Returns:

area averaged time series for the dataset of shape (ntime, nsubregion)

utils.calc_temporal_mean(dataset)

Calculate temporal mean of dataset’s values

Parameters:dataset (dataset.Dataset) – OCW Dataset whose first dimension is time
Returns:Mean values averaged for the first dimension (time)
utils.calc_time_series(dataset)

Calculate time series mean values for a dataset

Parameters:dataset (dataset.Dataset) – Dataset object
Returns:time series for the dataset of shape (nT)

Calculate temporal trends in an ensemble of time series :param timeseries_array: Two dimensional array. 1st index: model, 2nd index: time. :type timeseries_array: :class:`numpy.ndarray’

Parameters:sampling – A list whose elements are one-dimensional numpy arrays
Returns:temporal trend and estimated error from bootstrapping
Return type::float:`float’,’float’
utils.calculate_temporal_trend_of_time_series(x, y)

Calculate least-square trends (a) in y = ax+b and a’s standard error :param x: time series :type x: :class:`numpy.ndarray’

Parameters:x (:class:`numpy.ndarray’) – time series
Returns:temporal trend and standard error
Return type::float:`float’,’float’

Calculate temporal trends in dataset.values :param dataset: The dataset from which time values should be extracted. :type dataset: :class:`dataset.Dataset’

Returns:Arrays of the temporal trend and standard error
Return type:numpy.ma.core.MaskedArray
utils.decode_time_values(dataset, time_var_name)

Decode NetCDF time values into Python datetime objects.

Parameters:
  • dataset (netCDF4.Dataset) – The dataset from which time values should be extracted.
  • time_var_name (string) – The name of the time variable in dataset.
Returns:

The list of converted datetime values.

Raises:

ValueError – If the time units value couldn’t be parsed, if the base time value couldn’t be parsed, or if the time_var_name could not be found in the dataset.

utils.get_temporal_overlap(dataset_array)

Find the maximum temporal overlap across the observation and model datasets

Parameters:dataset_array – an array of OCW datasets
utils.normalize_lat_lon_values(lats, lons, values)

Normalize lat/lon values

Ensure that lat/lon values are within [-180, 180)/[-90, 90) as well as sorted. If the values are off the grid they are shifted into the expected range.

Parameters:
  • lats (numpy.ndarray) – A 1D numpy array of sorted lat values.
  • lons (numpy.ndarray) – A 1D numpy array of sorted lon values.
  • values – A 3D array of data values.
Returns:

A tuple() of the form (adjust_lats, adjusted_lons, adjusted_values)

Raises:

ValueError – If the lat/lon values are not sorted.

utils.parse_base_time_string(time_format)

Retrieve base time string from time data units information.

Parameters:time_format (string) – The time data units string from the dataset being processed. The string should be of the format ‘<units> since <base time date>’
Returns:The base time string split out of the time units information.
Raises:ValueError – When the time_format parameter is malformed.
utils.parse_time_base(time_format)

Parse time base object from the time units string.

Parameters:time_format (string) – The time data units string from the dataset being processed. The string should be of the format ‘<units> since <base time date>’
Returns:The base time as a datetime object.
Raises:ValueError – When the base time string couldn’t be parsed from the units time_format string or if the date string didn’t match any of the expected formats.
utils.parse_time_units(time_format)

Parse units value from time units string.

The only units that are supported are: seconds, minutes, hours, days,
months, or years.
Parameters:time_format (string) – The time data units string from the dataset being processed. The string should be of the format ‘<units> since <base time date>’
Returns:The unit substring from the time units string
Raises:ValueError – If the units present in the time units string doesn’t match one of the supported unit value.
utils.reshape_monthly_to_annually(dataset)

Reshape monthly binned dataset to annual bins.

Reshape a monthly binned dataset’s 3D value array with shape (num_months, num_lats, num_lons) to a 4D array with shape (num_years, 12, num_lats, num_lons). This causes the data to be binned annually while retaining its original shape.

It is assumed that the number of months in the dataset is evenly divisible by 12. If it is not you will receive error due to an invalid shape.

Example change of a dataset’s shape: (24, 90, 180) -> (2, 12, 90, 180)

Parameters:dataset (dataset.Dataset) – Dataset object with full-year format
Returns:Dataset values array with shape (num_year, 12, num_lat, num_lon)
utils.shapefile_boundary(boundary_type, region_names)
Parameters:
  • boundary_type (:mod:'string') – The type of spatial subset boundary
  • region_names (:mod:'list') – An array of regions for spatial subset