sup3r.models.multi_step.MultiStepSurfaceMetGan

class MultiStepSurfaceMetGan(models)

Bases: MultiStepGan

A two-step GAN where the first step is a spatial-only enhancement on a 4D tensor of near-surface temperature and relative humidity data, and the second step is a (spatio)temporal enhancement on a 5D tensor.

NOTE: no inputs are needed for the first spatial-only surface meteorology model. The spatial enhancement is determined by the low and high res topography inputs in the exogenous_data kwargs in the MultiStepSurfaceMetGan.generate() method.

NOTE: The low res input to the spatial enhancement should be a 4D tensor of the shape (temporal, spatial_1, spatial_2, features) where temporal (usually the observation index) is a series of sequential timesteps that will be transposed to a 5D tensor of shape (1, spatial_1, spatial_2, temporal, features) tensor and then fed to the 2nd-step (spatio)temporal GAN.

Parameters:

models (list | tuple) – An ordered list/tuple of one or more trained Sup3rGan models

Methods

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([surface_model_class, ...])	Load the GANs with its sub-networks from a previously saved-to output directory.
save_params(out_dir)
seed([s])	Set the random seed for reproducible results.
set_model_params(**kwargs)	Set parameters used for training the model

Attributes

hr_exo_features	Get list of high-resolution exogenous filter names the model uses.
hr_out_features	Get the list of high-resolution output feature names that the generative model outputs.
input_dims	Get dimension of model generator input.
input_resolution	'...km', 'temporal': '...min'}.
is_4d	Check if model expects spatial only input
is_5d	Check if model expects spatiotemporal input
lr_features	Get a list of low-resolution features input to the generative model.
means	Get the data normalization mean values.
meta	Get a tuple of meta data dictionaries for all models
model_params	Get a tuple of model parameters for all models
models	Get an ordered tuple of the Sup3rGan models that are part of this MultiStepGan
output_resolution	Resolution of output data.
s_enhance	Factor by which model will enhance spatial resolution.
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.
stdevs	Get the data normalization standard deviation values.
t_enhance	Factor by which model will enhance temporal resolution.
version_record	Get a tuple of version records from all models

generate(low_res, norm_in=True, un_norm_out=True, 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) – Flag to normalize low_res input data if the self.means, self.stdevs attributes are available. The generator should always received normalized data with mean=0 stdev=1.

• un_norm_out (bool) – Flag to un-normalize synthetically generated output data to physical units

• exogenous_data (dict) – For the MultiStepSurfaceMetGan, 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’: [

  {‘model’: 0, ‘combine_type’: ‘input’, ‘data’: lr_topo}, {‘model’: 0, ‘combine_type’: ‘output’, ‘data’: hr_topo’}]}}

Returns:

hi_res (ndarray) – Synthetically generated high-resolution data output from the 2nd step (spatio)temporal GAN with a 5D array shape: (1, spatial_1, spatial_2, n_temporal, n_features), Where the feature channel can include temperature_*m, relativehumidity_*m, and/or pressure_*m

classmethod load(surface_model_class='SurfaceSpatialMetModel', temporal_model_class='MultiStepGan', surface_model_kwargs=None, temporal_model_kwargs=None, verbose=True)

Load the GANs with its sub-networks from a previously saved-to output directory.

Parameters:

• surface_model_class (str) – Name of surface model class to be retrieved from sup3r.models, this is typically “SurfaceSpatialMetModel”

• temporal_model_class (str) – Name of temporal model class to be retrieved from sup3r.models, this is typically “Sup3rGan”

• surface_model_kwargs (None | dict) – Optional additional kwargs to surface_model_class.load()

• temporal_model_kwargs (None | dict) – Optional additional kwargs to temporal_model_class.load()

• verbose (bool) – Flag to log information about the loaded model.

Returns:

out (MultiStepGan) – Returns a pretrained gan model that was previously saved to model_dirs

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

Get list of high-resolution exogenous filter names the model uses. For the multi-step model, each entry in this list corresponds to one of the single-step models and is itself a list of hr_exo_features for that model.

property hr_out_features

Get the list of high-resolution output feature names that the generative model outputs.

property input_dims

Get dimension of model generator input. This is usually 4D for spatial models and 5D for spatiotemporal models. This gives the input to the first step if the model is multi-step. Returns 5 for linear models.

Returns:

int

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

property lr_features

Get a list of low-resolution features input to the generative model. This includes low-resolution features that might be supplied exogenously at inference time but that were in the low-res batches during training

property means

Get the data normalization mean values. This is a tuple of means from all models.

Returns:

tuple | np.ndarray

property meta

Get a tuple of meta data dictionaries for all models

Returns:

tuple

property model_params

Get a tuple of model parameters for all models

Returns:

tuple

property models

Get an ordered tuple of the Sup3rGan models that are part of this MultiStepGan

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_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 stdevs

Get the data normalization standard deviation values. This is a tuple of stdevs from all models.

Returns:

tuple | np.ndarray

property t_enhance

Factor by which model will enhance temporal resolution. Used in model training during high res coarsening

property version_record

Get a tuple of version records from all models

Returns:

tuple