likelihood {demest} | R Documentation

## Specify first two levels of hierarchical model.

### Description

Specify the likelihood and part of the prior for a Poisson, binomial, or normal hierarchical model.

### Usage

    Poisson(formula, useExpose = TRUE, structuralZeros = NULL, boxcox = 0)

    CMP(
      formula,
      dispersion = Dispersion(),
      useExpose = TRUE,
      structuralZeros = NULL,
      boxcox = 0
    )

    Binomial(formula)

    Normal(formula, sd = NULL, priorSD = HalfT())

### Arguments

`formula` | A `formula` with response `mean` and names of dimensions of demographic series or dataset being modelled.
`useExpose` | Whether the model includes an exposure term. Defaults to `TRUE`.
`structuralZeros` | Location of any structural zeros in the data. An object of class `Values`, or, for the typical case, the word `"diag"`.
`boxcox` | Parameter determining transformation of rates or counts used in Poisson or CMP models. Defaults to 0, implying that a log transform is used.
`dispersion` | The dispersion parameter for a CMP model. An object of class `Dispersion`, typically created by a call to function `Dispersion`.
`sd` | Standard deviation in the likelihood for the normal model. If a value is not supplied, it is estimated from the data.
`priorSD` | An object of class `HalfT` specifying a non-default prior for the standard deviation in the likelihood for the normal model.

### Details

Specify a likelihood and prior of the form

y_i \sim Poisson(γ_i n_i)

log(γ_i) \sim N(x_i β, σ_i),

y_i \sim Poisson(γ_i)

log(γ_i) \sim N(x_i β, σ_i),

y_i \sim CMP(γ_i n_i, ν_i)

log(γ_i) \sim N(x_i β, σ_i),

log(ν_i) \sim N(m, s^2)

y_i \sim CMP(γ_i, ν_i)

log(γ_i) \sim N(x_i β, σ_i),

log(ν_i) \sim N(m, s^2)

y_i \sim binomial(n_i, γ_i)

logit(γ_i) \sim N(x_i β, σ_i),

or

y_i \sim normal(γ_i, φ^2 / w_i)

γ_i \sim N(x_i β, σ_i)

.

Subscript i denotes a cell within a multiway array, such as an array with dimensions age, sex, and time. In Poisson and binomial models, y_i is a count. The n_i term is an exposure in the case of Poisson and CMP (COMPoisson) models and a sample size in the case of binomial models. It is not supplied in calls to function `Poisson` or `Binomial`. In normal models y_i is a cell-specific value such as a mean, and w_i is a cell-specific weight. Weights are not supplied in calls to function `Normal`. Vector β contains main effects and interactions, such as age effects, time effects, and age-region interactions. Vector x_i is the ith row from the design matrix X.

The main effects and interactions are specified via the `formula` argument. For instance,

`mean ~ age * sex + time`

specifies a model with age, sex, and time main effects, and an age-sex interaction.

The main effects and interactions in a hierarchical model are only weakly identified: see the documentation for function `fetch` for details.

If a model has two or more levels, the second level typically contains more than just main effects and interactions. For instance, the second level of Poisson, binomial, and normal hierarchical models contains a variance term. The remaining parts of the second level, such as the variances, as well as any higher levels, are specified in calls to function `Model`, or to functions `estimateModel`, `estimateCounts`, or `estimateAccount`.

Poisson and CMP models allow structural zeros in the data, that is, cells whose value must be zero by definition. Examples include the number of pregnant males or the number of people transitioning straight from "single" to "divorced". The most general way to specify structural zeros is to supply an object of class `Values`, with zeros in the places where structural zeros are expected, and non-zero values elsewhere. The Values object only has to contain enough dimensions to specify the positions where the structural zeros appear: other dimensions will be added as needed. See below for an example.

The most common situation where structural zeros are required is when the data has origin and destination dimensions, and values on the diagonal are always zero. Setting `structuralZeros` to `"diag"` is equivalent to supplying a Values object with zeros on the diagonal.

### Value

An object of class `SpecLikelihood`.

### See Also

Functions `Poisson`, `Binomial`, and `Normal` are used as part of a call to function `Model`.

### Examples

    ## age effect, sex effect, age-sex interaction,
    ## and time effect
    Poisson(mean ~ age * sex + time)

    ## same model, but without exposure term
    Poisson(mean ~ age * sex + time, useExpose = FALSE)

    ## use formula notation to specify second-order interactions
    Binomial(mean ~ (age + sex + region)^2)

    Normal(mean ~ age + education + income)
    ## specify the exact value of the standard deviation
    Normal(mean ~ age + education + income,
           sd = 0.3)
    ## specify a non-default prior for the standard deviation
    Normal(mean ~ age + education + income,
           priorSD = HalfT(scale = 100))

    ## Specify structural zero on the diagonal
    struc.zeros <- Values(array(c(0, 1, 1,
                                  1, 0, 1,
                                  1, 1, 0),
                                dim = c(3, 3),
                                dimnames = list(region_orig = c("A", "B", "C"),
                                              region_dest = c("A", "B", "C"))))
    ## Note that the model contains age and sex dimensions. These
    ## The pattern of zeros specified by 'struc.zeros' will be
    ## replicated for each combination of these dimensions.
    Poisson(mean ~ region_orig * region_dest + age * sex,
            structuralZeros = struc.zeros)
    ## The same pattern of structural zeros, with zeros on the diagonal
    ## formed by the origina and destination dimensions, can be specified
    ## by using the word "diag"
    Poisson(mean ~ region_orig * region_dest + age * sex,
            structuralZeros = "diag")

[Package demest version 0.0.0.3.1 Index]