sup3r.models.surface.SurfaceSpatialMetModel

sup3r.models.surface.SurfaceSpatialMetModel#

class SurfaceSpatialMetModel(lr_features, s_enhance, noise_adders=None, temp_lapse=None, w_delta_temp=None, w_delta_topo=None, pres_div=None, pres_exp=None, interp_method='LANCZOS', input_resolution=None, fix_bias=True)[source]#

Bases: LinearInterp

Model to spatially downscale daily-average near-surface temperature, relative humidity, and pressure

Note that this model can also operate on temperature_*m, relativehumidity_*m, and pressure_*m datasets that are not strictly at the surface but could be near hub height.

Parameters:

lr_features (list) – List of feature names that this model will operate on for both input and output. This must match the feature axis ordering in the array input to generate(). Typically this is a list containing: temperature_*m, relativehumidity_*m, and pressure_*m. The list can contain multiple instances of each variable at different heights. relativehumidity_*m entries must have corresponding temperature_*m entires at the same hub height.
s_enhance (int) – Integer factor by which the spatial axes are to be enhanced.
noise_adders (float | list | None) – Option to add gaussian noise to spatial model output. Noise will be normally distributed with mean of 0 and standard deviation = noise_adders. noise_adders can be a single value or a list corresponding to the lr_features list. None is no noise. The addition of noise has been shown to help downstream temporal-only models produce diurnal cycles in regions where there is minimal change in topography. A noise_adders around 0.07C (temperature) and 0.1% (relative humidity) have been shown to be effective. This is unnecessary if daily min/max temperatures are provided as low res training features.
temp_lapse (None | float) – Temperature lapse rate: change in degrees C/K per meter. Defaults to the cls.TEMP_LAPSE attribute.
w_delta_temp (None | float) – Weight for the delta-temperature feature for the relative humidity linear regression model. Defaults to the cls.W_DELTA_TEMP attribute.
w_delta_topo (None | float) – Weight for the delta-topography feature for the relative humidity linear regression model. Defaults to the cls.W_DELTA_TOPO attribute.
pres_div (None | float) – Divisor factor in the pressure scale height equation. Defaults to the cls.PRES_DIV attribute.
pres_exp (None | float) – Exponential factor in the pressure scale height equation. Defaults to the cls.PRES_EXP attribute.
interp_method (str) – Name of the interpolation method to use from PIL.Image.Resampling (NEAREST, BILINEAR, BICUBIC, LANCZOS) LANCZOS is default and has been tested to work best for SurfaceSpatialMetModel.
fix_bias (bool) – Some local bias can be introduced by the bilinear interp + lapse rate, this flag will attempt to correct that bias by using the low-resolution deviation from the input data
input_resolution (dict | None) – Resolution of the input data. e.g. {‘spatial’: ‘30km’, ‘temporal’: ‘60min’}. This is used to determine how to aggregate high-resolution topography data.

Methods

`downscale_arr`(arr, s_enhance[, method, fix_bias])	Downscale a 2D array of data Image.resize() method
`downscale_pres`(single_lr_pres, topo_lr, topo_hr)	Downscale pressure raster data at a single observation.
`downscale_rh`(single_lr_rh, single_lr_temp, ...)	Downscale relative humidity raster data at a single observation.
`downscale_temp`(single_lr_temp, topo_lr, topo_hr)	Downscale temperature raster data at a single observation.
`fix_downscaled_bias`(single_lr, single_hr[, ...])	Fix any bias introduced by the spatial downscaling with lapse rate.
`generate`(low_res[, norm_in, un_norm_out, ...])	Use the generator model to generate high res data from low res input.
`get_s_enhance_from_layers`()	Compute factor by which model will enhance spatial resolution from layer attributes.
`get_t_enhance_from_layers`()	Compute factor by which model will enhance temporal resolution from layer attributes.
`load`(model_dir[, verbose])	Load the LinearInterp model with its params saved to the model_dir created with LinearInterp.save(model_dir)
`save`(out_dir)
`save_params`(out_dir)
`seed`([s])	Set the random seed for reproducible results.
`set_model_params`(**kwargs)	Set parameters used for training the model
`train`(true_hr_temp, true_hr_rh, ...)	Trains the relative humidity linear model.

Attributes

