Minor changes in documentation

* Standardise examples across functions
* Fix a few typos
* Use dontrun for run_pioneer example

R/bootstrap-dea.R

@@ -3,17 +3,17 @@ NULL
 
 #' Bootstrap a DEA model
 #'
-#' Run bootstrap on a DEA model to estimate bias corrected efficiency scores and confidence
-#' intervals
+#' Run bootstrap on a DEA model to estimate bias corrected efficiency scores and
+#' confidence intervals.
 #'
-#' @param dea An object of class 'pioneer_dea' from `compute_dea()`
+#' @param dea An object of class 'pioneer_dea' from `compute_dea()`.
 #' @param alpha One minus the confidence level required. Default is 0.05.
-#' @param bw_rule A string with the type of bandwidth rule to be used, or a number with the
-#'   bandwidth parameter. See details.
-#' @param iterations Integer. The number of bootstrap iterations to perform. Default is 2000.
+#' @param bw_rule A string with the type of bandwidth rule to be used, or a number
+#'   with the bandwidth parameter. See details.
+#' @param iterations The number of bootstrap iterations to perform. Default is 2000.
 #'
 #' @details
-#' In order to bootstrap a DEA model, you must first create a DEA model object using the
+#' In order to bootstrap a DEA model, you must first create a model object using the
 #' `compute_dea()` function. Note that you currently can only bootstrap models using
 #' constant or variable returns to scale (RTS). If you try to bootstrap a model using another
 #' RTS, the bootstrap will fail with an error message.
@@ -22,23 +22,26 @@ NULL
 #' `silverman` for the Silverman rule, or `scott` for the Scott rule. If you provide a
 #' number, this will be used directly as the bandwidth parameter `h`. This can be useful
 #' to replicate results where `h` is given, such as Simar & Wilson (1998). For most practical
-#' applications of the bootstrap, the default of unbias cross validation is sensible.
+#' applications of the bootstrap, the default value of unbiased cross validation is sensible.
 #'
+#' @return A list of class `pioneer_bootstrap`.
 #' @examples
-#' # Get data
+#' # Load example data
 #' fare89 <- deaR::Electric_plants
 #' # Estimate efficiency
-#' mod <- compute_dea(fare89,
+#' mod <- compute_dea(
+#'   data = fare89,
 #'   input = c("Labor", "Fuel", "Capital"),
 #'   output = "Output",
 #'   id = "Plant",
 #' )
 #' # Run bootstrap. Reducing the number of iterations to save processing time
 #' boot <- bootstrap_dea(mod, iterations = 100)
-#'
-#' @return An object of class 'pioneer_bootstrap' containing bootstrap results.
+#' # Print results
+#' print(boot)
+#' # Get summary
+#' summary(boot)
 #' @seealso [compute_dea()]
