Merge pull request #10 from pachadotdev/issue8

reorganize srr comments

Author: pachadotdev

R/apes.R

@@ -11,6 +11,10 @@
 #'  \strong{Remark:} The routine currently does not allow to compute average
 #'  partial effects based on functional forms like interactions and polynomials.
 #'
+#' @srrstats {G2.3} *For univariate character input:*
+#' @srrstats {G2.3a} *Use `match.arg()` or equivalent where applicable to only permit expected values.*
+#' @srrstats {G2.3b} *Either: use `tolower()` or equivalent to ensure input of character parameters is not case dependent; or explicitly document that parameters are strictly case-sensitive.*
+#' 
 #' @param object an object of class \code{"bias_corr"} or \code{"feglm"};
 #'  currently restricted to \code{\link[stats]{binomial}}.
 #' @param n_pop unsigned integer indicating a finite population correction for
@@ -43,6 +47,8 @@
 #' @return The function \code{\link{apes}} returns a named list of class
 #'  \code{"apes"}.
 #'
+#' @srrstats {G1.0} *Statistical Software should list at least one primary reference from published academic literature.*
+#' 
 #' @references Cruz-Gonzalez, M., I. Fernández-Val, and M. Weidner (2017). "Bias
 #'  corrections for probit and logit models with two-way fixed effects". The
 #'  Stata Journal, 17(3), 517-545.

R/apes_bias_helpers.R

