ggeffects

https://strengejacke.github.io/ggeffects/
Admin
ggeffects is an R package for calculating and visualizing adjusted predictions and estimated...
Tokens:7,485
Snippets:88
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install ggeffects from CRAN

Source: https://strengejacke.github.io/ggeffects/index.html

Standard installation command for the stable release of the package.

```R
install.packages("ggeffects")
```

--------------------------------

### Install ggeffects development version from r-universe

Source: https://strengejacke.github.io/ggeffects/index.html

Installation command for the development version hosted on r-universe.

```R
install.packages("ggeffects", repos = "https://strengejacke.r-universe.dev")
```

--------------------------------

### Install ggeffects development version from GitHub

Source: https://strengejacke.github.io/ggeffects/index.html

Installation command using the remotes package to pull from the GitHub repository.

```R
remotes::install_github("strengejacke/ggeffects")
```

--------------------------------

### Install latest development version

Source: https://strengejacke.github.io/ggeffects/index.html

Convenience function to install the latest development version from r-universe.

```R
ggeffects::install_latest()
```

--------------------------------

### install_latest

Source: https://strengejacke.github.io/ggeffects/reference/install_latest.html

Installs the latest version of the ggeffects package from either CRAN or the development repository.

```APIDOC
## install_latest

### Description
This function installs the latest package version of ggeffects, either the development version from R-universe/GitHub or the current version from CRAN.

### Parameters
#### Arguments
- **source** (character) - Optional - Either "development" (default) or "cran".
- **force** (logical) - Optional - If FALSE, only installs if a newer version is available. If TRUE, forces installation. Only applies when source="development".
- **verbose** (logical) - Optional - Toggle messages.

### Request Example
install_latest(source = "development", force = FALSE, verbose = TRUE)

### Response
- **Value** (NULL) - Returns invisible NULL.
```

--------------------------------

### Install Latest ggeffects Version

Source: https://strengejacke.github.io/ggeffects/reference/install_latest.html

Installs the latest development or CRAN version of the ggeffects package. Use 'force = TRUE' to overwrite if the local version is identical to the development version.

```R
install_latest(
  source = c("development", "cran"),
  force = FALSE,
  verbose = TRUE
)
```

```R
install_latest()
```

--------------------------------

### Plotting Predictions with ggeffects plot method

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Use the `plot` method from ggeffects to visualize predictions. This example shows how to disable confidence intervals.

```R
plot(dat, show_ci = FALSE)
```

--------------------------------

### 3-Way Interaction with Continuous Variables

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Visualize a three-way interaction between continuous variables. This example converts a variable to a factor and then plots the interaction using `stat_smooth` and `facet_wrap`.

```R
data(efc)
efc$c161sex <- as_factor(efc$c161sex)
fit <- lm(neg_c_7 ~ c12hour * barthtot * c161sex, data = efc)
# select only levels 30, 50 and 70 from continuous variable Barthel-Index
dat <- predict_response(fit, terms = c("c12hour", "barthtot [30,50,70]", "c161sex"))
ggplot(dat, aes(x = x, y = predicted, colour = group)) +
  stat_smooth(method = "lm", se = FALSE, fullrange = TRUE) +
  facet_wrap(~facet) +
  labs(
    colour = get_legend_title(dat),
    x = get_x_title(dat),
    y = get_y_title(dat),
    title = get_title(dat)
  )
```

--------------------------------

### Predicting with Non-Numeric Factor Levels

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

This example shows how to specify non-numeric levels for factors when predicting response variables. Ensure the factor levels are correctly labeled or converted to labels before prediction.

```R
data(efc)
efc$c172code <- sjlabelled::as_label(efc$c172code)
fit <- lm(barthtot ~ c12hour + neg_c_7 + c161sex + c172code, data = efc)
predict_response(fit, terms = c(
  "c12hour",
  "c172code [low level of education, high level of education]",
  "c161sex [1]"
))
```

--------------------------------

### Predictions for Polynomial Terms

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Generate predictions for polynomial terms in a generalized linear model. This example uses `I(e17age^2)` and `I(e17age^3)` to include polynomial effects.

