# Keras Backend

## 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.