Type:	Package
Title:	R Interface to 'TensorFlow'
Version:	2.16.0
Description:	Interface to 'TensorFlow' https://www.tensorflow.org/, an open source software library for numerical computation using data flow graphs. Nodes in the graph represent mathematical operations, while the graph edges represent the multidimensional data arrays (tensors) communicated between them. The flexible architecture allows you to deploy computation to one or more 'CPUs' or 'GPUs' in a desktop, server, or mobile device with a single 'API'. 'TensorFlow' was originally developed by researchers and engineers working on the Google Brain Team within Google's Machine Intelligence research organization for the purposes of conducting machine learning and deep neural networks research, but the system is general enough to be applicable in a wide variety of other domains as well.
License:	Apache License 2.0
URL:	https://github.com/rstudio/tensorflow
BugReports:	https://github.com/rstudio/tensorflow/issues
SystemRequirements:	TensorFlow (https://www.tensorflow.org/)
Encoding:	UTF-8
Depends:	R (≥ 3.6)
Imports:	config, processx, reticulate (≥ 1.32), tfruns (≥ 1.0), utils, yaml, grDevices, tfautograph (≥ 0.3.1), rstudioapi (≥ 0.7), lifecycle
Suggests:	testthat (≥ 2.1.0), keras3, pillar, withr, callr
RoxygenNote:	7.3.1
NeedsCompilation:	no
Packaged:	2024-04-15 15:56:39 UTC; tomasz
Author:	JJ Allaire [aut, cph], Tomasz Kalinowski [ctb, cph, cre], Daniel Falbel [ctb, cph], Dirk Eddelbuettel [ctb, cph], Yuan Tang [aut, cph], Nick Golding [ctb, cph], Google Inc. [ctb, cph] (Examples and Tutorials), Posit, PBC [cph, fnd]
Maintainer:	Tomasz Kalinowski <tomasz.kalinowski@posit.co>
Repository:	CRAN
Date/Publication:	2024-04-15 16:30:02 UTC

TensorFlow for R

Description

TensorFlow is an open source software library for numerical computation using data flow graphs. Nodes in the graph represent mathematical operations, while the graph edges represent the multidimensional data arrays (tensors) communicated between them. The flexible architecture allows you to deploy computation to one or more CPUs or GPUs in a desktop, server, or mobile device with a single API.

Details

The TensorFlow API is composed of a set of Python modules that enable constructing and executing TensorFlow graphs. The tensorflow package provides access to the complete TensorFlow API from within R.

For additional documentation on the tensorflow package see https://tensorflow.rstudio.com

Author(s)

Maintainer: Tomasz Kalinowski tomasz.kalinowski@posit.co [contributor, copyright holder]

Authors:

• JJ Allaire [copyright holder]

• Yuan Tang terrytangyuan@gmail.com (ORCID) [copyright holder]

Other contributors:

• Daniel Falbel daniel@posit.co [contributor, copyright holder]

• Dirk Eddelbuettel edd@debian.org [contributor, copyright holder]

• Nick Golding nick.golding.research@gmail.com [contributor, copyright holder]

• Google Inc. (Examples and Tutorials) [contributor, copyright holder]

• Posit, PBC [copyright holder, funder]

See Also

Useful links:

• https://github.com/rstudio/tensorflow

• Report bugs at https://github.com/rstudio/tensorflow/issues

Subset tensors with [

Description

Subset tensors with [

Usage

## S3 method for class 'tensorflow.tensor'

  x[
  ...,
  drop = TRUE,
  style = getOption("tensorflow.extract.style"),
  options = tf_extract_opts(style)
]

Arguments

Examples

## Not run: 

x <- as_tensor(array(1:15, dim = c(3, 5)))
x
# by default, numerics supplied to [...] are interpreted R style
x[,1]    # first column
x[1:2,]  # first two rows
x[,1, drop = FALSE] # 1 column matrix

# strided steps can be specified in R syntax or python syntax
x[, seq(1, 5, by = 2)]
x[, 1:5:2]
# if you are unfamiliar with python-style strided steps, see:
# https://numpy.org/doc/stable/reference/arrays.indexing.html#basic-slicing-and-indexing

# missing arguments for python syntax are valid, but they must by backticked
# or supplied as NULL
x[, `::2`]
x[, NULL:NULL:2]
x[, `2:`]


# all_dims() expands to the shape of the tensor
# (equivalent to a python ellipsis `...`)
# (not to be confused with R dots `...`)
y <- as_tensor(array(1:(3^5), dim = c(3,3,3,3,3)))
all.equal(y[all_dims(), 1],
          y[, , , , 1])

# tf$newaxis are valid (equivalent to a NULL)
x[,, tf$newaxis]
x[,, NULL]


# negative numbers are always interpreted python style
# The first time a negative number is supplied to `[`, a warning is issued
# about the non-standard behavior.
x[-1,]  # last row, with a warning
x[-1,]  # the warning is only issued once

# specifying `style = 'python'` changes the following:
# +  zero-based indexing is used
# +  slice sequences in the form of `start:stop` do not include `stop`
#    in the returned value
# +  out-of-bounds indices in a slice are valid

# The style argument can be supplied to individual calls of `[` or set
# as a global option

# example of zero based  indexing
x[0, , style = 'python']  # first row
x[1, , style = 'python']  # second row

# example of slices with exclusive stop
options(tensorflow.extract.style = 'python')
x[, 0:1]  # just the first column
x[, 0:2]  # first and second column

# example of out-of-bounds index
x[, 0:10]
options(tensorflow.extract.style = NULL)

# slicing with tensors is valid too, but note, tensors are never
# translated and are always interpreted python-style.
# A warning is issued the first time a tensor is passed to `[`
x[, tf$constant(0L):tf$constant(2L)]
# just as in python, only scalar tensors are valid
# https://www.tensorflow.org/api_docs/python/tf/Tensor#__getitem__

# To silence the warnings about tensors being passed as-is and negative numbers
# being interpreted python-style, set
options(tensorflow.extract.style = 'R')

# clean up from examples
options(tensorflow.extract.style = NULL)

## End(Not run)

All dims

Description

This function returns an object that can be used when subsetting tensors with [. If you are familiar with python,, this is equivalent to the python Ellipsis ..., (not to be confused with ... in R).

Usage

all_dims()

Examples

## Not run: 
# in python, if x is a numpy array or tensorflow tensor
x[..., i]
# the ellipsis means "expand to match number of dimension of x".
# to translate the above python expression to R, write:
x[all_dims(), i]

## End(Not run)

as_tensor

Description

Coerce objects to tensorflow tensors (potentially of a specific dtype or shape). The provided default methods will call tf$convert_to_tensor. Depending on arguments supplied it may also call some combination of

• tf$saturate_cast or tf$cast

• tf$fill or tf$reshape

Usage

as_tensor(x, dtype = NULL, ..., name = NULL)

## Default S3 method:
as_tensor(x, dtype = NULL, ..., shape = NULL, name = NULL)

## S3 method for class 'double'
as_tensor(x, dtype = NULL, ..., name = NULL)

Arguments

Value

a tensorflow tensor

Examples

## Not run: 
as_tensor(42, "int32")
as_tensor(as_tensor(42))

## End(Not run)

Evaluate a Model

Description

Evaluate a model object. See implementations in the keras3 package.

Usage

evaluate(object, ...)

Arguments

Implementations

• keras3

Export a Saved Model

Description

Serialize a model to disk. See implementations in the keras3 package.

Usage

export_savedmodel(object, export_dir_base, ...)

Arguments

Value

The path to the exported directory, as a string.

Implementations

• keras3

Install TensorFlow and its dependencies

Description

install_tensorflow() installs just the tensorflow python package and it's direct dependencies. For a more complete installation that includes additional optional dependencies, use keras3::install_keras().

Usage

install_tensorflow(
  method = c("auto", "virtualenv", "conda"),
  conda = "auto",
  version = "default",
  envname = "r-tensorflow",
  extra_packages = NULL,
  restart_session = TRUE,
  conda_python_version = NULL,
  ...,
  cuda = NULL,
  metal = FALSE,
  pip_ignore_installed = FALSE,
  new_env = identical(envname, "r-tensorflow"),
  python_version = NULL
)

Arguments

Details

You may be prompted to download and install miniconda if reticulate did not find a non-system installation of python. Miniconda is the recommended installation method for most users, as it ensures that the R python installation is isolated from other python installations. All python packages will by default be installed into a self-contained conda or venv environment named "r-reticulate". Note that "conda" is the only supported method on M1 Mac.

If you initially declined the miniconda installation prompt, you can later manually install miniconda by running reticulate::install_miniconda().

Custom Installation

install_tensorflow() or keras3::install_keras() isn't required to use tensorflow with the package. If you manually configure a python environment with the required dependencies, you can tell R to use it by pointing reticulate at it, commonly by setting an environment variable:

Sys.setenv("RETICULATE_PYTHON" = "~/path/to/python-env/bin/python")

Apple Silicon

Beginning with Tensorflow version 2.13, the default tensorflow package now works on Apple Silicon. See https://developer.apple.com/metal/tensorflow-plugin/ for instructions on how to install older versions of Tensorflow on macOS. Please note that not all operations are supported on Arm Mac GPUs. You can work around the missing operations by pinning operations to CPU. For example:

x <- array(runif(64*64), c(1, 64, 64))
keras3::layer_random_rotation(x, .5)  # Error:
# No registered 'RngReadAndSkip' OpKernel for 'GPU' devices
# Pin the operation to the CPU to avoid the error
with(tf$device("CPU"), keras3::layer_random_rotation(x, .5) ) # No Error

Additional Packages

If you wish to add additional PyPI packages to your Keras / TensorFlow environment you can either specify the packages in the extra_packages argument of install_tensorflow() or install_keras(), or alternatively install them into an existing environment using the reticulate::py_install() function. Note that install_keras() includes a set of additional python packages by default, see ?keras3::install_keras for details.

See Also

• keras3::install_keras()

• https://tensorflow.rstudio.com/reference/tensorflow/install_tensorflow

Parse Command Line Arguments

Description

Parse command line arguments of the form --key=value and ⁠--key value⁠. The values are assumed to be valid yaml and will be converted using yaml.load().

Usage

parse_arguments(arguments = NULL)

Arguments

Parse Configuration Flags for a TensorFlow Application

Description

Parse configuration flags for a TensorFlow application. Use this to parse and unify the configuration(s) specified through a flags.yml configuration file, alongside other arguments set through the command line.

Usage

parse_flags(
  config = Sys.getenv("R_CONFIG_ACTIVE", unset = "default"),
  file = "flags.yml",
  arguments = commandArgs(TRUE)
)

Arguments

Value

A named R list, mapping configuration keys to values.

Examples

## Not run: 
# examine an example configuration file provided by tensorflow
file <- system.file("examples/config/flags.yml", package = "tensorflow")
cat(readLines(file), sep = "\n")

# read the default configuration
FLAGS <- tensorflow::parse_flags("default", file = file)
str(FLAGS)

# read the alternate configuration: note that
# the default configuration is inherited, but
# we override the 'string' configuration here
FLAGS <- tensorflow::parse_flags("alternate", file = file)
str(FLAGS)

# override configuration values using command
# line arguments (normally, these would be
# passed in through the command line invocation
# used to start the process)
FLAGS <- tensorflow::parse_flags(
  "alternate",
  file = file,
  arguments = c("--foo=1")
)
str(FLAGS)


## End(Not run)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

reticulate

%as%, array_reshape, dict, import, iterate, np_array, tuple, use_condaenv, use_python, use_virtualenv

tfruns

flag_boolean, flag_integer, flag_numeric, flag_string, flags, run_dir

Set random seed for TensorFlow

Description

Sets all random seeds needed to make TensorFlow code reproducible.

Usage

set_random_seed(seed, disable_gpu = TRUE)

Arguments

Details

This function should be used instead of use_session_with_seed() if you are using TensorFlow >= 2.0, as the concept of session doesn't really make sense anymore.

This functions sets:

• The R random seed with set.seed().

• The python and Numpy seeds via (reticulate::py_set_seed()).

• The TensorFlow seed with (tf$random$set_seed())

It also optionally disables the GPU execution as this is a potential source of non-reproducibility.

Create a tf.TensorShape object

Description

Create a tf.TensorShape object

Usage

shape(..., dims = list(...))

Arguments

See Also

https://www.tensorflow.org/api_docs/python/tf/TensorShape

Examples

## Not run: 

# --- construct ---
shape()       # tf.TensorShape()       # scalar
shape(NULL)   # tf.TensorShape([None]) # 1-D array of unknown length
shape(NA)     # tf.TensorShape([None]) # 1-D array of unknown length, NA is a synonym for NULL

shape(dims = NULL) # TensorShape(None)    # Unknown rank, unknown size
shape(3, 4)        # TensorShape([3, 4])  # 2-D array (matrix) with 3 rows, 4 columns
shape(NA, 4)           # TensorShape([None, 4])  # 2-D array (matrix) with unknown rows, 4 columns
shape(dims = c(NA, 4)) # TensorShape([None, 4]) # same as above; bypass ... and pass dims directly

# --- inspect ---
length(shape(dims = NULL)) # NA_integer_
length(shape(1,2,3,NA))    # 4L

# ---convert ---
x <- shape(dims = list(3L, 5L))
as.list(x)     # list(3L, 5L)
as.integer(x)  # c(3L, 5L)
as.numeric(x)  # c(3, 5)
as.double(x)   # c(3, 5) # alias for as.numeric
as_tensor(x)   # tf.Tensor([3 5], shape=(2,), dtype=int32)

# convert partially undefined shapes
x <- shape(NA, 3)
as.list(x)     # list(NULL, 3L)
as.integer(x)  # c(NA, 3L)
as_tensor(x)   # tf.Tensor([-1  3], shape=(2,), dtype=int32) # unspecified dims default is -1

# as_tensor() converts undefined dimensions to -1, which is useful for
# tf functions that only accept tensors for shapes, e.g,
tf$reshape(tf$zeros(shape(8)),
           as_tensor(shape(NA, 4)))
# tf.Tensor([[0. 0. 0. 0.]
#            [0. 0. 0. 0.]], shape=(2, 4), dtype=float32)

# converting fully unknown shapes raises an error
try(as.list(shape(dims = NULL))) # ValueError: as_list() is not defined on an unknown TensorShape.
# test for rank first if this a concern:
as.list_or_null <- function(x) if(is.na(length(x))) NULL else as.list(x)
as.list_or_null(shape(dims = NULL))


# --- compare ---
# Fully known shapes return TRUE if and only if each element is equal
shape(3, 4) == shape(3, 4) # TRUE
shape(3, 4) == shape(4, 4) # FALSE

# two unknown dimensions are treated as equal
shape(NA, 4) == shape(NA, 4) # TRUE
shape(NA, 4) == shape(3, 4)  # FALSE

# Two unknown shapes, return TRUE
shape(dims = NULL) == shape(dims = NULL) # TRUE

# Comparing an unknown shape to a partially or fully defined shape returns FALSE
shape(dims = NULL) == shape(NULL) # FALSE
shape(dims = NULL) == shape(4)    # FALSE


values of length greater than one supplied to `...`  are automatically flattened
shape(1, c(2, 3), 4) # shape(1, 2, 3, 4)
shape(1, shape(2, 3), 4) # shape(1, 2, 3, 4)
shape(1, as_tensor(2, 3), 4) # shape(1, 2, 3, 4)

# --- extract or replace ---
# regular R-list semantics for `[`, `[[`, `[<-`, `[[<-`
x <- shape(1, 2, 3)
x[1]       # TensorShape([1])
x[[1]]     # 1L
x[2:3]     # TensorShape([2, 3])
x[-1]      # TensorShape([2, 3])

x[1] <- 11        ; x # TensorShape([11, 2, 3])
x[1] <- shape(11) ; x # TensorShape([11, 2, 3])
x[1] <- list(11)  ; x # TensorShape([11, 2, 3])

x[[1]] <- 22            ; x # TensorShape([22, 2, 3])
x[1:2] <- c(NA, 99)     ; x # TensorShape([None, 99, 3])
x[1:2] <- shape(33, 44) ; x # TensorShape([33, 44, 3])

# --- concatenate ---
c(shape(1), shape(2, 3), shape(4, NA)) # TensorShape([1, 2, 3, 4, None])

# --- merge ---
merge(shape(NA, 2),
      shape(1 , 2)) # TensorShape([1, 2])

try(merge(shape(2, 2),
          shape(1, 2))) # ValueError: Shapes (2, 2) and (1, 2) are not compatible

rm(x) # cleanup

## End(Not run)

TensorBoard Visualization Tool

Description

TensorBoard is a tool inspecting and understanding your TensorFlow runs and graphs.

Usage

tensorboard(
  log_dir,
  action = c("start", "stop"),
  host = "127.0.0.1",
  port = "auto",
  launch_browser = getOption("tensorflow.tensorboard.browser", interactive()),
  reload_interval = 5,
  purge_orphaned_data = TRUE
)

Arguments

Details

When TensorBoard is passed a logdir at startup, it recursively walks the directory tree rooted at logdir looking for subdirectories that contain tfevents data. Every time it encounters such a subdirectory, it loads it as a new run, and the frontend will organize the data accordingly.

The TensorBoard process will be automatically destroyed when the R session in which it is launched exits. You can pass action = "stop" to manually terminate TensorBoard.

Value

URL for browsing TensorBoard (invisibly).

Main TensorFlow module

Description

Interface to main TensorFlow module. Provides access to top level classes and functions as well as sub-modules (e.g. tf$nn, tf$contrib$learn, etc.).

Usage

tf

Format

TensorFlow module

Examples

## Not run: 
library(tensorflow)

hello <- tf$constant('Hello, TensorFlow!')
zeros <- tf$Variable(tf$zeros(shape(1L)))

tf$print(hello)
tf$print(zeros)

## End(Not run)

TensorFlow configuration information

Description

TensorFlow configuration information

Usage

tf_config()

tf_version()

Value

List with information on the current configuration of TensorFlow. You can determine whether TensorFlow was found using the available member (other members vary depending on whether available is TRUE or FALSE)

Tensor extract options

Description

Tensor extract options

Usage

tf_extract_opts(
  style = getOption("tensorflow.extract.style"),
  ...,
  one_based = getOption("tensorflow.extract.one_based", TRUE),
  inclusive_stop = getOption("tensorflow.extract.inclusive_stop", TRUE),
  disallow_out_of_bounds = getOption("tensorflow.extract.dissallow_out_of_bounds", TRUE),
  warn_tensors_passed_asis = getOption("tensorflow.extract.warn_tensors_passed_asis",
    TRUE),
  warn_negatives_pythonic = getOption("tensorflow.extract.warn_negatives_pythonic", TRUE)
)

Arguments

Value

an object with class "tf_extract_opts", suitable for passing to ⁠[.tensorflow.tensor()⁠

Examples

## Not run: 
x <- tf$constant(1:10)

opts <-  tf_extract_opts("R")
x[1, options = opts]

# or for more fine-grained control
opts <- tf_extract_opts(
    one_based = FALSE,
    warn_tensors_passed_asis = FALSE,
    warn_negatives_pythonic = FALSE
)
x[0:2, options = opts]

## End(Not run)

Creates a callable TensorFlow graph from an R function.

Description

tf_function constructs a callable that executes a TensorFlow graph created by tracing the TensorFlow operations in f. This allows the TensorFlow runtime to apply optimizations and exploit parallelism in the computation defined by f.

Usage

tf_function(f, input_signature = NULL, autograph = TRUE, ...)

Arguments

Details

A guide to getting started with tf.function can be found here.

TensorFlow GPU configuration information

Description

TensorFlow GPU configuration information

Usage

tf_gpu_configured(verbose = TRUE)

Arguments

Value

A bool, whether GPU is configured or not, or NA if could not be determined.

TensorFlow Probability Module

Description

TensorFlow Probability Module

Usage

tf_probability()

Value

Reference to TensorFlow Probability functions and classes

Examples

## Not run: 
library(tensorflow)
## one time setup:
# reticulate::py_install("tensorflow_probability")
tfp <- tf_probability()
tfp$distributions$Normal(loc = 0, scale = 1)

## End(Not run)

(Deprecated) Train a Model

Description

Train a model object. See implementation in the tfestimators::train.tf_estimator() package.

Usage

train(object, ...)

Arguments

(Deprecated) Simultaneously Train and Evaluate a Model

Description

Train and evaluate a model object. See implementation in the tfestimators::train_and_evaluate.tf_estimator() package.

Usage

train_and_evaluate(object, ...)

Arguments

Use Compatibility

Description

Enables TensorFlow to run under a different API version for compatibility with previous versions. For instance, this is useful to run TensorFlow 1.x code when using TensorFlow 2.x.

Usage

use_compat(version = c("v1", "v2"))

Arguments

Examples

## Not run: 
library(tensorflow)
use_compat("v1")

## End(Not run)

Use a session with a random seed

Description

Set various random seeds required to ensure reproducible results. The provided seed value will establish a new random seed for R, Python, NumPy, and TensorFlow. GPU computations and CPU parallelism will also be disabled by default.

Usage

use_session_with_seed(
  seed,
  disable_gpu = TRUE,
  disable_parallel_cpu = TRUE,
  quiet = FALSE
)

Arguments

Details

This function must be called at the very top of your script (i.e. immediately after library(tensorflow), library(keras), etc.). Any existing TensorFlow session is torn down via tf$reset_default_graph().

This function takes all measures known to promote reproducible results from TensorFlow sessions, however it's possible that various individual TensorFlow features or dependent libraries escape its effects. If you encounter non-reproducible results please investigate the possible sources of the problem, contributions via pull request are very welcome!

Packages which need to be notified before and after the seed is set can register for the "tensorflow.on_before_use_session" and "tensorflow.on_use_session" hooks (see setHook()) for additional details on hooks).

Value

TensorFlow session object, invisibly

Parallelism

By default the use_session_with_seed() function disables GPU and CPU parallelism, since both can result in non-deterministic execution patterns (see https://stackoverflow.com/questions/42022950/). You can optionally enable GPU or CPU parallelism by setting the disable_gpu and/or disable_parallel_cpu parameters to FALSE.

Examples

## Not run: 
library(tensorflow)
use_session_with_seed(42)

## End(Not run)

View a Saved Model

Description

View a serialized model from disk.

Usage

view_savedmodel(model_dir)

Arguments

Value

URL for browsing TensorBoard (invisibly).