-#'
 #' @export
 bootstrap_dea <- function(dea, alpha = 0.05, bw_rule = 'ucv', iterations = 2000) {
 

R/compute_dea.R

@@ -18,22 +18,25 @@
 #' @param super If `TRUE` super efficiency scores are calculated.
 #' @param slack If `TRUE` slack values are calculated.
 #' @param peers If `TRUE` peers are added to the response.
-#'
+#' @return A list of class `pioneer_dea`.
 #' @examples
-#' # Get data
+#' # Load example data
 #' fare89 <- deaR::Electric_plants
 #' # Estimate efficiency
-#' mod <- compute_dea(fare89,
+#' mod <- compute_dea(
+#'   data = fare89,
 #'   input = c("Labor", "Fuel", "Capital"),
 #'   output = "Output",
 #'   id = "Plant",
 #'   rts = "vrs",
 #'   orientation = "in"
 #' )
-#' # Print the results
+#' # Print results
 #' print(mod)
-#'
-#' @return A list of class `pioneer_dea`
+#' # Get summary
+#' summary(mod)
+#' # Convert to data frame
+#' df <- as.data.frame(mod)
 #' @export
 compute_dea <- function(
     data,

R/compute_malmquist.R

@@ -17,12 +17,18 @@
 #' @param time A string with the time period variable.
 #' @return A list of class `pioneer_mlm`
 #' @examples
+#' # Load example data
 #' chnEconomy <- deaR::EconomyLong
 #' # Estimate Malmquist
 #' mod <- compute_malmquist(
-#'   data = chnEconomy, id = 'DMUs', time = 'Period',
-#'   input = c('Labor', 'Capital'), output = 'GIOV',
+#'   data = chnEconomy,
+#'   id = 'DMUs',
+#'   time = 'Period',
+#'   input = c('Labor', 'Capital'),
+#'   output = 'GIOV',
 #'   orientation = 'in')
+#' # Print results
+#' print(mod)
 #' # Get summary
 #' summary(mod)
 #' # Convert to data frame

R/dea-utils.R

@@ -44,17 +44,17 @@ create_matrix <- function(df, columns, id, normalize = FALSE) {
 #' @param digits An integer with the number of digits to round to. If `NULL` the
 #'   values are kept unrounded.
 #'
+#' @return A data frame containing the efficiency scores for CRS, VRS, the
+#'   Scale Efficiency, the VRS to NIRS ratio, and a recommendation on whether to
+#'   increase or decrease the size of the DMU.
+#'
 #' @examples
 #' # Create matrices with random values
 #' inputs <- matrix(runif(10, 1, 10), ncol = 2)
 #' outputs <- matrix(runif(10, 1, 10), ncol = 2)
 #' # Compute scale efficiency
-#' compute_scale_efficiency(inputs, outputs, orientation = 'out', digits = 2)
-#'
-#' @return A data frame containing the efficiency scores for CRS, VRS, the
-#'   Scale Efficiency, the VRS to NIRS ratio, and a recommendation on whether to
-#'   increase or decrease the size of the DMU.
-#'
+#' res <- compute_scale_efficiency(
+#'   inputs, outputs, orientation = 'out', digits = 2)
 #' @export
 compute_scale_efficiency <- function(
     x,

R/shiny-functions.R

@@ -27,7 +27,7 @@ pioneer_scripts <- function() {
 #'
 #' @param x A data frame that should be loaded with the app. See details.
 #' @param port Integer. The TCP port that the application should listen on.
-#' @param ... Other arguments to send to \code{\link[shiny]{runApp}}
+#' @param ... Other arguments to send to [shiny::runApp()].
 #'
 #' @details
 #' Note that pioneeR must be loaded into the namespace with `library(pioneeR)`
@@ -37,18 +37,20 @@ pioneer_scripts <- function() {
 #' a data frame or a character string with the object name of the data frame you
 #' want to be loaded when the app launches. Note that you should only use data
 #' frame objects. If you have a tibble (from the tidyverse) or a data table, you
-#' can convert to an ordinary data.frame using \code{\link[base]{as.data.frame}}.
+#' can convert to an ordinary data.frame using [as.data.frame()]
 #'
+#' @return None
 #' @examples
-#' # Only run this example in interactive R sessions
-#' if (interactive()) {
-#'   df = deaR::Electric_plants
-#'   # Load app with data.frame and set port to 8080
-#'   run_pioneer(x = df, port = 8080)
+#' \dontrun{
+#' # Load example data
+#' df = deaR::Electric_plants
+#' # Load the app (with a random port)
+#' run_pioneer()
+#' # Set a specific port number
+#' run_pioneer(port = 8080)
+#' # Load app with a specified dataset
+#' run_pioneer(x = df, port = 8080)
 #' }
-#'
-#' @return None
-#'
 #' @export
 run_pioneer <- function(x = NULL, port = NULL, ...) {
 
@@ -72,11 +74,9 @@ run_pioneer <- function(x = NULL, port = NULL, ...) {
 #'
 #' Unsets the environment variables set by pioneeR
 #'
+#' @return A logical vector, with elements being `TRUE` if unsetting the variable succeeded
 #' @examples
 #' unset_env_vars()
-#'
-#' @return A logical vector, with elements being true if unsetting the variable succeeded
-#'
 #' @export
 unset_env_vars <- \() Sys.unsetenv('PIONEER_DATA')
 

R/summary-dea.R

@@ -4,31 +4,29 @@
 #'
 #' @details
 #' The function will return a summary table for efficiency scores from a DEA model.
-#' Efficiency scores will be placed in 11 bins, where DMUs with an effciency score
+#' Efficiency scores will be placed in 11 bins, where DMUs with an efficiency score
 #' equal to 1 are placed in a separate bin. For output oriented models with range
 #' \[1, Inf\], bins are created with `1/bin`. Bin widths will be equal to models
 #' with range \[0, 1\].
 #'
 #' @param x A numeric vector of efficiency scores or an object of class `pioneer_dea`
 #'
+#' @return A [data.frame()] with summary statistics
 #' @examples
 #' # Load example data
-#' df <- deaR::Electric_plants
-#' # Compute efficiency scores
-#' prod <- compute_dea(
-#'   df,
+#' fare89 <- deaR::Electric_plants
+#' # Estimate efficiency
+#' mod <- compute_dea(
+#'   data = fare89,
 #'   input = c("Labor", "Fuel", "Capital"),
 #'   output = "Output",
 #'   rts = "vrs"
 #' )
 #' # Get a summary table of efficiency scores
-#' summary_tbl_dea(prod)
+#' summary_tbl_dea(mod)
 #' # You can also create the table from a numeric vector of efficiency scores
-#' res <- as.data.frame(prod)
+#' res <- as.data.frame(mod)
 #' summary_tbl_dea(res$efficiency)
-#'
-#' @return A [data.frame()] with summary statistics
-#'
 #' @export
 summary_tbl_dea <- function(x) {
   UseMethod("summary_tbl_dea")