[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, survival, mixed-effects, and generalized additive (mixed) models. Compatible model-fitting functions include: stats::lm, MASS::rlm, nlme::gls, stats::nls, stats::glm, MASS::glm.nb, betareg::betareg, survival::coxph, 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 supplied, easyViz() conditions predictions on by as follows:

• Categorical (factor/character): a separate prediction line (or point) is plotted for each level.

• Numeric with few distinct values (default: \le 6 unique values): the numeric values are treated as discrete groups, and a separate prediction line is plotted for each value. This is useful for variables coded as numbers (e.g., 0/1, 1–5, small ordinal scales).

• Numeric with many distinct values (default: > 6 unique values): by is treated as continuous and predictions are shown at representative values (by default the 10th, 50th, and 90th percentiles), unless overridden by by_breaks.

• Grouping variable in random effects: if by corresponds to a variable used as a grouping term (as in, e.g., (1|group) or s(group, bs="re")) and re_form = NULL, predictions are conditional on group-specific random effects.

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. See the Examples section for a demonstration of how to apply this approach.

Optional numeric vector specifying the values of a numeric conditioning variable to include in the plot (e.g., by_breaks = c(-2, 0, 2) or by_breaks = quantile(your.data$x2, c(0.25, 0.5, 0.75))). For numeric by, this selects the cross-sections to plot and overrides the default quantiles (0.1, 0.5, 0.9). Ignored if by is categorical.

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). For survival models (coxph), pred_type = "link" returns predictions on the linear predictor scale (log-hazard ratio), while pred_type = "response" returns hazard ratios. Survival probabilities are not produced because they require a time point and the baseline hazard.

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.