@@ -1,3 +1,9 @@
+#' @title Checks if the object is an `feglm` object
+#' @description Internal check
+#' @param object Object to check
+#' @param fun Function name (e.g., "apes")
+#' @srrstats {G1.4a} *All internal (non-exported) functions should also be documented in standard [`roxygen2`](https://roxygen2.r-lib.org/) format, along with a final `@noRd` tag to suppress automatic generation of `.Rd` files.*
+#' @noRd
 apes_bias_check_object_ <- function(object, fun) {
   if (is.null(object)) {
     stop("'object' has to be specified.", call. = FALSE)
@@ -12,6 +18,12 @@ apes_bias_check_object_ <- function(object, fun) {
   }
 }
 
+#' @title Checks if the `feglm` object is a binary choice model
+#' @description Internal check
+#' @param object Object to check
+#' @param fun Function name (e.g., "apes")
+#' @srrstats {G1.4a} *All internal (non-exported) functions should also be documented in standard [`roxygen2`](https://roxygen2.r-lib.org/) format, along with a final `@noRd` tag to suppress automatic generation of `.Rd` files.*
+#' @noRd
 apes_bias_check_binary_model_ <- function(family, fun) {
   if (family[["family"]] != "binomial") {
     stop(
@@ -21,6 +33,12 @@ apes_bias_check_binary_model_ <- function(family, fun) {
   }
 }
 
+#' @title Checks if the panel structure string is valid
+#' @description Internal check
+#' @param panel_structure Object to check
+#' @param k Number of fixed effects
+#' @srrstats {G1.4a} *All internal (non-exported) functions should also be documented in standard [`roxygen2`](https://roxygen2.r-lib.org/) format, along with a final `@noRd` tag to suppress automatic generation of `.Rd` files.*
+#' @noRd
 apes_bias_check_panel_ <- function(panel_structure, k) {
   if (panel_structure == "classic") {
     if (!(k %in% c(1L, 2L))) {

R/bias_corr.R

@@ -8,6 +8,10 @@
 #'  currently restricted to \code{\link[stats]{binomial}} with 1,2,3-way fixed
 #'  effects.
 #'
+#' @srrstats {G2.3} *For univariate character input:*
+#' @srrstats {G2.3a} *Use `match.arg()` or equivalent where applicable to only permit expected values.*
+#' @srrstats {G2.3b} *Either: use `tolower()` or equivalent to ensure input of character parameters is not case dependent; or explicitly document that parameters are strictly case-sensitive.*
+#' 
 #' @param object an object of class \code{"feglm"}.
 #' @param l unsigned integer indicating a bandwidth for the estimation of
 #'  spectral densities proposed by Hahn and Kuersteiner (2011). The default is
@@ -25,6 +29,8 @@
 #'
 #' @return A named list of classes \code{"bias_corr"} and \code{"feglm"}.
 #'
+#' @srrstats {G1.0} *Statistical Software should list at least one primary reference from published academic literature.*
+#' 
 #' @references Czarnowske, D. and A. Stammann (2020). "Fixed Effects Binary
 #'  Choice Models: Estimation and Inference with Long Panels". ArXiv e-prints.
 #' @references Fernández-Val, I. and M. Weidner (2016). "Individual and time

R/capybara-package.R

@@ -1,6 +1,10 @@
 #' @title Generalized Linear Models (GLMs) with high-dimensional k-way fixed
 #'  effects
 #'
+#' @srrstats {G1.1} *Statistical Software should document whether the algorithm(s) it implements are:* - *The first implementation of a novel algorithm*; or - *The first implementation within **R** of an algorithm which has previously been implemented in other languages or contexts*; or - *An improvement on other implementations of similar algorithms in **R***.
+#' @srrstats {G1.2} *Statistical Software should include a* Life Cycle Statement *describing current and anticipated future states of development.*
+#' @srrstats {G1.4} *Software should use [`roxygen2`](https://roxygen2.r-lib.org/) to document all functions.*
+#' 
 #' @description
 #' Provides a routine to partial out factors with many levels during the
 #' optimization of the log-likelihood function of the corresponding GLM. The
@@ -9,7 +13,11 @@
 #' post-estimation routine and includes robust and multi-way clustered standard
 #' errors. Further the package provides analytical bias corrections for binary
 #' choice models derived by Fernández-Val and Weidner (2016) and Hinz, Stammann,
-#' and Wanner (2020).
+#' and Wanner (2020). This package is a ground up rewrite with multiple
+#' refactors, optimizations, and new features compared to the original package
+#' `alpaca`. In its current state, the package is stable and future changes will
+#' be limited to bug fixes and improvements, but not to altering the functions'
+#' arguments or outputs.
 #'
 #' @name capybara-package
 #' @importFrom dplyr across all_of filter group_by mutate pull select summarise

R/feglm.R

@@ -8,6 +8,22 @@
 #' \strong{Remark:} The term fixed effect is used in econometrician's sense of
 #'  having intercepts for each level in each category.
 #'
+#' @srrstats {G2.3} *For univariate character input:*
+#' @srrstats {G2.3a} *Use `match.arg()` or equivalent where applicable to only permit expected values.*
+#' @srrstats {G2.3b} *Either: use `tolower()` or equivalent to ensure input of character parameters is not case dependent; or explicitly document that parameters are strictly case-sensitive.*
+#' @srrstats {RE4.4} *The specification of the model, generally as a formula (via `formula()`)*
+#' @srrstats {RE1.0} *Regression Software should enable models to be specified via a formula interface, unless reasons for not doing so are explicitly documented.*
+#' @srrstats {RE1.1} *Regression Software should document how formula interfaces are converted to matrix representations of input data.*
+#' @srrstats {RE1.2} *Regression Software should document expected format (types or classes) for inputting predictor variables, including descriptions of types or classes which are not accepted.*
+#' @srrstats {RE1.3} *Regression Software which passes or otherwise transforms aspects of input data onto output structures should ensure that those output structures retain all relevant aspects of input data, notably including row and column names, and potentially information from other `attributes()`.*
+#' @srrstats {RE1.3a} *Where otherwise relevant information is not transferred, this should be explicitly documented.*
+#' @srrstats {RE1.4} *Regression Software should document any assumptions made with regard to input data; for example distributional assumptions, or assumptions that predictor data have mean values of zero. Implications of violations of these assumptions should be both documented and tested.*
+#' @srrstats {RE2.3} *Where applicable, Regression Software should enable data to be centred (for example, through converting to zero-mean equivalent values; or to z-scores) or offset (for example, to zero-intercept equivalent values) via additional parameters, with the effects of any such parameters clearly documented and tested.*
+#' @srrstats {RE3.0} *Issue appropriate warnings or other diagnostic messages for models which fail to converge.*
+#' @srrstats {RE3.1} *Enable such messages to be optionally suppressed, yet should ensure that the resultant model object nevertheless includes sufficient data to identify lack of convergence.*
+#' @srrstats {RE3.2} *Ensure that convergence thresholds have sensible default values, demonstrated through explicit documentation.*
+#' @srrstats {RE3.3} *Allow explicit setting of convergence thresholds, unless reasons against doing so are explicitly documented.*
+#'
 #' @param formula an object of class \code{"formula"}: a symbolic description of
 #'  the model to be fitted. \code{formula} must be of type \code{y ~ x | k},
 #'  where the second part of the formula refers to factors to be concentrated
@@ -36,6 +52,9 @@
 #'  category. In this case, you should carefully inspect your model
 #'  specification.
 #'
+#' @srrstats {G1.3} *All statistical terminology should be clarified and unambiguously defined.*
+#' @srrstats {RE4.0} *Regression Software should return some form of "model" object, generally through using or modifying existing class structures for model objects (such as `lm`, `glm`, or model objects from other packages), or creating a new class of model objects.*
+#' 
 #' @return A named list of class \code{"feglm"}. The list contains the following
 #'  fifteen elements:
 #'  \item{coefficients}{a named vector of the estimated coefficients}
@@ -57,6 +76,8 @@
 #'  \item{family}{the family used in the model}
 #'  \item{control}{the control list used in the model}
 #'
+#' @srrstats {G1.0} *Statistical Software should list at least one primary reference from published academic literature.*
+#' 
 #' @references Gaure, S. (2013). "OLS with Multiple High Dimensional Category
 #'  Variables". Computational Statistics and Data Analysis, 66.
 #' @references Marschner, I. (2011). "glm2: Fitting generalized linear models