sim_numbers: Simulation based on polar form specifications

Description

Simulate real and complex numbers from polar form specifications. The numbers may be partially or fully specified. The distributions of absolute values and arguments/signs are specified independently.

Usage

sim_numbers(type = rep(as.character(NA), length(abs)),
            abs = rep(as.numeric(NA), length(type)),
            sign = rep(as.numeric(NA), length(type)), values = NULL, ...)

Arguments

type

character vector specifying the types of the eigenvalues, see Details.

abs

vector of absolute values (moduli).

sign

vector of signs (for reals) and arguments (for complex numbers), see Details for interpretation.

values

values, see details.

…

additional arguments to be passed to sim_real and sim_complex.

Value

a list with components

values

vector of values; it is of type numeric if all values are real and complex otherwise.

type

a character vector of the types as above

Details

sim_numbers simulates a vector of real and complex numbers with given distributions of their polar parts. It is possible also to fix some of the numbers or one of their polar parts. The length of the simulated vector is inferred from the length of type or abs, so one of them must be provided. sim_numbers as a flexible front-end for sim_real and sim_complex.

sim_numbers generates a vector of values with types specified by argument type and/or inferred from argument values. The recommended way to use sim_numbers is to provide argument type.

type[i] specifies the type of the i-th element of the result: real (type[i]=="r"), complex (type[i]=="c") or representing a complex conjugate pair (type[i]=="cp"). If values is provided, the imaginary parts of its non-NA elements are used to fill NA elements of type ("r" if zero, "cp" otherwise).

Some (or even all) values may be fixed or partially fixed with the help of arguments abs, sign and values. A non-missing value of values[i] fixes the i-th element of the result to that value. Simlarly abs[i] fixes the modulus and sign[i] fixes the sign/argument of the i-th element. If values[i] is not NA, then it takes precedence and abs[i] and sign[i] are ignored.

For real numbers sign is the sign with possible values 1 (positive) or -1 (negative). For complex numbers, sign is the argument and is in the interval (-pi,pi).

If values is supplied, then NA entries in type are replaced by "r" or "cp" depending on whether or not the imaginary parts of the corresponding entries in values are equal to zero. A check is done for consistency when both type[i] and values[i] are non-missing. Generally, values is meant to be used for values that are fixed and available directly in Cartesian form, to avoid having to fill the corresponding entries of abs and sign.

NA entries of abs and sign are filled with simulated values, the remaining entries are considered fixed and left unchanged. The default generator is uniform (0,1) for abs, uniform (-pi,pi) for the argument of complex values, and 1 or -1 with p=1/2 for the sign of real values.

To specify a different generator for the moduli and absolute values, use argument absgen, giving it a function or the name of a function. The arguments for this function can be specified by absarg (as a list). Similarly, the generator for arguments of complex numbers can be specified by arggen and argarg. Finally, the probability for the real numbers to be positive is given by signprob. These arguments are not in the signature of the function since they are passed on directly (via "...") to the underlying sim_complex and sim_real, see their documentation and the examples below for further details.

Examples

Run this code

# NOT RUN {
## one real number and one complex conjugated pair
## (maybe to specify a cubic polynomial through its roots)
sim_numbers(type = c("r", "cp"))

## here the real value is fixed to have modulus 1, leaving the sign unspecified
sim_numbers(type = c("r", "cp"), abs = c(1, NA))

## now the real value is fixed to 1,
##     the complex pair has argument  +-pi/2, and free modulus:
sim_numbers(type = c("r", "cp"), abs = c(1, NA), sign = c(0, pi/2))


## using argument 'values' to fix some values;
## here the the third value is fixed:
sim_numbers(type = c("r", "cp", "r"), values = c(NA,NA,3))  # type[3] = "r"
sim_numbers(type = c("r", "cp", "cp"), values = c(NA,NA,3i)) # type[3] = "cp"

## type[3] can be left NA since it can be inferred from values[3]:
sim_numbers(type = c("r", "cp", NA), values = c(NA,NA,3))  # type[3] = "r"
sim_numbers(type = c("r", "cp", NA), values = c(NA,NA,3i)) # type[3] = "cp"

## it is an error to have a mismatch between args `type' and value:
# }
# NOT RUN {
sim_numbers(type = c("r", "cp", "cp"), values = c(NA,NA,3))
sim_numbers(type = c("r", "cp", "r"), values = c(NA,NA,3i))
# }
# NOT RUN {
## simulate 10 reals with the default generators
sim_numbers(rep("r", 10))

## simulate modulus from Rayleigh distribution
##
rR <- function(n, sigma = 1) sigma * sqrt(-2*log(runif(n)))
sim_numbers(type = c("cp", "cp"), absgen = rR, absarg = list())

# test the the components are N(0,1)
## (not run to save time for CRAN check)
## \dontrun{
## v <- sim_numbers(type = rep("cp", 10000), absgen = "rR",
##                  absarg = list(sigma = 1))
## ks.test(Re(v$values), "pnorm")
## ks.test(Im(v$values), "pnorm")
## }
# }