vcd (version 1.4-8)

# lodds: Calculate Generalized Log Odds for Frequency Tables

## Description

Computes (log) odds and their asymptotic variance covariance matrix for R (by strata) tables. Odds are calculated for pairs of levels of one array dimension (typically a response or focal variable) separately for each level of all stratifying dimensions. See Friendly et al. (2011) for a sketch of a general theory.

## Usage

```lodds(x, …)
# S3 method for default
lodds(x, response = NULL, strata = NULL, log = TRUE,
ref = NULL, correct = any(x == 0), …)# S3 method for formula
lodds(formula, data = NULL, …,
subset = NULL, na.action = NULL)odds(x, log = FALSE, …)# S3 method for lodds
coef(object, log = object\$log, …)
# S3 method for lodds
vcov(object, log = object\$log, …)
# S3 method for lodds
print(x, log = x\$log, …)
# S3 method for lodds
confint(object, parm, level = 0.95, log = object\$log, …)# S3 method for lodds
dim(x, ...)
# S3 method for lodds
dimnames(x, ...)

# S3 method for lodds
as.array(x, log=x\$log, …)
# S3 method for lodds
t(x)
# S3 method for lodds
aperm(a, perm, …)```

## Arguments

x

an object. For the default method a k-way matrix/table/array of frequencies. The number of margins has to be at least 2.

response

Numeric or character indicating the margin of a \$k\$-way table `x` (with \$k\$ greater than 2) that should be employed as the response variable. By default the first dimension is used.

strata

Numeric or character indicating the margins of a \$k\$-way table `x` (with \$k\$ greater than 2) that should be employed as strata. Ignored if `response` is specified. By default all dimensions except the first are used as strata.

ref

numeric or character. Reference categories for the (non-stratum) row and column dimensions that should be employed for computing the odds. By default, odds for profile contrasts (or sequential contrasts, i.e., successive differences of adjacent categories) are used. See details below.

formula

a formula specifying the variables used to create a contingency table from `data`. A conditioning formula can be specified; the conditioning variables will then be used as strata variables.

data

either a data frame, or an object of class `"table"` or `"ftable"`.

subset

an optional vector specifying a subset of observations to be used.

na.action

a function which indicates what should happen when the data contain `NA`s. Ignored if `data` is a contingency table.

log

logical. Should the results be displayed on a log scale or not? All internal computations are always on the log-scale but the results are transformed by default if `log = TRUE`.

correct

logical or numeric. Should a continuity correction be applied before computing odds? If `TRUE`, 0.5 is added to all cells; if numeric (or an array conforming to the data) that value is added to all cells. By default, this not employed unless there are any zero cells in the table, but this correction is often recommended to reduce bias when some frequencies are small (Fleiss, 1981).

a, object

an object of class `lodds` as computed by `lodds`.

perm

numeric or character vector specifying a permutation of strata.

arguments passed to methods.

parm

a specification of which parameters are to be given confidence intervals, either a vector of numbers or a vector of names. If missing, all parameters are considered.

level

the confidence level required for the `confint` method.

## Value

An object of class `lodds`, with the following components:

coefficients

A named vector, of length (R-1) x (C-1) x `prod(dim(x)[strata])` containing the log odds. Use the `coef` method to extract these from the object, and the `confint` method for confidence intervals. For a two-way table, the names for the log oddsare constructed in the form Ri:Rj using the table names for rows and columns. For a stratified table, the names are constructed in the form Ri:Rj|Lk.

vcov

Variance covariance matrix of the log odds.

dimnames

Dimension names for the log odds, considered as a table of size (R-1, C-1, `dim(x)[strata]`). Use the `dim` and `dimnames` methods to extract these and manipulate the log odds in relation to the original table.

dim

Corresponding dimension vector.

contrasts

A matrix C, such that `C %*% as.vector(log(x))` gives the log odds ratios. Each row corresponds to one log odds, and is all zero, except for 2 elements of `c(1, -1)` for a given 2 x 1 subtable.

log

A logical, indicating the value of `log` in the original call.

## Details

For an n-way table with the `response` variable containing R levels, (log) odds are formed (by default) for the set of (R-1) contrasts among the response levels. The `ref` argument allows these to be specified in a general way.

`ref = NULL` (default) corresponds to “profile contrasts” (or sequential contrasts or successive differences) for ordered categories, i.e., R1--R2, R2--R3, R3--R4, etc., and similarly for the column categories. These are sometimes called “local odds” or “adjacent odds”.

`ref = 1` gives contrasts with the first category; `ref = dim(x)` gives contrasts with the last category.

Note that all such parameterizations are equivalent, in that one can derive all other possible odds from any non-redundant set, but the interpretation of these values depends on the parameterization.

See the help page of `plot.loddsratio` for related visualization methods. There is as yet no plot method for `lodds` objects.

## References

A. Agresti (2013), Categorical Data Analysis, 3rd Ed. New York: Wiley.

Fleiss, J. L. (1981). Statistical Methods for Rates and Proportions. 2nd Edition. New York: Wiley.

M. Friendly (2000), Visualizing Categorical Data. SAS Institute, Cary, NC.

Friendly, M., Turner, H,, Firth, D., Zeileis, A. (2011). Advances in Visualizing Categorical Data Using the vcd, gnm and vcdExtra Packages in R. Correspondence Analysis and Related Methods (CARME 2011). http://www.datavis.ca/papers/adv-vcd-4up.pdf

`loddsratio` for log odds ratios; `confint` for confidence intervals; `coeftest` for z-tests of significance

## Examples

```# NOT RUN {
## artificial example
set.seed(1)
x <- matrix(rpois(5 * 3, 7), ncol = 5, nrow = 3)
dimnames(x) <- list(Row = head(letters, 3), Col = tail(letters, 5))

x_lodds <- lodds(x)
coef(x_lodds)
x_lodds
confint(x_lodds)
summary(x_lodds)

### 2 x 2 x k cases
##data(CoalMiners, package = "vcd")
#lor_CM <- loddsratio(CoalMiners)
#lor_CM
#coef(lor_CM)
#confint(lor_CM)
#confint(lor_CM, log = FALSE)
#
### 2 x k x 2
#lor_Emp <-loddsratio(Employment)
#lor_Emp
#confint(lor_Emp)
#
### 4 way tables
#data(Punishment, package = "vcd")
#lor_pun <- loddsratio(Freq ~ memory + attitude | age + education, data = Punishment)
#lor_pun
#confint(lor_pun)
#summary(lor_pun)
#
## fit linear model using WLS
#lor_pun_df <- as.data.frame(lor_pun)
#pun_mod1 <- lm(LOR ~ as.numeric(age) * as.numeric(education),
#               data = lor_pun_df, weights = 1 / ASE^2)
#anova(pun_mod1)
#
### illustrate ref levels
#VA.fem <- xtabs(Freq ~ left + right, subset=gender=="female", data=VisualAcuity)
#VA.fem
#loddsratio(VA.fem)                  # profile contrasts
#loddsratio(VA.fem, ref=1)           # contrasts against level 1
#loddsratio(VA.fem, ref=dim(VA.fem)) # contrasts against level 4
#

# }
```