Fix submission comments

Author: kkbrum

DESCRIPTION

@@ -9,8 +9,8 @@ Description: Natural strata fix a constant ratio of controls to treated units wi
     each stratum. This ratio need not be an integer. The control units are 
     chosen using randomized rounding of a linear program that balances many 
     covariates.
-    To solve the linear program, the Gurobi commercial optimization software 
-    is recommended, but not required. The gurobi R package can be installed following the instructions 
+    To solve the linear program, the 'Gurobi' commercial optimization software 
+    is recommended, but not required. The 'gurobi' R package can be installed following the instructions 
     at <https://www.gurobi.com/documentation/9.1/refman/ins_the_r_package.html>.
 URL: https://github.com/kkbrum/natstrat, https://kkbrum.github.io/natstrat/, https://www.gurobi.com/documentation/9.1/refman/ins_the_r_package.html
 BugReports: https://github.com/kkbrum/natstrat/issues

R/balance_LP.R

@@ -8,12 +8,22 @@
 #' @param st_vals the unique stratum levels contained in \code{st}.
 #' @param S the number of unique stratum levels contained in \code{st}.
 #' @param N the total number of available controls in the data.
+#'
+#' @return A list containing two elements:
+#' \describe{
+#' \item{\code{lpdetails}}{The output of either \code{gurobi()} or \code{\link[Rglpk]{Rglpk_solve_LP}()},
+#' except that if \code{gurobi()} is used, the elements \code{objval} and \code{x}
+#' are renamed \code{optimum} and \code{solution}
+#' to be consistent with the output of \code{\link[Rglpk]{Rglpk_solve_LP}()}.}
+#' \item{\code{o}}{The original output of either \code{gurobi()} or \code{\link[Rglpk]{Rglpk_solve_LP}()}.}
+#' }
+#'
 #' @keywords internal
 
 balance_LP <- function(z, X, importances, st, st_vals, S, q_s, N,
                        solver, integer, time_limit) {
   if (solver == "gurobi" && !requireNamespace("gurobi", quietly = TRUE)) {
-    stop("Package \"gurobi\" needed if \"solver\" parameter set to \"gurobi\". Please
+    stop("Package \'gurobi\' needed if \"solver\" parameter set to \"gurobi\". Please
          install it or switch the \"solver\" parameter to \"Rglpk\".",
          call. = FALSE)
   }

R/generate_qs.R

@@ -105,11 +105,15 @@ generate_qs <- function(z, st, ratio = NULL,
 
 #' Verify the inputs to the earthmover's distance problem
 #'
-#' Check that the ratio, strata, and treated indicator provided
+#' Check that the ratio, strata, and treated indicator provided to \code{\link{generate_qs}()}
 #' are in the correct forms and that the desired ratio is feasible
 #' across the population.
 #'
 #' @inheritParams generate_qs
+#'
+#' @return No return value. If there is a problem with the inputs to \code{\link{generate_qs}()},
+#' an error is raised.
+#'
 #' @keywords internal
 
 

R/natstrat-package.R

@@ -3,8 +3,8 @@
 #' each stratum. This ratio need not be an integer. The control units are
 #' chosen using randomized rounding of a linear program that balances many
 #' covariates.
-#' To solve the linear program, the Gurobi commercial optimization software
-#' is recommended, but not required. The gurobi R package can be installed following
+#' To solve the linear program, the 'Gurobi' commercial optimization software
+#' is recommended, but not required. The 'gurobi' R package can be installed following
 #' the instructions \href{https://www.gurobi.com/documentation/9.1/refman/ins_the_r_package.html}{here}.
 #'
 #' @details

R/optimize_controls.R

@@ -23,8 +23,8 @@
 #' @param integer a logical stating whether to use a mixed integer programming solver
 #'   instead of randomized rounding. Default is \code{FALSE}.
 #' @param solver a character stating which solver to use to run the linear program.
-#'   Options are "Rglpk" (default) or "gurobi". You must have gurobi installed to use "gurobi".
-#'   If gurobi is available, this is the recommended solver.
+#'   Options are "Rglpk" (default) or "gurobi". You must have the 'gurobi' package
+#'   installed to use the "gurobi" option. If available, this is the recommended solver.
 #' @param seed the seed to use when doing the randomized rounding of the linear program.
 #'   This will allow results to be reproduced if desired. The default is \code{NULL},
 #'   which will choose a random seed to use and return.
@@ -67,7 +67,7 @@
 #'   not scaled by constraint importances.}
 #'   }}
 #'   \item{\code{lpdetails}}{the full return of the function \code{\link[Rglpk]{Rglpk_solve_LP}()}
-#'     or gurobi plus information about the epsilons and objective values
+#'     or \code{gurobi()} plus information about the epsilons and objective values
 #'     for the linear program solution.}
 #' }
 #'
@@ -280,12 +280,16 @@ optimize_controls <- function(z, X, st, importances = NULL,
   }
 }
 
-#' Verify the inputs to \code{\link{optimize_controls}}
+#' Verify the inputs to \code{\link{optimize_controls}()}
 #'
-#' Makes sure that the inputs to \code{\link{optimize_controls}} are in the correct
+#' Makes sure that the inputs to \code{\link{optimize_controls}()} are in the correct
 #' format and feasible.
 #'
 #' @inheritParams optimize_controls
+#'
+#' @return No return value. If there is a problem with the inputs to \code{\link{optimize_controls}()},
+#' an error is raised.
+#'
 #' @keywords internal
 
 verify_inputs <- function(X, importances, ratio, q_s, st, z, integer, solver) {
@@ -305,7 +309,7 @@ verify_inputs <- function(X, importances, ratio, q_s, st, z, integer, solver) {
          call. = FALSE)
   }
   if (solver == "gurobi" && !requireNamespace("gurobi", quietly = TRUE)) {
-    stop("Package \"gurobi\" needed if \"solver\" parameter set to \"gurobi\". Please
+    stop("Package \'gurobi\' needed if \"solver\" parameter set to \"gurobi\". Please
          install it or switch the \"solver\" parameter to \"Rglpk\".",
          call. = FALSE)
   }

R/presolve_EMD.R

@@ -10,6 +10,10 @@
 #' @param max_s a vector containing the maximum number of controls that should
 #' be selected in each stratum. The order of the strata should match that of \code{desired_qs}.
 #' @param strata_dist_flat a flattened distance matrix between the strata.
+#'
+#' @return A named vector with names identical to those of \code{desired_qs} and
+#' elements containing the number of controls to select from the given stratum.
+#'
 #' @keywords internal
 
 presolve_EMD <- function(S, desired_qs, max_s, strata_dist_flat) {

cran-comments.md

@@ -1,3 +1,12 @@
+## Resubmission
+This is a resubmission. In this version I have:
+
+* Written all package names and software names in single quotes.
+
+* I did not add references describing the methods in my package as they are not available yet.
+
+* Return values are described in the documentation for balance_LP(), presolve_EMD(), verify_inputs_EMD(), and verify_inputs().
+
 ## Test environments
 * local windows install, R 4.0.3
 * ubuntu-20.04 release (on github actions)