```R
data(efc)
fit <- glm(
  tot_sc_e ~ c12hour + e42dep + e17age + I(e17age^2) + I(e17age^3),
  data = efc,
  family = poisson()
)
predict_response(fit, terms = "e17age")
```

--------------------------------

### Prediction Configuration Parameters

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Overview of parameters used to configure model response predictions, including interval types, back-transformation, and variance-covariance matrix estimation.

```APIDOC
## Configuration Parameters

### Parameters
- **condition** (Named character vector) - Optional - Indicates covariates to be held constant at specific values.
- **interval** (string) - Optional - Type of interval calculation: "confidence" (default) or "prediction".
- **back_transform** (boolean) - Optional - If TRUE, back-transforms transformed responses to original scale.
- **vcov** (matrix/function/string) - Optional - Variance-covariance matrix for uncertainty estimates (e.g., "HC", "CR0", "BS").
- **vcov_args** (list) - Optional - Additional arguments for the vcov function.
```

--------------------------------

### Retrieve citation information for ggeffects

Source: https://strengejacke.github.io/ggeffects/index.html

Use this command within an R session to display the formal citation details for the package.

```R
citation('ggeffects')
```

--------------------------------

### Printing compact tables

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Use the print function with the collapse_table argument to display predicted response tables in a more compact format.

```R
out <- predict_response(fit, terms = c("c12hour", "c172code", "c161sex"))
print(out, collapse_table = TRUE)
```

--------------------------------

### Visualize Predictions with ggplot2

Source: https://strengejacke.github.io/ggeffects/index.html

Demonstrates how to use the output of predict_response to create custom visualizations with ggplot2.

```R
library(ggplot2)
mydf <- predict_response(fit, terms = "c12hour")
ggplot(mydf, aes(x, predicted)) +
  geom_line() +
  geom_ribbon(aes(ymin = conf.low, ymax = conf.high), alpha = 0.1)
```

--------------------------------

### Plot Predictions Using Built-in Method

Source: https://strengejacke.github.io/ggeffects/index.html

Uses the default plot method provided by ggeffects for quick visualization of prediction objects.

```R
mydf <- predict_response(fit, terms = "c12hour")
plot(mydf)
```

--------------------------------

### Predict Response with Formula

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Use predict_response with a formula to specify the terms for which to predict. This is useful for exploring the effects of multiple variables simultaneously.

```R
predict_response(fit, terms = ~ c12hour + c172code + c161sex)
```

--------------------------------

### Predicting with Named List for Terms

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

When `terms` is a named list, you can specify different sequences or values for each term. This allows for more granular control over the prediction grid.

```R
predict_response(fit, terms = list(
  c12hour = seq(0, 170, 30),
  c172code = c("low level of education", "high level of education"),
  c161sex = 1
))
```

--------------------------------

### Simulated Predictions

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Use type = "simulate" for predictions and intervals based on simulations from simulate(). This accounts for all model uncertainty. Supported models include lm, glm, glmmTMB, wbm, MixMod, and merMod. Adjust the number of simulations with nsim.

```R
predict_response(model, type = "simulate", nsim = 1000)
```

--------------------------------

### Specifying Variance-Covariance Matrix

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Use the 'vcov' argument to specify the variance-covariance matrix for uncertainty estimates. It accepts a matrix, a function returning a matrix, or a string identifying a sandwich package function (e.g., "HC", "CR0", "BS"). If NULL, standard errors from predict() are used.

```R
predict_response(model, vcov = "HC")
predict_response(model, vcov = "CR0")
predict_response(model, vcov = "BS")
predict_response(model, vcov = sandwich::vcovHC)
predict_response(model, vcov = clubSandwich::vcovCR)
```

--------------------------------

### Specify Specific Values for Terms in ggeffects

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Use the `terms` argument to specify meaningful values for focal terms. This can include specific levels, numeric ranges with optional step sizes, standard deviations from the mean, quartiles, or back-transformed values. It also supports sampling values or using all values.

