Set or display session-level package options

Controls session-wide settings that affect how the package handles missing-value information and related conventions. joptions complements joutput: joutput governs output verbosity and tiering, while joptions holds session-wide conventions plus a small number of per-function display defaults (the jcorr() cell layout via corr.layout, and the jfreq() missing-value range detail via missing.detail), and the width at which runtime message prose wraps (message.width). Settings are read fresh on each function call: changing a setting after data has been loaded does not retroactively transform data already in memory. jconvert is the explicit transform path for data already in the workspace.

Usage

joptions(
  missing.convention = NULL,
  missing.convention.codes = NULL,
  data.dir = NULL,
  output.dir = NULL,
  style = NULL,
  style.dir = NULL,
  corr.layout = NULL,
  missing.detail = NULL,
  message.width = NULL,
  quiet = FALSE,
  ...
)

Arguments

missing.convention: One of "none", "spss", "stata", or "sas" (any capitalization is accepted). See Slots. A slot name arriving here unnamed and positionally is read instead as a status query on that slot (see Call patterns).
missing.convention.codes: Numeric vector, length 1 to 3. See Slots.
data.dir: Character string (length 1), or NULL. See Slots.
output.dir: Character string (length 1), or NULL. See Slots.
style: Character, length 1: a style's name, or NULL to leave it. See Slots.
style.dir: Character string (length 1), or NULL. See Slots.
corr.layout: One of "wide" or "stacked", or NULL. See Slots.
missing.detail: One of "totals", "per_code", or "all", or NULL. See Slots.
message.width: One of "auto", "narrow", "medium", "wide", a whole number between 40 and 120, or NULL. See Slots.
quiet: Logical; default FALSE. When TRUE, joptions() applies the change silently, suppressing the settings echo, its pointer, the convention nudge, and the note that a data folder was created (the folder is created all the same). It has no effect on a status query, which makes no change to silence: the bare joptions() panel and a joptions("slot") query both print regardless.
...: Not used. An input joptions() 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 the side effect of updating session options and printing the settings panel – in full for a bare status query or a reset, as the named slots alone for a joptions("slot") query, or as an echo of the slots a setting call touched.

Slots