Number of prediction points to use for numeric predictors. Defaults to 101, consistent with visreg. The default should work well in most cases. Increasing pred_resolution may be particularly helpful when the predictor spans a wide range or when visualizing nonlinear relationships (e.g., splines or polynomials), to ensure smooth and accurate rendering of the effect. Note: A higher value may slightly increase computation time, especially when combined with many levels of a by variable.

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. 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, provide the desired level as a character string or factor (e.g., fix_values = c(group = "levelA"). Multiple values should be provided as a list (e.g., fix_values = list(x = 1, group = "levelA")). This overrides the default conditioning behavior specified via num_conditioning and cat_conditioning. 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 also useful for setting offsets. For count models with a log link in which the offset is specified as offset(log(exposure)), easyViz interprets the model as a rate model and, by default, fixes the exposure variable to 1 in the prediction grid. Raw response values are correspondingly scaled by the exposure so that both data points and predictions are displayed on the same unit-rate scale (e.g., detections per day; see show_data_points for more details). To obtain predictions on a different rate scale, fix the exposure at the desired value using fix_values. If the offset is specified outside the model formula, for gam() and glmer() models it is treated as offset = 0 during prediction (i.e., exposure = 1 for log-link models). This matches easyViz's default behavior, but in such cases easyViz cannot vary the exposure. Include the offset inside the formula (e.g., offset(log(exposure))) to enable full control. If the default behavior is not desired (i.e., if you do not want automatic rate standardization or fixing exposure to 1), you may still use an offset by specifying a pre-transformed exposure variable (e.g., log_exposure = log(exposure) and offset(log_exposure)). In this case, easyViz treats the offset as a generic additive term on the link scale. Model predictions are computed correctly, but the offset variable is conditioned using the default rules for numeric covariates (see num_conditioning) or values supplied via fix_values. Because the exposure structure is no longer explicit, raw data are plotted on the original response scale and no automatic rate standardization is applied. Additional uses: fix_values is useful also for forcing predictions at specific values or ensuring consistent conditioning across models, for example 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 for details, and the Examples section for a demonstration of how to apply this approach.

A formula specifying which random effects to include when generating predictions:

• re_form = NULL (default): produces 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 the prediction reflects the conditional estimate for that group. You can override this by explicitly fixing the grouping variable via fix_values (e.g., fix_values = c(group = "levelA")). If all levels are equally frequent and no value is specified, the first level (in factor order) is used, which is usually alphabetical unless re-leveled. If by corresponds to a grouping variable used in a random effect, predictions are visualized for all group levels (i.e., conditional predictions).

• re_form = NA or re_form = ~0: produces population-level (i.e., marginal) predictions by excluding random effects from the prediction step. The random effects are still part of the fitted model and influence the estimation of fixed effects and their uncertainty, but they are not included when computing predicted values. This is equivalent to assuming random effects are zero — representing an "average" group or subject.

This argument is relevant for mixed-effects models only (e.g., from lme4, glmmTMB, or mgcv::gam()). For mgcv::gam() models, random effects can be modeled using smooth terms like 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, while re_form = NA or ~0 excludes them via the exclude argument in predict.gam(). Note: For models fitted with lme4 (e.g., lmer(), glmer()), standard errors are not available when re_form = NULL.

Robust variance type for MASS::rlm models. May be one of the sandwich types: "HC0", "HC1", "HC2", "HC3", "HC4", "HC4m", "HC5", "const", "HC". Alternatively, users may provide a covariance matrix (used directly), or a function f(model) returning a covariance matrix. Default is "HC0".

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: For log-transformed responses, recall that in lognormal models the mean on the original scale is not simply exp(x) due to Jensen's inequality. If you want the expected value of a lognormal response, use a function such as function(x) exp(x + sigma2/2), where sigma2 is the residual variance on the log scale (e.g., sigma2 <- sigma(your.model)^2). 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.

x-axis limits for the plot (e.g., xlim = c(0, 10)). Defaults to automatic scaling based on the data range. Applies to both numeric and categorical predictors. For categorical variables, x-axis positions are treated as integer values (e.g., 1, 2, ..., k), and adjusting xlim (e.g., xlim = c(0.5, k + 0.5)) can control spacing and margins around the plotted levels.

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".

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

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, label text, tick mark spacing, and coordinate scaling. Note: Only arguments recognized by plot.default() are supported. Parameters that must be set via par() (such as mar, oma, mfrow, mgp) are not applied through plot_args. If you wish to adjust those settings, set them directly using par() before calling easyViz(). Many valid parameters are documented in both ?plot.default and ?par. In plot_args, they are passed to plot(), not to par(). 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.

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

• Coordinate settings and tick spacing: xlim, ylim, xaxs, yaxs, xaxp, yaxp, asp, xlog, ylog.

For a full list of supported parameters, see ?plot.default and ?par. Example usage:
plot_args = list(main = "Title", cex.lab = 1.2, col.axis = "gray40", xaxp = c(0, 10, 5)).

Logical. Whether to display raw data points (default: TRUE). For binomial models where the response is expressed as cbind(successes, failures) or as a proportion successes / trials, the raw data points shown on the y-axis are plotted as proportions: successes / (successes + failures) or successes / trials, respectively. For count models with a log link that include an offset specified as offset(log(exposure)), easyViz interprets the model as a rate model. Raw response values are rescaled as (count / exposure) * exposure_ref and, by default, exposure_ref = 1, so points are displayed on the unit-rate scale (e.g., detections per day). The prediction grid uses the same reference exposure value, ensuring that points and predictions are on the same scale. To use a different rate scale, set the exposure reference value via fix_values (e.g., fix_values = c(exposure = 7) for detections per 7 days). If this default behavior is not desired, the offset can instead be specified using a pre-transformed exposure variable (e.g., log_exposure = log(exposure) and offset(log_exposure) in the model formula). In this case, easyViz does not apply automatic rate standardization and treats the offset as a generic additive term on the link scale (see fix_values for details). For survival models (coxph), raw data points are not displayed, because survival outcomes involve event times and censoring and are not directly comparable to the plotted linear predictor (or hazard ratio) scale.

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 when binary_data_type = "binned" (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"). When the focal predictor is numeric, raw data points are plotted at the observation level. This typically matters when visualizing interactions involving a grouping variable (via by). In this case, point_col must be either a single value (applied to all points) or a vector of length equal to the number of observations in the data supplied to easyViz() (e.g., generated via ifelse(group == "levelA", "blue", "red") or similar logic; see the Example section). When the focal predictor is categorical and points are plotted for different levels of a grouping variable (via by), point_col can be a vector of colors, with one color per group (e.g., point_col = c("blue", "red"); see the Example section).
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 data points.

Point shape for raw data (default: 16). Dynamic: accepts multiple values when points are plotted for different values/levels of a variable. The same grouping logic described for point_col applies.

Point size for raw data (default: 0.75). Dynamic: accepts multiple values when points are plotted for different values/levels of a variable. The same grouping logic described for point_col applies.

Color of the predicted line for numeric 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 numeric 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 numeric predictors (default: 2). Dynamic: accepts multiple values (e.g., c(1, 2, 3)) when multiple lines are plotted (i.e., when by is specified).

Confidence level for the intervals (between 0 and 1). Defaults to 0.95. For example, ci_level = 0.85 plots 85 percent confidence intervals.

Type of confidence intervals for numeric predictors. Either "polygon" (default) to draw shaded confidence bands, "lines" to draw lines, or NULL to suppress confidence intervals for numeric predictors. Note: ci_type = NULL does not suppress confidence bars for categorical predictors; these are always shown unless manually suppressed via custom logic (e.g., by setting ci_bar_lwd = 0).

Color for 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 CIs are plotted for multiple lines (i.e., when by is specified).

Numeric value between 0 and 1 controlling the transparency of confidence interval bands when ci_type = "polygon". Default is 0.5. Higher values make the band more opaque; lower values make it more transparent.

Color for 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 CIs are plotted for multiple lines (i.e., when by is specified).

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

Width for confidence interval lines (default: 1). Requires ci_type = "lines". Dynamic: accepts multiple values (e.g., c(1, 2, 3)) when 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. When by is specified (interaction plots), pred_point_col may be a vector with one color per group (i.e., per level/value of by); the same group color is then used for predicted points across all levels of the focal predictor.

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). The same grouping logic described for pred_point_col applies.

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). The same grouping logic described for pred_point_col applies.

