# random: Specify a Random Effects Fit in a GAM Formula In gam: Generalized Additive Models

## Description

A symbolic wrapper for a factor term, to specify a random effect term in a formula argument to gam

## Usage

 ```1 2``` ```random(f, df = NULL, lambda = 0, intercept = TRUE) gam.random(f, y, w, df = sum(non.zero), lambda = 0, intercept=TRUE, xeval) ```

## Arguments

 `f` factor variable, or expression that evaluates to a factor. `y` a response variable passed to `gam.random` during backfitting `w` weights `df` the target equivalent degrees of freedom, used as a smoothing parameter. The real smoothing parameter (`lambda` below) is found such that `df=tr(S)`, where `S` is the implicit smoother matrix. Values for `df` should be greater than `0` and less than the number of levels of `f`. If both `df` and `lambda` are supplied, the latter takes precedence. Note that `df` is not necessarily an integer. `lambda` the non-negative penalty parameter. This is interpreted as a variance ratio in a mixed effects model - namely the ratio of the noise variance to the random-effect variance. `intercept` if `intercept=TRUE` (the default) then the estimated level effects are centered to average zero, otherwise they are left alone. `xeval` If this argument is present, then `gam.random` produces a prediction at `xeval`.

## Details

This "smoother" takes a factor as input and returns a shrunken-mean fit. If `lambda=0`, it simply computes the mean of the response at each level of `f`. With `lambda>0`, it returns a shrunken mean, where the j'th level is shrunk by `nj/(nj+lambda)`, with `nj` being the number of observations (or sum of their weights) at level `j`. Using such smoother(s) in gam is formally equivalent to fitting a mixed-effect model by generalized least squares.

## Value

`random` returns the vector `f`, endowed with a number of attributes. The vector itself is used in computing the means in backfitting, while the attributes are needed for the backfitting algorithms `general.wam`. Note that `random` itself does no smoothing; it simply sets things up for `gam`.

One important attribute is named `call`. For example, `random(f, lambda=2)` has a call component `gam.random(data[["random(f, lambda = 2)"]], z, w, df = NULL, lambda = 2, intercept = TRUE)`. This is an expression that gets evaluated repeatedly in `general.wam` (the backfitting algorithm).

`gam.random` returns an object with components

 `residuals` The residuals from the smooth fit. `nl.df` the degrees of freedom `var` the pointwise variance for the fit `lambda` the value of `lambda` used in the fit

When `gam.random` is evaluated with an `xeval` argument, it returns a vector of predictions.

## Author(s)

Written by Trevor Hastie, following closely the design in the "Generalized Additive Models" chapter (Hastie, 1992) in Chambers and Hastie (1992).

## References

Hastie, T. J. (1992) Generalized additive models. Chapter 7 of Statistical Models in S eds J. M. Chambers and T. J. Hastie, Wadsworth \& Brooks/Cole.

Hastie, T. and Tibshirani, R. (1990) Generalized Additive Models. London: Chapman and Hall.

Cantoni, E. and hastie, T. (2002) Degrees-of-freedom tests for smoothing splines, Biometrika 89(2), 251-263

`lo`, `s`, `bs`, `ns`, `poly`
 ```1 2 3``` ```# fit a model with a linear term in Age and a random effect in the factor Level y ~ Age + random(Level, lambda=1) ```