```R
terms = c("age", "education [1,3]")
```

```R
terms = c("education", "age [30:60]")
```

```R
terms = "age [30:60 by=5]"
```

```R
terms = "age [meansd]"
```

```R
terms = "age [quart2]"
```

```R
terms = "income [exp]"
```

```R
v = c(1000, 2000, 3000)
terms = "income [v]"
```

```R
terms = "income [sample=8]"
```

```R
terms = "age [all]"
```

```R
terms="age [n=5]"
```

```R
terms="age [n=12]"
```

--------------------------------

### Plot Multiple Variables with Facets and Colors

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Demonstrates plotting predicted values for multiple variables using ggplot2, incorporating facets for different categories and colors to distinguish groups. This is useful for complex model interpretations.

```R
library(ggplot2)
mydf <- predict_response(fit, terms = c("c12hour", "c161sex", "c172code"))
ggplot(mydf, aes(x = x, y = predicted, colour = group)) +
  stat_smooth(method = "lm", se = FALSE) +
  facet_wrap(~facet, ncol = 2)
```

--------------------------------

### Predicting Specific Levels for Grouping Terms

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Use the `terms` argument to specify which levels of a factor should be included in the prediction. This is useful for comparing specific groups within your model.

```R
mydf <- predict_response(fit, terms = c("c12hour", "c172code [1,3]", "c161sex"))
ggplot(mydf, aes(x = x, y = predicted, colour = group)) +
  stat_smooth(method = "lm", se = FALSE) +
  facet_wrap(~facet) +
  labs(
    y = get_y_title(mydf),
    x = get_x_title(mydf),
    colour = get_legend_title(mydf)
  )
```

--------------------------------

### predict_response Arguments

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Configuration parameters for calculating adjusted predictions from model objects.

```APIDOC
## predict_response Arguments

### Description
Defines the parameters used to calculate adjusted predictions for focal terms in a statistical model.

### Parameters
- **model** (object) - Required - A model object.
- **terms** (character/list/formula/data.frame) - Required - Names of focal terms for which predictions should be displayed.
- **margin** (string) - Optional - Method for marginalizing over non-focal predictors (e.g., "mean_reference", "mean_mode", "marginalmeans", "empirical").
- **ci_level** (numeric) - Optional - Confidence interval level (e.g., 0.95). Use NA to disable.
- **type** (string) - Optional - Prediction type conditioned on model components (e.g., "fixed", "random").
```

--------------------------------

### Predict Response with Named List of Terms

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Provide terms as a named list to predict responses for specific values or ranges of variables. This offers a structured way to define prediction conditions.

```R
predict_response(fit, terms = list(c12hour = 40:60))
```

--------------------------------

### Conditioning Covariates

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Use the 'condition' argument to hold covariates constant at specific values, e.g., condition = c(covariate1 = 20, covariate2 = 5). This differs from 'typical' which applies a function to determine covariate values.

```R
predict_response(model, condition = c(covariate1 = 20, covariate2 = 5))
```

--------------------------------

### Variance-Covariance Matrix Arguments

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

The 'vcov_args' argument passes additional arguments to the specified vcov function.

```R
predict_response(model, vcov = "HC", vcov_args = list(type = "HC3"))
```

--------------------------------

### Back-Transforming Predicted Values

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Set 'back_transform' to TRUE (default) to return predictions on the original response scale for log-, log-log, exp, sqrt, and similar transformed responses. See insight::find_transformation() for details.

```R
predict_response(model, back_transform = TRUE)
```

--------------------------------

### Predict Response Types for Zero-Inflated Models

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Use 'zero_inflated' or 'zi' for expected response (mu*(1-p)) on the population level. Use 'zi_random' for unit-level predictions in mixed models, specifying the random effect term. 'zi_prob' returns the predicted zero-inflation probability.

```R
predict_response(model, type = "zero_inflated")
predict_response(model, type = "zi")
predict_response(model, type = "zi_random", terms = "random_effect_term")
predict_response(model, type = "zi_prob")
```

--------------------------------

