gratia version 0.5.0 now on CRAN

gratia 0.5.0

Covid-19- and teaching left me little development time, but a prompt from CRAN to address the use of {vdiffr} 📦 in package tests spurred me to wrap up some of the new features I had committed to the development version.

I also took the opportunity to complete the initial steps on a replacement for (or more accurately a successor to) evaluate_smooth(). Some early decisions I made when developing evaluate_smooth() meant that it was increasingly difficult to maintain and add support for more complex models, due to the way I had handled factor by variable smooths.

The replacement/successor is smooth_estimates(). At the moment it only handles simple 1-D smooths, but it should be much easier to accommodate other smooth types and more complex models with multiple linear predictors.

Eventually, once smooth_estimates() can handle the range of smooths and models that evaluate_smooth() can currently, I'll swap out instances of evaluate_smooth() from the higher-level functions that rely upon it. At the moment I don't plan on removing evaluate_smooth() from {gratia}, but its use will be at the very least soft-deprecated.

Some of the News for the release is copied below.

New features

• Partial residuals for models can be computed with partial_residuals(). The
  partial residuals are the weighted residuals of the model added to the
  contribution of each smooth term (as returned by predict(model, type = "terms").

  Wish of #76 (@noamross)

  Also, new function add_partial_residuals() can be used to add the partial
  residuals to data frames.

• Users can now control to some extent what colour or fill scales are used when
  plotting smooths in those draw() methods that use them. This is most useful
  to change the fill scale when plotting 2D smooths, or to change the discrete
  colour scale used when plotting random factor smooths (bs = "fs").

  The user can pass scales via arguments discrete_colour and
  continuous_fill.

• The effects of certain smooths can be excluded from data simulated from a model
  using simulate.gam() and predicted_samples() by passing exclude or terms
  on to predict.gam(). This allows for excluding random effects, for example, from
  model predicted values that are then used to simulate new data from the conditional
  distribution. See the example in predicted_samples().

  Wish of #74 (@hgoldspiel)

• draw.gam() and related functions gain arguments constant and fun to allow
  for user-defined constants and transformations of smooth estimates and
  confidence intervals to be applied.

  Part of wish of Wish of #79.

• confint.gam() now works for 2D smooths also.

• smooth_estimates() is an early version of code to replace (or more likely
  supersede) evaluate_smooth(). smooth_estimates() can currently only handle
  1D smooths of the standard types.

User visible changes

• The meaning of parm in confint.gam has changed. This argument now requires
  a smooth label to match a smooth. A vector of labels can be provided, but
  partial matching against a smooth label only works with a single parm value.

  The default behaviour remains unchanged however; if parm is NULL then all
  smooths are evaluated and returned with confidence intervals.

• data_class() is no longer exported; it was only ever intended to be an internal
  function.