orlm {ic.infer}R Documentation

Functions for order restricted linear regression estimation and testing

Description

Function orlm calculates order-restricted linear models (linear equality and inequality constraints). It uses function boot.orlm for bootstrapping, which in turn uses the orlm.forboot... functions (not intended for use by users). The remaining functions extract coefficients, provide a residual plot, give a short printout or a more extensive summary.

Usage

orlm(model, ui, ci, index = 2:length(coef(model)), meq = 0, 
    orig.out = FALSE, boot = FALSE, B = 1000, fixed = FALSE, 
    tol = sqrt(.Machine$double.eps), ...)
boot.orlm(model, B = 1000, fixed = FALSE, ui, ci, index, meq)
orlm.forboot.fixed(data, indices, ...)
orlm.forboot(data, indices, ...)
## S3 method for class 'orlm':
coef(object, ...)
## S3 method for class 'orlm':
plot(x, caption = "Residuals vs Fitted", 
        panel = if (add.smooth) panel.smooth else points, sub.caption = NULL, 
        main = "", ..., id.n = 3, labels.id = names(x$residuals), cex.id = 0.75, 
        add.smooth = getOption("add.smooth"), label.pos = c(4, 2), 
        cex.caption = 1)
## S3 method for class 'orlm':
print(x, digits = max(3, getOption("digits") - 3), ...)
## S3 method for class 'orlm':
summary(object, display.unrestr = FALSE, 
        digits = max(3, getOption("digits") - 3), 
        scientific = FALSE, overall.tests = TRUE, 
        bootCIs = TRUE, bty = "perc", level = 0.95, ...)

Arguments

model a linear model object (class lm) with data included
ui matrix (or vector in case of one single restriction only) defining the left-hand side of the restriction
ui%*%beta >= ci,
where beta is the parameter vector; the first few of these restrictions can be declared equality- instead of inequality restrictions (cf. argument meq); if only part of the elements of beta are subject to restrictions, the columns of ui can be restricted to these elements, if their index numbers are provided in index; by default, index excludes the intercept, i.e. the columns of ui refer to the non-intercept elements of coef(model)
Rows of ui must be linearly independent; in case of linearly dependent rows the function gives an error message with a hint which subset of rows is independent. Note that the restrictions must define a (possibly translated) cone, i.e. e.g. interval restrictions on a parameter are not permitted.
ci vector on the right-hand side of the restriction (cf. ui)
index index numbers of the components of beta, which are subject to the specified constraints as ui%*%beta[index] >= ci, default is 2:length(coef(model)), i.e. ui is supposed to have columns for all coefficients except the intercept; CAUTION: when modifying index, note that intercept is counted as the first coefficient!
meq integer number (default 0) giving the number of rows of ui that are used for equality restrictions instead of inequality restrictions.
orig.out should the original model be included in the output list ? (default: FALSE)
boot should bootstrapping be conducted ? (default: FALSE)
B number of bootstrap samples (default: 1000)
fixed should bootstrapping consider the sample as fixed and bootstrap residuals ? (default: FALSE)
data data handed to bootstrap sampling routine
indices indices for sampling
tol numerical tolerance value; estimates closer to 0 than tol are set to exactly 0
... Further options
object object of class orlm (created by function orlm)
x object of class orlm (created by function orlm)
caption like in function plot.lm
panel like in function plot.lm
sub.caption like in function plot.lm
main like in function plot.lm
id.n like in function plot.lm
labels.id like in function plot.lm
cex.id like in function plot.lm
add.smooth like in function plot.lm
label.pos like in function plot.lm
cex.caption like in function plot.lm
digits number of digits to display
display.unrestr if TRUE, also display unrestricted model; default: FALSE
scientific if FALSE, suppresses scientific format; default: FALSE
overall.tests if FALSE, suppresses output of overall model tests; default: TRUE; for models with large sets of restrictions, tests can take up substantial time because of weight calculation
bootCIs if FALSE, suppresses bootstrap confidence intervals, even though the obj contains a bootout element; default: TRUE
bty type of bootstrap confidence interval; any of \dQuote{perc}, \dQuote{bca}, \dQuote{norm} or \dQuote{basic}, cf. function boot.ci from package boot, default: \dQuote{perc}
level confidence level for bootstrap confidence intervals, default: 0.95

Details

Function orlm performs order restricted linear model analysis. Functions coef.orlm, plot.orlm, print.orlm, and summary.orlm provide methods for reporting the results on an object of S3 class orlm. The functions directly referring to bootstrapping are not to be called by the user but are called from within function orlm if option boot is set to TRUE.

The output from summary.orlm provides information about the restrictions, a comparison of $R^2$-values for unrestricted and restricted model, restricted estimates, and

- if requested (option boot set to TRUE in function orlm and option bootCIs set to TRUE in the summary function) with bootstrap confidence intervals,

- if requested (option overall.tests set to TRUE) several restriction-related tests (implemented by calls to ic.test): The analogue to the overall F-Test in the ordinary linear model is the test of all coefficients but intercept equal to 0 within the restricted parameter space. In addition, three tests related to the restriction are reported:

Test 1: H0: Restriction valid with equality vs. H1: at least one inequality

Test 2: H0: Restriction valid vs. H1: restriction violated

Test 3: H0: Restriction violated or valid with equality vs. H1: all restrictions valid with inequality

Test 3 is conducted in case of no equality-restrictions only.

Value

The output of function orlm belongs to S3 classes orlm and orest. It is a list with the following items:

b.restr restricted estimate
b.unrestr unrestricted estimate
R2 R-squared
residuals residuals of restricted model
fitted.values fitted values of restricted model
weights observation weights
orig.R2 R-squared of unrestricted model
df.error error degrees of freedom of unrestricted model
s2 MSE of unrestricted model
Sigma variance covariance matrix of beta-hat in unrestricted model
origmodel unrestricted model itself (NULL, if orig.out=FALSE)
ui as input
ci as input
restr.index the input vector index
meq as input
iact active restrictions, i.e. restrictions that are satisfied with equality in the solution, as output by solve.QP
bootout object of class boot obtained by bootstrapping, will be used by summary.orlm for calculating bootstrap confidence intervals; NULL if boot=FALSE

Author(s)

Ulrike Groemping, TFH Berlin

References

Shapiro, A. (1988) Towards a unified theory of inequality-constrained testing in multivariate analysis. International Statistical Review 56, 49–62

See Also

See also ic.est, ic.test, solve.QP

Examples

limo <- lm(swiss)
## restricted linear model with restrictions that
## - Education and Examination have same coefficient
## - Catholic and Infant.Mortality have non-negative coefficients
orlimo <- orlm(limo, ui=rbind(c(0,1,-1,0,0),c(0,0,0,1,0),c(0,0,0,0,1)), meq=1)
orlimo
plot(orlimo)
summary(orlimo)
## same model using index vector
orlimo <- orlm(limo, ui=rbind(c(1,-1,0,0),c(0,0,1,0),c(0,0,0,1)), index=3:6, meq=1)

## reduce number of bootstrap samples for example run time
orlimo <- orlm(limo, ui=rbind(c(1,-1,0,0),c(0,0,1,0),c(0,0,0,1)), 
    index=3:6, meq=1, boot=TRUE, B=100)
summary(orlimo)

[Package ic.infer version 0.7 Index]