A package for minimal vector adjustment.

Description

Given a vector \boldsymbol{x}^0, and a set linear restrictions of the form \boldsymbol{a}_i\cdot\boldsymbol{x}_i=b_i and/or \boldsymbol{a}_i\cdot\boldsymbol{x}_i\leq b_i with i=1,2,\ldots,m. This package finds the nearest vector to \boldsymbol{x}^0 (in the (weighted) euclidean sense) that satisfies all restrictions.

Details

Much of this package's functionality, including algorithms for working with large, sparse problems has been moved to the lintools package. This package will serve as a front-end for application of the succsessive projection algorithm for data stored in data.frame like objects.

DEPRECATED Adjust a data to meet linear (in)equality constraints

Description

Adjust a vector \boldsymbol{x} to meet constraints \boldsymbol{Ax} \leq \boldsymbol{b}. As of version 0.2 this function is deprecated. Please use

• project from package lintools to replace adjust.matrix

• sparse_project from pacakge lintools to replace adjust.sparseConstraints

Usage

adjust(object, ...)

## S3 method for class 'editmatrix'
adjust(object, x, w = rep(1, length(x)), method = c("dense", "sparse"), ...)

## S3 method for class 'sparseConstraints'
adjust(object, x, w = rep(1, length(x)), tol = 0.01, maxiter = 1000L, ...)

## S3 method for class 'matrix'
adjust(
  object,
  b,
  x,
  neq = length(b),
  w = rep(1, length(x)),
  tol = 0.01,
  maxiter = 1000L,
  ...
)

Arguments

Value

Object of class adjusted.

Details

adjust is a generic function allowing several definitions of the constraints in object.

• editmatrix:If object is an editmatrix, the function will try to match the names of x to the variable names in object before further processing. In that case the length of x is unimportant, as long as all variables in object are also in x. Depending on the choice of method, object is converted to matrix or sparseConstraints format before solving the adjustment problem.

• matrix: If object is a matrix, you also need to provide the constant vector b and the number of equations neq to define the problem. It is assumed that the first neq rows of object and the first new elements of b correspond to equalities. No names are matched, so x must be in the correct order and must be of the right dimension. See sparseConstraints on how to translate a matrix problem to the sparse version.

• sparseConstraints: If object is of class sparseConstraints, the sparse method is used to adjust x. Some basic checks on x and w are performed, but no attempt is made to match names of x to those of object.

The tolerance tol is defined as the maximum absolute value of the difference vector \boldsymbol{Ax}-\boldsymbol{b} for equalities. For inequalities, the difference vector is set to zero when it's value is lesser than zero (i.e. when the restriction is obeyed). The function keeps iterating until either the tolerance is met, the number of allowed iterations is exceeded or divergence is detected.

Note

adjust does not perform any consistency checks. When the system of constraints is contradictory (e.g. x>1 and x<0) this will result in either divergence or in exceeding the number of iterations.

DEPRECATED Adjust records in a data.frame

Description

A convenient wrapper around adjust that loops over all records in a data.frame. DEPRECATED. See match_restrictions.

Usage

adjustRecords(
  E,
  dat,
  adjust = array(TRUE, dim = dim(dat)),
  w = rep(1, ncol(dat)),
  verbose = FALSE,
  ...
)

Arguments

Value

An object of class adjustedRecords

Details

This function is not written to be especiallty speedy or memory-efficient, but to offer a convenient interface to adjusting a data.frame of records.

See Also

adjust

Adjusted object

Description

Adjusted object

Usage

## S3 method for class 'adjusted'
print(x, maxprint = 10, ...)

Arguments

Details

A adjusted object contains the adjusted vector as well as some information on how the adjustment was achieved. In particular, it contains the following slots (to be accessed with the dollar operator):

• \$x: the adjusted vector.

• \$accuracy: Maximum deviance of \$x from the constraints (see adjust for details).

• \$objective : Square root of objective function \sum_i(x_i-x^0_i)^2w_i.

• \$duration: proc_time object showing time it took to run the adjustment. (See proc.time).

• \$niter: Number of iterations.

• \$status: A character string stating whether the adjustment was successful, aborted, or if the maximum number of iterations was reached before convergence.

• \$method: 'sparse' or 'dense'.

See Also

adjust

DEPRECATED Adjusted records

Description

