Merge pull request #1274 from rstudio/preprocessing-layers-guide

t-kalinowski · web-flow · commit 647391bdffb3 · 2021-09-29T15:10:35.000-04:00
Preprocessing layers vignette
diff --git a/.Rbuildignore b/.Rbuildignore
@@ -12,6 +12,7 @@
 ^issues$
 ^external$
 ^vignettes/examples$
+^vignettes/new-guides$
 ^vignettes/learn\.Rmd$
 ^vignettes/tools\.Rmd$
 ^vignettes/images/resources-.*$
@@ -40,4 +41,5 @@
 ^cran-comments\.md$
 ^\.github$
 ^\.vscode$
+^scratch$
 
diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml
@@ -31,7 +31,7 @@ jobs:
           - {os: 'ubuntu-20.04', tf: 'default', r: '3.6'} # default R in ubuntu-20.04
           - {os: 'ubuntu-20.04', tf: 'default', r: '3.5'} #
           - {os: 'ubuntu-20.04', tf: 'default', r: '3.4'} #
-          - {os: 'ubuntu-20.04', tf: 'default', r: '3.3'} # Oldest R available in Rstudio Marketplace offerings
+          # - {os: 'ubuntu-20.04', tf: 'default', r: '3.3'} # Oldest R available in RStudio Marketplace offerings; rcmdcheck not available
           # - {os: 'ubuntu-20.04', tf: 'tensorflow-cpu', r: '3.2'} # rcmdcheck not available
           # - {os: 'ubuntu-20.04', tf: 'tensorflow-cpu', r: '3.1'} # remotes not available
 
diff --git a/.gitignore b/.gitignore
@@ -18,3 +18,4 @@ doc
 Meta
 .vscode
 scratch
+inst/doc
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -26,7 +26,7 @@ License: MIT + file LICENSE
 URL: https://keras.rstudio.com
 BugReports: https://github.com/rstudio/keras/issues
 Depends:
-    R (>= 3.2)
+    R (>= 3.4)
 Imports:
     generics (>= 0.0.1),
     reticulate (>= 1.10),
diff --git a/NAMESPACE b/NAMESPACE
@@ -104,6 +104,7 @@ export(application_vgg16)
 export(application_vgg19)
 export(application_xception)
 export(array_reshape)
+export(as_tensor)
 export(backend)
 export(bidirectional)
 export(callback_csv_logger)
@@ -611,6 +612,7 @@ importFrom(reticulate,use_python)
 importFrom(reticulate,use_virtualenv)
 importFrom(rlang,"%||%")
 importFrom(stats,predict)
+importFrom(tensorflow,as_tensor)
 importFrom(tensorflow,evaluate)
 importFrom(tensorflow,export_savedmodel)
 importFrom(tensorflow,install_tensorflow)
diff --git a/NEWS.md b/NEWS.md
@@ -1,6 +1,8 @@
 # keras (development version)
 
-- New family of *preprocessing* layers. These are the spiritual successor to the `tfdatasets::step_*` family of data transformers (to be deprecated in a future release). New function:
+- New family of *preprocessing* layers. These are the spiritual successor to the `tfdatasets::step_*` family of data transformers (to be deprecated in a future release).
+  Added a new vignette: "Working with preprocessing layers".
+  New functions:
 
   Image preprocessing:
     - `layer_resizing()`
@@ -53,9 +55,9 @@
 
 - Fixed an issue in `layer_input()` where passing a tensorflow `DType` objects to argument `dtype` would throw an error.
 
-- Fixed an issue in `compile()` where passing an R function via an in-line 
+- Fixed an issue in `compile()` where passing an R function via an in-line
   call would result in an error from subsequent `fit()` calls.
-  (e.g., `compile(loss = function(y_true, y_pred) my_loss(y_true, y_pred))` 
+  (e.g., `compile(loss = function(y_true, y_pred) my_loss(y_true, y_pred))`
   now succeeds)
 
 - `clone_model()` gains a `clone_function` argument that allows you to customize each layer as it is cloned.
@@ -72,9 +74,10 @@
   `layer_subtract()`, `layer_multiply()`, `layer_average()`, `layer_maximum()`,
   `layer_minimum()` ,  `layer_dot()`)
 
