equate (version 2.0.8)

freqtab: Frequency Distribution Tables

Description

Functions for creating and manipulating frequency tables of class “freqtab”.

Usage

freqtab(x, ...)
# S3 method for default
freqtab(x, scales, items, design, na.rm = TRUE, ...)
as.freqtab(x, scales, design, drop = FALSE, ...)
# S3 method for table
freqtab(x, design, ...)
# S3 method for freqtab
as.data.frame(x, row.names = NULL, optional = FALSE, drop = FALSE, ...)
# S3 method for freqtab
head(x, ...)
# S3 method for freqtab
tail(x, ...)
scales(x, margin = 1)
margin(x, margin = 1)
margins(x)
# S3 method for freqtab
droplevels(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 first column in x must be the total test; any remaining columns may contain anchor scores. See below for details.

...

further arguments passed to or from other functions.

scales

list of vectors containing the score scales for each score scale in x.

items

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

design

the equating design used in data collection. For univariate x, design = "eg" is assumed for equivalent groups. For multivariate x, design = "ng" is assumed for nonequivalent groups. Single-groups and counterbalanced designs must be specified with design = "sg" and design = "cb".

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.

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.

row.names, optional

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

margin

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

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.

Methods (by class)

• default: Default method for a data.frame of item responses, a data.frame of total and anchor scores, or a vector of total scores.

• table: Method for tables.

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.

design is used to set the dimnames of the frequency table, with total1 and total2 used with single and counterbalanced groups, and total and anchor(s) used otherwise. design also sets the design attribute, which is used in equate.

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

# NOT RUN {
# 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)

# }