bentcableAR (version 0.3.0)

cable.fit.known.change: Grid-based Bent-Cable Regression for Independent or AR Data

Description

These functions compute the profile deviance over a $(\tau,\gamma)$-grid to either fit a bent-cable regression with known transition, or to generate initial values for a bent-cable regression with unknown transition. cable.dev and cable.fit.known.change form the main engine of bentcable.dev.plot.

Usage

cable.ar.0.fit(y.vect, t.vect = NULL, tau.vect, gamma.vect, dev.mat,
	stick = FALSE)
cable.dev(tau.vect, gamma.vect, y.vect, t.vect = NULL, p = 0)
cable.fit.known.change(y.vect, t.vect = NULL, n = NA,
	tau.vect, gamma.vect, dev.mat, p = 0)

Arguments

y.vect

A numeric vector of response values.

t.vect

A numeric vector of design points. Specifying t.vect=NULL is equivalent to specifying the default time points c(0,1,2,...). Also see Warnings below.

n

Length of response vector (optional).

tau.vect

A numeric vector of $\tau$-coordinates of the grid points.

gamma.vect

A numeric vector of $\gamma$-coordinates of the grid points.

dev.mat

A numeric matrix (can be single column) corresponding to the bent-cable profile deviance surface / function over the $(\tau,\gamma)$-grid.

p

The autoregressive order (non-negative integer). p=0 specifies independent data that may or may not be from a time series context.

stick

A logical value; if TRUE then a broken stick (i.e. bent cable with $\gamma$=0.) is fitted.

Value

fit

Returned by cable.fit.known.change and cable.ar.0.fit.For cable.fit.known.change, $fit is the AR(p) bent-cable regression at the known transition grid point; if p=0, it is an lm object, otherwise it is an arima object.For cable.ar.0.fit, $fit is an nls object that is the maximum likelihood bent-cable fit.

init

Returned by cable.fit.known.change, containing the coefficients from $fit that can be used as initial values in bent-cable regression with unknown transition.

y

Same as y.vect: returned by cable.ar.0.fit.

t

Same as t.vect: returned by cable.ar.0.fit.

n, p, stick

As supplied by the user: returned by cable.ar.0.fit.

cable.dev returns the evaluated profile deviance surface / function as a matrix.

Warnings

For time-series data, t.vect MUST be equidistant with unit increments; otherwise, these functions will return meaningless values. (For independent data, t.vect can be non-equidistant.) Grid-based bent-cable regression and its use in subsequent overall fits rely on locating the region in which the continous deviance surface truly peaks. The user should be aware of possible local maxima and/or coarse grids that result in less-than-best fits.

Details

Given the response data in y.vect and design points in t.vect, cable.dev evaluates the bent-cable profile deviance surface / function over the user-specified $(\tau,\gamma)$-grid. The returned values are intended to be used in conjunction with contour or persp, in which case tau.vect and gamma.vect should have length greater than 1 so that the returned object is a matrix with at least two columns. If such a plot is not required, then tau.vect and/or gamma.vect can be scalar. This function is internal to the main plotting interface bentcable.dev.plot.

The grid point at which the profile deviance is maximum corresponds to a bent-cable fit given a known transition that is best among the specified grid points. cable.fit.known.change locates this peak and computes this fit. If multiple peaks exist (such as along a ridge), then only that at the smallest $\tau$ and smallest $\gamma$ is used.

For both functions, p=0 should be specified to indicate independent data (time series or otherwise). For time-series data, a positive integer p should be specified as the autoregressive order. Fitting is done by internally calling the built-in R function lm for p=0 and arima for non-zero p; this procedure is appropriate since bent-cable regression with a known transition is linear.

Note that the grid-based cable.fit.known.change does not locate the true peak of the continuous profile deviance surface / function. However, for a grid that traps the true peak between grid points, the returned fit is approximately the overall best fit (with all parameters unknown), and thus can be fed into bentcable.ar as initial values for computing the actual best fit. A special case is p=0 for independent data (time-series or otherwise), which can be handled by cable.ar.0.fit (called internally by bentcable.ar). cable.ar.0.fit calls cable.ar.p.iter when stick=FALSE but calls stick.ar.0 when stick=TRUE; in both cases, the built-in R function nls is utilized to perform maximum likelihood.

For all three functions, to fit a broken stick with a known break point, gamma.vect should be the single value 0, and thus dev.mat is a column matrix (see bentcable.dev.plot).

References

See the bentcableAR package references.

See Also

bentcable.dev.plot, bentcable.ar, nls, lm, arima

Examples

data(stagnant)
data(sockeye)

# non-time-series data: compute grid-based profile deviance
cable.dev( seq(-.04,.16,length=10), seq(.2,.65,length=10), 
	stagnant$loght, stagnant$logflow )
	# compare to this:
	# bentcable.dev.plot( seq(-.04,.16,length=10), 
	#	seq(.2,.65,length=10), stagnant$loght, stagnant$logflow )$dev

# AR(2) bent cable, start time at 0: find best grid-based fit
dev <- cable.dev( seq(6,18,length=15), seq(.01,12,length=15),
		sockeye$logReturns, p=2 )
contour( seq(6,18,length=15), seq(.01,12,length=15), dev )
cable.fit.known.change( sockeye$logReturns, tau.v=seq(6,18,length=15), 
	gamma.v=seq(.01,12,length=15), dev.mat=dev, p=2 )

# AR(0) broken stick, start time at 80: find best overall fit
dev <- cable.dev ( seq(85,97,length=15), 0, sockeye$logReturns, 
	sockeye$year)
plot( seq(85,97,length=15), dev, type="l" )
cable.ar.0.fit( sockeye$logReturns, sockeye$year,
	tau.v=seq(85,97,length=15), gamma.v=0, dev.mat=dev, 
	stick=TRUE )
	# compare to this:
	# bentcable.ar( sockeye$logReturns, bentcable.dev.plot(
	#	seq(85,97,length=15), 0, sockeye$logReturns, sockeye$year, TRUE
	#	), stick=TRUE, t.vect=sockeye$year )