Add return documentation for all functions

R/data-documentation.R

@@ -48,15 +48,17 @@
 #' dat <-
 #'     data.frame(party = as.character(docvars(data_corpus_dailnoconf1991, "party")),
 #'                govt = coef(pred)[, "Govt"],
-#'                position = as.character(docvars(data_corpus_dailnoconf1991, "position")),
-#'                stringsAsFactors = FALSE)
+#'                position = as.character(docvars(data_corpus_dailnoconf1991, "position")))
 #' bymedian <- with(dat, reorder(paste(party, position), govt, median))
-#' par(mar = c(5, 6, 4, 2)+.1)
+#' oldpar <- par(no.readonly = TRUE)
+#' par(mar = c(5, 6, 4, 2) + .1)
 #' boxplot(govt ~ bymedian, data = dat,
 #'         horizontal = TRUE, las = 1,
-#'         xlab = "Degree of support for government")
+#'         xlab = "Degree of support for government",
+#'         ylab = "")
 #' abline(h = 7.5, col = "red", lty = "dashed")
 #' text(c(0.9, 0.9), c(8.5, 6.5), c("Goverment", "Opposition"))
+#' par(oldpar)
 #' }
 "data_corpus_dailnoconf1991"
 

R/textmodel-methods.R

@@ -27,8 +27,11 @@ print.summary.textmodel <- function(x, digits = max(3L, getOption("digits") - 3L
 }
 
 #' Assign the summary.textmodel class to a list
+#' 
+#' Assigns the class `summary.textmodel` to a list
 #' @param x a named list
 #' @keywords internal
+#' @returns an object of class `summary.textmodel`
 #' @export
 as.summary.textmodel <- function(x) {
     class(x) <- c("summary.textmodel", "list")
@@ -61,7 +64,7 @@ as.summary.textmodel <- function(x) {
 # }
 
 #' Print methods for textmodel features estimates
-
+#' 
 #' This is a helper function used in `print.summary.textmodel`.
 #' @param x a coefficients_textmodel object
 #' @param digits minimal number of *significant digits*, see
@@ -83,12 +86,13 @@ print.coefficients_textmodel <- function(x, digits = max(3L, getOption("digits")
 }
 
 #' Coerce various objects to coefficients_textmodel
-
-#' This is a helper function used in `summary.textmodel_*`.
+#'
+#' Helper functions used in `summary.textmodel_*()`.
 #' @param x an object to be coerced
 #' @importFrom stats coefficients
 #' @importFrom stats coef
 #' @keywords internal
+#' @returns an object with the class tag of `coefficients_textmodel`
 #' @export
 as.coefficients_textmodel <- function(x) {
     UseMethod('as.coefficients_textmodel')
@@ -138,6 +142,7 @@ print.statistics_textmodel <- function(x, digits = max(3L, getOption("digits") -
 #' This is a helper function used in `summary.textmodel_*`.
 #' @param x an object to be coerced
 #' @keywords internal textmodel
+#' @returns an object of class `statistics_textmodel`
 #' @export
 as.statistics_textmodel <- function(x) {
     UseMethod("as.statistics_textmodel")

R/textmodel_affinity.R

@@ -1,6 +1,6 @@
 #' Class affinity maximum likelihood text scaling model
 #'
-#' `textmodel_affinity` implements the maximum likelihood supervised text
+#' `textmodel_affinity()` implements the maximum likelihood supervised text
 #' scaling method described in Perry and Benoit (2017).
 #' @param x the [dfm] or [bootstrap_dfm] object on which the model
 #'   will be fit.  Does not need to contain only the training documents, since
@@ -14,6 +14,15 @@
 #'   defaults to 0.5
 #' @param verbose logical; if `TRUE` print diagnostic information during
 #'   fitting.
+#' @returns A `textmodel_affinity` class list object, with elements:
+#' * `smooth` a numeric vector of length two for the smoothing parameters `smooth`
+#'   and `ref_smooth`
+#' `x` the input model matrix `x`
+#' `y` the vector of class training labels `y`
+#' `p` a feature \eqn{\times} class sparse matrix of estimated class affinities
+#' * `support` logical vector indicating whether a feature was included in computing
+#'   class affinities
+#' * `call` the model call
 #' @author Patrick Perry and Kenneth Benoit
 #' @references Perry, P.O. & Benoit, K.R. (2017). Scaling Text with
 #'   the Class Affinity Model.
@@ -34,7 +43,7 @@
 #' @importFrom stats sd predict
 #' @importFrom quanteda dfm_group as.dfm
 #' @seealso [predict.textmodel_affinity()] for methods of applying a
-#'   fitted [textmodel_affinity] model object to predict quantities from
+#'   fitted [textmodel_affinity()] model object to predict quantities from
 #'   (other) documents.
 textmodel_affinity <- function(x, y, exclude = NULL,
                                smooth = 0.5, ref_smooth = 0.5,
@@ -46,7 +55,7 @@ textmodel_affinity <- function(x, y, exclude = NULL,
 textmodel_affinity.default <- function(x, y, exclude = NULL,
                                        smooth = 0.5, ref_smooth = 0.5,
                                        verbose = quanteda_options("verbose")) {
-    stop(friendly_class_undefined_message(class(x), "textmodel_affinity"))
+    stop(check_class(class(x), "textmodel_affinity"))
 }
 
 
@@ -90,7 +99,7 @@ textmodel_affinity.dfm <- function(x, y, exclude = NULL,
         y = y,
         p = p,
         support = fitted$support,
-        method = "affinity",
+        # method = "affinity",
         call = match.call()
     )
     class(result) <- "textmodel_affinity"
@@ -139,7 +148,12 @@ textmodel_affinity.dfm_bootstrap <- function(x, y, exclude = NULL,
 #' @param smooth a misnamed smoothing parameter, either a scalar or a vector
 #'   equal in length to the number of documents
 #' @author Patrick Perry
-#' @return a list with stuff
+#' @returns a list containing:
+#' * `coefficients` point estimates of theta
+#' * `se` (likelihood) standard error of theta
+#' * `cov` covariance matrix
+#' * `smooth` values of the smoothing parameter
+#' * `support` logical indicating if the feature was included
 #' @examples
 #' p <- matrix(c(c(5/6, 0, 1/6), c(0, 4/5, 1/5)), nrow = 3,
 #'             dimnames = list(c("A", "B", "C"), NULL))
@@ -449,8 +463,21 @@ print.textmodel_affinity <- function(x, ...) {
 #' @param level probability level for confidence interval width
 #' @param newdata dfm on which prediction should be made
 #' @param ... unused
-#' @return `predict()` returns a list of predicted affinity textmodel
-#'   quantities.
+#' @returns `predict()` returns a list of predicted affinity textmodel
+#'   quantities, containing:
+#' * `coefficients` a numeric matrix of affinity estimates (coefficients) for 
+#'    each class (columns) for each document (rows)
+#' * `se` a numeric matrix of likelihood standard errors for affinity coefficients
+#'    each class (columns) for each document (rows)
+#' * `cov` an array of covariance matrices for each affinity class, one per document
+#' * `smooth` a numeric vector of length two for the smoothing parameters `smooth`
+#'   and `ref_smooth` from [textmodel_affinity()]
+#' * `newdata` a [dfm][quanteda::dfm] on which prediction has been made
+#' * `train` a logical vector indicating which documents were used in training the model
+#' * `level` the confidence level for computing standard errors
+#' * `p` the `p` return from `textmodel_affinity`
+#' * `support` logical vector indicating whether a feature was included in computing
+#'   class affinities
 #' @importFrom methods new
 #' @importFrom stats predict
 #' @method predict textmodel_affinity
@@ -497,7 +524,7 @@ print.predict.textmodel_affinity <- function(x, ...) {
 
 #' @rdname predict.textmodel_affinity
 #' @method coef predict.textmodel_affinity
-#' @return `coef()` returns a document \eqn{\times} class matrix of class
+#' @returns `coef()` returns a document \eqn{\times} class matrix of class
 #'   affinities for each document.
 #' @export
 coef.predict.textmodel_affinity <- function(object, ...) {
@@ -511,7 +538,7 @@ coefficients.predict.textmodel_affinity <- function(object, ...) {
 }
 
 #' @rdname predict.textmodel_affinity
-#' @return
+#' @returns
 #' `residuals()` returns a document-by-feature matrix of residuals.
 #' `resid()` is an alias.
 #' @method residuals predict.textmodel_affinity
@@ -540,7 +567,7 @@ resid.predict.textmodel_affinity <- function(object, ...) {
 
 #' @rdname predict.textmodel_affinity
 #' @method rstandard predict.textmodel_affinity
-#' @return `rstandard()` is a shortcut to return the pearson residuals.
+#' @returns `rstandard()` is a shortcut to return the Pearson residuals.
 #' @importFrom stats rstandard sd
 #' @export
 rstandard.predict.textmodel_affinity <- function(model, ...) {
@@ -552,20 +579,35 @@ rstandard.predict.textmodel_affinity <- function(model, ...) {
 
 #' Compute feature influence from a predicted textmodel_affinity object
 #'
-#' Computes the influence of features on scaled [textmodel_affinity]
+#' Computes the influence of features on scaled [textmodel_affinity()]
 #' applications.
-#' @param model a predicted
-#'   [textmodel_affinity][predict.textmodel_affinity] object
+#' @param model a predicted [textmodel_affinity()][predict.textmodel_affinity]
+#'   object
 #' @param subset whether to use all data or a subset (for instance, exclude the
 #'   training set)
 #' @param ... unused
 #' @seealso [influence.lm()]
 #' @keywords textmodel internal
 #' @importFrom stats influence
 #' @method influence predict.textmodel_affinity
+#' @returns a named list classed as [influence.predict.textmodel_affinity] that
+#'   contains
+#' * `norm` a document by feature class sparse matrix of normalised influence 
+#'   measures
+#' * `count` a vector of counts of each non-zero feature in the input matrix
+#' * `rate` the normalised feature count for each non-zero feature in the input 
+#'    matrix
+#' * `mode` an integer vector of 1 or 2 indicating the class which the feature 
+#'    is influencing, for each non-zero feature
+#' * `levels` a character vector of the affinity class labels
+#' * `subset` a logical vector indicating whether the document was included in 
+#'   the computation of influence; `FALSE` for documents assigned a class label 
+#'   in training the model
+#' * `support` logical vector for each feature matching the same return from 
+#'   [predict.textmodel_affinity]
 #' @examples
-#' tmot <- textmodel_affinity(quanteda::data_dfm_lbgexample, y = c("L", NA, NA, NA, "R", NA))
-#' pred <- predict(tmot)
+#' tmod <- textmodel_affinity(quanteda::data_dfm_lbgexample, y = c("L", NA, NA, NA, "R", NA))
+#' pred <- predict(tmod)
 #' influence(pred)
 #' @export
 influence.predict.textmodel_affinity <- function(model, subset = !train, ...) {
@@ -665,6 +707,24 @@ print.influence.predict.textmodel_affinity <- function(x, n = 30, ...) {
 
 #' @rdname textmodel_affinity-internal
 #' @method summary influence.predict.textmodel_affinity
+#' @returns `summary.influence.predict.textmodel_affinity()` returns a list
+#' classes as `summary.influence.predict.textmodel_affinity` that includes:
+#' 
+#' * `word` the feature name
+#' * `count` the total counts of each feature for which influence was computed
+#' * `mean`, `median`, `sd`, `max` mean, median, standard deviation, and maximum
+#'   values of influence for each feature, computed across classes
+#' * `direction` an integer vector of 1 or 2 indicating the class which the feature 
+#'    is influencing
+#' * `rate` a document by feature class sparse matrix of normalised influence 
+#'   measures
+#' * `count` a vector of counts of each non-zero feature in the input matrix
+#' * `rate` the median of `rate` from [influence.predict.textmodel_affinity()]
+#' * `support` logical vector for each feature matching the same return from 
+#'   [predict.textmodel_affinity()]
+#' 
+#' the mean, the standard deviation, the direction of the influence, the rate,
+#' and the support
 #' @importFrom stats median
 #' @export
 summary.influence.predict.textmodel_affinity <- function(object, ...) {
@@ -731,9 +791,12 @@ summary.influence.predict.textmodel_affinity <- function(object, ...) {
     levels <- seq_along(labels)
     max_dir <- factor(max_dir, levels, labels)
 
-    result <- list(word = words, count = count_val,
-                   mean = mean_val, median = med_val,
-                   sd = sd_val, max = max_val,
+    result <- list(word = words, 
+                   count = count_val,
+                   mean = mean_val, 
+                   median = med_val,
+                   sd = sd_val, 
+                   max = max_val,
                    direction = max_dir,
                    rate = med_rate,
                    support = object$support)
@@ -789,6 +852,3 @@ interleave <- function(v1, v2) {
     ord2 <- 2 * (seq_along(v2))
     c(v1, v2)[order(c(ord1, ord2))]
 }
-
-
-

R/textmodel_ca.R

@@ -45,7 +45,7 @@ textmodel_ca <- function(x, smooth = 0, nd = NA, sparse = FALSE,
 #' @export
 textmodel_ca.default <- function(x, smooth = 0, nd = NA, sparse = FALSE,
                                  residual_floor = 0.1) {
-    stop(friendly_class_undefined_message(class(x), "textmodel_ca"))
+    stop(check_class(class(x), "textmodel_ca"))
 }
 
 #' @export
@@ -151,6 +151,14 @@ textmodel_ca.dfm <- function(x, smooth = 0, nd = NA, sparse = FALSE,
 #'   extracted
 #' @param ... unused
 #' @keywords textmodel internal
+#' @returns a list containing numeric vectors of feature and document
+#'   coordinates.  Includes `NA` vectors of standard errors for consistency with
+#'   other models' coefficient outputs, and for the possibility of having these
+#'   computed in the future.
+#' * `coef_feature` column coordinates of the features
+#' * `coef_feature_se` feature length vector of `NA` values
+#' * `coef_document` row coordinates of the documents
+#' * `coef_document_se` document length vector of `NA` values
 #' @export
 coef.textmodel_ca <- function(object, doc_dim = 1, feat_dim = 1, ...) {
     list(coef_feature = object$colcoord[, feat_dim],

R/textmodel_lr.R

@@ -12,6 +12,14 @@
 #'   in \code{train}.  (These will be converted to factors if not already
 #'   factors.)
 #' @param ... additional arguments passed to [`cv.glmnet()`][glmnet::cv.glmnet()]
+#' @returns an object of class `textmodel_lr`, a list containing:
+#' * `x`, `y` the input model matrix and input training class labels
+#' * `algorithm` character; the type and family of logistic regression model used in calling
+#'   [`cv.glmnet()`][glmnet::cv.glmnet()]
+#' * `type` the type of associated with `algorithm`
+#' * `classnames` the levels of training classes in `y`
+#' * `lrfitted` the fitted model object from [`cv.glmnet()`][glmnet::cv.glmnet()]
+#' * `call` the model call
 #' @seealso [`cv.glmnet()`][glmnet::cv.glmnet()], [predict.textmodel_lr()],
 #'   [coef.textmodel_lr()]
 #' @references
@@ -49,7 +57,7 @@ textmodel_lr <- function(x, y, ...) {
 
 #' @export
 textmodel_lr.default <- function(x, y, ...) {
-    stop(quanteda:::friendly_class_undefined_message(class(x), "textmodel_lr"))
+    stop(check_class(class(x), "textmodel_lr"))
 }
 
 #' @export
@@ -219,6 +227,9 @@ coefficients.textmodel_lr <- function(object, ...) {
 #' @param n how many coefficients to print before truncating
 #' @param ... additional arguments not used
 #' @keywords textmodel internal
+#' @returns a `summary.textmodel` classed list containing elements from the 
+#' call to `textmodel_lr()`, including the call, statistics for lambda, and
+#' the estimated feature scores
 #' @method summary textmodel_lr
 #' @export
 summary.textmodel_lr <- function(object, n = 30, ...) {

R/textmodel_lsa.R

@@ -5,6 +5,12 @@
 #' @param x the [dfm] on which the model will be fit
 #' @param nd  the number of dimensions to be included in output
 #' @param margin margin to be smoothed by the SVD
+#' @returns a `textmodel_lsa` class object, a list containing:
+#' * `sk` a numeric vector containing the d values from the SVD
+#' * `docs` document coordinates from the SVD (u)
+#' * `features` feature coordinates from the SVD (v)
+#' * `matrix_low_rank` the multiplication of udv'
+#' * `data` the input data as a CSparseMatrix from the \pkg{Matrix} package
 #' @author Haiyan Wang and Kohei Watanabe
 #' @details [svds][RSpectra::svds] in the \pkg{RSpectra} package is applied to
 #'   enable the fast computation of the SVD.

R/textmodel_nb.R

@@ -106,7 +106,7 @@ textmodel_nb <- function(x, y, smooth = 1,
 textmodel_nb.default <- function(x, y, smooth = 1,
                                  prior = c("uniform", "docfreq", "termfreq"),
                                  distribution = c("multinomial", "Bernoulli")) {
-    stop(friendly_class_undefined_message(class(x), "textmodel_nb"))
+    stop(check_class(class(x), "textmodel_nb"))
 }
 
 #' @export
@@ -200,7 +200,7 @@ textmodel_nb.dfm <- function(x, y, smooth = 1,
 predict.textmodel_nb <- function(object, newdata = NULL,
                                  type = c("class", "probability", "logposterior"),
                                  force = FALSE, ...) {
-    unused_dots(...)
+    check_dots(...)
     type <- match.arg(type)
     if ("Pc" %in% names(object)) {
       names(object)[which(names(object) == "Pc")] <- "priors"
@@ -278,6 +278,8 @@ print.textmodel_nb <- function(x, ...) {
 #' @param object output from [textmodel_nb()]
 #' @param n how many coefficients to print before truncating
 #' @param ... additional arguments not used
+#' @returns a `summary.textmodel` classed list containing the call, the class
+#'   priors, and the estimated feature scores
 #' @keywords textmodel internal
 #' @method summary textmodel_nb
 #' @export