environment docs (#175)

* add file for r packages list * Update r-packages-docker.md * Update r-packages-docker.md * Update r-packages-docker.md * Update r-packages-docker.md * Update r-packages-docker.md * Update r-packages-docker.md * environment docstring updates * Update .Rbuildignore
Azure · Nov 5, 2019 · ccd6483 · ccd6483
1 parent d7d559b
commit ccd6483
Show file tree

Hide file tree

Showing 5 changed files with 195 additions and 15 deletions.
diff --git a/.Rbuildignore b/.Rbuildignore
@@ -14,3 +14,4 @@
 ^samples$
 ^CODE_OF_CONDUCT\.md$
 ^_pkgdown\.yml
+^misc$
diff --git a/R/environment.R b/R/environment.R
@@ -10,7 +10,7 @@
 #' your `Environment` object within that Docker container.
 #'
 #' If the `custom_docker_image` parameter
-#' is not set, Azure ML will build a default base image (CPU or GPU
+#' is not set, Azure ML will build a predefined base image (CPU or GPU
 #' depending on the `use_gpu` flag) and install any R packages specified in the
 #' `cran_packages`, `github_packages`, or `custom_url_packages` parameters.
 #' @param name A string of the name of the environment.
@@ -24,15 +24,14 @@
 #' from local directory or custom URL.
 #' @param custom_docker_image A string of the name of the Docker image from
 #' which the image to use for training or deployment will be built. If not set,
-#' a default CPU-based image will be used as the base image. To use an image
-#' from a private Docker repository, you will also have to specify the
-#' `image_registry_details` parameter.
+#' a predefined Docker image will be used. To use an image from a private Docker
+#' repository, you will also have to specify the `image_registry_details` parameter.
 #' @param image_registry_details A `ContainerRegistry` object of the details of
 #' the Docker image registry for the custom Docker image.
 #' @param use_gpu Indicates whether the environment should support GPUs.
-#' If `TRUE`, a GPU-based default Docker image will be used in the environment.
-#' If `FALSE`, a CPU-based image will be used. Default Docker images (CPU or
-#' GPU) will only be used if the `custom_docker_image` parameter is not set.
+#' If `TRUE`, a predefined GPU-based Docker image will be used in the environment.
+#' If `FALSE`, a predefined CPU-based image will be used. Predefined Docker images
+#' (CPU or GPU) will only be used if the `custom_docker_image` parameter is not set.
 #' @param shm_size A string for the size of the Docker container's shared
 #' memory block. For more information, see
 #' [Docker run reference](https://docs.docker.com/engine/reference/run/)
@@ -51,6 +50,29 @@
 #' a new version of the environment is created when you either submit a run,
 #' deploy a model, or manually register the environment. The versioning allows
 #' you to view changes to the environment over time.
+#' @section Predefined Docker images:
+#' When submitting a training job or deploying a model, Azure ML runs your
+#' training script or scoring script within a Docker container. If no custom
+#' Docker image is specified with the `custom_docker_image` parameter, Azure
+#' ML will build a predefined CPU or GPU Docker image. The predefine images extend
+#' the Ubuntu 16.04 [Azure ML base images](https://github.com/Azure/AzureML-Containers)
+#' and include the following dependencies:
+#' \tabular{rrr}{
+#' **Dependencies** \tab **Version** \tab **Remarks**\cr
+#' azuremlsdk \tab latest \tab (from GitHub)\cr
+#' R \tab 3.6.0 \tab -\cr
+#' Commonly used R packages \tab - \tab 80+ of the most popular R packages for
+#' data science, including the IRKernel, dplyr, shiny, ggplot2, tidyr, caret,
+#' and nnet. For the full list of packages included, see
+#' [here](https://github.com/Azure/azureml-sdk-for-r/tree/master/misc/r-packages-docker.md).\cr
+#' Python \tab 3.7.0 \tab -\cr
+#' azureml-defaults \tab latest \tab `azureml-defaults` contains the
+#' `azureml-core` and `applicationinsights` packages of the Python SDK that
+#' are required for tasks such as logging metrics, uploading artifacts, and
+#' deploying models. (from pip)\cr
+#' rpy2 \tab latest \tab (from conda)\cr
+#' CUDA (GPU image only) \tab 10.0 \tab CuDNN (version 7) is also included
+#' }
 #' @examples
 #' # The following example defines an environment that will build the default
 #' # base CPU image.

diff --git a/R/estimator.R b/R/estimator.R
@@ -8,6 +8,14 @@
 #' of executing an R script. Running an Estimator experiment
 #' (using `submit_experiment()`) will return a `ScriptRun` object and
 #' execute your training script on the specified compute target.
+#'
+#' To define the environment to use for training, you can either directly
+#' provide the environment-related parameters (e.g. `cran_packages`,
+#' `custom_docker_image`) to `estimator()`, or you can provide an
+#' `Environment` object to the `environment` parameter. For more information
+#' on the predefined Docker images that are used for training if
+#' `custom_docker_image` is not specified, see the documentation
+#' [here](https://azure.github.io/azureml-sdk-for-r/reference/r_environment.html#predefined-docker-images).
 #' @param source_directory A string of the local directory containing
 #' experiment configuration and code files needed for the training job.
 #' @param compute_target The `AmlCompute` object for the compute target
@@ -32,16 +40,16 @@
 #' @param custom_url_packages A character vector of packages to be installed
 #' from local directory or custom URL.
 #' @param custom_docker_image A string of the name of the Docker image from
-#' which the image to use for training will be built. If not set, a default
-#' CPU-based image will be used as the base image. To use an image from a
+#' which the image to use for training will be built. If not set, a predefined
+#' image will be used as the base image. To use an image from a
 #' private Docker repository, you will also have to specify the
 #' `image_registry_details` parameter.
 #' @param image_registry_details A `ContainerRegistry` object of the details of
 #' the Docker image registry for the custom Docker image.
 #' @param use_gpu Indicates whether the environment to run the experiment should
-#' support GPUs. If `TRUE`, a GPU-based default Docker image will be used in the
-#' environment. If `FALSE`, a CPU-based image will be used. Default Docker
-#' images (CPU or GPU) will only be used if the `custom_docker_image` parameter
+#' support GPUs. If `TRUE`, a predefined GPU-based Docker image will be used in the
+#' environment. If `FALSE`, a predefined CPU-based image will be used. Predefined
+#' Docker images (CPU or GPU) will only be used if the `custom_docker_image` parameter
 #' is not set.
 #' @param environment_variables A named list of environment variables names
 #' and values. These environment variables are set on the process where the user

diff --git a/R/model.R b/R/model.R
@@ -411,8 +411,7 @@ wait_for_model_package_creation <- function(package, show_output = FALSE) {
 #' environment does not have to be registered.
 #' @return The `InferenceConfig` object.
 #' @export
-#' @details
-#' \subsection{Defining the entry script}{
+#' @section Defining the entry script:
 #' To deploy a model, you must provide an entry script that accepts requests,
 #' scores the requests by using the model, and returns the results. The
 #' entry script is specific to your model. It must understand the format of
@@ -449,7 +448,6 @@ wait_for_model_package_creation <- function(package, show_output = FALSE) {
 #' ```
 #' model1_path <- file.path(Sys.getenv("AZUREML_MODEL_DIR"), "my_model/1/my_model.rds")
 #' ```
-#' }
 #' @seealso
 #' `r_environment()`, `deploy_model()`
 #' @md

diff --git a/misc/r-packages-docker.md b/misc/r-packages-docker.md
@@ -0,0 +1,151 @@
+## R packages
+List of R packages that are installed for predefined Docker image for training and deployment. These include the `r-essentials` bundle and additional commonly used packages. See [r_environment()](https://azure.github.io/azureml-sdk-for-r/reference/r_environment.html#predefined-docker-images) reference for more information.
+
+### R Essentials bundle
+The R Essentials bundle (3.6.0) from conda contains approximately 80 of the most popular R packages for data science. The following packages are included:
+
+| Dependency  | Version  |
+| ----------- | -------- |
+| assertthat  | 1.0      |
+| askpass     | 0.2.1    |
+| backports   | 1.1.4    |
+| base64enc   | 0.1-3    |
+| bh          | 1.69.0-1 |
+| boot        | 1.3-20   |
+| broom       | 0.5.2    |
+| callr       | 3.2.0    |
+| caret       | 6.0-83   |
+| cellranger  | 1.1.0    |
+| class       | 7.3-15   |
+| cli         | 1.1.0    |
+| clipr       | 0.6.0    |
+| cluster     | 2.0.8    |
+| codetools   | 0.2-16   |
+| colorspace  | 1.4-1    |
+| crayon      | 1.3.4    |
+| curl        | 3.3      |
+| data.table  | 1.12.2   |
+| dbi         | 1.0.0    |
+| dbplyr      | 1.4.0    |
+| dichromat   | 2.0-0    |
+| digest      | 0.6.18   |
+| dplyr       | 0.8.0.1  |
+| ellipsis    | 0.1.0    |
+| essentials  | 3.6.0    |
+| evaluate    | 0.13     |
+| fansi       | 0.4.0    |
+| forcats     | 0.4.0    |
+| foreach     | 1.4.4    |
+| foreign     | 0.8-71   |
+| formatr     | 1.6      |
+| fs          | 1.6      |
+| generics    | 0.0.2    |
+| ggplot2     | 3.1.1    |
+| glmnet      | 2.0-16   |
+| glue        | 1.3.1    |
+| gower       | 0.2.0    | 
+| gtable      | 0.3.0    |
+| haven       | 2.1.0    |
+| hexbin      | 1.27.2   |
+| highr       | 0.8      |
+| hms         | 0.4.2    |
+| htmltools   | 0.3.6    |
+| htmlwidgets | 1.3      |
+| httpuv      | 1.5.1    |
+| httr        | 1.4.0    |
+| ipred | 0.9-8 |
+| irdisplay | 0.7.0 |
+| irkernel | 0.8.15 |
+| iterators | 1.0.10 |
+| jsonlite | 1.6 |
+| kernsmooth | 2.23_15 |
+| knitr | 1.22 |
+| labeling | 0.3 |
+| later | 0.8.0 |
+| lattice | 0.20-38 |
+| lava | 1.6.5 |
+| lazyeval | 0.2.2 |
+| lubridate | 1.7.4 |
+| magrittr | 1.5 |
+| maps | 3.3.0 |
+| markdown | 0.9 |
+| mass | 7.3_51.3 |
+| matrix | 1.2_17 |
+| mgcv | 1.8_28 |
+| mime | 0.6 |
+| modelmetrics | 1.2.2 |
+| modelr | 0.1.4 |
+| munsell | 0.5.0 |
+| nlme | 3.1-139 |
+| nnet | 7.3-12 |
+| numderiv | 2016.8-1 |
+| openssl | 1.3 |
+| pbdzmq | 0.3-3 |
+| pillar | 1.3.1 |
+| pkgconfig | 2.0.2 |
+| plogr | 0.2.0 |
+| plyr | 1.8.4 |
+| prettyunits | 1.0.2 |
+| processx | 3.3.0 |
+| prodlim | 2018.04.18 |
+| progress | 1.2.0 |
+| promises | 1.0.1 |
+| ps | 1.3.0 |
+| purrr | 0.3.2 |
+| quantmod | 0.4-14 |
+| r6 | 2.4.0 |
+| randomforest | 4.6-14 |
+| rbokeh | 0.6.3 |
+| rcolorbrewer | 1.1-2 |
+| rcpp | 1.0.1 |
+| rcpproll | 0.3.0 |
+| readr | 1.3.1 |
+| readxl | 1.3.1 |
+| recipes | 0.1.5 |
+| recommended | 3.6.0 |
+| rematch | 1.0.1 |
+| repr | 0.19.2 |
+| reprex | 0.2.1 |
+| reshape2 | 1.4.3 |
+| rlang | 0.3.4 |
+| rmarkdown | 1.12 |
+| rpart | 4.1-15 |
+| rstudioapi | 0.10 |
+| rvest | 0.3.3 |
+| scales | 1.0.0 |
+| selectr | 0.4-1 |
+| shiny | 1.3.2 |
+| sourcetools | 0.1.7 |
+| spatial | 7.3-11 |
+| squarem | 2017.10-1 |
+| stringi | 1.4.3 |
+| stringr | 1.4.0 |
+| survival | 2.44-1.1 |
+| sys | 3.2 |
+| tibble | 2.1.1 |
+| tidyr | 0.8.3 |
+| tidyselect | 0.2.5 |
+| tidyverse | 1.2.1 |
+| timedate | 3043.102 |
+| tinytex | 0.12 |
+| ttr | 0.23-4 |
+| utf8 | 1.1.4 |
+| uuid | 0.1-2 |
+| viridislite | 0.3.0 |
+| whisker | 0.3-2 |
+| withr | 2.1.2 |
+| xfun | 0.6 |
+| xml2 | 1.2.0 |
+| xtable | 1.8-4 |
+| xts | 0.11-2 |
+| yaml | 2.2.0 |
+| zoo | 1.8-5
+
+### Additional R packages
+The following additional R packages from CRAN are also installed:
+
+| Dependency  | Version |
+| ----------- | ------- |
+| remotes     | latest  |
+| e1071       | latest  |
+| optparse    | latest  |