From 5b3fb5417cceb3df011fe0a722e10dac5c3bbbbb Mon Sep 17 00:00:00 2001 From: Tomasz Kalinowski Date: Wed, 9 Aug 2023 13:44:53 -0400 Subject: [PATCH] redocument. --- R/model.R | 52 ++++++++++----------- man/evaluate.keras.engine.training.Model.Rd | 5 +- man/fit.keras.engine.training.Model.Rd | 50 ++++++++++---------- man/fit_generator.Rd | 5 +- man/install_keras.Rd | 10 ---- 5 files changed, 57 insertions(+), 65 deletions(-) diff --git a/R/model.R b/R/model.R index e88d63008..0f4a27d69 100644 --- a/R/model.R +++ b/R/model.R @@ -610,21 +610,21 @@ resolve_main_thread_generators <- function(x, callback_type = "on_train_batch_be #' multiple inputs). If all inputs in the model are named, you can also pass a #' list mapping input names to data. `x` can be `NULL` (default) if feeding #' from framework-native tensors (e.g. TensorFlow data tensors). You can also -#' pass a `tfdataset` or a generator returning a list with `(inputs, targets)` or -#' `(inputs, targets, sample_weights)`. -#' @param y Vector, matrix, or array of target (label) data (or list if the model has -#' multiple outputs). If all outputs in the model are named, you can also pass -#' a list mapping output names to data. `y` can be `NULL` (default) if feeding -#' from framework-native tensors (e.g. TensorFlow data tensors). +#' pass a `tfdataset` or a generator returning a list with `(inputs, targets)` +#' or `(inputs, targets, sample_weights)`. +#' @param y Vector, matrix, or array of target (label) data (or list if the +#' model has multiple outputs). If all outputs in the model are named, you can +#' also pass a list mapping output names to data. `y` can be `NULL` (default) +#' if feeding from framework-native tensors (e.g. TensorFlow data tensors). #' @param batch_size Integer or `NULL`. Number of samples per gradient update. #' If unspecified, `batch_size` will default to 32. -#' @param epochs Number of epochs to train the model. -#' Note that in conjunction with `initial_epoch`, -#' `epochs` is to be understood as "final epoch". The model is -#' not trained for a number of iterations given by `epochs`, but +#' @param epochs Number of epochs to train the model. Note that in conjunction +#' with `initial_epoch`, `epochs` is to be understood as "final epoch". The +#' model is not trained for a number of iterations given by `epochs`, but #' merely until the epoch of index `epochs` is reached. -#' @param verbose Verbosity mode (0 = silent, 1 = progress bar, 2 = one line per -#' epoch). Defaults to +#' @param verbose Verbosity mode (0 = silent, 1 = progress bar, 2 = one line +#' per epoch). Defaults to 1 in most contexts, 2 if in knitr render or running +#' on a distributed training server. #' @param view_metrics View realtime plot of training metrics (by epoch). The #' default (`"auto"`) will display the plot when running within RStudio, #' `metrics` were specified during model [compile()], `epochs > 1` and @@ -634,21 +634,21 @@ resolve_main_thread_generators <- function(x, callback_type = "on_train_batch_be #' @param validation_split Float between 0 and 1. Fraction of the training data #' to be used as validation data. The model will set apart this fraction of #' the training data, will not train on it, and will evaluate the loss and any -#' model metrics on this data at the end of each epoch. The validation data -#' is selected from the last samples in the `x` and `y` data provided, -#' before shuffling. +#' model metrics on this data at the end of each epoch. The validation data is +#' selected from the last samples in the `x` and `y` data provided, before +#' shuffling. #' @param validation_data Data on which to evaluate the loss and any model #' metrics at the end of each epoch. The model will not be trained on this #' data. This could be a list (x_val, y_val) or a list (x_val, y_val, #' val_sample_weights). `validation_data` will override `validation_split`. -#' @param shuffle shuffle: Logical (whether to shuffle the training data -#' before each epoch) or string (for "batch"). "batch" is a special option -#' for dealing with the limitations of HDF5 data; it shuffles in batch-sized -#' chunks. Has no effect when `steps_per_epoch` is not `NULL`. +#' @param shuffle shuffle: Logical (whether to shuffle the training data before +#' each epoch) or string (for "batch"). "batch" is a special option for +#' dealing with the limitations of HDF5 data; it shuffles in batch-sized +#' chunks. Has no effect when `steps_per_epoch` is not `NULL`. #' @param class_weight Optional named list mapping indices (integers) to a -#' weight (float) value, used for weighting the loss function -#' (during training only). This can be useful to tell the model to -#' "pay more attention" to samples from an under-represented class. +#' weight (float) value, used for weighting the loss function (during training +#' only). This can be useful to tell the model to "pay more attention" to +#' samples from an under-represented class. #' @param sample_weight Optional array of the same length as x, containing #' weights to apply to the model's loss for each sample. In the case of #' temporal data, you can pass a 2D array with shape (samples, @@ -660,14 +660,14 @@ resolve_main_thread_generators <- function(x, callback_type = "on_train_batch_be #' @param steps_per_epoch Total number of steps (batches of samples) before #' declaring one epoch finished and starting the next epoch. When training #' with input tensors such as TensorFlow data tensors, the default `NULL` is -#' equal to the number of samples in your dataset divided by the batch -#' size, or 1 if that cannot be determined. +#' equal to the number of samples in your dataset divided by the batch size, +#' or 1 if that cannot be determined. #' @param validation_steps Only relevant if `steps_per_epoch` is specified. #' Total number of steps (batches of samples) to validate before stopping. #' @param ... Unused #' -#' @return A `history` object that contains all information collected -#' during training. +#' @return A `history` object that contains all information collected during +#' training. #' #' @family model functions #' diff --git a/man/evaluate.keras.engine.training.Model.Rd b/man/evaluate.keras.engine.training.Model.Rd index 3a98a8d38..bab46b9db 100644 --- a/man/evaluate.keras.engine.training.Model.Rd +++ b/man/evaluate.keras.engine.training.Model.Rd @@ -34,8 +34,9 @@ from framework-native tensors (e.g. TensorFlow data tensors).} \item{batch_size}{Integer or \code{NULL}. Number of samples per gradient update. If unspecified, \code{batch_size} will default to 32.} -\item{verbose}{Verbosity mode (0 = silent, 1 = progress bar, 2 = one line per -epoch).} +\item{verbose}{Verbosity mode (0 = silent, 1 = progress bar, 2 = one line +per epoch). Defaults to 1 in most contexts, 2 if in knitr render or running +on a distributed training server.} \item{sample_weight}{Optional array of the same length as x, containing weights to apply to the model's loss for each sample. In the case of diff --git a/man/fit.keras.engine.training.Model.Rd b/man/fit.keras.engine.training.Model.Rd index 1b7c7518b..4cbc6e1b2 100644 --- a/man/fit.keras.engine.training.Model.Rd +++ b/man/fit.keras.engine.training.Model.Rd @@ -31,25 +31,25 @@ multiple inputs). If all inputs in the model are named, you can also pass a list mapping input names to data. \code{x} can be \code{NULL} (default) if feeding from framework-native tensors (e.g. TensorFlow data tensors). You can also -pass a \code{tfdataset} or a generator returning a list with \verb{(inputs, targets)} or -\verb{(inputs, targets, sample_weights)}.} +pass a \code{tfdataset} or a generator returning a list with \verb{(inputs, targets)} +or \verb{(inputs, targets, sample_weights)}.} -\item{y}{Vector, matrix, or array of target (label) data (or list if the model has -multiple outputs). If all outputs in the model are named, you can also pass -a list mapping output names to data. \code{y} can be \code{NULL} (default) if feeding -from framework-native tensors (e.g. TensorFlow data tensors).} +\item{y}{Vector, matrix, or array of target (label) data (or list if the +model has multiple outputs). If all outputs in the model are named, you can +also pass a list mapping output names to data. \code{y} can be \code{NULL} (default) +if feeding from framework-native tensors (e.g. TensorFlow data tensors).} \item{batch_size}{Integer or \code{NULL}. Number of samples per gradient update. If unspecified, \code{batch_size} will default to 32.} -\item{epochs}{Number of epochs to train the model. -Note that in conjunction with \code{initial_epoch}, -\code{epochs} is to be understood as "final epoch". The model is -not trained for a number of iterations given by \code{epochs}, but +\item{epochs}{Number of epochs to train the model. Note that in conjunction +with \code{initial_epoch}, \code{epochs} is to be understood as "final epoch". The +model is not trained for a number of iterations given by \code{epochs}, but merely until the epoch of index \code{epochs} is reached.} -\item{verbose}{Verbosity mode (0 = silent, 1 = progress bar, 2 = one line per -epoch).} +\item{verbose}{Verbosity mode (0 = silent, 1 = progress bar, 2 = one line +per epoch). Defaults to 1 in most contexts, 2 if in knitr render or running +on a distributed training server.} \item{callbacks}{List of callbacks to be called during training.} @@ -62,24 +62,24 @@ different default.} \item{validation_split}{Float between 0 and 1. Fraction of the training data to be used as validation data. The model will set apart this fraction of the training data, will not train on it, and will evaluate the loss and any -model metrics on this data at the end of each epoch. The validation data -is selected from the last samples in the \code{x} and \code{y} data provided, -before shuffling.} +model metrics on this data at the end of each epoch. The validation data is +selected from the last samples in the \code{x} and \code{y} data provided, before +shuffling.} \item{validation_data}{Data on which to evaluate the loss and any model metrics at the end of each epoch. The model will not be trained on this data. This could be a list (x_val, y_val) or a list (x_val, y_val, val_sample_weights). \code{validation_data} will override \code{validation_split}.} -\item{shuffle}{shuffle: Logical (whether to shuffle the training data -before each epoch) or string (for "batch"). "batch" is a special option -for dealing with the limitations of HDF5 data; it shuffles in batch-sized +\item{shuffle}{shuffle: Logical (whether to shuffle the training data before +each epoch) or string (for "batch"). "batch" is a special option for +dealing with the limitations of HDF5 data; it shuffles in batch-sized chunks. Has no effect when \code{steps_per_epoch} is not \code{NULL}.} \item{class_weight}{Optional named list mapping indices (integers) to a -weight (float) value, used for weighting the loss function -(during training only). This can be useful to tell the model to -"pay more attention" to samples from an under-represented class.} +weight (float) value, used for weighting the loss function (during training +only). This can be useful to tell the model to "pay more attention" to +samples from an under-represented class.} \item{sample_weight}{Optional array of the same length as x, containing weights to apply to the model's loss for each sample. In the case of @@ -94,8 +94,8 @@ resuming a previous training run).} \item{steps_per_epoch}{Total number of steps (batches of samples) before declaring one epoch finished and starting the next epoch. When training with input tensors such as TensorFlow data tensors, the default \code{NULL} is -equal to the number of samples in your dataset divided by the batch -size, or 1 if that cannot be determined.} +equal to the number of samples in your dataset divided by the batch size, +or 1 if that cannot be determined.} \item{validation_steps}{Only relevant if \code{steps_per_epoch} is specified. Total number of steps (batches of samples) to validate before stopping.} @@ -103,8 +103,8 @@ Total number of steps (batches of samples) to validate before stopping.} \item{...}{Unused} } \value{ -A \code{history} object that contains all information collected -during training. +A \code{history} object that contains all information collected during +training. } \description{ Trains the model for a fixed number of epochs (iterations on a dataset). diff --git a/man/fit_generator.Rd b/man/fit_generator.Rd index ed1157108..d63402e3a 100644 --- a/man/fit_generator.Rd +++ b/man/fit_generator.Rd @@ -53,8 +53,9 @@ An epoch is an iteration over the entire data provided, as defined by for a number of iterations given by \code{epochs}, but merely until the epoch of index \code{epochs} is reached.} -\item{verbose}{Verbosity mode (0 = silent, 1 = progress bar, 2 = one line per -epoch).} +\item{verbose}{Verbosity mode (0 = silent, 1 = progress bar, 2 = one line +per epoch). Defaults to 1 in most contexts, 2 if in knitr render or running +on a distributed training server.} \item{callbacks}{List of callbacks to apply during training.} diff --git a/man/install_keras.Rd b/man/install_keras.Rd index 5c32b0d66..c9a5273e1 100644 --- a/man/install_keras.Rd +++ b/man/install_keras.Rd @@ -11,8 +11,6 @@ install_keras( tensorflow = version, extra_packages = NULL, ..., - envname = "r-keras", - new_env = identical(envname, "r-keras"), pip_ignore_installed = TRUE ) } @@ -48,14 +46,6 @@ TensorFlow.} \item{...}{other arguments passed to \code{\link[reticulate:conda-tools]{reticulate::conda_install()}} or \code{\link[reticulate:virtualenv-tools]{reticulate::virtualenv_install()}}, depending on the \code{method} used.} -\item{envname}{The name, or full path, of the environment in which Python -packages are to be installed. When \code{NULL} (the default), the active -environment as set by the \code{RETICULATE_PYTHON_ENV} variable will be used; -if that is unset, then the \code{r-reticulate} environment will be used.} - -\item{new_env}{If \code{TRUE}, any existing Python virtual environment and/or -conda environment specified by \code{envname} is deleted first.} - \item{pip_ignore_installed}{Whether pip should ignore installed python packages and reinstall all already installed python packages. This defaults to \code{TRUE}, to ensure that TensorFlow dependencies like NumPy are compatible