Some fixes for R API documentation (mlflow#1313)

Style and content updates for R API documentation in preparation for MLflow 1.0

CONTRIBUTING.rst

@@ -30,7 +30,9 @@ You can verify that ``npm`` is on the PATH by running ``npm -v``, and
 
 If contributing to MLflow's R APIs, install `R <https://cloud.r-project.org/>`_. For changes to R
 documentation, also install `pandoc <https://pandoc.org/installing.html>`_ 2.2.1 or above,
-verifying the version of your installation via ``pandoc --version``.
+verifying the version of your installation via ``pandoc --version``. If using Mac OSX, note that
+the homebrew installation of pandoc may be out of date - you can find newer pandoc versions at
+https://github.com/jgm/pandoc/releases.
 
 If contributing to MLflow's Java APIs or modifying Java documentation,
 install `Java <https://www.java.com/>`_ and `Apache Maven <https://maven.apache.org/download.cgi>`_.

docs/build-rdoc.sh

@@ -4,7 +4,12 @@ set -ex
 pushd ../mlflow/R/mlflow
 Rscript -e 'install.packages("devtools", repos = "https://cloud.r-project.org")'
 Rscript -e 'devtools::install_dev_deps(dependencies = TRUE)'
-Rscript -e 'install.packages("Rd2md", repos = "https://cloud.r-project.org")'
+# Install Rd2md from source as a temporary fix for the rendering of code examples, until
+# a release is published including the fixes in https://github.com/quantsch/Rd2md/issues/1
+# Note that this commit is equivalent to commit 6b48255 of Rd2md master
+# (https://github.com/quantsch/Rd2md/tree/6b4825579a2df8a22898316d93729384f92a756b)
+# with a single extra commit to fix rendering of \link tags between methods in R documentation.
+Rscript -e 'devtools::install_github("https://github.com/smurching/Rd2md", ref = "ac7b22bb")'
 Rscript -e 'install.packages("rmarkdown", repos = "https://cloud.r-project.org")'
 rm -rf man
 Rscript -e "roxygen2::roxygenise()"

docs/source/tutorial.rst

@@ -111,7 +111,7 @@ First, train a linear regression model that takes two hyperparameters: ``alpha``
 
     .. code-block:: R
 
-        mlflow_run(uri = "examples/r_wine", entry_point = "train.R", param_list = list(alpha = 0.1, lambda = 0.5))
+        mlflow_run(uri = "examples/r_wine", entry_point = "train.R", parameters = list(alpha = 0.1, lambda = 0.5))
 
     Each time you run the example, MLflow logs information about your experiment runs in the directory ``mlruns``.
 
@@ -235,7 +235,7 @@ Now that you have your training code, you can package it so that other data scie
 
       .. code-block:: r
 
-        mlflow_run("examples/r_wine", entry_point = "train.R", param_list = list(alpha = 0.2))
+        mlflow_run("examples/r_wine", entry_point = "train.R", parameters = list(alpha = 0.2))
 
       After running this command, MLflow runs your training code in a new R session.
 
@@ -244,7 +244,7 @@ Now that you have your training code, you can package it so that other data scie
       .. code-block:: r
 
         mlflow_restore_snapshot()
-        mlflow_run("examples/r_wine", entry_point = "train.R", param_list = list(alpha = 0.2))
+        mlflow_run("examples/r_wine", entry_point = "train.R", parameters = list(alpha = 0.2))
 
       You can also run a project directly from GitHub. This tutorial is duplicated in the https://github.com/rstudio/mlflow-example repository which you can run with:
 
@@ -253,7 +253,7 @@ Now that you have your training code, you can package it so that other data scie
         mlflow_run(
           "train.R",
           "https://github.com/rstudio/mlflow-example",
-          param_list = list(alpha = 0.2)
+          parameters = list(alpha = 0.2)
         )
 
 Serving the Model

mlflow/R/mlflow/.lintr

@@ -1 +1 @@
-linters: with_defaults(line_length_linter(120), closed_curly_linter = NULL, open_curly_linter = NULL, absolute_paths_linter = NULL, object_usage_linter = NULL, object_length_linter = NULL)
+linters: with_defaults(line_length_linter(120), closed_curly_linter = NULL, open_curly_linter = NULL, absolute_paths_linter = NULL, object_usage_linter = NULL, object_length_linter = NULL, commented_code_linter = NULL)

mlflow/R/mlflow/R/install.R

@@ -20,9 +20,10 @@ mlflow_maybe_create_conda_env <- function() {
 
 #' Install MLflow
 #'
-#' Installs MLflow for individual use.
+#' Installs auxiliary dependencies of MLflow (e.g. the MLflow CLI). As a one-time setup step, you
+#' must run install_mlflow() to install these dependencies before calling other MLflow APIs.
 #'
-#' MLflow requires Python and Conda to be installed.
+#' install_mlflow() requires Python and Conda to be installed.
 #' See \url{https://www.python.org/getit/} and \url{https://docs.conda.io/projects/conda/en/latest/user-guide/install/}.
 #'
 #' @examples

mlflow/R/mlflow/R/model.R

@@ -1,7 +1,7 @@
 #' Save Model for MLflow
 #'
-#' Saves model in MLflow format that can later be used
-#' for prediction and serving.
+#' Saves model in MLflow format that can later be used for prediction and serving. This method is
+#' generic to allow package authors to save custom model types.
 #'
 #' @param model The model that will perform a prediction.
 #' @param path Destination path where this MLflow compatible model
@@ -59,8 +59,8 @@ mlflow_write_model_spec <- function(path, content) {
 #'
 #' @template roxlate-model-uri
 #' @template roxlate-client
-#' @param flavor Optional flavor specification. Can be used to load a particular flavor in case
-#'        there are multiple flavors available.
+#' @param flavor Optional flavor specification (string). Can be used to load a particular flavor in
+#' case there are multiple flavors available.
 #' @export
 mlflow_load_model <- function(model_uri, flavor = NULL, client = mlflow_client()) {
   model_path <- mlflow_download_artifacts_from_uri(model_uri, client = client)
@@ -117,10 +117,13 @@ mlflow_flavor <- function(flavor) {
 
 #' Load MLflow Model Flavor
 #'
-#' Loads an MLflow model flavor, to be used by package authors
-#' to extend the supported MLflow models.
+#' Loads an MLflow model using a specific flavor. This method is called internally by
+#' \link[mlflow]{mlflow_load_model}, but is exposed for package authors to extend the supported
+#' MLflow models. See https://mlflow.org/docs/latest/models.html#storage-format for more
+#' info on MLflow model flavors.
 #'
-#' @param flavor An MLflow flavor object.
+#' @param flavor An MLflow flavor object loaded by \link[mlflow]{mlflow_load_model}, with class
+#' loaded from the flavor field in an MLmodel file.
 #' @param model_path The path to the MLflow model wrapped in the correct
 #'   class.
 #'

mlflow/R/mlflow/R/project-param.R

@@ -1,7 +1,28 @@
 #' Read Command-Line Parameter
 #'
-#' Reads a command-line parameter.
+#' Reads a command-line parameter passed to an MLflow project
+#' MLflow allows you to define named, typed input parameters to your R scripts via the mlflow_param
+#' API. This is useful for experimentation, e.g. tracking multiple invocations of the same script
+#' with different parameters.
 #'
+#' @examples
+#' \dontrun{
+#' # This parametrized script trains a GBM model on the Iris dataset and can be run as an MLflow
+#' # project. You can run this script (assuming it's saved at /some/directory/params_example.R)
+#' # with custom parameters via:
+#' # mlflow_run(entry_point = "params_example.R", uri = "/some/directory",
+#' #   parameters = list(num_trees = 200, learning_rate = 0.1))
+#' install.packages("gbm")
+#' library(mlflow)
+#' library(gbm)
+#' # define and read input parameters
+#' num_trees <- mlflow_param(name = "num_trees", default = 200, type = "integer")
+#' lr <- mlflow_param(name = "learning_rate", default = 0.1, type = "numeric")
+#' # use params to fit a model
+#' ir.adaboost <- gbm(Species ~., data=iris, n.trees=num_trees, shrinkage=lr)
+#' }
+#'
+
 #' @param name The name of the parameter.
 #' @param default The default value of the parameter.
 #' @param type Type of this parameter. Required if `default` is not set. If specified,

mlflow/R/mlflow/R/project-run.R

@@ -1,6 +1,26 @@
 #' Run an MLflow Project
 #'
-#' Wrapper for `mlflow run`.
+#' Wrapper for the `mlflow run` CLI command. See https://www.mlflow.org/docs/latest/cli.html#run
+#' for more info.
+#'
+#' @examples
+#' \dontrun{
+#' # This parametrized script trains a GBM model on the Iris dataset and can be run as an MLflow
+#' # project. You can run this script (assuming it's saved at /some/directory/params_example.R)
+#' # with custom parameters via:
+#' # mlflow_run(entry_point = "params_example.R", uri = "/some/directory",
+#' #   parameters = list(num_trees = 200, learning_rate = 0.1))
+#' install.packages("gbm")
+#' library(mlflow)
+#' library(gbm)
+#' # define and read input parameters
+#' num_trees <- mlflow_param(name = "num_trees", default = 200, type = "integer")
+#' lr <- mlflow_param(name = "learning_rate", default = 0.1, type = "numeric")
+#' # use params to fit a model
+#' ir.adaboost <- gbm(Species ~., data=iris, n.trees=num_trees, shrinkage=lr)
+#' }
+#'
+
 #'
 #' @param entry_point Entry point within project, defaults to `main` if not specified.
 #' @param uri A directory containing modeling scripts, defaults to the current directory.

mlflow/R/mlflow/R/tracking-client.R

@@ -126,6 +126,9 @@ new_mlflow_client.mlflow_https <- function(tracking_uri) {
 
 #' Initialize an MLflow Client
 #'
+#' Initializes and returns an MLflow client that communicates with the tracking server or store
+#' at the specified URI.
+#'
 #' @param tracking_uri The tracking URI. If not provided, defaults to the service
 #'  set by `mlflow_set_tracking_uri()`.
 #' @export

mlflow/R/mlflow/R/tracking-runs.R

@@ -61,6 +61,7 @@ mlflow_create_run <- function(start_time = NULL, tags = NULL, experiment_id = NU
 
 #' Delete a Run
 #'
+#' Deletes the run with the specified ID.
 #' @template roxlate-client
 #' @template roxlate-run-id
 #' @export
@@ -77,6 +78,7 @@ mlflow_delete_run <- function(run_id, client = NULL) {
 
 #' Restore a Run
 #'
+#' Restores the run with the specified ID.
 #' @template roxlate-client
 #' @template roxlate-run-id
 #' @export
@@ -358,7 +360,8 @@ mlflow_download_artifacts_from_uri <- function(artifact_uri, client = mlflow_cli
 
 #' List Run Infos
 #'
-#' List run infos.
+#' Returns a tibble whose columns contain run metadata (run ID, etc) for all runs under the
+#' specified experiment.
 #'
 #' @param experiment_id Experiment ID. Attempts to use the active experiment if not specified.
 #' @param run_view_type Run view type.
@@ -394,30 +397,8 @@ mlflow_list_run_infos <- function(run_view_type = c("ACTIVE_ONLY", "DELETED_ONLY
 #'
 #' @details
 #'
-#' When logging to Amazon S3, ensure that the user has a proper policy
-#' attached to it, for instance:
-#'
-#' \code{
-#' {
-#' "Version": "2012-10-17",
-#' "Statement": [
-#'   {
-#'     "Sid": "VisualEditor0",
-#'     "Effect": "Allow",
-#'     "Action": [
-#'       "s3:PutObject",
-#'       "s3:GetObject",
-#'       "s3:ListBucket",
-#'       "s3:GetBucketLocation"
-#'       ],
-#'     "Resource": [
-#'       "arn:aws:s3:::mlflow-test/*",
-#'       "arn:aws:s3:::mlflow-test"
-#'       ]
-#'   }
-#'   ]
-#' }
-#' }
+#' When logging to Amazon S3, ensure that you have the s3:PutObject, s3:GetObject,
+#' s3:ListBucket, and s3:GetBucketLocation permissions on your bucket.
 #'
 #' Additionally, at least the \code{AWS_ACCESS_KEY_ID} and \code{AWS_SECRET_ACCESS_KEY}
 #' environment variables must be set to the corresponding key and secrets provided
@@ -544,13 +525,14 @@ mlflow_get_run_context.default <- function(client, experiment_id, ...) {
 #'
 #' Terminates a run. Attempts to end the current active run if `run_id` is not specified.
 #'
-#' @param status Updated status of the run. Defaults to `FINISHED`.
+#' @param status Updated status of the run. Defaults to `FINISHED`. Can also be set to
+#' "FAILED" or "KILLED".
 #' @param end_time Unix timestamp of when the run ended in milliseconds.
 #' @template roxlate-run-id
 #' @template roxlate-client
 #'
 #' @export
-mlflow_end_run <- function(status = c("FINISHED", "SCHEDULED", "FAILED", "KILLED"),
+mlflow_end_run <- function(status = c("FINISHED", "FAILED", "KILLED"),
                            end_time = NULL, run_id = NULL, client = NULL) {
 
   status <- match.arg(status)

mlflow/R/mlflow/R/tracking-ui.R

@@ -22,20 +22,20 @@ mlflow_view_url <- function(url) {
 #' mlflow_ui()
 #' }
 #'
-#' @param x An `mlflow_client` object.
+#' @template roxlate-client
 #' @param ... Optional arguments passed to `mlflow_server()` when `x` is a path to a file store.
 #' @export
-mlflow_ui <- function(x, ...) {
+mlflow_ui <- function(client, ...) {
   UseMethod("mlflow_ui")
 }
 
 #' @export
-mlflow_ui.mlflow_client <- function(x, ...) {
-  mlflow_view_url(x$get_host_creds()$host)
+mlflow_ui.mlflow_client <- function(client, ...) {
+  mlflow_view_url(client$get_host_creds()$host)
 }
 
 #' @export
-mlflow_ui.NULL <- function(x, ...) {
+mlflow_ui.NULL <- function(client, ...) {
   client <- mlflow_client()
   mlflow_ui(client)
 }

mlflow/R/mlflow/document.R

@@ -18,7 +18,7 @@ markdown_fixed <- gsub("## Description", "", markdown_fixed)
 markdown_fixed <- gsub("## Usage", "", markdown_fixed)
 
 # Remove objects exported from other packages section
-last_section <- which(grepl("Objects exported from other packages", markdown_fixed))[[1]]
+last_section <- which(grepl("reexports", markdown_fixed))[[1]]
 markdown_fixed <- markdown_fixed[1:last_section - 1]
 
 # Write fixed markdown file
@@ -39,9 +39,9 @@ rst_header <- ".. _R-api:
 R API
 ========
 
-The MLflow R API allows you to use MLflow :doc:`Tracking <tracking/>`, :doc:`Projects <projects/>` and :doc:`Models <models/>`.
+The MLflow `R <https://www.r-project.org/about.html/>`_ API allows you to use MLflow :doc:`Tracking <tracking/>`, :doc:`Projects <projects/>` and :doc:`Models <models/>`.
 
-You can use the R API to `install MLflow`_, start the `user interface <Run MLflow user interface_>`_, `create <Create Experiment_>`_ and `list experiments <List Experiments_>`_, `save models <Save Model for MLflow_>`_, `run projects <Run in MLflow_>`_ and `serve models <Serve an RFunc MLflow Model_>`_ among many other functions available in the R API.
+You can use the R API to `install MLflow <install_mlflow_>`_, start the `user interface <mlflow_ui>`_, `create <mlflow_create_experiment>`_ and `list experiments <mlflow_list_experiments_>`_, `save models <mlflow_save_model>`_, `run projects <mlflow_run_>`_ and `serve models <mlflow_rfunc_serve_>`_ among many other functions available in the R API.
 
 .. contents:: Table of Contents
     :local:

mlflow/R/mlflow/man-roxygen/roxlate-client.R

@@ -1,2 +1,4 @@
-#' @param client (Optional) An `mlflow_client` object.
-#' @details When `client` is not specified, these functions attempt to infer the current active client.
+#' @param client (Optional) An MLflow client object returned from \link[mlflow]{mlflow_client}.
+#' If specified, MLflow will use the tracking server associated with the passed-in client. If
+#' unspecified (the common case),
+#' MLflow will use the tracking server associated with the current tracking URI.

mlflow/R/mlflow/man-roxygen/roxlate-model-uri.R

@@ -1,11 +1,12 @@
 #' @param model_uri The location, in URI format, of the MLflow model.
-#' @family artifact uri
 #' @details The URI scheme must be supported by MLflow - i.e. there has to be an MLflow artifact
 #'          repository corresponding to the scheme of the URI. The content is expected to point to a
 #'          directory containing MLmodel. The following are examples of valid model uris:
+#'
 #'                  - ``file:///absolute/path/to/local/model``
 #'                  - ``file:relative/path/to/local/model``
 #'                  - ``s3://my_bucket/path/to/model``
 #'                  - ``runs:/<mlflow_run_id>/run-relative/path/to/model``
-#'          For more information about supported URI schemes, see the Artifacts Documentation
-#'                  `<https://www.mlflow.org/docs/latest/tracking.html#supported-artifact-stores>`_.
+#'
+#'  For more information about supported URI schemes, see the Artifacts Documentation at
+#'  https://www.mlflow.org/docs/latest/tracking.html#supported-artifact-stores.