`sim_numbers.Rd`

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.

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, ...)

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_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.

a list with components

vector of values; it is of type `numeric`

if
all values are real and `complex`

otherwise.

a character vector of the types as above

Values of type "cp" (complex pairs) are represented by one element, the complex conjugate elements are NOT generated. (todo: maybe add an argument to control this)

The convention for the sign of a real eigenvalue is 1 and -1, not 0 and pi.

The checks for consistency between `type`

and `values`

are
not complete and only straightforward use is recommended.

The current defaults for the arguments, see the signature
above, require that at least one of `type`

and `abs`

is not
missing.

## one real number and one complex conjugated pair ## (maybe to specify a cubic polynomial through its roots) sim_numbers(type = c("r", "cp"))#> $values #> [1] 0.69582388+0.0000000i -0.00477644-0.0308629i #> #> $type #> [1] "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))#> $values #> [1] -1.0000000+0.0000000i 0.6309461-0.0836389i #> #> $type #> [1] "r" "cp" #>## 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))#> $values #> [1] -1+0.0000000i 0+0.4321713i #> #> $type #> [1] "r" "cp" #>## 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"#> $values #> [1] 0.7064338+0.0000000i -0.0372360-0.1764527i 3.0000000+0.0000000i #> #> $type #> [1] "r" "cp" "r" #>sim_numbers(type = c("r", "cp", "cp"), values = c(NA,NA,3i)) # type[3] = "cp"#> $values #> [1] -0.6801629+0.0000000i 0.3428605+0.5424012i 0.0000000+3.0000000i #> #> $type #> [1] "r" "cp" "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"#> $values #> [1] 0.09602416+0.0000000i -0.76836463+0.0448899i 3.00000000+0.0000000i #> #> $type #> [1] "r" "cp" "r" #>sim_numbers(type = c("r", "cp", NA), values = c(NA,NA,3i)) # type[3] = "cp"#> $values #> [1] -0.9705209+0.0000000i 0.1838019-0.4229773i 0.0000000+3.0000000i #> #> $type #> [1] "r" "cp" "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)) # }## simulate 10 reals with the default generators sim_numbers(rep("r", 10))#> $values #> [1] 0.17467589 -0.53157354 0.49363702 -0.77930863 0.20417834 0.71339728 #> [7] 0.06521611 -0.35420680 -0.82519942 -0.27381825 #> #> $type #> [1] "r" "r" "r" "r" "r" "r" "r" "r" "r" "r" #>## 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())#> $values #> [1] 2.060180-1.703645i -1.225989-0.155389i #> #> $type #> [1] "cp" "cp" #># 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") ## }