`PRES_DIV`	Air pressure scaling equation divisor variable: 101325 * (1 - (1 - topo / PRES_DIV)**PRES_EXP)
`PRES_EXP`	Air pressure scaling equation exponent variable: 101325 * (1 - (1 - topo / PRES_DIV)**PRES_EXP)
`TEMP_LAPSE`	change in degrees C/K per meter
`W_DELTA_TEMP`	Weight for the delta-temperature feature for the relative humidity linear regression model.
`W_DELTA_TOPO`	Weight for the delta-topography feature for the relative humidity linear regression model.
`feature_inds_other`	Get the feature index values for the features that are not temperature, pressure, or relativehumidity.
`feature_inds_pres`	Get the feature index values for the pressure features.
`feature_inds_rh`	Get the feature index values for the relative humidity features.
`feature_inds_temp`	Get the feature index values for the temperature features.
`hr_exo_features`	Returns an empty list for LinearInterp model
`hr_out_features`	Get the list of output feature names that the generative model outputs
`input_dims`	Get dimension of model input.
`input_resolution`	Resolution of input data.
`is_4d`	Check if model expects spatial only input
`is_5d`	Check if model expects spatiotemporal input
`lr_features`	Get the list of input feature names that the generative model was trained on.
`meta`	Get meta data dictionary that defines the model params
`model_params`	Model parameters, used to save model to disc
`output_resolution`	Resolution of output data.
`s_enhance`	Factor by which model will enhance spatial resolution.
`s_enhancements`	List of spatial enhancement factors.
`smoothed_features`	Get the list of smoothed input feature names that the generative model was trained on.
`smoothing`	Value of smoothing parameter used in gaussian filtering of coarsened high res data.
`t_enhance`	Factor by which model will enhance temporal resolution.
`t_enhancements`	List of temporal enhancement factors.
`version_record`	A record of important versions that this model was built with.

TEMP_LAPSE = 0.0065#

change in degrees C/K per meter

Type:: Temperature lapse rate

PRES_DIV = 44307.69231#: Air pressure scaling equation divisor variable: 101325 * (1 - (1 - topo / PRES_DIV)**PRES_EXP)

PRES_EXP = 5.25328#: Air pressure scaling equation exponent variable: 101325 * (1 - (1 - topo / PRES_DIV)**PRES_EXP)

W_DELTA_TEMP = -3.9924283#: Weight for the delta-temperature feature for the relative humidity linear regression model.

W_DELTA_TOPO = -0.01736911#: Weight for the delta-topography feature for the relative humidity linear regression model.

property feature_inds_temp#: Get the feature index values for the temperature features.

property feature_inds_pres#: Get the feature index values for the pressure features.

property feature_inds_rh#: Get the feature index values for the relative humidity features.

property feature_inds_other#: Get the feature index values for the features that are not temperature, pressure, or relativehumidity.

classmethod fix_downscaled_bias(single_lr, single_hr, method=Resampling.LANCZOS)[source]#

Fix any bias introduced by the spatial downscaling with lapse rate.

Parameters:

single_lr (np.ndarray) – Single timestep raster data with shape (lat, lon) matching the low-resolution input data.
single_hr (np.ndarray) – Single timestep downscaled raster data with shape (lat, lon) matching the high-resolution input data.
method (Image.Resampling.LANCZOS) – An Image.Resampling method (NEAREST, BILINEAR, BICUBIC, LANCZOS). NEAREST enforces zero bias but makes slightly more spatial seams.

Returns:

single_hr (np.ndarray) – Single timestep downscaled raster data with shape (lat, lon) matching the high-resolution input data.

classmethod downscale_arr(arr, s_enhance, method=Resampling.LANCZOS, fix_bias=False)[source]#

Downscale a 2D array of data Image.resize() method

Parameters:

arr (np.ndarray) – 2D raster data, typically spatial daily average data with shape (lat, lon)
s_enhance (int) – Integer factor by which the spatial axes are to be enhanced.
method (Image.Resampling.LANCZOS) – An Image.Resampling method (NEAREST, BILINEAR, BICUBIC, LANCZOS). LANCZOS is default and has been tested to work best for SurfaceSpatialMetModel.
fix_bias (bool) – Some local bias can be introduced by the bilinear interp + lapse rate, this flag will attempt to correct that bias by using the low-resolution deviation from the input data

downscale_temp(single_lr_temp, topo_lr, topo_hr)[source]#

Downscale temperature raster data at a single observation.

This model uses a simple lapse rate that adjusts temperature as a function of elevation. The process is as follows:

add a scale factor to the low-res temperature field: topo_lr * TEMP_LAPSE

perform bilinear interpolation of the scaled temperature field.

subtract the scale factor from the high-res temperature field: topo_hr * TEMP_LAPSE

Parameters:

single_lr_temp (np.ndarray) – Single timestep temperature (deg C) raster data with shape (lat, lon) matching the low-resolution input data.
topo_lr (np.ndarray) – low-resolution surface elevation data in meters with shape (lat, lon)
topo_hr (np.ndarray) – High-resolution surface elevation data in meters with shape (lat, lon)

Returns:

hi_res_temp (np.ndarray) – Single timestep temperature (deg C) raster data with shape (lat, lon) matching the high-resolution output data.

downscale_rh(single_lr_rh, single_lr_temp, single_hr_temp, topo_lr, topo_hr)[source]#

Downscale relative humidity raster data at a single observation.

Here’s a description of the humidity scaling model:

Take low-resolution and high-resolution daily average temperature, relative humidity, and topography data.
Downscale all low-resolution variables using a bilinear image enhancement
The target model output is the difference between the interpolated low-res relative humidity and the true high-res relative humidity. Calculate this difference as a linear function of the same difference in the temperature and topography fields.
Use this linear regression model to calculate high-res relative humidity fields when provided low-res input of relative humidity along with low-res/high-res pairs of temperature and topography.

Parameters:

single_lr_rh (np.ndarray) – Single timestep relative humidity (%) raster data with shape (lat, lon) matching the low-resolution input data.
single_lr_temp (np.ndarray) – Single timestep temperature (deg C) raster data with shape (lat, lon) matching the low-resolution input data.
single_hr_temp (np.ndarray) – Single timestep temperature (deg C) raster data with shape (lat, lon) matching the high-resolution output data.
topo_lr (np.ndarray) – low-resolution surface elevation data in meters with shape (lat, lon)
topo_hr (np.ndarray) – High-resolution surface elevation data in meters with shape (lat, lon)

Returns:

hi_res_rh (np.ndarray) – Single timestep relative humidity (%) raster data with shape (lat, lon) matching the high-resolution output data.

downscale_pres(single_lr_pres, topo_lr, topo_hr)[source]#

Downscale pressure raster data at a single observation.

This model uses a simple exponential scale height that adjusts temperature as a function of elevation. The process is as follows:

add a scale factor to the low-res pressure field: 101325 * (1 - (1 - topo_lr / PRES_DIV)**PRES_EXP)

perform bilinear interpolation of the scaled pressure field.

subtract the scale factor from the high-res pressure field: 101325 * (1 - (1 - topo_hr / PRES_DIV)**PRES_EXP)

Parameters:

single_lr_pres (np.ndarray) – Single timestep pressure (Pa) raster data with shape (lat, lon) matching the low-resolution input data.
topo_lr (np.ndarray) – low-resolution surface elevation data in meters with shape (lat, lon)
topo_hr (np.ndarray) – High-resolution surface elevation data in meters with shape (lat, lon)

Returns:

hi_res_pres (np.ndarray) – Single timestep pressure (Pa) raster data with shape (lat, lon) matching the high-resolution output data.

get_s_enhance_from_layers()#: Compute factor by which model will enhance spatial resolution from layer attributes. Used in model training during high res coarsening

get_t_enhance_from_layers()#: Compute factor by which model will enhance temporal resolution from layer attributes. Used in model training during high res coarsening

property hr_exo_features#: Returns an empty list for LinearInterp model

property hr_out_features#: Get the list of output feature names that the generative model outputs

property input_resolution#: Resolution of input data. Given as a dictionary {'spatial': '...km', 'temporal': '...min'}. The numbers are required to be integers in the units specified. The units are not strict as long as the resolution of the exogenous data, when extracting exogenous data, is specified in the same units.

property is_4d#: Check if model expects spatial only input

property is_5d#: Check if model expects spatiotemporal input

classmethod load(model_dir, verbose=False)#

Load the LinearInterp model with its params saved to the model_dir created with LinearInterp.save(model_dir)

Parameters:

model_dir (str) – Directory to load LinearInterp model files from. Must have a model_params.json file containing “meta” key with all of the class init args.
verbose (bool) – Flag to log information about the loaded model.

Returns:

out (LinearInterp) – Returns an initialized LinearInterp model

property lr_features#: Get the list of input feature names that the generative model was trained on.

property model_params#

Model parameters, used to save model to disc

Returns:: dict

property output_resolution#: Resolution of output data. Given as a dictionary {‘spatial’: ‘…km’, ‘temporal’: ‘…min’}. This is computed from the input resolution and the enhancement factors.

property s_enhance#: Factor by which model will enhance spatial resolution. Used in model training during high res coarsening and also in forward pass routine to determine shape of needed exogenous data

