[required] A fitted model object (e.g., model = your.model). Supported models include a wide range of regression types, including linear, robust linear, nonlinear, generalized least squares, generalized linear, mixed-effects, and generalized additive (mixed) models. Compatible model-fitting functions include: stats::lm, MASS::rlm, stats::nls, nlme::gls, stats::glm, MASS::glm.nb, lme4::lmer, lme4::glmer, lme4::glmer.nb, glmmTMB::glmmTMB, and mgcv::gam.

[required] The data frame used to fit the model (e.g., data = your.data). This data frame is used internally for generating predictions. All variables used in the model formula (including predictors, offsets, grouping variables, and interaction terms) must be present in this data frame. If the model was fitted without using a data argument (e.g., using variables from the global environment), you must ensure that data includes all required variables. Otherwise, prediction may fail or produce incorrect results.

[required] The name of the target explanatory variable to be plotted (e.g., predictor = "x1").

The name of an interaction or additional variable for conditioning (e.g., by = "x2"). If a continuous variable is used, cross-sections are taken at the 10th, 50th, and 90th quantiles. If a categorical variable is used, a separate line or point will be plotted for each level. This can also be used to visualize group-level random effects all at once: namely, when by corresponds to a grouping variable used in a random effect term (e.g., if by = "group" when the random term is specified as (1|group) or s(group, bs="re")) and re.form = NULL, predictions are conditional on each group's estimated random effect. Although easyViz does not natively support direct visualization of three-way interactions in a multi-panel plot, this can be easily achieved by combining the by and fix_values arguments. For example, if your model includes a term like x1*x2*x3, you can visualize the effect of x1 across levels of x2 by setting predictor = "x1", by = "x2", and fixing x3 at a specific value using fix_values = c(x3 = ...). Repeating this with different values of x3 produces multiple plots that can be arranged to visualize the full three-way interaction.

Character string indicating the type of predictions to plot. Either "response" (default), which returns predictions on the original outcome scale by applying the inverse of the model's link function (e.g., probabilities for binary models), or "link", which returns predictions on the linear predictor (link) scale (e.g., log-odds, log-counts, or other transformed scales depending on the model).

Logical. Applies only when the predictor is numeric and a categorical by variable is specified. If TRUE (default), the prediction range for each level of the by variable is limited to the range of the predictor observed within that level. This avoids extrapolating predictions beyond the available data for each subgroup. If FALSE, predictions span the entire range of the predictor across all levels of the by variable. If the by variable is numeric, pred_range_limit is automatically set to FALSE, since numeric by values are treated as continuous rather than grouping factors.

Logical. If TRUE, prediction lines (and their confidence intervals) for numeric predictors are drawn after raw data, so they appear on top. Default is FALSE, which draws predictions underneath the data. This has no effect for categorical predictors — for those, predictions are always drawn on top of raw data.

How to condition non-target numeric predictors. Either "median" (default) or "mean". This determines how numeric variables that are not directly plotted are held constant during prediction, while varying the predictor of interest — a common approach when visualizing effects in multivariable models. To fix specific variables at custom values instead, use the fix_values argument.

How to condition non-target categorical predictors. Either "mode" (default) or "reference". As for "num_conditioning", conditioning means holding these variables constant while varying the predictor of interest. If multiple levels are equally frequent when "mode" is selected, the level chosen will be the first in the factor's level order (which by default is alphabetical and typically coincides with the reference level, unless explicitly re-leveled). This behavior also applies to grouping variables used as random effects when re.form = NULL. To fix categorical variables (including grouping variables) at specific levels, use fix_values.

A named vector or named list specifying fixed values for one or more variables during prediction. Supports both numeric and categorical variables. For numeric variables, specify a fixed value (e.g., fix_values = c(x = 1)). For categorical variables (factors), provide the desired level as a character string or factor (e.g., fix_values = c(group = "levelA") or fix_values = list(group = levels(data$group)[1])). This overrides the default conditioning behavior specified via num_conditioning and cat_conditioning. Note: This argument also applies to grouping variables used as random effects: when re.form = NULL, predictions are conditional on the level specified in fix_values; if not specified, the level is chosen based on cat_conditioning. This argument is useful for setting offsets, forcing predictions at specific values, or ensuring consistent conditioning across models. For example, it is particularly useful when you want to visualize the effect of a predictor at a specific level of an interacting variable, without conditioning on all levels. E.g., to plot the conditional effect of a continuous predictor x1 at a specific value of another variable x2 (numeric or categorical), simply set fix_values = c(x2 = ...) and omit the by argument. This creates a clean single-effect plot for x1 at the desired level of x2, without plotting multiple lines or groups as by would. This argument can also be used to visualize three-way interactions when combined with by. See the by argument description for details and an example of how to apply this approach.