missing.convention: Character, length 1. One of "none", "spss", "stata", or "sas". Default: "none", meaning no stated preference: loaded data is preserved as-is, and a call that would create a fresh missing-value declaration stops with a guided error asking you to choose a convention – the package never infers one. A set value states your working convention: it supplies the target for fresh missing-value declarations on columns with no existing convention, becomes the default target for jconvert when to is not given, and is the reference point for the environment-scan notice (see below). Data already loaded is never changed by setting this; jconvert is the explicit transform path.
missing.convention.codes: Numeric vector, length 1 to 3, whole numbers, no duplicates. Sign unconstrained. Default: c(-99, -98, -97). The recommended missing-value code set used by jconvert when translating Stata-style or SAS-style missing values into SPSS-style numeric codes: the first tag letter (.a or .A) takes the first code, the second the second, and so on, so a column carrying more distinct tags than there are codes cannot be converted. Also the source of the value the missing keyword creates in a jrecode or jencode map under an SPSS-style convention (the first code).
data.dir: Character string (length 1), or NULL. Default: NULL. When NULL, jsave writes bare-filename saves to the working directory and jload searches the working directory. When set, names a folder (relative to the working directory) used as both the save target for bare-filename saves and as the first directory searched on bare-filename loads. If the folder does not exist it is created when the setting is made, with a note saying so unless quiet = TRUE (nested paths are created in full); a folder that cannot be created stops the call and leaves every setting as it was. jsave creates the folder again if it has been removed since. To clear a previously-set folder back to this default, pass data.dir = NULL or data.dir = "" (an empty string; see Call patterns). Filenames containing a directory separator (a forward slash, or a backslash on Windows) bypass this setting and are taken literally. Write the folder with forward slashes: a folder typed with single backslashes, which R reads as special characters, stops the call with nothing set.
output.dir: Character string (length 1), or NULL. Default: NULL. The folder a file of output is written into: when NULL, a table written with a bare file name goes in the working directory; when set, names the folder (relative to the working directory, or a full path) such a file goes in. Created when the setting is made, as data.dir is, and created again at the first write if it has been removed since; cleared with output.dir = NULL or output.dir = "". A file name with a folder in it bypasses the setting. Distinct from data.dir on purpose: data come in from one folder, and output goes out to another.
style: Character, length 1. Default: "apa". The style a publication table is made in when its call names none: the built-in "apa" style, or the name of a style file ("myjournal" for myjournal.jstyle) found in the style folder, the working directory or your jstats folder, or a path to one. Checked when it is set: a style that cannot be found or read stops the call with nothing changed. Set back with style = "apa".
style.dir: Character string (length 1), or NULL. Default: NULL. A folder of style files, searched before the working directory and your jstats folder (tools::R_user_dir("jstats")), and the folder a copied style is saved in. Created when the setting is made; cleared with style.dir = NULL or style.dir = "".
corr.layout: Character, length 1. One of "wide" or "stacked". Default: "wide". The default cell layout for jcorr when three or more variables are correlated: "wide" puts r and p on one line with N beneath; "stacked" stacks r, p, and N on three lines for a narrower table that fits more variables. A per-call layout argument to jcorr() overrides this. It lives here rather than in joutput because it is specific to one function's output, not a tiered analysis-content toggle.
missing.detail: Character, length 1. One of "totals", "per_code", or "all". Default: "per_code". Governs how much of a declared missing-value RANGE jfreq spells out in its Missing block. "totals" collapses the whole band into one row; "per_code" prints one row per observed in-band value, at most 10, with the remainder gathered into a single line at the foot of the block; "all" prints every observed in-band value with no cap. Declared discrete codes always print in full at every setting – the cap applies only to values reached by a range. A per-call missing.detail argument to jfreq() overrides this. Like corr.layout it lives here rather than in joutput because it is specific to one function's output.
message.width: Character or numeric, length 1. One of "auto", "narrow" (50 columns), "medium" (76), "wide" (90), or a whole number between 40 and 120. Default: "auto". The target width at which the package wraps runtime MESSAGE prose – errors, warnings and notes. "auto" follows the console pane, which R keeps current as the pane is resized, so it is resolved afresh for each message rather than fixed when it is set. A width outside 40 to 120 is refused rather than quietly adjusted. Analysis TABLES are not affected and do not reflow: prose can be re-wrapped without losing information, whereas breaking a correlation matrix mid-row would destroy the alignment that makes it readable.

Call patterns

joptions(): Print the full settings panel: all nine slots, whatever the convention. The missing.convention.codes row is labeled as SPSS-style; jconvert to SPSS-style missing values uses those codes under any setting.
joptions("slot"): Print one slot and nothing else – joptions("data.dir"), or several at once with joptions(c("data.dir", "corr.layout")) – closed by a pointer to joptions() for the full panel. A slot name given WITHOUT an argument name is read as a query rather than a setting; the nine slot names and the four missing.convention values share no string, so the two readings cannot collide. A named argument is always a setting, which leaves joptions(missing.convention = "data.dir") an error. Only the slots named are shown: a query pulls in no related slot, and missing.convention.codes appears whenever it is asked for, whatever the convention. Like the full panel, a query prints regardless of quiet.
joptions(NULL): Reset all slots to defaults, then print the full panel – everything changed.
joptions(slot = value, ...): Set one or more slots, then echo only what the call touched: the slots named, plus missing.convention whenever missing.convention.codes is set (the codes are read in light of the convention), and plus missing.convention.codes when missing.convention is set to "spss" (under any other convention the codes are dormant and the row is omitted), closed by a pointer to joptions() for the full panel. The other four slots are independent and are not pulled in. Passing slot = NULL as a named argument leaves that slot at its current value – useful for setting one slot without touching another – and echoes that unchanged value back. To reset a single slot to its default, pass the default value explicitly (e.g. joptions(missing.convention = "none")). data.dir is the one slot whose default is itself NULL, so for it a named NULL is that default: joptions(data.dir = NULL) clears the folder back to the working directory, as data.dir = "" does.

Environment-scan notice