property s_enhancements#: List of spatial enhancement factors. In the case of a single step model this is just [self.s_enhance]. This is used to determine shapes of needed exogenous data in forward pass routine

save(out_dir)#

Parameters:: out_dir (str) – Directory to save linear model params. This directory will be created if it does not already exist.

save_params(out_dir)#

Parameters:: out_dir (str) – Directory to save linear model params. This directory will be created if it does not already exist.

static seed(s=0)#

Set the random seed for reproducible results.

Parameters:: s (int) – Random seed

set_model_params(**kwargs)#

Set parameters used for training the model

Parameters:: kwargs (dict) – Keyword arguments including ‘input_resolution’, ‘lr_features’, ‘hr_exo_features’, ‘hr_out_features’, ‘smoothed_features’, ‘s_enhance’, ‘t_enhance’, ‘smoothing’

property smoothed_features#: Get the list of smoothed input feature names that the generative model was trained on.

property smoothing#: Value of smoothing parameter used in gaussian filtering of coarsened high res data.

property t_enhance#: Factor by which model will enhance temporal resolution. Used in model training during high res coarsening and also in forward pass routine to determine shape of needed exogenous data

property t_enhancements#: List of temporal enhancement factors. In the case of a single step model this is just [self.t_enhance]. This is used to determine shapes of needed exogenous data in forward pass routine

property version_record#

A record of important versions that this model was built with.

Returns:: dict

property input_dims#

Get dimension of model input. This is 4 for linear and surface models (n_obs, spatial_1, spatial_2, temporal)

Returns:: int

generate(low_res, norm_in=False, un_norm_out=False, exogenous_data=None)[source]#

Use the generator model to generate high res data from low res input. This is the public generate function.

Parameters:

low_res (np.ndarray) – Low-resolution spatial input data, a 4D array of shape: (n_obs, spatial_1, spatial_2, n_features), Where the feature channel can include temperature_*m, relativehumidity_*m, and/or pressure_*m
norm_in (bool) – This doesnt do anything for this SurfaceSpatialMetModel, but is kept to keep the same interface as Sup3rGan
un_norm_out (bool) – This doesnt do anything for this SurfaceSpatialMetModel, but is kept to keep the same interface as Sup3rGan
exogenous_data (dict) – For the SurfaceSpatialMetModel, this must be a nested dictionary with a main ‘topography’ key and two entries for exogenous_data[‘topography’][‘steps’]. The first entry includes a 2D (lat, lon) array of low-resolution surface elevation data in meters (must match spatial_1, spatial_2 from low_res), and the second entry includes a 2D (lat, lon) array of high-resolution surface elevation data in meters. e.g. .. code-block:: JSON

{‘topography’: {
‘steps’: [{‘data’: lr_topo}, {‘data’: hr_topo’}] }

}

Returns:

hi_res (ndarray) – high-resolution spatial output data, a 4D array of shape: (n_obs, spatial_1, spatial_2, n_features), Where the feature channel can include temperature_*m, relativehumidity_*m, and/or pressure_*m

property meta#: Get meta data dictionary that defines the model params

train(true_hr_temp, true_hr_rh, true_hr_topo, input_resolution)[source]#

Trains the relative humidity linear model. The temperature and surface lapse rate models are parameterizations taken from the NSRDB and are not trained.

Parameters:

true_hr_temp (np.ndarray) – True high-resolution daily average temperature data in a 3D array of shape (lat, lon, n_days)
true_hr_rh (np.ndarray) – True high-resolution daily average relative humidity data in a 3D array of shape (lat, lon, n_days)
true_hr_topo (np.ndarray) – High-resolution surface elevation data in meters with shape (lat, lon)
input_resolution (dict) – Dictionary of spatial and temporal input resolution. e.g. {‘spatial’: ‘20km’: ‘temporal’: ‘60min’}

Returns:

w_delta_temp (float) – Weight for the delta-temperature feature for the relative humidity linear regression model.
w_delta_topo (float) – Weight for the delta-topography feature for the relative humidity linear regression model.
regr (sklearn.LinearRegression) – Trained regression object that predicts regr(x) = y
x (np.ndarray) – 2D array of shape (n, 2) where n is the number of observations being trained on and axis=1 is 1) the True high-res temperature minus the interpolated temperature and 2) the True high-res topo minus the interpolate topo.
y (np.ndarray) – 2D array of shape (n,) that represents the true high-res humidity minus the interpolated humidity

sup3r.models.surface.SurfaceSpatialMetModel

Contents

sup3r.models.surface.SurfaceSpatialMetModel#