Add docstrings to R Client

R/rdeephaven/NAMESPACE

@@ -7,7 +7,6 @@ S3method(as_tibble,TableHandle)
 S3method(dim,TableHandle)
 S3method(head,TableHandle)
 S3method(tail,TableHandle)
-export(Aggregation)
 export(Client)
 export(TableHandle)
 export(agg_abs_sum)
@@ -33,4 +32,4 @@ importFrom(arrow,as_arrow_table)
 importFrom(arrow,as_record_batch_reader)
 importFrom(dplyr,as_data_frame)
 importFrom(dplyr,as_tibble)
-useDynLib(rdeephaven, .registration = TRUE)
+useDynLib(rdeephaven, .registration = TRUE)

R/rdeephaven/R/aggregate_wrapper.R

@@ -1,3 +1,6 @@
+#' @description
+#' An Aggregation represents an aggregation operation that can be passed to `agg_by()` or `agg_all_by()`.
+#' Note that Aggregations should not be instantiated directly by user code, but rather by provided agg_* functions.
 Aggregation <- R6Class("Aggregation",
  cloneable = FALSE,
  public = list(
@@ -17,69 +20,150 @@ Aggregation <- R6Class("Aggregation",
 
 ### All of the functions below return an instance of the above class
 
+#' @description
+#' Creates a First aggregation that computes the first value of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_first <- function(cols = character()) {
  verify_string("cols", cols, FALSE)
  return(Aggregation$new(INTERNAL_agg_first, "agg_first", cols=cols))
 }
 
+#' @description
+#' Creates a Last aggregation that computes the last value of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_last <- function(cols = character()) {
  verify_string("cols", cols, FALSE)
  return(Aggregation$new(INTERNAL_agg_last, "agg_last", cols=cols))
 }
 
+#' @description
+#' Creates a Minimum aggregation that computes the minimum of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_min <- function(cols = character()) {
  verify_string("cols", cols, FALSE)
  return(Aggregation$new(INTERNAL_agg_min, "agg_min", cols=cols))
 }
 
+#' @description
+#' Creates a Maximum aggregation that computes the maximum of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_max <- function(cols = character()) {
  verify_string("cols", cols, FALSE)
  return(Aggregation$new(INTERNAL_agg_max, "agg_max", cols=cols))
 }
 
+#' @description
+#' Creates a Sum aggregation that computes the sum of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_sum <- function(cols = character()) {
  verify_string("cols", cols, FALSE)
  return(Aggregation$new(INTERNAL_agg_sum, "agg_sum", cols=cols))
 }
 
+#' @description
+#' Creates an Absolute Sum aggregation that computes the sum of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_abs_sum <- function(cols = character()) {
  verify_string("cols", cols, FALSE)
  return(Aggregation$new(INTERNAL_agg_abs_sum, "agg_abs_sum", cols=cols))
 }
 
+#' @description
+#' Creates an Average aggregation that computes the average of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_avg <- function(cols = character()) {
  verify_string("cols", cols, FALSE)
  return(Aggregation$new(INTERNAL_agg_avg, "agg_avg", cols=cols))
 }
 
+#' @description
+#' Creates a Weighted Average aggregation that computes the weighted average of each column in `cols` for each aggregation group.
+#' @param wcol String denoting the column to use for weights. This must be a numeric column.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_w_avg <- function(wcol, cols = character()) {
  verify_string("wcol", wcol, TRUE)
  verify_string("cols", cols, FALSE)
  return(Aggregation$new(INTERNAL_agg_w_avg, "agg_w_avg", wcol=wcol, cols=cols))
 }
 
+#' @description
+#' Creates a Median aggregation that computes the median of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_median <- function(cols = character()) {
  verify_string("cols", cols, FALSE)
  return(Aggregation$new(INTERNAL_agg_median, "agg_median", cols=cols))
 }
 
+#' @description
+#' Creates a Variance aggregation that computes the variance of each column in `cols` for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_var <- function(cols = character()) {
  verify_string("cols", cols, FALSE)
  return(Aggregation$new(INTERNAL_agg_var, "agg_var", cols=cols))
 }
 
