Skip to content

Commit

Permalink
Prepare Release 1.0.0: Check {insight} API / documentation on API (#938)
Browse files Browse the repository at this point in the history
* Check {insight} API / documentation on API
Fixes #937

* remove deprecated args

* methods for `find_statistic()`

* export `get_dispersion()`

* docs

* lintr

* fix labelling

* remove http from desc

* lintr

* update

* update

* news

* pkgdown

* please checks

* fix test

* typo

* docs

* lintr

* fix

* update RD
  • Loading branch information
strengejacke authored Oct 22, 2024
1 parent 6cfb9e2 commit 3d69974
Show file tree
Hide file tree
Showing 30 changed files with 417 additions and 209 deletions.
3 changes: 1 addition & 2 deletions DESCRIPTION
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Type: Package
Package: insight
Title: Easy Access to Model Information for Various Model Objects
Version: 0.20.5.4
Version: 0.99.0
Authors@R:
c(person(given = "Daniel",
family = "Lüdecke",
Expand Down Expand Up @@ -134,7 +134,6 @@ Suggests:
grDevices,
gt,
httptest2,
httr,
httr2,
interp,
ivreg,
Expand Down
9 changes: 9 additions & 0 deletions NAMESPACE
Original file line number Diff line number Diff line change
Expand Up @@ -329,6 +329,7 @@ S3method(find_response,mediate)
S3method(find_response,mjoint)
S3method(find_response,model_fit)
S3method(find_response,selection)
S3method(find_statistic,default)
S3method(find_terms,afex_aov)
S3method(find_terms,aovlist)
S3method(find_terms,bfsl)
Expand Down Expand Up @@ -550,6 +551,12 @@ S3method(get_df,svy2lme)
S3method(get_df,systemfit)
S3method(get_df,truncreg)
S3method(get_df,vgam)
S3method(get_dispersion,brmsfit)
S3method(get_dispersion,default)
S3method(get_dispersion,glm)
S3method(get_dispersion,glmerMod)
S3method(get_dispersion,glmmTMB)
S3method(get_dispersion,model_fit)
S3method(get_family,default)
S3method(get_family,list)
S3method(get_family,model_fit)
Expand Down Expand Up @@ -1699,6 +1706,7 @@ export(get_data)
export(get_datagrid)
export(get_deviance)
export(get_df)
export(get_dispersion)
export(get_family)
export(get_intercept)
export(get_loglikelihood)
Expand Down Expand Up @@ -1761,3 +1769,4 @@ export(standardize_names)
export(supported_models)
export(text_remove_backticks)
export(trim_ws)
export(validate_argument)
16 changes: 15 additions & 1 deletion NEWS.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,13 @@
# insight 0.20.x
# insight 1.0.0

## Breaking changes

* All deprecated arguments have been removed.

## General

* `get_dispersion()` is now an exported function.

* `get_transformation()` can now deal with any power-transformation, and also
returns results for divisions (scaled response) and Box-Cox transformations.

Expand All @@ -11,6 +17,14 @@
* Updated `get_varcov()` (and related documentation) to support new covariance
matrix estimation methods from the **sandwich** package.

* New function `validate_argument()` as a replacement for `match.arg()` with
more informative error message.

## Bug fix

* `clean_parameters()` now uses the correct labels for the random effects
variances (`"SD/Cor"` has changed to `"Var/Cov"`).

* The function to calculate the corrections for likelihood-values when the
response-variable is transformed is now exported as `get_likelihood_adjustment()`.

Expand Down
12 changes: 6 additions & 6 deletions R/clean_parameters.R
Original file line number Diff line number Diff line change
Expand Up @@ -528,7 +528,7 @@ clean_parameters.mlm <- function(x, ...) {
out$Cleaned_Parameter <- gsub(pattern = "^b_(?!zi_)(.*)\\.(\\d)\\.$", "\\1[\\2]", out$Cleaned_Parameter, perl = TRUE)
out$Cleaned_Parameter <- gsub(pattern = "^b_zi_(.*)\\.(\\d)\\.$", "\\1[\\2]", out$Cleaned_Parameter, perl = TRUE)
out$Cleaned_Parameter <- gsub(pattern = "^(b_|bs_|bsp_|bcs_)(?!zi_)(.*)", "\\2", out$Cleaned_Parameter, perl = TRUE)
out$Cleaned_Parameter <- gsub(pattern = "^(b_zi_|bs_zi_|bsp_zi_|bcs_zi_)(.*)", "\\2", out$Cleaned_Parameter, perl = TRUE)
out$Cleaned_Parameter <- gsub(pattern = "^(b_zi_|bs_zi_|bsp_zi_|bcs_zi_)(.*)", "\\2", out$Cleaned_Parameter, perl = TRUE) # nolint

# correlation and sd

Expand All @@ -539,7 +539,7 @@ clean_parameters.mlm <- function(x, ...) {
# replace "__" by "~"
cor_only <- startsWith(out$Parameter[cor_sd], "cor_")
if (any(cor_only)) {
out$Cleaned_Parameter[which(cor_sd)[cor_only]] <- sub("__", " ~ ", out$Cleaned_Parameter[which(cor_sd)[cor_only]], fixed = TRUE)
out$Cleaned_Parameter[which(cor_sd)[cor_only]] <- sub("__", " ~ ", out$Cleaned_Parameter[which(cor_sd)[cor_only]], fixed = TRUE) # nolint
}
}

Expand Down Expand Up @@ -585,7 +585,7 @@ clean_parameters.mlm <- function(x, ...) {

simplex <- startsWith(out$Cleaned_Parameter, "simo_")
if (length(simplex)) {
out$Cleaned_Parameter[simplex] <- gsub("^(simo_|simo_mo)(.*)\\[(\\d)\\]$", "\\2[\\3]", out$Cleaned_Parameter[simplex])
out$Cleaned_Parameter[simplex] <- gsub("^(simo_|simo_mo)(.*)\\[(\\d)\\]$", "\\2[\\3]", out$Cleaned_Parameter[simplex]) # nolint
out$Component[simplex] <- "simplex"
}

Expand Down Expand Up @@ -652,7 +652,7 @@ clean_parameters.mlm <- function(x, ...) {
if (any(rand_cor)) {
out$Cleaned_Parameter[which(cor_sd)[rand_cor]] <- paste0(parm1[rand_cor], " ~ ", parm2[rand_cor])
}
out$Group[cor_sd] <- paste("SD/Cor:", gsub("^Sigma\\[(.*):(.*),(.*)\\]", "\\1", out$Parameter[cor_sd], perl = TRUE))
out$Group[cor_sd] <- paste("Var/Cov:", gsub("^Sigma\\[(.*):(.*),(.*)\\]", "\\1", out$Parameter[cor_sd], perl = TRUE))
}


Expand All @@ -669,9 +669,9 @@ clean_parameters.mlm <- function(x, ...) {
out$Group[rand_effects] <- r_grps
out$Level[rand_effects] <- r_levels
# fix labelling of SD and correlation component
sd_cor <- grepl("SD/Cor:", out$Group, fixed = TRUE)
sd_cor <- grepl("Var/Cov:", out$Group, fixed = TRUE)
if (any(sd_cor)) {
out$Group[sd_cor] <- gsub("SD/Cor: (.*)", "\\1", out$Group[sd_cor])
out$Group[sd_cor] <- gsub("Var/Cov: (.*)", "\\1", out$Group[sd_cor])
}
} else {
re_grp_level <- gsub("b\\[(.*) (.*):(.*)\\]", "\\2", out$Cleaned_Parameter[rand_effects])
Expand Down
48 changes: 0 additions & 48 deletions R/download_model.R
Original file line number Diff line number Diff line change
Expand Up @@ -32,54 +32,6 @@ download_model <- function(name,
url = "https://raw.github.com/easystats/circus/master/data/",
extension = ".rda",
verbose = TRUE) {
if (check_if_installed("httr2", quietly = TRUE)) {
.download_data_httr2(name, url, extension, verbose)
} else {
.download_data_httr(name, url, extension, verbose)
}
}


# Download rda files from github, using httr
.download_data_httr <- function(name, url, extension, verbose) {
check_if_installed("httr", "to download models from the circus-repo")

url <- paste0(url, name, extension)

temp_file <- tempfile()
on.exit(unlink(temp_file))

result <- tryCatch(
{
request <- httr::GET(url)
httr::stop_for_status(request)
},
error = function(e) {
if (verbose) {
format_alert(
"Could not download model. Request failed with following error:",
e$message
)
}
NULL
}
)
if (is.null(result)) {
return(NULL)
}

writeBin(httr::content(request, type = "raw"), temp_file)

x <- load(temp_file)
model <- get(x)
rm(x)

model
}


# Download rda files from github, using httr2
.download_data_httr2 <- function(name, url, extension = ".rda", verbose = TRUE) {
check_if_installed("httr2", "to download models from the circus-repo")

url <- paste0(url, name, extension)
Expand Down
5 changes: 5 additions & 0 deletions R/find_statistic.R
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,11 @@
#' find_statistic(m)
#' @export
find_statistic <- function(x, ...) {
UseMethod("find_statistic")
}

#' @export
find_statistic.default <- function(x, ...) {
# model object check --------------------------------------------------------

# check if the object is a model object; if not, quit early
Expand Down
40 changes: 24 additions & 16 deletions R/get_auxiliary.R
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,13 @@
#'
#' @details Currently, only sigma and the dispersion parameter are returned, and
#' only for a limited set of models.
#' \subsection{Sigma Parameter}{
#' See [get_sigma()].
#' }
#' \subsection{Dispersion Parameter}{
#'
#' @section Sigma Parameter:
#'
#' See [`get_sigma()`].
#'
#' @section Dispersion Parameter:
#'
#' There are many different definitions of "dispersion", depending on the context.
#' `get_auxiliary()` returns the dispersion parameters that usually can
#' be considered as variance-to-mean ratio for generalized (linear) mixed
Expand All @@ -36,12 +39,12 @@
#' and is the ratio of the sum of the squared Pearson-residuals and the residual
#' degrees of freedom. For models of class `glmmTMB`, dispersion is
#' \ifelse{html}{\out{&sigma;<sup>2</sup>}}{\eqn{\sigma^2}}.
#' }
#' \subsection{**brms** models}{
#'
#' @section brms-models:
#'
#' For models of class `brmsfit`, there are different options for the
#' `type` argument. See a list of supported auxiliary parameters here:
#' [find_parameters.BGGM()].
#' }
#' [`find_parameters.BGGM()`].
#'
#' @examples
#' # from ?glm
Expand Down Expand Up @@ -74,21 +77,26 @@ get_auxiliary <- function(x,





# dispersion parameter -----------------------

#' @keywords internal
#' @rdname get_auxiliary
#' @export
get_dispersion <- function(x, ...) {
UseMethod("get_dispersion")
}

#' @keywords internal
#' @rdname get_auxiliary
#' @export
get_dispersion.default <- function(x, ...) {
format_error(sprintf("`get_dispersion()` does not yet support models of class \"%s\".", class(x)[1])) # nolint
}

#' @export
get_dispersion.model_fit <- function(x, ...) {
get_dispersion(x$fit, ...)
}

#' @keywords internal
#' @export
get_dispersion.glm <- function(x, verbose = TRUE, ...) {
info <- model_info(x, verbose = verbose)
disp <- NULL
Expand All @@ -103,7 +111,7 @@ get_dispersion.glm <- function(x, verbose = TRUE, ...) {
disp
}

#' @keywords internal
#' @export
get_dispersion.glmerMod <- function(x, verbose = TRUE, ...) {
info <- model_info(x, verbose = verbose)
disp <- NULL
Expand All @@ -122,7 +130,7 @@ get_dispersion.glmerMod <- function(x, verbose = TRUE, ...) {
disp
}

#' @keywords internal
#' @export
get_dispersion.glmmTMB <- function(x, verbose = TRUE, ...) {
info <- model_info(x, verbose = verbose)
disp <- NULL
Expand All @@ -135,7 +143,7 @@ get_dispersion.glmmTMB <- function(x, verbose = TRUE, ...) {
disp
}

#' @keywords internal
#' @export
get_dispersion.brmsfit <- get_dispersion.glmmTMB


Expand Down
40 changes: 17 additions & 23 deletions R/get_varcov.R
Original file line number Diff line number Diff line change
Expand Up @@ -30,19 +30,21 @@
#' * A string which indicates the kind of uncertainty estimates to return.
#' - Heteroskedasticity-consistent: `"HC"`, `"HC0"`, `"HC1"`, `"HC2"`,
#' `"HC3"`, `"HC4"`, `"HC4m"`, `"HC5"`. See `?sandwich::vcovHC`
#' - Cluster-robust: `"vcovCR"`, `"CR0"`, `"CR1"`, `"CR1p"`, `"CR1S"`,
#' `"CR2"`, `"CR3"`. See `?clubSandwich::vcovCR`
#' - Bootstrap: `"vcovBS"`, `"xy"`, `"residual"`, `"wild"`, `"mammen"`,
#' `"fractional"`, `"jackknife"`, `"norm"`, `"webb"`.
#' See `?sandwich::vcovBS`
#' - Other `sandwich` package functions: `"HAC"`, `"PC"`, `"vCL"`, `"PL"`.
#' - Cluster-robust: `"CR"`, `"CR0"`, `"CR1"`, `"CR1p"`, `"CR1S"`, `"CR2"`,
#' `"CR3"`. See `?clubSandwich::vcovCR`
#' - Bootstrap: `"BS"`, `"xy"`, `"residual"`, `"wild"`, `"mammen"`,
#' `"fractional"`, `"jackknife"`, `"norm"`, `"webb"`. See
#' `?sandwich::vcovBS`
#' - Other `sandwich` package functions: `"HAC"`, `"PC"`, `"CL"`, `"OPG"`,
#' `"PL"`.
#' - Kenward-Roger approximation: `kenward-roger`. See `?pbkrtest::vcovAdj`.
#' @param vcov_args List of arguments to be passed to the function identified by
#' the `vcov` argument. This function is typically supplied by the **sandwich**
#' or **clubSandwich** packages. Please refer to their documentation (e.g.,
#' `?sandwich::vcovHAC`) to see the list of available arguments. If no estimation
#' type (argument `type`) is given, the default type for `"HC"` (or `"vcovHC"`)
#' equals the default from the **sandwich** package; for type `"CR"` (or
#' `"vcoCR"`), the default is set to `"CR3"`.
#' the `vcov` argument. This function is typically supplied by the
#' **sandwich** or **clubSandwich** packages. Please refer to their
#' documentation (e.g., `?sandwich::vcovHAC`) to see the list of available
#' arguments. If no estimation type (argument `type`) is given, the default
#' type for `"HC"` equals the default from the **sandwich** package; for type
#' `"CR"`, the default is set to `"CR3"`.
#' @param verbose Toggle warnings.
#' @param ... Currently not used.
#'
Expand Down Expand Up @@ -1172,6 +1174,9 @@ get_varcov.LORgee <- get_varcov.gee
sprintf("The `vcov` argument of the `insight::get_varcov()` function is not yet supported for models of class `%s`.", paste(class(x), collapse = "/")) # nolint
)
}
if ("robust" %in% names(dots) && !is.null(dots[["robust"]])) {
format_warning("The `robust` argument is no longer supported. Please use the `vcov` and `vcov_args` instead.") # nolint
}
}


Expand All @@ -1182,16 +1187,5 @@ get_varcov.LORgee <- get_varcov.gee
if (is.null(vcov) && "vcov_estimation" %in% names(dots)) {
vcov <- dots[["vcov_estimation"]]
}

if ("robust" %in% names(dots)) {
# default robust covariance
if (is.null(vcov)) {
vcov <- "HC3"
}
if (isTRUE(verbose)) {
format_warning("The `robust` argument is deprecated. Please use `vcov` instead.")
}
}

vcov
}
21 changes: 3 additions & 18 deletions R/get_weights.R
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@
#' if no weights were specified in the model (as if the weights were all set
#' to 1).
#' @param ... Currently not used.
#' @param na_rm Deprecated, use `remove_na` instead.
#'
#' @return The weighting variable, or `NULL` if no weights were specified.
#' If the weighting variable should also be returned (instead of `NULL`)
Expand Down Expand Up @@ -42,11 +41,7 @@ get_weights <- function(x, ...) {

#' @rdname get_weights
#' @export
get_weights.default <- function(x, remove_na = FALSE, null_as_ones = FALSE, na_rm = remove_na, ...) {
## TODO: remove deprecated later
if (!missing(na_rm)) {
remove_na <- na_rm
}
get_weights.default <- function(x, remove_na = FALSE, null_as_ones = FALSE, ...) {
weight_vars <- find_weights(x)
w <- tryCatch(
stats::weights(x, ...),
Expand Down Expand Up @@ -100,12 +95,7 @@ get_weights.default <- function(x, remove_na = FALSE, null_as_ones = FALSE, na_r


#' @export
get_weights.brmsfit <- function(x, remove_na = FALSE, null_as_ones = FALSE, na_rm = remove_na, ...) {
## TODO: remove deprecated later
if (!missing(na_rm)) {
remove_na <- na_rm
}

get_weights.brmsfit <- function(x, remove_na = FALSE, null_as_ones = FALSE, ...) {
w <- unique(find_weights(x))

if (!is.null(w)) {
Expand Down Expand Up @@ -139,12 +129,7 @@ get_weights.btergm <- function(x, null_as_ones = FALSE, ...) {


#' @export
get_weights.list <- function(x, remove_na = FALSE, null_as_ones = FALSE, na_rm = remove_na, ...) {
## TODO: remove deprecated later
if (!missing(na_rm)) {
remove_na <- na_rm
}

get_weights.list <- function(x, remove_na = FALSE, null_as_ones = FALSE, ...) {
# For GAMMs
if ("gam" %in% names(x)) {
get_weights(x$gam, remove_na = remove_na, null_as_ones = null_as_ones, ...)
Expand Down
Loading

0 comments on commit 3d69974

Please sign in to comment.