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)

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)

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)

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)

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)

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)

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)

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)

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.