-- `%py_class%` gains the ability to delay initializing the python session until first use.
+- `%py_class%` gains the ability to delay initializing the Python session until first use.
   It is now safe to implement and export `%py_class%` objects in an R package.
 
+- Bumped minimum R version to 3.4. Expanded CI to test on all supported R version. Fixed regression that prevented package installation on R <= 3.4
 # keras 2.6.0
 
 Breaking changes (Tensorflow 2.6):
@@ -600,7 +603,7 @@ SavedModel format.
 - Don't re-export `install_tensorflow()` and `tf_config()` from tensorflow
   package.
 
-- `is_keras_available()` function to probe whether the Keras python
+- `is_keras_available()` function to probe whether the Keras Python
   package is available in the current environment.
 
 - `as.data.frame()` S3 method for Keras training history
diff --git a/R/backend.R b/R/backend.R
@@ -2160,7 +2160,10 @@ k_random_normal_variable <- function(shape, mean, scale, dtype = NULL, name = NU
 #'
 #' @export
 k_random_uniform <- function(shape, minval = 0.0, maxval = 1.0, dtype = NULL, seed = NULL) {
-  # TODO: if dtype is int, then minval/maxval should be cast to int
+  if(!is.null(dtype)) {
+    minval <- as_tensor(minval, dtype = dtype)
+    maxval <- as_tensor(maxval, dtype = dtype)
+  }
   keras$backend$random_uniform(
     shape = backend_normalize_shape(shape),
     minval = minval,
diff --git a/R/install.R b/R/install.R
@@ -1,4 +1,4 @@
-#' Install TensorFlow and Keras, including all python dependencies
+#' Install TensorFlow and Keras, including all Python dependencies
 #'
 #' This function will install Tensorflow and all Keras dependencies. This is a
 #' thin wrapper around [`tensorflow::install_tensorflow()`], with the only
@@ -27,7 +27,7 @@ install_keras <- function(method = c("auto", "virtualenv", "conda"),
                           ...) {
 
   pkgs <- default_extra_packages(tensorflow)
-  if(!is.null(extra_packages))
+  if(!is.null(extra_packages)) # user supplied package version constraints take precedence
     pkgs[gsub("[=<>~]{1,2}[0-9.]+$", "", extra_packages)] <- extra_packages
 
   if(tensorflow == "default") # may be different from tensorflow
diff --git a/R/layers-core.R b/R/layers-core.R
@@ -423,32 +423,45 @@ normalize_path <- function(path) {
 }
 
 
-normalize_shape <- function (x) {
-  # reflect NULL back
-  if (is.null(x))
-    return(x)
-  else
-    as_shape(x)
-}
 
-as_shape <- function (x) {
+# Helper function to coerce shape arguments to tuple
+# tf$reshape()/k_reshape() doesn't accept a tf.TensorShape object
+normalize_shape <- function(shape) {
 
-  if (inherits(x, "tensorflow.python.framework.tensor_shape.TensorShape"))
-    return(x)
-
-  if (is.null(x))
-    dims <- NULL
-  else
-    dims <- lapply(x, function(d) {
-      if (is.null(d) || isTRUE(is.na(d)))
-        NULL
+  # reflect NULL back
+  if (is.null(shape))
+    return(shape)
+
+  # if it's a list or a numeric vector then convert to integer
+  if (is.list(shape) || is.numeric(shape)) {
+    shape <- lapply(shape, function(value) {
+      if (!is.null(value))
+        as.integer(value)
       else
-        as.integer(d)
+        NULL
     })
+  }
+
+  if(inherits(shape, "tensorflow.python.framework.tensor_shape.TensorShape"))
+    shape <- as.list(shape$as_list()) # unpack for tuple()
 
-  tensorflow::tf$TensorShape(dims)
+  # coerce to tuple so it's iterable
+  tuple(shape)
 }
 
+# @export
+# format.python.builtin.object <- function(x, ...) {
+#   capture.output(print(x, ...))
+# }
+
+as_shape <- function(x) {
+  lapply(x, function(d) {
+    if (is.null(d))
+      NULL
+    else
+      as.integer(d)
+  })
+}
 
 #' Create a Keras Layer
 #'
diff --git a/R/layers-merge.R b/R/layers-merge.R
@@ -12,9 +12,6 @@
 #'   layer instance is returned.
 #'
 #' @family merging_layers
-#' @seealso
-#' @seealso
-#'
 #'
 #' @seealso
 #' +  <https://www.tensorflow.org/api_docs/python/tf/keras/layers/add>
diff --git a/R/layers-preprocessing.R b/R/layers-preprocessing.R
@@ -1434,10 +1434,6 @@ function(object, run_eagerly = NULL, steps_per_execution = NULL, ...) {
   do.call(object$compile, args)
 }
 
-# TODO: impl and add `require_tf_version("2.6")`
-# TODO: tests
-# TODO: add @family to all the preprocessing layers
-#
 
 # TODO: isn't there a hashing trick already? text_hashing_trick
 
diff --git a/R/preprocessing.R b/R/preprocessing.R
@@ -213,10 +213,10 @@ text_one_hot <- function(input_text, n, filters = '!"#$%&()*+,-./:;<=>?@[\\]^_`{
 #'
 #' @param text Input text (string).
 #' @param n Dimension of the hashing space.
-#' @param hash_function if `NULL` uses python `hash` function, can be 'md5' or
-#'   any function that takes in input a string and returns a int. Note that
+#' @param hash_function if `NULL` uses the Python `hash()` function. Otherwise can be `'md5'` or
+#'   any function that takes in input a string and returns an int. Note that
 #'   `hash` is not a stable hashing function, so it is not consistent across
-#'   different runs, while 'md5' is a stable hashing function.
+#'   different runs, while `'md5'` is a stable hashing function.
 #' @param filters Sequence of characters to filter out such as
 #'   punctuation. Default includes basic punctuation, tabs, and newlines.
 #' @param lower Whether to convert the input to lowercase.
@@ -906,7 +906,7 @@ flow_images_from_directory <- function(
 #'   image data, which is useful to use in  `predict_generator()`).
 #'
 #' @note
-#' This functions requires that `pandas` (python module) is installed in the
+#' This functions requires that `pandas` (Python module) is installed in the
 #' same environment as `tensorflow` and `keras`.
 #'
 #' If you are using `r-tensorflow` (the default environment) you can install
@@ -928,7 +928,7 @@ flow_images_from_dataframe <- function(
   interpolation = "nearest", drop_duplicates = NULL) {
 
   if (!reticulate::py_module_available("pandas"))
-    stop("Pandas (python module) must be installed in the same environment as Keras.",
+    stop("Pandas (Python module) must be installed in the same environment as Keras.",
          'Install it using reticulate::virtualenv_install("pandas", envname = "r-tensorflow") ',
          'or reticulate::conda_install("pandas", envname = "r-tensorflow") depending on ',
          'the kind of environment you are using.')
diff --git a/R/reexports.R b/R/reexports.R
@@ -62,6 +62,10 @@ tensorflow::export_savedmodel
 #' @export
 tensorflow::shape
 
+#' @importFrom tensorflow as_tensor
+#' @export
+tensorflow::as_tensor
+
 #' @importFrom tfruns flags
 #' @export
 tfruns::flags
diff --git a/R/utils.R b/R/utils.R
@@ -283,7 +283,7 @@ keras_array <- function(x, dtype = NULL) {
 
 #' Check if Keras is Available
 #'
-#' Probe to see whether the Keras python package is available in the current
+#' Probe to see whether the Keras Python package is available in the current
 #' system environment.
 #'
 #' @param version Minimum required version of Keras (defaults to `NULL`, no
@@ -429,7 +429,7 @@ capture_args <- function(cl, modifiers = NULL, ignore = NULL,
   if("..." %in% fn_arg_nms && !"..." %in% ignore) {
     assert_all_dots_named(envir, cl)
     # this might reorder args by assuming ... are last, but it doesn't matter
-    # since everything is supplied as a keyword arg to the python side anyway
+    # since everything is supplied as a keyword arg to the Python side anyway
     cl2 <- c(cl2, quote(...))
   }
 
diff --git a/man/reexports.Rd b/man/reexports.Rd
diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml
@@ -28,12 +28,22 @@ navbar:
     - text: "Articles"
       menu:
         - text: "Guides (New for TF 2.6)"
+
         - text: "Python Subclasses"
-          href: articles/python_subclasses.html
+          href: articles/new-guides/python_subclasses.html
+
         - text: "Making New Layers and Models via Subclassing"
-          href: articles/guides/making_new_layers_and_models_via_subclassing.html
-        - text: "Customizing what happens in fit"
-          href: articles/guides/customizing_what_happens_in_fit.html
+          href: articles/new-guides/making_new_layers_and_models_via_subclassing.html
+
+        - text: "Customizing What Happens in Fit"
+          href: articles/new-guides/customizing_what_happens_in_fit.html
+
+        - text: "Writing Your Own Callbacks"
+          href: articles/new-guides/writing_your_own_callbacks.html
+
+        - text: "Working with Preprocessing Layers"
+          href: articles/new-guides/preprocessing_layers.html
+
         - text: "--------------------------"
         - text: "Using Keras"
         - text: "Guide to Keras Basics"
diff --git a/tools/experimental-utils.R b/tools/experimental-utils.R
@@ -116,3 +116,37 @@ maybe_rename <- function(x, ...) {
   names(x)[i] <- names(spec)[spec == names(x)[i]]
   x
 }
+
+
+
+
+# tf$reshape() doesn't accept a tf.TensorShape object
+# normalize_shape <-
+function (x) {
+  # reflect NULL back
+  if (is.null(x))
+    return(x)
+  else
+    as_shape(x)
+}
+
+
+# tf$reshape() doesn't accept a tf.TensorShape object
+# as_shape <-
+function (x) {
+
+  if (inherits(x, "tensorflow.python.framework.tensor_shape.TensorShape"))
+    return(x)
+
+  if (is.null(x))
+    dims <- NULL
+  else
+    dims <- lapply(x, function(d) {
+      if (is.null(d) || isTRUE(is.na(d)))
+        NULL
+      else
+        as.integer(d)
+    })
+
+  tensorflow::tf$TensorShape(dims)
+}
diff --git a/vignettes/.gitignore b/vignettes/.gitignore
@@ -1,3 +1,5 @@
 logs
 *.h5
 
+*.html
+*.R
diff --git a/vignettes/faq.Rmd b/vignettes/faq.Rmd
@@ -554,12 +554,12 @@ You can pass the `version` argument to check for a specific version of Keras.
 
 ### Keras Module
 
-Another consideration is gaining access to the underlying Keras python module. You might need to do this if you require lower level access to Keras than is provided for by the Keras R package. 
+Another consideration is gaining access to the underlying Keras Python module. You might need to do this if you require lower level access to Keras than is provided for by the Keras R package. 
 
 Since the Keras R package can bind to multiple different implementations of Keras (either the original Keras or the TensorFlow implementation of Keras), you should use the `keras::implementation()` function to obtain access to the correct python module. You can use this function within the `.onLoad` function of a package to provide global access to the module within your package. For example:
 
 ```{r}
-# Keras python module
+# Keras Python module
 keras <- NULL
 
 # Obtain a reference to the module from the keras R package
diff --git a/vignettes/new-guides/customizing_what_happens_in_fit.Rmd b/vignettes/new-guides/customizing_what_happens_in_fit.Rmd
diff --git a/vignettes/new-guides/making_new_layers_and_models_via_subclassing.Rmd b/vignettes/new-guides/making_new_layers_and_models_via_subclassing.Rmd
diff --git a/vignettes/new-guides/preprocessing_layers.Rmd b/vignettes/new-guides/preprocessing_layers.Rmd
diff --git a/vignettes/new-guides/python_subclasses.Rmd b/vignettes/new-guides/python_subclasses.Rmd
diff --git a/vignettes/new-guides/writing_your_own_callbacks.Rmd b/vignettes/new-guides/writing_your_own_callbacks.Rmd

-Original file line number
+Diff line change
 Meta
 .vscode
 scratch
 +inst/doc