integratedGradients: Computes integrated gradients for a neural network in the C4R...

In SantanderMetGroup/downscaleR.keras: A climate4R package for statistical downscaling <http://meteo.unican.es/climate4r>

Computes integrated gradients for a neural network in the C4R framework.

Description

Given a neural network, computes integrated gradients for a particular predictand (or output neuron of the model) w.r.t an input predictand field, to gain explainability. The integrated gradients method is described in Sundarayan et al., 2017 (see References section).

Usage

integratedGradients(
  x = x,
  model = model,
  baseline = NULL,
  num_steps = 50,
  model.info = list(first.connection = "conv", last.connection = "dense", channels =
    "last", time.frames = NULL, nature = NULL, ind_TrainingPredictandSites = NULL,
    ind_TrainingPredictorSites = NULL, data.structure = NULL, coords = NULL),
  site = NULL,
  saliency.fun = NULL,
  batch = NULL
)

Arguments

x	The input climate4R object or predictor field.
model	A keras sequential or functional model.
baseline	The integrated gradients method attributes the prediction at input 'x' relative to a 'baseline', computing the contribution of 'x' to the prediction. The baseline parameter defines this baseline, . Default to NULL which set the baseline to a 0 array. For custom baselines, input an array with the dimensions matching those of the input layer of the neural network.
num_steps	Number of interpolation steps between the baseline and the input used in the computation of integrated gradients. These steps along determine the integral approximation error. By default, num_steps is set to 50. The authors suggest an interval from 20 to 300.
model.info	List of arguments containing metadata of the neural network. @param first.connection A string. Possible values are c("dense","conv") depending on whether @param last.connection A string. Same as first.connection but for the last connection (i.e., last hidden layer to output layer). @param channels A string. Possible values are c("first","last") and indicates the dimension of the channels (i.e., climate variables) in the array. If "first" then dimensions = c("channel","latitude","longitude") for regular grids or c("channel","loc") for irregular grids. @param time.frames The number of time frames to build the recurrent neural network. If e.g., time.frame = 2, then the value y(t) is a function of x(t) and x(t-1). The time frames stack in the input array prior to the input neurons or channels (in conv. layers). See layer_simple_rnn,layer_lstm or layer_conv_lstm_2d. @param nature An attribute as returned by prepareData.keras. @param ind_TrainingPredictandSites An attribute as returned by prepareData.keras. @param ind_TrainingPredictorSites An attribute as returned by prepareData.keras. @param data.structure An attribute as returned by prepareData.keras. @param coords A data frame containing the 'x' and 'y' coordinates of all the predictand sites represented in the output layer of the neural network.
site	A data frame containing the 'x' and 'y' coordinates of the desired site where to compute the gradients. e.g., site = data.frame("x" = -3.82, "y" = 43.46)
saliency.fun	Apply a function to the resulting saliency maps. e.g., saliency.fun = list(FUN = "mean", na.rm = TRUE).
batch	An integer indicating the size of the batch. Default to NULL.

Details

This function relies on keras, which is a high-level neural networks API capable of running on top of tensorflow, CNTK or theano. There are official keras tutorials regarding how to build deep learning models. We suggest the user, especially the beginners, to consult these tutorials before using downscaleR.keras.

Value

The integrated gradients in a climate4R object.

Author(s)

J. Bano-Medina

References

• Sundararajan, Mukund, Ankur Taly, and Qiqi Yan. "Axiomatic attribution for deep networks." International conference on machine learning. PMLR, 2017.

See Also

relevanceMaps for computing saliency maps based on prediction difference analysis downscaleTrain.keras to train neural networks in the C4R framework downscaleR.keras Wiki

Examples

require(climate4R.datasets)
require(transformeR)
require(magrittr)

data("NCEP_Iberia_hus850", "NCEP_Iberia_psl", "NCEP_Iberia_ta850")
x <- makeMultiGrid(NCEP_Iberia_hus850, NCEP_Iberia_psl, NCEP_Iberia_ta850)
data("VALUE_Iberia_tas")
y <- VALUE_Iberia_tas

# Preparing the predictors
x_scaled <- scaleGrid(x, type = "standardize")
data <- prepareData.keras(x = x_scaled, 
                          y = y, 
                          first.connection = "conv",
                          last.connection = "dense",
                          channels = "last")

# Defining the keras model.... 
# We define 3 hidden layers that consists on 
# 2 convolutional steps followed by a dense connection.
input_shape  <- dim(data$x.global)[-1]
output_shape  <- dim(data$y$Data)[2]
inputs <- layer_input(shape = input_shape)
hidden <- inputs %>% 
  layer_conv_2d(filters = 25, kernel_size = c(3,3), activation = 'relu') %>%  
  layer_conv_2d(filters = 10, kernel_size = c(3,3), activation = 'relu') %>% 
  layer_flatten() %>% 
  layer_dense(units = 10, activation = "relu")
outputs <- layer_dense(hidden,units = output_shape)
model <- keras_model(inputs = inputs, outputs = outputs)

# Training model.... 
model <- downscaleTrain.keras(obj = data, 
                              model = model,
                              compile.args = list("loss" = "mse", 
                                                  "optimizer" = optimizer_adam(lr = 0.01)),
                              fit.args = list("epochs" = 150, "batch_size" = 100), 
                              clear.session = FALSE)

# Choose site.... 
site <- 5 
xCoord <- y$xyCoords$x[site]
yCoord <- y$xyCoords$y[site]

# Compute the saliency maps for 
# the selected site....
saliency_grids <- integratedGradients(x = x_scaled,
                                      model = model,
                                      baseline = NULL,
                                      num_steps = 500,
                                      model.info = list(first.connection            = "conv",
                                                        last.connection             = "dense",
                                                        channels                    = "last",
                                                        time.frames                 = NULL,
                                                        nature                      = NULL,
                                                        ind_TrainingPredictandSites = attr(data, "indices_noNA_y"),
                                                        ind_TrainingPredictorSites  = NULL,
                                                        data.structure = NULL,
                                                        coords = y$xyCoords),
                                      site = data.frame("x" = xCoord, "y" = yCoord),
                                      saliency.fun = list(FUN = "mean", na.rm = TRUE)
)

# Display the saliency maps for 
# the selected site....
require(visualizeR)
require(sp)
spatialPlot(climatology(saliency_grids, clim.fun = list(FUN = "abs")), 
            backdrop.theme = "coastline",
            sp.layout = list(list(SpatialPoints(y$xyCoords[site,]),
                                  first = FALSE,
                                  col = "black",
                                  pch = 16)
            )
)

SantanderMetGroup/downscaleR.keras documentation built on July 7, 2023, 1:22 p.m.