Color for confidence interval bars (default: "black"). Applies only when the predictor is categorical. Can be a single color (applied to all CI bars) or a vector of colors. When by is used, CI bars are drawn by looping first over the levels of the focal predictor and then over the levels of the grouping variable. Colors are assigned following this order, so they may need to be repeated to match predictor levels within each group. For example, with 2 levels of x and 2 groups for by, four CI bars are drawn, and a length-4 vector can be used to assign colors to each bar (e.g., c("blue","blue","red","red"); see the Examples section).

Type for confidence interval bars (default: 1). Applies only when the predictor is categorical. Follows the same assignment logic as ci_bar_col.

Width for confidence interval bars (default: 1). Applies only when the predictor is categorical. Follows the same assignment logic as ci_bar_col. To suppress confidence interval bars, set ci_bar_lwd = 0 (line width of zero).

Size of the caps on confidence interval bars (default: 0.1). Applies only when the predictor is categorical. Follows the same assignment logic as ci_bar_col. Increase for more visible caps, set to 0 to remove caps and draw plain vertical bars.

Logical. Whether to draw a legend for the by variable. By default, a legend is drawn automatically (i.e., add_legend = TRUE) when by is supplied and omitted otherwise. Set add_legend = FALSE to suppress the legend even when by is present.

Legend position. Either a named position string ("top", "bottom", "left", "right", "topleft", "topright", "bottomleft", "bottomright"), the special keyword "out", or a numeric vector c(x, y) specifying exact coordinates for manual placement. When a by variable is specified, a legend is drawn automatically with default position "out", i.e., a horizontal legend is drawn above the plotting region. All other values follow standard base R legend positioning rules. Advanced manual placement outside the plot region is possible by temporarily increasing margins with par(mar = ...) and/or allowing drawing outside the plot region with par(xpd = TRUE), then adjusting the legend position using inset or explicit coordinates. For example, to place a legend to the right of the axes, you may need to increase the right margin (e.g., par(mar = c(5, 4, 4, 8))) and set par(xpd = TRUE) before calling easyViz(). You can then fine-tune placement using inset via legend_args when legend_position is a keyword (i.e., "topright", "right", "bottomright"). If legend_position is given as explicit coordinates c(x, y), inset is not used because the legend is positioned directly at (x, y). See the Examples section for demonstrations.

Logical. If TRUE, the legend is drawn horizontally (side-by-side). If FALSE, the legend is drawn vertically (stacked). Note: when legend_position = "out", easyViz may automatically draw the legend horizontally (and adjust legend settings) to improve readability, unless overridden by user-supplied legend_args.

Optional character string controlling the legend title. If legend_title is not specified, and a by variable is present, easyViz() automatically uses the name of the by variable as the legend title, and legend labels correspond to the levels of by (e.g., "A", "B", "C"). If legend_title is explicitly set to NULL, no legend title is drawn, and legend labels revert to the verbose form "by = level" (e.g., "group = A"). If legend_title is a character string, it is used as the legend title, and legend labels correspond to the levels of by. In all cases, legend labels can be manually overridden using legend_labels.

Custom labels for the legend (e.g., legend_labels = c("Level A", "Level B", "Level C")).

Numeric. Text size for the legend title (default: 1).

Numeric. Text size for the legend labels (default: 0.9).

A named list of additional arguments passed to base R's legend() function. These allow fine-tuned control over the appearance and placement of the legend and override the high-level options provided by legend_position, legend_title and other legend_* arguments. For example, you can adjust the legend's box style, border color, spacing, point size, or background color. Common options include:

• Point and line appearance: pch, col, pt.cex, pt.lwd, lty, lwd.

• Layout and spacing: ncol, x.intersp, y.intersp, inset, xjust, yjust.

• Text style and color: cex, text.col, font, adj.

• Box and background: bty, box.lwd, box.col, bg.

• Title control: title, title.col, title.cex, title.adj.

For a full list of supported parameters, see ?legend. Example usage:
legend_args = list(bty = "o", box.col = "black", pt.cex = 1.5). Tip: Legends can be pushed outside the plotting region by combining par(xpd = TRUE) and wider margins (e.g., via par(mar = ...)), and by supplying appropriate coordinates or negative inset values through legend_args.

Logical. If TRUE, easyViz prints a concise summary in the R console describing how predictions are conditioned. The message reports:

• Whether predictions from mixed-effects or GAM models are conditional on random effects (re_form = NULL) or represent marginal / population-level predictions (re_form = NA or ~0).

• For numeric by variables, the values (e.g., quantiles or user-specified by_breaks) at which predictions are evaluated.

• Which variables are held fixed during prediction (and their values).

• Which variables vary across the prediction grid (typically the focal predictor and, if specified, the by variable).

This option does not affect the plot or returned values and is intended as a diagnostic aid to improve transparency and reproducibility. Default is FALSE.

Logical. If TRUE (default), easyViz produces a plot. If FALSE, no plot is drawn and the function only returns the predicted values (as an invisible easyviz.pred.df object). This is useful when you want to extract or store the predictions (e.g., in a data frame) without generating any graphical output.