+#' @description
+#' Creates a Standard Deviation aggregation that computes the standard deviation of each column in `cols`, for each aggregation group.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_std <- function(cols = character()) {
  verify_string("cols", cols, FALSE)
  return(Aggregation$new(INTERNAL_agg_std, "agg_std", cols=cols))
 }
 
+#' @description
+#' Creates a Percentile aggregation that computes the given percentile of each column in `cols` for each aggregation group.
+#' @param percentile Numeric scalar between 0 and 1 denoting the percentile to compute.
+#' @param cols String or list of strings denoting the column(s) to aggregate. Can be renaming expressions, i.e. “new_col = col”.
+#' Default is to aggregate all non-grouping columns, which is only valid in the `agg_all_by()` operation.
+#' @return Aggregation function to be used in `agg_by()` or `agg_all_by()`.
+#' @export
 agg_percentile <- function(percentile, cols = character()) {
  verify_in_unit_interval("percentile", percentile, TRUE)
  verify_string("cols", cols, FALSE)
  return(Aggregation$new(INTERNAL_agg_percentile, "agg_percentile", percentile=percentile, cols=cols))
 }
 
-agg_count <- function(col) {
+#' @description
+#' Creates a Count aggregation that counts the number of rows in each aggregation group.
+#' Note that this operation is not supported in `agg_all_by()`.
+#' @param col String denoting the name of the new column to hold the counts of each aggregation group.
+#' Defaults to "n".
+#' @return Aggregation function to be used in `agg_by()`.
+#' @export
+agg_count <- function(col = "n") {
  verify_string("col", col, TRUE)
  return(Aggregation$new(INTERNAL_agg_count, "agg_count", col=col))
 }

R/rdeephaven/R/client_wrapper.R

@@ -1,8 +1,18 @@
+#' @description
+#' A Client is the entry point for interacting with the Deephaven server. It is used to create new tables,
+#' import data to and from the server, and run scripts on the server.
 #' @export
 Client <- R6Class("Client",
  cloneable = FALSE,
  public = list(
  .internal_rcpp_object = NULL,
+
+ #' @description
+ #' Initializes a Client object that connects to the Deephaven server.
+ #' This method can accept either a string or an Rcpp::XPtr object, and will call
+ #' `initialize_for_target` or `initialize_for_xptr` accordingly.
+ #' @param ... String denoting the address of a running Deephaven server, formatted as `"ip:port"`,
+ #' or an Rcpp::XPtr object that points to an existing client connection.
  initialize = function(...) {
  args <- list(...)
  if (length(args) == 1) {
@@ -19,10 +29,41 @@ Client <- R6Class("Client",
  }
  return(do.call(self$initialize_for_target, args))
  },
+
+ #' @description
+ #' Initialize a Client object using a pointer to an existing client connection.
+ #' @param xptr External pointer to an existing client connection.
  initialize_for_xptr = function(xptr) {
  verify_type("xptr", xptr, "externalptr", "XPtr", TRUE)
  self$.internal_rcpp_object = new(INTERNAL_Client, xptr)
  },
+
+ #' @description
+ #' Initializes a Client object that connects to a Deephaven server
+ #' @param target String denoting the address of a Deephaven server, formatted as `"ip:port"`.
+ #' @param auth_type String denoting the authentication type. Can be `"anonymous"`, `"basic"`,
+ #' or any custom-built authenticator supported by the server, such as `"io.deephaven.authentication.psk.PskAuthenticationHandler"`.
+ #' Default is `anonymous`.
+ #' @param username String denoting the username, which only applies if `auth_type` is `basic`.
+ #' Username and password should not be used in conjunction with `auth_token`. Defaults to an empty string.
+ #' @param password String denoting the password, which only applies if `auth_type` is `basic`.
+ #' Username and password should not be used in conjunction with `auth_token`. Defaults to an empty string.
+ #' @param auth_token String denoting the authentication token. When `auth_type`
+ #' is `anonymous`, it will be ignored; when `auth_type` is `basic`, it must be
+ #' `"user:password"` or left blank; when `auth_type` is a custom-built authenticator, it must
+ #' conform to the specific requirement of that authenticator. This should not be used
+ #' in conjunction with `username` and `password`. Defaults to an empty string.
+ #' @param session_type String denoting the session type supported on the server.
+ #' Currently, `python` and `groovy` are supported. Defaults to `python`.
+ #' @param use_tls Whether or not to use a TLS connection. Defaults to `FALSE`.
+ #' @param tls_root_certs String denoting PEM encoded root certificates to use for TLS connection,
+ #' or `""` to use system defaults. Only used if `use_tls == TRUE`. Defaults to system defaults.
+ #' @param int_options List of name-value pairs for int-valued options to the underlying
+ #' grpc channel creation. Defaults to an empty list, which implies not using any channel options.
+ #' @param string_options List of name-value pairs for string-valued options to the underlying
+ #' grpc channel creation. Defaults to an empty list, which implies not using any channel options.
+ #' @param extra_headers List of name-value pairs for additional headers and values
+ #' to add to server requests. Defaults to an empty list, which implies not using any extra headers.
  initialize_for_target = function(
  target,
  auth_type = "anonymous",
@@ -138,22 +179,46 @@ Client <- R6Class("Client",
  client_options = options
  )
  },
+
+ #' @description
+ #' Creates an empty table on the server with 'size' rows and no columns.
+ #' @param size Non-negative integer specifying the number of rows for the new table.
+ #' @return TableHandle reference to the new table.
  empty_table = function(size) {
  verify_nonnegative_int("size", size, TRUE)
  return(TableHandle$new(self$.internal_rcpp_object$empty_table(size)))
  },
+
+ #' @description
+ #' Creates a ticking table on the server.
+ #' @param period ISO-8601-formatted string specifying the update frequency of the new table.
+ #' @param start_time Optional ISO-8601-formatted string specifying the start time of the table.
+ #' Defaults to now.
+ #' @return TableHandle reference to the new table.
  time_table = function(period, start_time = "now") {
  verify_string("period", period, TRUE)
  verify_string("start_time", start_time, TRUE)
  return(TableHandle$new(self$.internal_rcpp_object$time_table(period, start_time)))
  },
+
+ #' @description
+ #' Opens a table named `name` from the server if it exists.
+ #' @param name String denoting the name of the table to open from the server.
+ #' @return TableHandle reference to the requested table.
  open_table = function(name) {
  verify_string("name", name, TRUE)
  if (!private$check_for_table(name)) {
  stop(paste0("The table '", name, "' does not exist on the server."))
  }
  return(TableHandle$new(self$.internal_rcpp_object$open_table(name)))
  },
+
+ #' @description
+ #' Imports a new table to the Deephaven server. Note that this new table is not automatically bound to
+ #' a variable name on the server. See `?TableHandle` for more information.
+ #' @param table_object R Data Frame, a dplyr Tibble, an Arrow Table, or an Arrow RecordBatchReader
+ #' containing the data to import to the server.
+ #' @return TableHandle reference to the new table.
  import_table = function(table_object) {
  table_object_class <- class(table_object)
  if (table_object_class[[1]] == "data.frame") {
@@ -170,14 +235,27 @@ Client <- R6Class("Client",
  stop(paste0("'table_object' must be a single data frame, tibble, arrow table, or record batch reader. Got an object of class ", table_object_class[[1]], "."))
  }
  },
+
+ #' @description
+ #' Uses an existing ticket to create a new table on the server.
+ #' @param ticket String denoting the ticket to use to create the new table.
+ #' @return TableHandle reference to the new table.
  ticket_to_table = function(ticket) {
  verify_string("ticket", ticket, TRUE)
  return(TableHandle$new(self$.internal_rcpp_object$make_table_handle_from_ticket(ticket)))
  },
+
+ #' @description
+ #' Runs a script on the server. The script must be in the language that the server console was started with.
+ #' @param script String containing the code to be executed on the server.
  run_script = function(script) {
  verify_string("script", script, TRUE)
  self$.internal_rcpp_object$run_script(script)
  },
+
+ #' @description
+ #' Closes the client connection. After this method is called, any further server calls will
+ #' be undefined and will likely result in an error.
  close = function() {
  self$.internal_rcpp_object$close()
  }