As this is output from deprecated adjustRecords, this object is deprecated as of version 0.2.0 as well.

Usage

## S3 method for class 'adjustedRecords'
print(x, ...)

## S3 method for class 'adjustedRecords'
summary(object, ...)

## S3 method for class 'adjustedRecords'
plot(x, ...)

Arguments

Details

The adjustedRecords object contains adjusted data as well as some information on the adjusting process. In particular:

• \$adjusted: data.frame similar to dat with adjusted values.

• $status: data.frame with the same number of rows as dat. Each row stores the information of one adjusted object.

When printed, only the first 10 rows of cbind(adjusted, status) are shown. Use summary for a quick overview. The plot method shows kernel density estimates of the accuracy and objective functions. To avoid densities at values below 0, the accuracy densities are evaluated under a sqrt-transform and transformed back before plotting. For the objective function values a log-transform is used.

See Also

adjustRecords

Alter numeric data records to match linear (in)equality constraints.

Description

Apply the successive projection algorithm to adjust each record in dat to satisfy a set of linear (in)equality constraints.

Usage

match_restrictions(
  dat,
  restrictions,
  adjust = NULL,
  weight = rep(1, ncol(dat)),
  remove_tag = TRUE,
  ...
)

Arguments

Value

dat, with values adapted.

Note on inequality restrictions

All inequality restrictions of the form a.x < b are treated as a.x \leq b. The idea is to project the original record x onto the boundary defined by the (in)equations. Projection on a boundary defined by a strict inequation is illdefined sice the value b in the restriction a.x < b is strictly outside the valid region.

See Also

tag_missing

Examples

# a very simple adjustment example

v <- validate::validator(
	x + y == 10,
	x > 0,
	y > 0
)

# x and y will be adjusted by the same amount
match_restrictions(data.frame(x=4,y=5), v)

# One of the inequalies violated
match_restrictions(data.frame(x=-1,y=5), v)

# Weighted distances: 'heavy' variables change less
match_restrictions(data.frame(x=4,y=5), v, weight=c(100,1))

# if w=1/x0, the ratio between coefficients of x0 stay the same (to first order)
x0 <- data.frame(x=4,y=5)
x1 <- match_restrictions(x0, v, weight=1/as.matrix(x0))

x0[,1]/x0[,2]
x1[,1] / x1[2]

# example of tag usage
v <- validate::validator(x + y == 1, x>0,y>0)
d <- data.frame(x=NA,y=0.5)
d <- tag_missing(d)
# impute
d[1,1] <- 1

# only the tagged values will be altered. The tag is
# removed afterwards.
match_restrictions(d,v)

Remove cell position tags

Description

Remove cell position tags

Usage

remove_tag(dat, ...)

Arguments

Value

dat with tag removed

See Also

Other tagging: tag_missing(), tagged_values()

DEPRECATED Generate sparse set of constraints.

Description

This function is deprecated. Please use function sparse_constraints from package lintools instead.

Usage

sparseConstraints(x, ...)

## S3 method for class 'editmatrix'
sparseConstraints(x, tol = 1e-08, ...)

## S3 method for class 'matrix'
sparseConstraints(x, b, neq = length(b), tol = 1e-08, ...)

## S3 method for class 'data.frame'
sparseConstraints(
  x,
  b,
  neq = length(b),
  base = min(x[, 2]),
  sorted = FALSE,
  ...
)

## S3 method for class 'sparseConstraints'
print(x, range = 1L:10L, ...)

Arguments

Value

Object of class sparseConstraints (see details).

Details

The sparseConstraints objects holds the system \boldsymbol{Ax}\leq \boldsymbol{b} in column sparse format, outside of R's memory. In R, it is a reference object. In particular, it is meaningless to

• Copy the object. You only will only generate a pointer to physically the same object.

• Save the object. The physical object is destroyed when R closes, or when R's garbage collector cleans up a removed sparseConstraints object.

Tag currently missing elements of a data.frame

Description

Attach an attribute that marks which cells are empty (NA).

Usage

tag_missing(dat, ...)

Arguments

Value

dat, tagged for missing values.

See Also

Other tagging: remove_tag(), tagged_values()

Retrieve tagged cell positions

Description

Retrieve tagged cell positions

Usage

tagged_values(dat, ...)

Arguments

Value

A logical matrix, or NULL

See Also

Other tagging: remove_tag(), tag_missing()