Overview

Keras is a model-level library, providing high-level building blocks for developing deep learning models. It does not handle itself low-level operations such as tensor products, convolutions and so on. Instead, it relies on a specialized, well-optimized tensor manipulation library to do so, serving as the “backend engine” of Keras.

The R interface to Keras uses TensorFlow™ as it’s default tensor backend engine, however it’s possible to use other backends if desired. At this time, Keras has three backend implementations available:

  • TensorFlow is an open-source symbolic tensor manipulation framework developed by Google.

  • Theano is an open-source symbolic tensor manipulation framework developed by LISA Lab at Université de Montréal.

  • CNTK is an open-source toolkit for deep learning developed by Microsoft.

Selecting a Backend

Keras uses the TensorFlow backend by default. If you want to switch to Theano set the KERAS_BACKEND environment variable before loading the Keras package as follows:

Sys.setenv(KERAS_BACKEND = "theano")
library(keras)

If you want to use the CNTK backend then you should follow the installation instructions for CNTK and then set the KERAS_BACKEND environment variable before loading the keras R package as follows:

Sys.setenv(KERAS_BACKEND = "cntk")
library(keras)

Environment Variables

If you want to use a backend provided by the keras Python package you typically need only to install the package and the backend, then set the KERAS_BACKEND environment variable as described above.

If you need to customize things further there are several environment variables that affect the version of Keras used:

Variable Description
KERAS_IMPLEMENTATION Keras specifies an API that can be implemented by multiple providers. By default, the Keras R package uses the implementation provided by the Keras Python package (“keras”). TensorFlow also provides an integrated implementation of Keras which you can use by specifying “tensorflow” as the implementation.
KERAS_BACKEND The “keras” implementation supports the “tensorflow”, “keras”, and “cntk” backends. Note that the “tensorflow” implementation supports only the “tensorflow” backend.
KERAS_PYTHON The Keras R package will automatically scan installed versions of Python (and virtual/conda environments) to find the one that includes the selected implementation of Keras. If this scanning doesn’t find the right version or you want to override its behavior, you can set the KERAS_PYTHON environment variable to the location of the Python binary you want to use.

Note that if you want to use TensorFlow as the backend engine you wouldn’t need to set any of these variables, as it will be used automatically by default.

Keras Configuration File

If you have run Keras at least once, you will find the Keras configuration file at:

$HOME/.keras/keras.json

If it isn’t there, you can create it.

NOTE for Windows Users: Please replace $HOME with %USERPROFILE%.

The default configuration file looks like this:

{
    "image_data_format": "channels_last",
    "epsilon": 1e-07,
    "floatx": "float32",
    "backend": "tensorflow"
}

You can change these settings by editing $HOME/.keras/keras.json.

  • image_data_format: String, either "channels_last" or "channels_first". It specifies which data format convention Keras will follow. (backend()$image_data_format() returns it.)
  • For 2D data (e.g. image), "channels_last" assumes (rows, cols, channels) while "channels_first" assumes (channels, rows, cols).
  • For 3D data, "channels_last" assumes (conv_dim1, conv_dim2, conv_dim3, channels) while "channels_first" assumes (channels, conv_dim1, conv_dim2, conv_dim3).
  • epsilon: Float, a numeric fuzzing constant used to avoid dividing by zero in some operations.
  • floatx: String, "float16", "float32", or "float64". Default float precision.
  • backend: String, "tensorflow", "theano", or "cntk".

Accessing the Backend in Code

If you want the Keras modules you write to be compatible with all available backends, you have to write them via the abstract Keras backend API. You can obtain a reference to the TensorFlow backend by calling the backend() function:

library(keras)
K <- backend()

The code below instantiates an input placeholder. It’s equivalent to tf$placeholder():

inputs <- K$placeholder(shape = list(2L, 4L, 5L))
# also works:
inputs <-  K$placeholder(shape = list(NULL, 4L, 5L))
# also works:
inputs <- K$placeholder(ndim = 3L)

The code below instantiates a variable. It’s equivalent to tf$Variable():

val <- array(runif(60), dim = c(3L, 4L, 5L))
var <- K$variable(value = val)

