Set session-level output verbosity

Controls what analysis functions display by default. Three preset levels are available, and individual toggles can override specific settings within any level; a fourth, silent, prints nothing from the analysis functions and is for a script that keeps their results. Per-call arguments on analysis functions always take precedence over joutput() settings.

Usage

joutput(
  level,
  effect.size = NULL,
  regression.ci = NULL,
  means.ci = NULL,
  posthoc = NULL,
  diagnostics = NULL,
  case.processing = NULL,
  case.processing.detail = NULL,
  case.processing.filter = NULL,
  variable.id = NULL,
  value.id = NULL,
  ref.categories = NULL,
  model.layout = NULL,
  missing.notice = NULL,
  digits = NULL,
  quiet = FALSE,
  ...
)

Arguments

level

Character. One of minimal, standard (default), full, or silent. If omitted, prints the current settings. If NULL, resets to defaults (standard with no toggle overrides).

minimal: Stripped-down output for power users. Core results only – no Case Processing table (a one-line N statement in its place), no variable labels, no reference categories, no effect sizes, no CIs.
standard: Default. Suitable for teaching and routine use. Includes the Case Processing table when a filter or listwise deletion excluded cases (otherwise a one-line N statement), reference categories, effect sizes, and confidence intervals for means and mean differences (jt, jaov); regression coefficient CIs (jlm, jlogistic) are reserved for full. Variable labels are off by default (variable.id = "names"); request a label legend or in-table labels per call or via the variable.id toggle.
full: Everything in standard plus a variable label legend (variable.id = "legend"), regression coefficient confidence intervals, post-hoc tests, and the Case Processing table on every call, with the per-code missing breakdown. Diagnostic output is not part of it: see diagnostics.
silent: For a script that runs many analyses and keeps their results – a loop over models, a table built from several calls. The analysis functions (jdesc, jfreq, jt, jaov, jcrosstab, jlm, jlogistic, jcorr, jalpha, jscreen) print nothing, their notes included, and return their results as they always do; errors and warnings still show. Every other function prints as at standard, so a load's notice and the recode family's reminders stay, and the settings are standard's: a result made under silent holds what a standard call's would. A result is still there to keep: m <- jlm(...) saves it, as it does at any level. The same for one call: print = FALSE on any analysis function; and print = TRUE prints one call under a silent level.

effect.size

Logical or NULL. Override the level's default for effect size display.

regression.ci

Logical or NULL. Override the level's default for confidence intervals on regression coefficients (jlm, jlogistic). Off at minimal and standard, on at full.

means.ci

Logical or NULL. Override the level's default for confidence intervals on means and mean differences (jt, jaov). Off at minimal, on at standard and full.

posthoc

Logical or NULL. Override the level's default for post-hoc test display (jaov only).

diagnostics

Logical, character vector, or NULL. The diagnostic output of the analysis functions – assumption checks and the like – which no level turns on. TRUE shows every diagnostic a function has; FALSE (the setting until one is made) shows none; a character vector shows the ones named, each function taking those that apply to it:

"levene" – Levene's test for homogeneity of variance (jt, jaov);
"vif" – the variance inflation factors (jlm, jlogistic);
"qq" – the normal Q-Q plot of the residuals (jt, jaov, jlm);
"residuals", "scale" – the regression diagnostic plots (jlm);
"binned" – the binned residual plot (jlogistic);
"cooks", "leverage" – Cook's distance and residuals against leverage (jlm, jlogistic).

Name more than one with c(): joutput(diagnostics = c("levene", "vif")). A diagnostic prints with its brief interpretation (the note under a significant Levene's test, the lines under a VIF above 10) except at the minimal level, which prints the table alone. Unlike the other settings it is not cleared by a level call: joutput("full") leaves it as it was. joutput(NULL) turns it off with everything else. The same argument on jt(), jaov(), jlm() and jlogistic() sets it for one call.

case.processing

Three-state toggle for the Case Processing table – the block at the top of every analysis function's output (and of jscreen()'s) that accounts for the cases: the original N, each active filter (jcomplete, jsubset, per-call subset) with the cases it excluded, any cases dropped listwise by the analysis, and the N analyzed.

Every call states its N. What the toggle decides is the FORM: when the table does not print, a one-line N statement takes its place (Analysis N: 63 for the listwise functions; for jdesc, jfreq, and jcorr, the number of cases in the variable pool, adding the count complete on every variable when the per-variable Ns differ, and adding the excluded count whenever cases were excluded before the analysis). jscreen() prints no separate line: its header's Cases line states the count, adding the excluded count the same way (for example Cases: 53 (17 Excluded)).

