Utils Module¶
-
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 objectReturns: 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 12Returns: 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
- subregions (
numpy.ma.array
) – list of subregions
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 timeReturns: 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 objectReturns: time series for the dataset of shape (nT)
-
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.
- lats (
-
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 formatReturns: Dataset values array with shape (num_year, 12, num_lat, num_lon)