beta_builder {sim2Dpredictr}

Create a Parameter Vector from Lattice Locations

Description

Specify the locations in the lattice/image that have non-zero parameters as well as the values for those parameters, and the function creates the parameter vector that matches the correct locations in the design matrix.

Usage

beta_builder(
  row.index,
  col.index,
  im.res,
  B0 = 0,
  B.values,
  index.type = "manual",
  decay.fn = "gaussian",
  phi = 0.5,
  max.d = Inf,
  h,
  w,
  bayesian = FALSE,
  bayesian.dist = NULL,
  bayesian.scale = NULL,
  output.indices = TRUE
)

Arguments

row.index, col.index

Vectors of row/columns indices for non-zero parameters. If index.type = "manual", each vector should contain specific coordinates. If index.type = "rectangle", each vector should specify rectangle length; e.g. row.index = 1:3 means the rectangle's 'length' is from rows 1 to 3. If index.type = "ellipse", the arguments should be scalar values specifying the row/column coordinates for the center of the ellipse. If index.type = "decay", the arguments should specify the row/column coordinates, respectively, of the peak parameter value.

im.res

A vector specifying the dimension/resolution of the image. The first entry is the number of 'rows' in the lattice/image, and the second entry is the number of 'columns' in the lattice/image.

B0

is the "true" intercept value; default is 0.

B.values

is a vector "true" parameter values for non-zero parameters. The order of assignment is by row. If B.values argument is a single value, then all non-zero parameters are assigned to that value, unless decay.fn has been specified, in which case B.values is the "peak", and non-zero parameters decay smoothly by distance.

index.type

is one of index.type = c("manual", "rectangle", "ellipse", "decay")

• index.type = "manual" uses row.index and col.index arguments to specify manually selected non-zero locations. This setting is good for irregular shaped regions.

• index.type = "rectangle" uses row.index and col.index arguments to specify a rectangular region of non-zero parameters.

• index.type = "ellipse" uses w and h arguments to specify elliptical region of non-zero parameters.

• index.type = "decay" allows the user to specify a peak location with row.index and col.index, as with index.type = "ellipse". However, the non-zero parameter values decay as a function of distance from the peak.

decay.fn

An argument to specify the decay function of non-zero parameters decay from the peak when index.type = "decay". Options are "exponential" or "gaussian". The rate of decay is given by B.values * exp(-phi * d) and B.values * exp(-phi * d ^ 2) for "exponential" and "gaussian", respectively. The default is decay.fn = "gaussian". Note that d is the Euclidean distance between the peak and a specified location, while phi is the rate of decay and is set by the user with phi.

phi

A scalar value greater than 0 that determines the decay rate of non-zero parameters when index.type = "decay". The default is phi = 0.5.

max.d

When index.type = "decay", max.d determines the maximum Euclidean distance from the peak that is allowed to be non-zero; parameters for locations further than max.d from the peak are set to zero. If this argument is not set by the user then all parameter values are determined by the decay function.

w, h

If index.type = "ellipse" then the width and height of the ellipse, respectively.

bayesian

If TRUE, then parameters are drawn from distributions based on initial B.values vector. Default is FALSE.

bayesian.dist

When bayesian = TRUE, specifies the distribution of the parameters. Options are "gaussian" and uniform.

bayesian.scale

A list. When bayesian = TRUE and bayesian.dist = "gaussian", specifies the sd for the distributions of parameters. When bayesian = TRUE and bayesian.dist = "uniform", specifies the width for the uniform distributions for the parameters. The first entry should be one of "unique", "binary". If "unique", then the second entry in the list should be a vector with length equal to B.values + 1 with unique values for the sd's/widths, including B0. B0 can be set to a constant value by setting the first position of bayesian.scale[[2]] to 0. If "binary", then the second entry in the list should be a 3-element vector whose first entry is the sd/width of B0, second entry the sd/width of "non-zero" or "important" parameters, and the third entry is the sd/width of the "zero" or "irrelevant" parameters.

output.indices

If output.indices = TRUE, then the first element of the returned list contains the indices for the non-zero parameter locations (Default). If output.indices = FALSE, then only the parameter vector is returned.

Value

A 2-element list containing (1) indices for the locations of "true" non-zero parameters, and (2) a parameter vector.

Note

The order of the parameters is by row. That is, if the lattice/image is 4x4, then parameters 1-4 make up the first row, 5-8 then second, and so forth.

Examples

## example
Bex1 <- beta_builder(row.index = c(5, 5, 6, 6),
                    col.index = c(5, 6, 5, 6),
                    im.res = c(10, 10),
                    B0 = 0, B.values = rep(1, 4))

## True non-zero parameters are locations 45, 46, 55, 56 in B
## i.e. locations (5, 5), (5, 6), (6, 5), (6, 6)

## Suppose that we index rows by i = 1, ... , I
##                       cols by j = 1, ... , J

## The index for a parameter is given by  J * (i - 1) + j
## In this example, I = 10, J = 10; Thus:

## (5, 5) -> 10 * (5 - 1) + 5 = 45
## (5, 6) -> 10 * (5 - 1) + 6 = 46
## (6, 5) -> 10 * (6 - 1) + 5 = 55
## (6, 6) -> 10 * (6 - 1) + 6 = 45
Bex1
## length 101 (includes B0 w/ 100 variable parameter values)
length(Bex1$B)

## example: index.type = "rectangle"
Bex2 <- beta_builder(row.index = 12:15, col.index = 6:19,
                    im.res = c(20, 20), B0 = 16,
                    B.values = 1:(length(12:15) * length(6:19)),
                    index.type = "rectangle")

Bex2
matrix(Bex2$B[-1], nrow = 20, byrow = TRUE)

## example: index.type = "ellipse"
Bex3 <- beta_builder(row.index = 4, col.index = 5,
                    im.res = c(10, 10),
                    B0 = 16, B.values = 3,
                    index.type = "ellipse",
                    h = 5, w = 4)
Bex3
matrix(Bex3$B[-1], nrow = 10, byrow = TRUE)

## decaying parameter values
Bex4 <- beta_builder(row.index = 10, col.index = 20,
                     im.res = c(30, 30), B0 = 0, B.values = 10,
                     index.type = "decay", max.d = 7,
                     output.indices = FALSE)
inf_2D_image(B = Bex4, im.res = c(30, 30), binarize.B = FALSE)

Bex5 <- beta_builder(row.index = 4, col.index = 5,
                     im.res = c(10, 10),
                     B0 = 16, B.values = 5,
                     index.type = "ellipse",
                     h = 5, w = 4,
                     bayesian = TRUE,
                     bayesian.dist = "gaussian",
                     bayesian.scale = list("binary", c(0, 1, 0.25)))

inf_2D_image(B = Bex5$B, im.res = c(10, 10), binarize.B = FALSE)