# all-zeros variable:
var <- K$zeros(shape = list(3L, 4L, 5L))
# all-ones:
var <- K$ones(shape = list(3L, 4L, 5L))

Note that the examples above all pass integer values explicitly (e.g. 5L). This is because unlike the high level R functions in the Keras package the backend APIs are all strongly typed (i.e. float values are not automatically converted to integers).

Backend Functions

Name Description
abs Element-wise absolute value.
all Bitwise reduction (logical AND).
any Bitwise reduction (logical OR).
arange Creates a 1D tensor containing a sequence of integers.
argmax Returns the index of the maximum value along an axis.
argmin Returns the index of the minimum value along an axis.
backend Publicly accessible method for determining the current backend.
batch_dot Batchwise dot product.
batch_flatten Turn a nD tensor into a 2D tensor with same 0th dimension.
batch_get_value Returns the value of more than one tensor variable.
batch_normalization Applies batch normalization on x given mean, var, beta and gamma.
batch_set_value Sets the values of many tensor variables at once.
bias_add Adds a bias vector to a tensor.
binary_crossentropy Binary crossentropy between an output tensor and a target tensor.
cast Casts a tensor to a different dtype and returns it.
cast_to_floatx Cast a Numpy array to the default Keras float type.
categorical_crossentropy Categorical crossentropy between an output tensor and a target tensor.
clear_session Destroys the current TF graph and creates a new one.
clip Element-wise value clipping.
concatenate Concatenates a list of tensors alongside the specified axis.
constant Creates a constant tensor.
conv1d 1D convolution.
conv2d 2D convolution.
conv2d_transpose 2D deconvolution (i.e.
conv3d 3D convolution.
cos Computes cos of x element-wise.
count_params Returns the number of scalars in a Keras variable.
ctc_batch_cost Runs CTC loss algorithm on each batch element.
ctc_decode Decodes the output of a softmax.
ctc_label_dense_to_sparse Converts CTC labels from dense to sparse.
cumprod Cumulative product of the values in a tensor, alongside the specified axis.
cumsum Cumulative sum of the values in a tensor, alongside the specified axis.
dot Multiplies 2 tensors (and/or variables) and returns a tensor.
dropout Sets entries in x to zero at random, while scaling the entire tensor.
dtype Returns the dtype of a Keras tensor or variable, as a string.
elu Exponential linear unit.
epsilon Returns the value of the fuzz factor used in numeric expressions.
equal Element-wise equality between two tensors.
eval Evaluates the value of a variable.
exp Element-wise exponential.
expand_dims Adds a 1-sized dimension at index “axis”.
eye Instantiate an identity matrix and returns it.
flatten Flatten a tensor.
floatx Returns the default float type, as a string.
foldl Reduce elems using fn to combine them from left to right.
foldr Reduce elems using fn to combine them from right to left.
`function` Instantiates a Keras function.
gather Retrieves the elements of indices indices in the tensor reference.
get_session Returns the TF session to be used by the backend.
get_uid Associates a string prefix with an integer counter in a TensorFlow graph.
get_value Returns the value of a variable.
gradients Returns the gradients of variables w.r.t. loss.
greater Element-wise truth value of (x > y).
greater_equal Element-wise truth value of (x >= y).
hard_sigmoid Segment-wise linear approximation of sigmoid.
identity Returns a tensor with the same content as the input tensor.
image_data_format Returns the default image data format convention.
in_test_phase Selects x in test phase, and alt otherwise.
in_top_k Returns whether the targets are in the top k predictions.
in_train_phase Selects x in train phase, and alt otherwise.
int_shape Returns the shape tensor or variable as a list of int or NULL entries.
is_sparse Returns whether a tensor is a sparse tensor.
l2_normalize Normalizes a tensor wrt the L2 norm alongside the specified axis.
learning_phase Returns the learning phase flag.
less Element-wise truth value of (x < y).
less_equal Element-wise truth value of (x <= y).
local_conv1d Apply 1D conv with un-shared weights.
local_conv2d Apply 2D conv with un-shared weights.
log Element-wise log.
logsumexp Computes log(sum(exp(elements across dimensions of a tensor))).
manual_variable_initialization Sets the manual variable initialization flag.
map_fn Map the function fn over the elements elems and return the outputs.
max Maximum value in a tensor.
maximum Element-wise maximum of two tensors.
mean Mean of a tensor, alongside the specified axis.
min Minimum value in a tensor.
minimum Element-wise minimum of two tensors.
moving_average_update Compute the moving average of a variable.
name_scope Returns a context manager for use when defining a Python op.
ndim Returns the number of axes in a tensor, as an integer.
normalize_batch_in_training Computes mean and std for batch then apply batch_normalization on batch.
not_equal Element-wise inequality between two tensors.
one_hot Computes the one-hot representation of an integer tensor.
ones Instantiates an all-ones tensor variable and returns it.
ones_like Instantiates an all-ones variable of the same shape as another tensor.
permute_dimensions Permutes axes in a tensor.
placeholder Instantiates a placeholder tensor and returns it.
pool2d 2D Pooling.
pool3d 3D Pooling.
pow Element-wise exponentiation.
print_tensor Prints message and the tensor value when evaluated.
prod Multiplies the values in a tensor, alongside the specified axis.
py_all all(iterable) -> bool
py_sum sum(sequence[, start]) -> value
random_binomial Returns a tensor with random binomial distribution of values.
random_normal Returns a tensor with normal distribution of values.
random_normal_variable Instantiates a variable with values drawn from a normal distribution.
random_uniform Returns a tensor with uniform distribution of values.
random_uniform_variable Instantiates a variable with values drawn from a uniform distribution.
relu Rectified linear unit.
repeat_elements Repeats the elements of a tensor along an axis, like np.repeat.
reset_uids Reset graph identifiers.
reshape Reshapes a tensor to the specified shape.
resize_images Resizes the images contained in a 4D tensor.
resize_volumes Resizes the volume contained in a 5D tensor.
reverse Reverse a tensor along the specified axes.
rnn Iterates over the time dimension of a tensor.
round Element-wise rounding to the closest integer.
separable_conv2d 2D convolution with separable filters.
set_epsilon Sets the value of the fuzz factor used in numeric expressions.
set_floatx Sets the default float type.
set_image_data_format Sets the value of the image data format convention.
set_learning_phase Sets the learning phase to a fixed value.
set_session Sets the global TensorFlow session.
set_value Sets the value of a variable, from a Numpy array.
shape Returns the symbolic shape of a tensor or variable.
sigmoid Element-wise sigmoid.
sign Element-wise sign.
sin Computes sin of x element-wise.
softmax Softmax of a tensor.
softplus Softplus of a tensor.
softsign Softsign of a tensor.
sparse_categorical_crossentropy Categorical crossentropy with integer targets.
spatial_2d_padding Pads the 2nd and 3rd dimensions of a 4D tensor.
spatial_3d_padding Pads 5D tensor with zeros along the depth, height, width dimensions.
sqrt Element-wise square root.
square Element-wise square.
squeeze Removes a 1-dimension from the tensor at index “axis”.
stack Stacks a list of rank R tensors into a rank R+1 tensor.
std Standard deviation of a tensor, alongside the specified axis.
stop_gradient Returns variables but with zero gradient w.r.t. every other variable.
sum Sum of the values in a tensor, alongside the specified axis.
switch Switches between two operations depending on a scalar value.
tanh Element-wise tanh.
temporal_padding Pads the middle dimension of a 3D tensor.
tile Creates a tensor by tiling x by n.
to_dense Converts a sparse tensor into a dense tensor and returns it.
transpose Transposes a tensor and returns it.
truncated_normal Returns a tensor with truncated random normal distribution of values.
update Update the value of x to new_x.
update_add Update the value of x by adding increment.
update_sub Update the value of x by subtracting decrement.
var Variance of a tensor, alongside the specified axis.
variable Instantiates a variable and returns it.
zeros Instantiates an all-zeros variable and returns it.
zeros_like Instantiates an all-zeros variable of the same shape as another tensor.