SPSS-like frequency tables for categorical variables

Prints an SPSS-style frequency table (Freq, Total %, Valid %, Cum. %) for each variable supplied. Designed for use with unquoted variable names, and also accepts a plain vector.

Usage

jfreq(
  data,
  ...,
  subset = NULL,
  variable.id = NULL,
  value.id = NULL,
  missing.detail = NULL,
  case.processing.detail = NULL,
  print = NULL
)

Arguments

data: A data frame, or a single variable: a column of a data frame or a vector.
...: Unquoted variable name(s) within data. None when data is a single variable. A c() of names, bare or quoted, is read as the names.
subset: An optional unquoted logical expression (e.g. Group == 1) to subset cases for this call only. Applied after jcomplete and jsubset. Does not affect other function calls. Written in R syntax and checked the way jsubset() checks a filter: subset = NOT(Age < 40), for example, is refused with the corrected subset = !(Age < 40) shown (see jsubset for a translation table).
variable.id: Character or NULL. Variable label display mode: one of "both", "names", "labels", "legend", or "legend.bottom". "names" shows variable names only; "both" shows "name: label"; "labels" uses each variable's label as its table caption (best for short labels); "legend" prints a label legend under each variable's own table; "legend.bottom" prints one consolidated legend after all tables. NULL (default) defers to joutput()'s variable.id setting. Not a logical. (Replaces the former inline Type/label block.)
value.id: Character or NULL. Value-label display mode for the frequency-table valid rows: "both" ("code: label"), "values" (bare code), or "labels" (the label, degrading to the bare code where a code has none). "legend" and "legend.bottom" keep the bare code in the table and print a value-label legend after it ("legend" per-table, "legend.bottom" consolidated where multiple tables are produced). A no-op for variables with no value labels. NULL (default) defers to joutput()'s value.id setting. Not a logical.
missing.detail: Character or NULL. How much of a declared missing-value RANGE the Missing block spells out: one of "totals" (collapse the whole band into a single row), "per_code" (one row per observed in-band value, at most 10, with the remainder gathered into one line at the foot of the block), or "all" (every observed in-band value, no cap). NULL (default) defers to the missing.detail setting in joptions, whose own default is "per_code". Declared discrete codes always print in full at every setting; the cap applies only to values reached by a range. Has no effect on a variable with no declared range.
case.processing.detail: Accepted for API symmetry. jfreq's Case Processing Summary is top-table only (no missing-data breakdown), so this argument has no effect; per-variable code detail already appears in each variable's frequency table. The table itself prints only when a filter is active (even one that excluded no cases); otherwise a one-line N statement takes its place. See ?joutput (case.processing).
print: Logical or NULL. FALSE prints nothing – no table, no title, no note – and returns the result as every call does; errors and warnings still show. TRUE prints even under joutput("silent"). NULL (the default) prints unless the level is silent. For a script that keeps many results and wants no output: see joutput.

Value

Invisibly returns a list of class jst_freq containing: frequencies (a named list, one element per variable; each element is itself a list with seven components – valid, the valid-row frequency table as a data frame; udm, the declared-missing rows as a data frame, empty when the variable has none; na, the system-missing row as a one-row data frame, or NULL when there are none; total, valid_count, and missing, the case counts; and var_label, the variable's display label) and sample_info (pipeline and missing data counts).

Details

Output is structured consistently with jdesc(): a single red "Frequencies" title is printed first, followed by the default-data note (if a juse() default was used), any pipeline messages, and then either the Case Processing table (when a filter is active) or a one-line statement of the N. Each variable then gets its own block: its caption on its own line (the name, or name and label, as variable.id directs), a blank line, and the frequency table. Declared missing values get Missing rows of their own below the valid rows. The frequency table ends with a Total row showing the post-pipeline N.

When the table has Missing rows, a "Total valid" row closes the valid rows – the valid N, the base of every Valid % – and, when there is more than one Missing row, a "Total missing" row closes them, as in SPSS FREQUENCIES.

A value that has a value label but no case gets a row of its own at 0, as an empty level of a factor does: a valid value, a declared missing code, and a labelled code inside a declared missing-value range when the range's values are listed one by one. A range with no case in it keeps its single "range" row. When more than ten labelled values (or factor levels) in one table have no case, none of them is listed, and a line under the table says how many there are.

In a text variable, cells with no text – empty, or holding only spaces or tabs – are tabulated together in one row labeled <blank>. They are counted as valid values, not as missing: a blank is absent data in one file and a real answer in the next (a column coded "Y" or left empty), and only you know which. A short footnote under the table says how many there are; jencode gives them a code, and jdeclare_missing with codes = "" declares them missing. <blank> is the row's label, not a value in the data: a filter selects those cells by what they hold, subset = trimws(Source) == "" (or Source == "" for the empty cells alone, leaving out those holding only spaces).

A list column (a tibble's, or the geometry column of a spatial data frame), a raw column, and a column that is itself a data frame cannot be tabulated, and are refused before anything prints.

For haven-labelled variables, value labels and numeric codes are combined in the frequency table rows (e.g. 1: Strongly Oppose) at the default value.id setting. Where variable labels are shown, they are shown for all variable types, not only haven-labelled ones.

Given a single variable instead of a data frame, as in jfreq(community$Region), jfreq() tabulates that variable. A column of a data frame is tabulated in its frame, exactly as jfreq(community, Region) tabulates it: the frame's jsubset() and jcomplete() settings and its registrations apply. Any other vector is tabulated on its own. A second variable, and a subset condition naming another variable, need the data frame, and each stops with that form of the call.

With a juse() default set, a name the default data frame has is that frame's variable, as in every jstats function, even when a separate object of the same name exists in the workspace: jfreq(Region) tabulates the default frame's Region, and a line under "Using default data frame" says so. A separate object is read only when the default frame has no variable of that name, or when no default is set.

Examples