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.
Compute factor by which model will enhance spatial resolution from layer attributes.
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
Air pressure scaling equation divisor variable: 101325 * (1 - (1 - topo / PRES_DIV)**PRES_EXP)
Air pressure scaling equation exponent variable: 101325 * (1 - (1 - topo / PRES_DIV)**PRES_EXP)
change in degrees C/K per meter
Weight for the delta-temperature feature for the relative humidity linear regression model.
Weight for the delta-topography feature for the relative humidity linear regression model.
Get the feature index values for the features that are not temperature, pressure, or relativehumidity.
Get the feature index values for the pressure features.
Get the feature index values for the relative humidity features.
Get the feature index values for the temperature features.
Returns an empty list for LinearInterp model
Get the list of output feature names that the generative model outputs
Get dimension of model input.
'...km', 'temporal': '...min'}.
Check if model expects spatial only input
Check if model expects spatiotemporal input
Get the list of input feature names that the generative model was trained on.
Get meta data dictionary that defines the model params
Model parameters, used to save model to disc
Resolution of output data.
Factor by which model will enhance spatial resolution.
Get the list of smoothed input feature names that the generative model was trained on.
Value of smoothing parameter used in gaussian filtering of coarsened high res data.
Factor by which model will enhance temporal resolution.
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
‘…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.
- Type:
Resolution of input data. Given as a dictionary {‘spatial’
- 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
- 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
- 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. {‘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.