Random variables backed by factor-like arrays of arbitrary dimension.

- x
(multiple options) The object to convert to an

`rvar`

:A vector of draws from a distribution.

An array where the first dimension represents draws from a distribution. The resulting

`rvar`

will have dimension`dim(x)[-1]`

; that is, everything except the first dimension is used for the shape of the variable, and the first dimension is used to index draws from the distribution (see**Examples**). Optionally, if`with_chains == TRUE`

, the first dimension indexes the iteration and the second dimension indexes the chain (see`with_chains`

).An

`rvar`

.

- dim
(integer vector) One or more integers giving the maximal indices in each dimension to override the dimensions of the

`rvar`

to be created (see`dim()`

). If`NULL`

(the default),`dim`

is determined by the input.**NOTE:**This argument controls the dimensions of the`rvar`

, not the underlying array, so you cannot change the number of draws using this argument.- dimnames
(list) Character vectors giving the names in each dimension to override the names of the dimensions of the

`rvar`

to be created (see`dimnames()`

). If`NULL`

(the default), this is determined by the input.**NOTE:**This argument controls the names of the dimensions of the`rvar`

, not the underlying array.- nchains
(positive integer) The number of chains. The if

`NULL`

(the default),`1`

is used unless`x`

is already an`rvar`

, in which case the number of chains it has is used.- with_chains
(logical) Does

`x`

include a dimension for chains? If`FALSE`

(the default), chains are not included, the first dimension of the input array should index draws, and the`nchains`

argument can be used to determine the number of chains. If`TRUE`

, the`nchains`

argument is ignored and the second dimension of`x`

is used to index chains. Internally, the array will be converted to a format without the chain index. Ignored when`x`

is already an`rvar`

.- ...
Arguments passed on to

`base::factor`

`levels`

an optional vector of the unique values (as character strings) that

`x`

might have taken. The default is the unique set of values taken by`as.character(x)`

, sorted into increasing order*of*. Note that this set can be specified as smaller than`x`

`sort(unique(x))`

.`labels`

*either*an optional character vector of labels for the levels (in the same order as`levels`

after removing those in`exclude`

),*or*a character string of length 1. Duplicated values in`labels`

can be used to map different values of`x`

to the same factor level.`exclude`

a vector of values to be excluded when forming the set of levels. This may be factor with the same level set as

`x`

or should be a`character`

.`ordered`

logical flag to determine if the levels should be regarded as ordered (in the order given).

`nmax`

an upper bound on the number of levels; see ‘Details’.

An object of class `"rvar_factor"`

representing a `factor`

-like random variable.

A subtype of `rvar()`

that represents a (possibly multidimensional) sample of
a factor or an ordered factor. It is otherwise very similar to the basic `rvar()`

:
it is backed by a multidimensional array with draws as the first dimension.
The primary difference is that the backing array has class `"factor"`

(for `rvar_factor()`

)
or `c("ordered", "factor")`

(for `rvar_ordered()`

). If you
pass a factor or ordered factor to `rvar()`

it will automatically return
an object with the classes `"rvar_factor"`

or `c("rvar_ordered", "rvar_factor")`

.

See `rvar()`

for more details on the internals of the random variable datatype.

`as_rvar_factor()`

to convert objects to `rvar_factor`

s. See `rdo()`

, `rfun()`

, and
`rvar_rng()`

for higher-level interfaces for creating `rvar`

s.

```
set.seed(1234)
# To create a "scalar" `rvar_factor`, pass a one-dimensional array or a vector
# whose length (here `4000`) is the desired number of draws:
x <- rvar(sample(c("a","a","a","b","c"), 4000, replace = TRUE))
x
#> rvar_factor<4000>[1] mode <entropy>:
#> [1] a <0.87>
#> 3 levels: a b c
# Create random vectors by adding an additional dimension:
x_array <- array(c(
sample(c("a","a","a","b","c"), 4000, replace = TRUE),
sample(c("a","a","b","c","c"), 4000, replace = TRUE),
sample(c("b","b","b","b","c"), 4000, replace = TRUE),
sample(c("d","d","b","b","c"), 4000, replace = TRUE)
), dim = c(4000, 4))
rvar_factor(x_array)
#> rvar_factor<4000>[4] mode <entropy>:
#> [1] a <0.68> c <0.76> b <0.36> b <0.76>
#> 4 levels: a b c d
# You can also create ordered factors
rvar_ordered(x_array)
#> rvar_ordered<4000>[4] mode <dissent>:
#> [1] a <0.41> c <0.47> b <0.17> b <0.47>
#> 4 levels: a < b < c < d
# arguments of factor() and ordered() are passed down by the constructor
# e.g. we can reorder levels of an ordered factor:
rvar_ordered(x_array, levels = c("d","c","b","a"))
#> rvar_ordered<4000>[4] mode <dissent>:
#> [1] a <0.41> c <0.47> b <0.17> b <0.47>
#> 4 levels: d < c < b < a
# Unlike base factors, rvar factors can be matrices or arrays:
rvar_factor(x_array, dim = c(2, 2))
#> rvar_factor<4000>[2,2] mode <entropy>:
#> [,1] [,2]
#> [1,] a <0.68> b <0.36>
#> [2,] c <0.76> b <0.76>
#> 4 levels: a b c d
# If the input to rvar_factor() is an array with a `"levels"` attribute, it
# will use those as the levels of the factor
y_array <- t(array(rbinom(3000, 1, c(0.1, 0.5, 0.9)) + 1, dim = c(3, 1000)))
rvar(y_array)
#> rvar<1000>[3] mean ± sd:
#> [1] 1.1 ± 0.30 1.5 ± 0.50 1.9 ± 0.29
# with levels
attr(y_array, "levels") = c("a", "b")
rvar_factor(y_array)
#> rvar_factor<1000>[3] mode <entropy>:
#> [1] a <0.46> a <1.00> b <0.45>
#> 2 levels: a b
```