A custom function to back-transform predictions for transformed response variables (e.g., exp for log-transformed responses, or function(x) x^2 for square root-transformed responses). Note: If you wish to model a transformed response, it is recommended to apply the transformation directly in the model formula (e.g., log(y)), rather than modifying the response variable in the data set. This ensures that observed data points are correctly plotted on the original (back-transformed) scale. Otherwise, raw data and predicted values may not align properly in the plot.

A formula specifying which random effects to include when generating predictions. This argument is relevant for mixed-effects models only (e.g., from lme4, glmmTMB, or mgcv::gam). Use re.form = NULL (default) to include group-specific predictions, conditional on the random-effect levels present in the data. By default, easyViz fixes grouping variables at their mode (i.e., the most frequent level), so that, when re.form = NULL, the prediction reflects the conditional estimate for that group level. However, you can explicitly fix the level of the grouping variable using the fix_values argument — this allows you to visualize group-specific predictions for a specific level of the random term (e.g., fix_values = c(group = "levelA")). If all levels are equally frequent and no value is specified via fix_values, the first level (in factor order) is used, which typically follows alphabetical order unless manually re-leveled. Use re.form = NA or re.form = ~0 to obtain population-level predictions based only on fixed effects — this means that random effects are part of the model fit but are excluded from the prediction, resulting in population-level (i.e., marginal) predictions based solely on fixed effects. This is equivalent to assuming the random effects are zero — i.e., an ‘average’ group or subject. For mgcv::gam() models, random effects are typically modeled using smooth terms such as s(group, bs = "re"). Although predict.gam() does not support a re.form argument, easyViz emulates its behavior: re.form = NULL includes random-effect smooths in the prediction, while re.form = NA or re.form = ~0 excludes them by internally using the exclude argument in predict.gam(). For all types of mixed models, when re.form = NULL and by corresponds to a grouping variable used in a random effect term, group-specific (i.e., conditional) predictions are visualized for all levels of the grouping variable. Note: For models fitted with lme4 (e.g., lmer(), glmer()), standard errors are not available when re.form = NULL.

x-axis limits for the plot (e.g., xlim = c(0, 10)). Defaults to automatic scaling based on the data range.

y axis limits for the plot (e.g., ylim = c(10, 20)). Defaults to automatic scaling based on the data and prediction range.

x axis labels (e.g., xlab = "x"). Defaults to "predictor".

y axis labels (e.g., ylab = "y"). Defaults to "response".

Font family for the plot. E.g., "sans" (default), "serif", "mono".

Text orientation for axis labels (default: 1).

Box type around the plot. E.g., "o" (default), "n", "L".

A named list of additional graphical parameters passed to base R's plot() function. These arguments allow users to override default appearance settings in a flexible way. Common options include axis label size, color, margin settings, font family, and tick mark style. Common plot() parameters you may override:

• Label/Text size and style: cex.lab, cex.axis, cex.main, font.lab, font.axis, font.main

• Colors: col.lab, col.axis, col.main, col.sub, col, bg, fg

• Label/Text content: xlab, ylab, main, sub

• Margins and layout: mar, oma, mgp, tcl, las, adj

• Box and axis rendering: bty, axes, frame.plot, ann

• Coordinate settings: xlim, ylim, xaxs, yaxs, asp, xlog, ylog

This is a flexible alternative to manually setting individual plot parameters in the function signature. For a full list of supported parameters, see ?par and ?plot.default. Example usage:
plot_args = list(main = "Title", cex.lab = 1.2, col.axis = "gray40", mar = c(5, 4, 4, 2), las = 1).

Logical. Whether to display raw data points (default: TRUE). For binomial models where the response is expressed in the formula as cbind(successes, failures) or as successes / trials, the raw data points plotted on the y-axis are based on the calculated proportions: successes / (successes + failures) or successes / trials, respectively. These proportions are computed internally from the original data and temporarily added to the data set for visualization purposes.

For binary responses, how to display raw data points in the plot. Either "plain" (default), which plots each individual 0/1 observation as-is, or "binned", which groups observations into intervals (bins) of the predictor and plots the proportion of 0s and 1s within each bin. This makes it easier to visualize trends in binary outcomes, especially when many points overlap.

Number of bins for displaying binary response raw data (default: 10).

Logical. If TRUE, raw data points are jittered horizontally to reduce overplotting. Applies to both categorical and numeric predictors. Default is FALSE. For categorical predictors, jittering helps distinguish overlapping points. For numeric predictors, it can be useful when many data points share the same x-value (e.g., integers or rounding).