NULL (auto; the standard tier's default) prints the table only when it has an exclusion row to show: a filter is active (shown even when it excluded 0 cases, as the reminder that it is active) or listwise deletion dropped at least one case. Otherwise the N statement. A clean call with no filter therefore gets one line, not a table of zeros.
TRUE (the full tier's default) prints the table on every call, even when its only rows are Original and the final N.
FALSE (the minimal tier's default) never prints the table or its missing-data breakdown; the N statement only.

In every form, a listwise-deletion row appears only when it dropped at least one case; a clean analysis never shows a Auto-listwise 0 row. A grouped jdesc() call has the same kind of row for cases missing on its grouping variable, labeled by =, shown on the same terms. The missing-data breakdown beneath the table (or beneath the N statement) is governed separately by case.processing.detail.

case.processing.detail

Detail tier for the Case Processing Summary's missing-data breakdown: "none" (no bottom table), "totals" (one summed missing row per variable), or "per_code" (per declared missing-value code plus system-missing). The minimal tier defaults to "none", standard to "totals", full to "per_code". Each row counts the variable's missing cases in the original data (From N and its percent); when a filter step ran, the row also shows how many of those cases the filter removed (Filtered) and how many remain in the analysis pool (the second From N), where listwise deletion takes them. The breakdown lists the analysis variables and, after them, any variables in the jcomplete() list that the analysis itself does not use, each tagged (jcomplete() only): every case jcomplete() drops is missing, and these rows say on which variable. The breakdown counts each variable's missing cases, so a case missing on two variables appears under both. A case that a jsubset() or per-call subset condition dropped because the condition could not be evaluated for it (a missing value in the condition's variables) is counted on that row of the upper table instead, as a (k missing) note after the condition, and gets no row here. Row form for the jcomplete()-only variables is set by case.processing.filter.

case.processing.filter

Row form for the jcomplete()-only variables in the missing-data breakdown: "list" (one row per variable), "collapse" (a single jcomplete()-only variables (k) row counting the cases missing on at least one of them), or "auto" (named up to three variables, collapsed from four; the jcomplete() list of a long survey battery is the case that collapses). A lone variable is always named. The minimal tier defaults to "collapse", standard to "auto", full to "list". Session-level only; the analysis functions take no per-call form of it.

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", with no labels block. "labels" replaces variable names with their labels in the analysis output itself (table rows, captions, crosstab dimnames, or jplot axis/legend titles) – best when labels are short. "legend" keeps names in place and prints a label legend at the function's mid position (for jlm/jlogistic between the coefficients and fit blocks; for jfreq under each variable's own table; elsewhere directly after the single table). "legend.bottom" keeps names in place and prints one consolidated legend at the very end of the output. The minimal and standard tiers default to "names"; the full tier defaults to "legend". Not a logical – TRUE/FALSE are not accepted.

value.id

Character or NULL. Value-label display mode for the categorical levels that appear in jfreq valid rows, the jt/jaov group descriptives, the jcrosstab axes, and the grouped jdesc headers. One of "both" ("code: label", degrading to a bare code where a code has no label), "values" (the bare stored code), or "labels" (the value label, degrading to the bare code per code where none exists). "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). Variables with no value labels render identically under every mode, so this is a no-op for plain numeric data. The minimal tier defaults to "labels"; the standard and full tiers default to "both". Distinct from variable.id, which governs the one-per-variable descriptive label. Not a logical.

ref.categories

Logical or NULL. Override the level's default for the reference categories block (registered dummies).

model.layout

Character or NULL. The order of jlm()'s and jlogistic()'s output: "coefficients" (every level's default) prints the Coefficients table first and the fit statistics after it; "fit" prints the fit statistics first. A level call puts it back to "coefficients", as it puts back the other settings.

missing.notice

Logical or NULL. Controls the notification about declared missing values that jload() emits for files whose variables carry them. TRUE prints it on every such load; FALSE suppresses it; NULL (the default) leaves the level's setting in place. The standard and full levels print it; the minimal level suppresses it.

digits

Integer or NULL. Number of decimal places shown for continuous statistics in the analysis-function output tables (range 0-7; digits = 0 prints whole numbers with no trailing decimal point). Every such statistic shows exactly this many places, trailing zeros included (0.100, not 0.1). Does not affect p-values, percentages, or integer quantities (counts, N, degrees of freedom), which keep their own fixed conventions, or the Min and Max columns of jdesc(), which show each variable's values to the decimal places its own data carry. All three preset levels default to 3.

quiet

Logical; default FALSE. When TRUE, joutput() applies the level/toggle change silently (nothing is printed). A bare joutput() status query, and a joutput("setting") query, always print regardless of quiet.

...

Not used. An input joutput() does not take – a misspelled argument – stops with "unused input" and the name as typed, in place of R's own "unused argument".

Value

Invisibly returns NULL. Called for its side effect of setting session options and printing the settings panel – in full for a bare status query, a level change or a reset, as the named settings alone for a joutput("setting") query, or as an echo of the settings a setting call touched.

Details

Diagnostic output – Levene's test, the VIF table, the regression diagnostic plots – is set apart from the levels: it is off at every level and is turned on with diagnostics, here or in an analysis call.

Call patterns

joutput(): Print the full settings panel: the level and every setting, each marked (override) where its value differs from the level's default.
joutput("setting"): Print one setting and nothing else – joutput("digits"), or several at once with joutput(c("posthoc", "digits")) – closed by a pointer to joutput() for the full panel. A setting name given WITHOUT an argument name is read as a query rather than as a level; the three level names and the setting names share no string, so the two readings cannot collide. Only the settings named are shown, and like the full panel a query prints regardless of quiet.
joutput("level"): Set the level, clearing any earlier overrides, then print the full panel – a level moves most settings at once. Settings given in the same call are applied as overrides on the new level. diagnostics is the exception: it belongs to no level, so a level call leaves it as it was.
joutput(setting = value, ...): Set one or more settings within the current level, then echo only what the call touched, closed by a pointer to joutput() for the full panel. The three Case Processing settings (case.processing, case.processing.detail, case.processing.filter) are echoed together whenever one of them is set, because each is read in light of the others: case.processing = FALSE silences the other two, and case.processing.detail = "none" silences case.processing.filter. Passing setting = NULL as a named argument leaves that setting as it is and echoes its current value.
joutput(NULL): Reset to the standard level with no overrides.

Session options

joutput() stores its settings through R's standard options() / getOption() mechanism, under two keys: .jst_output_level (the preset level) and .jst_output_toggles (a named list holding any per-slot overrides). getOption(".jst_output_level") returns the raw stored level – NULL until a level has been set, which the package reads as the "standard" default. joutput(NULL) clears both keys. The same values can be read or set with base R's options() directly; joutput() is the supported interface, adding validation and the settings display.

Color

jstats prints its titles in red and its status notes in yellow, and only where the color can be drawn: in the RStudio Console. Everywhere else the same text is printed plain – in RGui, in a terminal, in output captured with sink() or capture.output(), and in a knitr or Quarto document – because the codes that make the color would print there as stray characters.

One R option overrides the rule. options(jstats.color = TRUE) prints the colors wherever the output goes, which suits a console that draws color but is not RStudio's (Positron, VS Code, most terminals). options(jstats.color = FALSE) prints plain text everywhere, the RStudio Console included. Leaving it unset keeps the rule above. Like any R option it lasts for the session; put the line in your .Rprofile file to make it permanent.

Examples

joutput("standard")                       # effect sizes + means/diff CIs (jt, jaov)
#> Output Settings
#> Level: standard
#>   effect.size: ON
#>   regression.ci: OFF
#>   means.ci: ON
#>   posthoc: OFF
#>   diagnostics: OFF
#>   case.processing: AUTO
#>   case.processing.detail: TOTALS
#>   case.processing.filter: AUTO
#>   variable.id: NAMES
#>   value.id: BOTH
#>   ref.categories: ON
#>   model.layout: COEFFICIENTS
#>   missing.notice: ON
#>   digits: 3
#> 
joutput("standard", regression.ci = TRUE) # also show jlm/jlogistic coefficient CIs
#> Output Settings
#> Level: standard
#>   effect.size: ON
#>   regression.ci: ON (override)
#>   means.ci: ON
#>   posthoc: OFF
#>   diagnostics: OFF
#>   case.processing: AUTO
#>   case.processing.detail: TOTALS
#>   case.processing.filter: AUTO
#>   variable.id: NAMES
#>   value.id: BOTH
#>   ref.categories: ON
#>   model.layout: COEFFICIENTS
#>   missing.notice: ON
#>   digits: 3
#> 
joutput("full")                         # every statistic and every detail
#> Output Settings
#> Level: full
#>   effect.size: ON
#>   regression.ci: ON
#>   means.ci: ON
#>   posthoc: ON
#>   diagnostics: OFF
#>   case.processing: ON
#>   case.processing.detail: PER_CODE
#>   case.processing.filter: LIST
#>   variable.id: LEGEND
#>   value.id: BOTH
#>   ref.categories: ON
#>   model.layout: COEFFICIENTS
#>   missing.notice: ON
#>   digits: 3
#> 
joutput(diagnostics = TRUE)             # diagnostic output on, at any level
#> Output Settings
#>   diagnostics: ON
#> Run joutput() to see all settings.
#> 
joutput(diagnostics = c("levene", "vif")) # only the diagnostics named
#> Output Settings
#>   diagnostics: LEVENE, VIF
#> Run joutput() to see all settings.
#> 
joutput(diagnostics = FALSE)            # and off again
#> Output Settings
#>   diagnostics: OFF
#> Run joutput() to see all settings.
#> 
joutput(digits = 2)                     # set one setting; echoes only that one
#> Output Settings
#>   digits: 2 (override)
#> Run joutput() to see all settings.
#> 
joutput("digits")                       # show one setting
#> Output Settings
#>   digits: 2 (override)
#> Run joutput() to see all settings.
#> 
joutput()                               # show current settings
#> Output Settings
#> Level: full
#>   effect.size: ON
#>   regression.ci: ON
#>   means.ci: ON
#>   posthoc: ON
#>   diagnostics: OFF
#>   case.processing: ON
#>   case.processing.detail: PER_CODE
#>   case.processing.filter: LIST
#>   variable.id: LEGEND
#>   value.id: BOTH
#>   ref.categories: ON
#>   model.layout: COEFFICIENTS
#>   missing.notice: ON
#>   digits: 2 (override)
#> 
getOption(".jst_output_level")          # the raw option behind the level
#> [1] "full"
joutput(NULL)                           # reset to defaults
#> Output Settings
#> Reset to defaults (standard, no toggle overrides).
#>