equate (version 2.0-3)

freqtab: Frequency Distribution Tables

Description

Functions for creating and manipulating frequency tables of class freqtab.

Usage

## S3 method for class 'default':
freqtab(x, scales, items, na.rm = TRUE, ...)
## S3 method for class 'table':
freqtab(x, ...)
as.freqtab(x, scales, drop = FALSE, ...)
is.freqtab(x)
## S3 method for class 'freqtab':
as.data.frame(x, row.names = NULL,
  optional = FALSE, drop = FALSE, ...)
scales(x, margin = 1)
margin(x, margin = 1)
margins(x)
## S3 method for class 'freqtab':
droplevels(x, ...)
## S3 method for class 'freqtab':
head(x, ...)
## S3 method for class 'freqtab':
tail(x, ...)

Arguments

x

either an object (vector or data.frame) containing total scores or item responses with which total scores will be calculated, or an object inheriting from class freqtab. In the freqtab function, the

scales

list of vectors containing the score scales for each column in x. length(scales) should equal ncol(x).

items

list of vectors of column indices (numbers or column names) with which total scores will be computed for x it contains item responses. length(items) should equal ncol(x).

na.rm

logical with default TRUE specifying whether or not missing item responses should be ignored, i.e., treated as 0, when calculating total scores.

row.names, optional

arguments passed to as.data.frame, currently ignored.

drop

logical, with default FALSE, indicating whether or not unused factor levels, or score values with zero counts, should be dropped. See below for details.

margin

integer vector specifying the margin(s) over which frequencies should be summed.

...

further arguments passed to or from other functions.

Value

• A table array with dimensions equal to the number of score scales. In most cases, this will be a univariate or bivariate distribution, but multivariate distributions are supported. scales and margins return numeric vectors.

Details

freqtab creates a frequency table from a vector or data.frame of scores. When the items argument is included, scores are assumed to be item responses, which are summed to create total scores. The scores are tabulated and stored as an array, with dimensions for each variable. Note that in previous versions of the freqtab class the frequency table was stored as a data.frame. This is no longer the case. Instead, the table is stored as an array and converted to a data.frame when printed or manipulated with the head and tail methods.

as.data.frame converts an object of class freqtab to data.frame. droplevels returns x with any unused factor levels, or levels with zero counts, removed.

When x is an object of class table, freqtab simply modifies the attributes and converts to class freqtab. In this case, x must already be structured similar to a freqtab object, with the first dimension containing counts for total scores, and remaining dimensions containing counts for one or more anchor tests.

as.freqtab converts a 'flat' contingency table (see ftable) to class freqtab with the appropriate attributes. A flat contingency table is the data.frame version of a freqtab object, where the first column contains the total score scale, the last column contains counts, and the columns in between contain different anchor test score combinations. is.freqtab tests for class freqtab.

scales extracts the measurement scales for the variables specified in margin, with margin = 1 referring to the total score scale, and subsequent margins referring to anchor tests. margin is a wrapper for margin.table, which itself is a simple wrapper for summing over marginal counts, i.e., apply(x, margin, sum). And margins returns the number of dimensions, i.e., score variables, in a frequency table.

The main difference between the freqtab class and other tabulation classes, like table and ftable, is that the dimnames, i.e., the score scales, are required to be numeric. This facilitates plotting with plot.freqtab, equating with the equate function, and descriptive statistics with the summary.freqtab and other methods.

See Also

table, ftable, summary.freqtab, plot.freqtab

Examples

# Univariate distribution with score scale
set.seed(2005)
x <- round(rnorm(1000, 100, 10))
head(freqtab(x, scales = 70:130))

# Existing frequency table converted to class "freqtab"
# The first score of zero, with zero counts, is dropped
head(as.freqtab(ACTmath[, 1:2], drop = TRUE))

# Bivariate distribution
# Reduce y to the anchor test margin (2)
ny <- freqtab(x = KBneat$y, scales = list(0:36, 0:12))
margin(ny, margin = 2)

# Summing scored item responses with the PISA data
attach(PISA)
r6items <- paste(items$itemid[items$clusterid == "r6"])
r7items <- paste(items$itemid[items$clusterid == "r7"])
pisa67 <- freqtab(students[students$book == 6, ],
	items = list(r6items, r7items),
	scales = list(0:16, 0:14))
detach(PISA)

# Scales for both margins
# Zero total score is unobserved
scales(pisa67, 1:2)
scales(droplevels(pisa67), 1:2)