Descriptive statistics for one or more variables

Computes basic descriptive statistics (N, non-missing, min, max, mean, SD) for one or more variables in a data frame. Prints a formatted table and invisibly returns the underlying results as a data frame.

Usage

jdesc(
  data,
  ...,
  by = NULL,
  subset = NULL,
  variable.id = NULL,
  numeric = NULL,
  categorical = NULL,
  count = NULL,
  value.id = NULL,
  case.processing.detail = NULL,
  digits = NULL,
  print = NULL
)

Arguments

data: A data frame, or a single variable: a column of a data frame or a numeric vector.
...: Unquoted variable names within data. None when data is a single variable. A c() of names, bare or quoted, is read as the names.
by: An optional unquoted grouping variable name. When provided, descriptives are computed separately for each group, with a separate titled table per dependent variable. Each table's Total is the group's size and Non_missing the cases in it with a value on that variable, the same two columns as the ungrouped table. A case with a missing value on the grouping variable belongs to no group and so to no table; the Case Processing Summary reports those cases on a by = row (shown only when there are any), and its N counts the cases that have a group. The grouping variable cannot also be one of the variables described.
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" shows each variable's label in place of its name (in the descriptives table; for grouped output, as the per-variable caption and the grouping-variable column header) – best for short labels; "legend" and "legend.bottom" keep names and print a label legend after the table. NULL (default) defers to joutput()'s variable.id setting. Not a logical.
numeric: Optional. Variables to treat as continuous for this call (the per-call counterpart of jnumeric()), named bare or in quotes, several with c(): numeric = Age. Its only effect in jdesc() is to suppress the structural "seems categorical" descriptive caution for those variables; the descriptives themselves are computed the same way regardless.
categorical: Not supported by jdesc() yet. jdesc() always computes numeric descriptives; supplying categorical raises an error pointing to jfreq() for a categorical summary. (How jdesc() should handle an asserted-categorical variable is a parked design decision.)
count: Optional. Variables to treat as counts for this call (the per-call counterpart of jcount()), named bare or in quotes, several with c(). A count is numeric-like here, so it behaves like numeric: it suppresses the "seems categorical" caution for those variables.
value.id: Character or NULL. Value-label display mode for the grouped descriptive headers (the by-group 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 grouping variables with no value labels, and for ungrouped calls. NULL (default) defers to joutput()'s value.id setting. Not a logical.
case.processing.detail: Per-call override of the Case Processing Summary detail tier: one of "none", "totals", or "per_code". NULL (default) uses the active joutput() level default. The Case Processing table itself prints only when a filter or listwise deletion excluded cases; otherwise a one-line N statement takes its place. See ?joutput (case.processing).
digits: Integer or NULL. Number of decimal places for continuous statistics in the output tables (range 0-7; digits = 0 prints whole numbers with no trailing decimal point). Does not affect p-values, percentages, or integer quantities (counts, N, degrees of freedom), which keep their own fixed conventions. The Min and Max columns are values of the variables rather than statistics: each variable shows as many decimal places as its own data carry, up to this many, so a variable measured in whole numbers prints 0 and 75 beside another's 4.8 and 9.7, and the two columns are aligned on the decimal point. NULL (default) defers to joutput()'s digits setting (default 3).
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_desc containing: descriptives (data frame of statistics, or NULL for grouped output), and sample_info (pipeline and missing data counts). Also prints a formatted table to the console.

Details

Output is structured consistently with jfreq(): a single red "Descriptive Statistics" 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 – for several variables, the size of the variable pool and how many cases are complete on all of them. One shared table follows, a row per variable. Variable labels are not printed in the table; variable.id puts them in the row names or in a legend under the table.

Summarizes numeric, haven-labelled, logical, numeric-coded factor, and numeric-looking character variables. Variables that cannot be summarized — text factors, text character variables, and date/time variables — are skipped with a warning directing the user to jfreq() (date/time variables are not supported here). When every requested variable is unsummarizable, jdesc() stops with an error. Also accepts a simple numeric vector. Supports grouped descriptives via the by parameter.

Given a single variable instead of a data frame, as in jdesc(community$Age), jdesc() describes that variable. A column of a data frame is described in its frame, exactly as jdesc(community, Age) describes it: the frame's jsubset() and jcomplete() settings and its registrations apply. Any other vector is described on its own. A second variable, by, 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: jdesc(Age) describes the default frame's Age, 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.

With by, the case-processing summary counts the cases that have a group. Where it is a single line rather than a table (at the minimal output level, for example), that line counts "Grouped Cases" once the grouping variable has excluded any.

A haven-labelled variable is summarized by its codes, like any numeric variable. One whose codes look like categories gets a warning that the statistics may not be meaningful, with jfreq() as the alternative.

Examples