Point color for raw data (default: rgb(0,0,0, alpha = 0.4)). Can be specified as a color name (e.g., "gray"), an integer (e.g., 1), or an RGB (e.g., rgb(0,0,0,alpha=0.4)) or hex string (e.g., "#808080"). Dynamic: accepts multiple values when points are plotted for different values/levels of a variable.
Tip: For large data sets with many overlapping data points, it is recommended to use semi-transparent colors to reduce overplotting. You can achieve this by setting a low alpha value (e.g., rgb(1,0,0, alpha = 0.1), or by using adjustcolor() with the argument alpha.f (e.g., adjustcolor("red", alpha.f = 0.1)). In such cases, consider setting pred_on_top = TRUE to ensure that prediction lines and confidence intervals remain clearly visible above the dense cloud of raw points.

Point shape for raw data (default: 16). Dynamic: accepts multiple values when points are plotted for different values/levels of a variable.

Point size for raw data (default: 0.75). Dynamic: accepts multiple values when points are plotted for different values/levels of a variable.

Color of the predicted line for numerical predictors (default: "black"). Can be specified as a color name, number or RGB/hex string. Dynamic: accepts multiple values (e.g., c("red", "green", "blue")) when multiple lines are plotted (i.e., when by is specified).

Type of the predicted line for numerical predictors (default: 1). Dynamic: accepts multiple values (e.g., c(1, 2, 3)) when multiple lines are plotted (i.e., when by is specified).

Width of the predicted line for numerical predictors (default: 2). Dynamic: accepts multiple values (e.g., c(1, 2, 3)) when multiple lines are plotted (i.e., when by is specified).

Type of 95 percent confidence intervals for numerical predictors. "polygon" (default) or "lines".

Color for 95 percent confidence interval polygon (default: "gray"). Requires ci_type = "polygon". Can be specified as a color name, number or RGB/hex string. Dynamic: accepts multiple values (e.g., c("red", "green", "blue")) when 95 percent CIs are plotted for multiple lines (i.e., when by is specified). Tip: To hide confidence bands entirely, set this to rgb(0,0,0,0).

Color for 95 percent confidence interval lines (default: "black"). Requires ci_type = "lines". Can be specified as a color name, number or RGB/hex string. Dynamic: accepts multiple values (e.g., c("red", "green", "blue")) when 95 percent CIs are plotted for multiple lines (i.e., when by is specified).

Type for 95 percent confidence interval lines (default: 1). Requires ci_type = "lines". Dynamic: accepts multiple values (e.g., c(1, 2, 3)) when 95 percent CIs are plotted for multiple lines (i.e., when by is specified).

Width for 95 percent confidence interval lines (default: 1). Requires ci_type = "lines". Dynamic: accepts multiple values (e.g., c(1, 2, 3)) when 95 percent CIs are plotted for multiple lines (i.e., when by is specified).

Color for predicted point values of categorical predictors (default: "black"). Can be specified as a color name, number or RGB/hex string. Dynamic: accepts multiple values (e.g., c("red", "green", "blue")) when points are plotted for an interaction (i.e., when by is specified).

Shape for predicted point values of categorical predictors (default: 16). Dynamic: accepts multiple values (e.g., c(1, 2, 3)) when points are plotted for an interaction (i.e., when by is specified).

Size for predicted point values of categorical predictors (default: 1). Dynamic: accepts multiple values (e.g., c(1, 2, 3)) when points are plotted for an interaction (i.e., when by is specified).

Color for 95 percent confidence interval bars (default: "black"). Applies only when the predictor is categorical. Can be specified as a color name, number, or RGB/hex string.

Type for 95 percent confidence interval bars (default: 1). Applies only when the predictor is categorical.

Width for 95 percent confidence interval bars (default: 1). Applies only when the predictor is categorical.

Size of the caps on 95 percent confidence interval bars (default: 0.1). Increase for more visible caps, set to 0 to remove caps and draw plain vertical bars.

Custom labels for levels of a categorical predictor (e.g., cat_labels = c("Level A", "Level B", "Level C")).

Logical. Whether to add a legend for by variable levels (default: FALSE).

Legend position. Either a named position string ("top", "bottom", "left", "right", "topleft", "topright", "bottomleft", "bottomright") or a numeric vector c(x, y) specifying exact coordinates for the legend placement.

Legend text size (default: 0.9).

Custom labels for the legend (e.g., legend_labels = c("Label 1", "Label 2", "Label 3")).