# Object Describing Saturated Aster Model Functions to construct and test conformance to the contract for objects of class `"asterdata"`. All other functions in this package take model descriptions of this form. ```r asterdata(data, vars, pred, group, code, families, delta, response.name = "resp", varb.name = "varb", tolerance = 8 * .Machine$double.eps) validasterdata(object, tolerance = 8 * .Machine$double.eps) is.validasterdata(object, tolerance = 8 * .Machine$double.eps) ``` ## Arguments - `data`: a data frame containing response and predictor variables for the aster model. - `vars`: a character vector containing names of variables in the data frame `data` that are components of the response vector of the aster model. - `pred`: an integer vector satisfying `length(pred) == length(vars)` specifying the arrows of the subgraph of the aster model corresponding to a single individual. Must be nonnegative and satisfy `all(pred < seq(along = pred))`. A zero value of `pred[j]` indicates the predecessor of node `j` is an initial node (formerly called root node) of the subgraph. A nonzero value of `pred[j]` indicates the predecessor of node `j` is node `pred[j]`. In either case there is an arrow in the subgraph from predecessor node to successor node. - `group`: an integer vector satisfying `length(group) == length(vars)` specifying the lines of the subgraph of the aster model corresponding to a single individual, which in turn specify the dependence groups. Must be nonnegative and satisfy `all(group < seq(along = group))`. Nonzero elements of `group` indicate nodes of the subgraph that are connected by a line and hence are in the same dependence group: nodes `j` and `group[j]` are connected by a line. Since nodes in the same dependence group must have the same predecessor, this requires `pred[group[j]] == pred[j]`. Since nodes in the same dependence group must be in the same family, this requires `code[group[j]] == code[j]`. It also requires that the dimension of the family specified by `code[j]` be the same as the number of nodes in the dependence group. Zero elements of `group` indicate nothing about dependence groups. The lines indicate a transitive relation. If there is a line from node `j1` to node `j2` and a line from node `j2` to node `j3` then there is also a line from node `j1` to node `j3`, but this line need not be specified by the `group` vector, and indeed cannot. If there is a dependence group with `d` nodes, then there are `choose(d, 2)` lines connecting these nodes, but the `group` vector can only specify `d - 1` lines which imply the rest. For example, if nodes `j1`, `j2`, `j3`, and `j4` are to make up a four-dimensional dependence group and `j1 < j2`, `j2 < j3`, and `j3 < j4`, we must have `group[j1] == 0`, `group[j2] == j1`, `group[j3] == j2`, and `group[j4] == j3`. This is forced by the requirement `all(group < seq(along = group))`. - `code`: an integer vector satisfying `length(code) == length(vars)` specifying the families corresponding to the dependence groups. This requires ``` all(code %in% seq(along = families) ``` Node `j` is in a dependence group with family described by `families[code[j]]`. Note that `group[j] == k` requires `families[j] == families[k]` when `k != 0`. - `families`: a list of family specifications (see `families`). Specifications of families not having hyperparameters may be abbreviated as character strings, for example, `"binomial"` rather than `fam.binomial()`. - `delta`: a numeric vector satisfying `length(delta) == length(vars)` specifying the degeneracies of the aster model for a single individual. The model specified is the limit as $s to infinity$ of nondegenerate models having conditional canonical parameter vector $theta + s delta$ (note that the conditional canonical parameter vector is always used here, regardless of whether conditional or unconditional canonical affine submodels are to be used). May be missing (and usually is) in which case $delta = 0$ is implied, meaning the limit is trivial (same as not taking a limit). - `response.name`: a character string giving the name of the response vector. - `varb.name`: a character string giving the name of the factor covariate that says which of the variables in the data frame `data` correspond to which components of the response vector. - `tolerance`: numeric >= 0. Relative errors smaller than `tolerance` are not considered in checking validity of normal location-scale data. - `object`: an object of class `"asterdata"`. The function `validasterdata` always returns `TRUE` or throws an error with an informative message. The function `is.validasterdata` never throws an error unless `object` has the wrong class, returning `TRUE` or `FALSE` according to whether `object` does or does not conform to the contract for class `"asterdata"`. ## Details Response variables in dependence groups are taken to be in the order they appear in the response vector. The first to appear in the response vector is the first canonical statistic for the dependence group distribution, the second to appear the second canonical statistic, and so forth. The number of response variables in the dependence group must match the dimension of the dependence group distribution. This function only handles the usual case where the subgraph for every individual is isomorphic to subgraph for every other individual and all initial nodes (formerly called root nodes) correspond to the constant one. Each row of `data` is the data for one individual. The vectors `vars`, `pred`, `group`, `code`, and `delta` (if not missing) describe the subgraph for one individual (which is the same for all individuals). In other cases for which this function does not have the flexibility to construct the appropriate object of class `"asterdata"`, such an object will have to be constructed by hand using R statements not involving this function or modifying an object produced by this function. See the following section for description of such objects. The functions `validasterdata` and `is.validasterdata` can be used to check whether objects constructed by hand have been constructed correctly. ## Returns an object of class `"asterdata"` is a list containing the following components - **redata**: a data frame having `nrow(data) * length(vars)` rows and containing variables having names in `setdiff(names(data), vars)` and also the names `"id"`, `response.name`, and `varb.name`. Produced from `data` using the `reshape` function. Each variable in `setdiff(names(data), vars)` is repeated `length(vars)` times. The variable named `response.name` is the concatenation of the variables in `data` with names in `vars`. The variable named `varb.name` is a factor having levels `vars` that says which of the variables in the data frame `data` correspond to which components of the response vector. The variable named `"id"` is an integer vector that says which of the individuals (which rows of `data`) correspond to which rows of `redata`. Not all objects of class `"asterdata"` need have an `id` variable, although all those constructed by this function do. - **repred**: an integer vector satisfying `length(repred) == nrow(redata)` specifying the arrows of the graph of the aster model for all individuals. Must be nonnegative and satisfy `all(repred < seq(along = repred))`. A zero value of `repred[j]` indicates the predecessor of node `j` is an initial node (formerly called root node) of the graph. A nonzero value of `repred[j]` indicates the predecessor of node `j` is node `repred[j]`. In either case there is an arrow in the graph from predecessor node to successor node. Note that `repred` is determined by `pred` but is quite different from it. Firstly, the lengths differ. Secondly, `repred` is not just a repetition of `pred`. The numbers in `pred`, if nonzero, are indices for the vector `vars` whereas the numbers in `repred`, if nonzero, are row indices for the data frame `redata`. - **initial**: a numeric vector specifying constants associated with initial nodes (formerly called root nodes) of the graphical model for all individuals. If `repred[j] == 0` then the predecessor of node `j` is an initial node associated with the constant `initial[j]`, which must be a positive integer unless the family associated with the arrow from this initial node to node `j` is infinitely divisible (the only such family currently implemented being Poisson), in which case `initial[j]` must be a strictly positive and finite real number. If `repred[j] != 0`, then `initial[j]` is ignored and may be any numeric value, including `NA` or `NaN`. This function always makes `initial` equal to `rep(1, nrow(redata))` but the more general description above is valid for objects of class `"asterdata"` constructed by hand . - **regroup**: an integer vector satisfying `length(regroup) == nrow(redata)` specifying the lines of the graph of the aster model for all individuals, which in turn specify the dependence groups. Must be nonnegative and satisfy `all(regroup < seq(along = regroup))`. Nonzero elements of `regroup` indicate nodes of the graph that are connected by a line and hence are in the same dependence group: nodes `j` and `regroup[j]` are connected by a line. Since nodes in the same dependence group must have the same predecessor, this requires `repred[regroup[j]] == repred[j]`. Since nodes in the same dependence group must be in the same family, this requires `recode[regroup[j]] == recode[j]`. It also requires that the dimension of the family specified by `recode[j]` be the same as the number of nodes in the dependence group. Zero elements of `regroup` indicate nothing about dependence groups. The lines indicate a transitive relation. If there is a line from node `j1` to node `j2` and a line from node `j2` to node `j3` then there is also a line from node `j1` to node `j3`, but this line need not be specified by the `group` vector, and indeed cannot. If there is a dependence group with `d` nodes, then there are `choose(d, 2)` lines connecting these nodes, but the `group` vector can only specify `d - 1` lines which imply the rest. For example, if nodes `j1`, `j2`, `j3`, and `j4` are to make up a four-dimensional dependence group and `j1 < j2`, `j2 < j3`, and `j3 < j4`, we must have `regroup[j1] == 0`, `regroup[j2] == j1`, `regroup[j3] == j2`, and `regroup[j4] == j3`. This is forced by the requirement `all(regroup < seq(along = regroup))`. Note that `regroup` is determined by `group` but is quite different from it. Firstly, the lengths differ. Secondly, `regroup` is not just a repetition of `group`. The numbers in `group`, if nonzero, are indices for the vector `vars` whereas the numbers in `regroup`, if nonzero, are row indices for the data frame `redata`. - **recode**: an integer vector satisfying `length(recode) == nrow(redata)` specifying the families corresponding to the dependence groups. This requires ``` all(recode %in% seq(along = families) ``` Node `j` is in a dependence group with family described by `families[recode[j]]`. Note that `regroup[j] == k` requires `recode[j] == recode[k]` when `regroup[j] != 0`. Also note that `recode` is determined by `code` but is different from it. Firstly, the lengths differ. Secondly, `recode` need not be just a repetition of `code`. This function always makes `recode` equal to `rep(code, each = nrow(redata))` but the more general description above is valid for objects of class `"asterdata"` constructed by hand . - **families**: a copy of the argument of the same name of this function except that any character string abbreviations are converted to objects of class `"astfam"`. - **redelta**: a numeric vector satisfying `length(redelta) == nrow(redata)` specifying the degeneracies of the aster model for all individuals. If not the zero vector, the degenerate model specified is the limit as $s to infinity$ of nondegenerate models having conditional canonical parameter vector $theta + s delta$ (note that the conditional canonical parameter vector is always used here, regardless of whether conditional or unconditional canonical affine submodels are to be used). Note that `redelta` is determined by `delta` but is different from it. Firstly, the lengths differ. Secondly, `redelta` need not be just a repetition of `delta`. This function always makes `redelta` equal to `rep(delta, each = nrow(redata))` but the more general description above is valid for objects of class `"asterdata"` constructed by hand . - **response.name**: a character string giving the name of the response variable in `redata`. For this function, a copy of the argument `response.name`. - **varb.name**: a character string giving the name of the varb variable in `redata`. For this function, a copy of the argument `varb.name`. In addition an object of class `"asterdata"` may contain (and those constructed by this function do contain) components `pred`, `group`, and `code`, which are copies of the arguments of the same names of this function. Objects of class `"asterdata"` not constructed by this function need not contain these additional components, since they may make no sense if the graph for all individuals is not the repetition of isomorphic subgraphs, one for each individual. ## See Also `families` and `subset.asterdata` ## Examples ```r data(test1) fred <- asterdata(test1, vars = c("m1", "n1", "n2"), pred = c(0, 1, 1), group = c(0, 0, 2), code = c(1, 2, 2), families = list("bernoulli", "normal.location.scale")) is.validasterdata(fred) ```

asterdata function