Setting missing.convention to "spss", "stata", or "sas" triggers a one-time scan of globalenv() for data frames whose missing-value convention differs from the newly-set value. When mismatches exist, a notice lists the affected data frames and suggests jconvert: frames whose declared columns all carry one convention read "use X-style missing values", while frames with a genuine internal majority read "predominantly use". The notice is informational; nothing is changed. Plain data frames with no declared missing values – including the course datasets in their standard form – do not trigger the notice.

Examples

joptions()                                        # show current settings
#> Options Settings
#> Missing-value convention: SPSS-style
#> SPSS-style missing value codes: -99, -98, -97
#> Data folder: Working directory
#> Output folder: Working directory
#> Style: apa
#> Style folder: Not set
#> Correlation layout: wide
#> Missing-value detail: per_code
#> Message width: Auto (currently 79)
#> 
joptions("data.dir")                              # show one slot
#> Options Settings
#> Data folder: Working directory
#> Run joptions() to see all settings.
#> 
joptions(c("data.dir", "corr.layout"))            # show two
#> Options Settings
#> Data folder: Working directory
#> Correlation layout: wide
#> Run joptions() to see all settings.
#> 

# Setting a convention echoes the convention and its codes, then scans
# the workspace and notes any data frames whose missing-value
# convention differs (see the Environment-scan notice section):
joptions(missing.convention = "spss")             # set, echo, scan notice
#> Options Settings
#> Missing-value convention: SPSS-style
#> SPSS-style missing value codes: -99, -98, -97
#> Run joptions() to see all settings.
#> 
joptions(missing.convention = "sas")              # SAS-style: .A, .B, ...
#> Options Settings
#> Missing-value convention: SAS-style
#> Run joptions() to see all settings.
#> 
joptions(missing.convention.codes = c(-99, -98))      # set, echo, no scan
#> Options Settings
#> Missing-value convention: SAS-style
#> SPSS-style missing value codes: -99, -98
#> Run joptions() to see all settings.
#> 
joptions(data.dir = file.path(tempdir(), "Data")) # set save/load folder
#> Options Settings
#> Data folder: /tmp/RtmpMNZa3u/Data
#> Run joptions() to see all settings.
#> 
#> Created the data folder:
#>   /tmp/RtmpMNZa3u/Data
#> 
                                                  # (created if absent)
joptions(data.dir = NULL)                         # back to the working directory
#> Options Settings
#> Data folder: Working directory
#> Run joptions() to see all settings.
#> 
joptions(output.dir = file.path(tempdir(), "Tables")) # where tables are written
#> Options Settings
#> Output folder: /tmp/RtmpMNZa3u/Tables
#> Run joptions() to see all settings.
#> 
#> Created the output folder:
#>   /tmp/RtmpMNZa3u/Tables
#> 
joptions(output.dir = NULL)                       # back to the working directory
#> Options Settings
#> Output folder: Working directory
#> Run joptions() to see all settings.
#> 
joptions(message.width = 60)                      # wrap message prose at 60
#> Options Settings
#> Message width: 60
#> Run joptions() to see all settings.
#> 
joptions(message.width = "narrow")                # preset width (50 columns)
#> Options Settings
#> Message width: Narrow (50)
#> Run joptions() to see all settings.
#> 
joptions(message.width = "auto")                  # follow the console pane
#> Options Settings
#> Message width: Auto (currently 79)
#> Run joptions() to see all settings.
#> 
joptions(missing.convention = "stata",
         missing.convention.codes = c(-99, -98, -97)) # set both
#> Options Settings
#> Missing-value convention: Stata-style
#> SPSS-style missing value codes: -99, -98, -97
#> Run joptions() to see all settings.
#> 
joptions(missing.convention = "spss",
         missing.convention.codes = NULL)             # set mc, leave codes
#> Options Settings
#> Missing-value convention: SPSS-style
#> SPSS-style missing value codes: -99, -98, -97
#> Run joptions() to see all settings.
#> 
joptions(NULL)                                    # reset all to defaults
#> Options Settings
#> Missing-value convention: None selected
#> SPSS-style missing value codes: -99, -98, -97
#> Data folder: Working directory
#> Output folder: Working directory
#> Style: apa
#> Style folder: Not set
#> Correlation layout: wide
#> Missing-value detail: per_code
#> Message width: Auto (currently 79)
#>