### Survival Analysis Predictions

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

For coxph objects, use type = "survival" for survival probability or type = "cumulative_hazard" for cumulative hazard. For survreg objects, use type = "quantile" and pass probabilities via the p argument.

```R
predict_response(model, type = "survival")
predict_response(model, type = "cumulative_hazard")
predict_response(model, type = "quantile", p = c(0.2, 0.5, 0.8))
```

--------------------------------

### Calculate and Visualize Predictions for Multiple Predictors

Source: https://strengejacke.github.io/ggeffects/index.html

Handles multiple focal predictors to generate grouped and faceted predictions.

```R
result <- predict_response(fit, terms = c("neg_c_7", "c161sex", "e42dep"))
# we want a more compact table, thus we use `print()` explicitly
print(result, collapse_table = TRUE, collapse_ci = TRUE)

ggplot(result, aes(x = x, y = predicted, colour = group)) +
  geom_line() +
  facet_wrap(~facet)
```

--------------------------------

### Plot Multi-predictor Results

Source: https://strengejacke.github.io/ggeffects/index.html

Applies the default plot method to prediction objects containing multiple focal predictors.

```R
plot(result)
```

--------------------------------

### Predicting response values

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Calculate predicted values for a linear model using one or more terms. The output includes predicted values and confidence intervals adjusted for other model covariates.

```R
library(sjlabelled)
data(efc)
fit <- lm(barthtot ~ c12hour + neg_c_7 + c161sex + c172code, data = efc)

predict_response(fit, terms = "c12hour")
predict_response(fit, terms = c("c12hour", "c172code"))
```

--------------------------------

### predict_response() Function

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

The main function to calculate marginal means and adjusted predictions. It returns adjusted predictions, marginal means, or averaged counterfactual predictions depending on the 'margin' argument.

```APIDOC
## POST /predict_response

### Description
Computes marginal means and adjusted predicted values for the response variable of a statistical model, based on specified terms and conditions.

### Method
POST

### Endpoint
/predict_response

### Parameters
#### Query Parameters
- **model** (object) - Required - The fitted statistical model object.
- **terms** (character or list) - Required - The terms for which to calculate predictions.
- **margin** (character) - Optional - Specifies the type of prediction (e.g., 'mean_reference', 'response'). Defaults to 'mean_reference'.
- **ci_level** (numeric) - Optional - The confidence interval level. Defaults to 0.95.
- **type** (character) - Optional - Prediction type for specific models (e.g., 'fixed').
- **condition** (list) - Optional - A list to specify conditions for predictions.
- **interval** (character) - Optional - Type of interval ('confidence' or 'prediction'). Defaults to 'confidence'.
- **back_transform** (logical) - Optional - Whether to back-transform predictions. Defaults to TRUE.
- **vcov** (matrix) - Optional - A custom variance-covariance matrix.
- **vcov_args** (list) - Optional - Arguments for calculating the variance-covariance matrix.
- **weights** (numeric) - Optional - Weights to be applied.
- **bias_correction** (logical) - Optional - Whether to apply bias correction. Defaults to FALSE.
- **verbose** (logical) - Optional - Whether to print verbose output. Defaults to TRUE.

### Request Example
```json
{
  "model": "<fitted_model_object>",
  "terms": ["term1", "term2"],
  "margin": "response",
  "ci_level": 0.99,
  "condition": {
    "categorical_var": "level1"
  }
}
```

### Response
#### Success Response (200)
- **predicted_values** (data.frame) - A data frame containing the adjusted predictions, confidence intervals, and other relevant information.

#### Response Example
```json
{
  "predicted_values": [
    {
      "term": "term1",
      "x": 1,
      "predicted": 2.5,
      "lower_ci": 2.1,
      "upper_ci": 2.9
    },
    {
      "term": "term1",
      "x": 2,
      "predicted": 3.0,
      "lower_ci": 2.6,
      "upper_ci": 3.4
    }
  ]
}
```
```

--------------------------------

### Calculate adjusted predictions with predict_response

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

The primary function for generating model-based estimates. It supports various arguments for configuring confidence levels, marginalization methods, and model types.

```R
predict_response(
  model,
  terms,
  margin = "mean_reference",
  ci_level = 0.95,
  type = "fixed",
  condition = NULL,
  interval = "confidence",
  back_transform = TRUE,
  vcov = NULL,
  vcov_args = NULL,
  weights = NULL,
  bias_correction = FALSE,
  verbose = TRUE,
  ...
)
```

--------------------------------

### Predict Response with Conditional Covariates

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Use the 'condition' argument to hold other covariates constant at specific values (e.g., mean, median, or a custom value) while predicting for the specified terms. This isolates the effect of interest.

```R
predict_response(fit, terms = "c12hour [40:60]", condition = c(neg_c_7 = 20))
```

--------------------------------

### Predict Response for a Variable Range

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Specify a range of values for a single variable using bracket notation to predict responses across that range. This helps visualize the effect of a continuous variable.

```R
predict_response(fit, terms = "c12hour [40:60]")
```

--------------------------------

### Predictions for Mixed Models

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

For mixed models, predictions can be made at the population-level (`type = "fixed"`) or unit-level (`type = "random"`). Population-level predictions can be conditional (default) or marginal (`margin = "empirical"`). Prediction intervals account for random effects uncertainty.

```R
type = "fixed"
```

```R
type = "random"
```

```R
margin = "empirical"
```

```R
interval = "predictions"
```

--------------------------------

### Predictions for Bayesian Regression Models

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

When working with Stan-models from rstanarm or brms, predictions are based on posterior samples. The median of posterior samples is used for predicted values, and median absolute deviation for standard errors. Consider using `interval = "prediction"` for posterior predictive intervals.

```R
interval = "prediction"
```

--------------------------------

### Prediction Types

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Supported prediction types for various model classes, including zero-inflated and survival models.

```APIDOC
## Prediction Types

### Supported Types
- **zero_inflated / zi** - Expected value of response conditioned on fixed effects and zero-inflation component.
- **zi_random / zero_inflated_random** - Unit-level predictions for mixed models including random effects.
- **zi_prob** - Predicted zero-inflation probability.
- **simulate** - Predictions based on simulations to account for model uncertainty.
- **survival / cumulative_hazard** - Survival probability or cumulative hazard for coxph objects.
- **quantile** - Predicted quantiles for survreg objects.
```

--------------------------------

### Interval Calculation Types

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

Set 'interval' to "confidence" (default) or "prediction". Prediction intervals include residual variance for greater uncertainty. Prediction intervals are not available for all models. For Bayesian models, "confidence" uses posterior draws of the linear predictor, while "prediction" uses posterior_predict().

```R
predict_response(model, interval = "confidence")
predict_response(model, interval = "prediction")
```

--------------------------------

### Categorical Variable on X-axis with Error Bars

Source: https://strengejacke.github.io/ggeffects/reference/predict_response.html

This snippet demonstrates plotting predictions for a categorical variable on the x-axis, including error bars and custom axis labels. Use `geom_point` and `geom_errorbar` for this visualization.

```R
dat <- predict_response(fit, terms = c("c172code", "c161sex"))
ggplot(dat, aes(x, predicted, colour = group)) +
  geom_point(position = position_dodge(0.1)) +
  geom_errorbar(
    aes(ymin = conf.low, ymax = conf.high),
    position = position_dodge(0.1)
  ) +
  scale_x_discrete(breaks = 1:3, labels = get_x_labels(dat))
```

--------------------------------

### Calculate Adjusted Predictions for One Predictor

Source: https://strengejacke.github.io/ggeffects/index.html

Computes predicted values for a single focal predictor while adjusting for other model terms.

```R
library(ggeffects)
library(splines)
library(datawizard)
data(efc, package = "ggeffects")
efc <- to_factor(efc, c("c161sex", "e42dep"))
fit <- lm(barthtot ~ c12hour + bs(neg_c_7) * c161sex + e42dep, data = efc)

predict_response(fit, terms = "c12hour")
```
Tokens:
Raw