Skip to contents

Register categorical variables for dummy coding in regression

Source: R/pipeline.R
jdummy.Rd

jdummy() registers a categorical variable so that jlm() automatically expands it into dummy (indicator) variables when it appears in a regression formula. The original data frame is never modified. Several variables can be registered in one call; the ref setting then applies to each of them.

Registrations are stored per dataset, so switching juse() between datasets preserves each dataset's registrations independently.

Usage

jdummy(
  data,
  ...,
  ref = "auto",
  show = FALSE,
  remove = FALSE,
  clear.all = FALSE,
  max.categories = 20L
)

Arguments

data

A data frame, or omit to use the juse() default. jdummy(NULL) clears the dummy registrations on the juse() default data frame (or, with no default set, the only frame that carries them; if several do, it asks rather than wiping all). Registrations are stored under the data frame's name, so it is given as a name (or as a place such as lst$d); an expression that builds one, such as a subset, is refused, with the two lines that name it first. For the same reason jdummy(data, NULL) and remove = TRUE work on a name whose data frame has since been removed.

...

One or more unquoted variable names to register. The variable may be haven-labelled, numeric, logical, character, or a factor: for a factor the levels are the categories, in level order, and a level with no cases is left out; for a text variable the distinct values are the categories, in alphabetical order, and cells with no text (empty, or holding only spaces or tabs) are one more category, <blank>, placed last. Omit (along with data) to display all current registrations. A lone NULL in the variable slot – jdummy(data, NULL) – clears that frame's dummy registrations.

ref

The reference category (excluded from the regression model). Can be a numeric code, a quoted label name, first, last, or auto (the default). Under auto, a variable with three or more categories takes its first (lowest) category as the reference. A two-category variable is parameterized so the category representing presence is the one modeled: if the value labels are a recognized yes/no pair (yes/no, y/n, true/false, t/f, present/absent, success/failure; capitalization does not matter), the affirmative category is modeled and the negative category is the reference – the same rule jlogistic() uses to encode its outcome. Otherwise, if one of the two codes is 1, that category is modeled (so a 1 = Yes / 2 = No variable models Yes, and a 0/1 variable models 1). A text variable holding one word or nothing ("Y" or blank) models the word, with <blank> as the reference. Applied to every variable named in the call; to use different reference categories, register the variables in separate calls. One value only. Every variable is checked before any is registered, so a call that stops – a reference one of the variables does not have, for example – registers none of them. When the reference was chosen by auto, the printed "Reference category:" line ends with (default; change with ref =); a reference you name carries no such tag.

show

Logical. If TRUE, prints the dummy coding scheme table showing the pattern of 0s and 1s. Default is FALSE.

remove

Logical. If TRUE, removes the registration for the specified variable(s). Default is FALSE.

clear.all

Logical. If TRUE, clears dummy registrations on every data frame that carries them. Default is FALSE.

max.categories

Integer. Maximum number of categories a variable may have to be dummy-coded; a variable with more raises an error. Raise it to dummy-code a higher-cardinality variable. Default 20L.

Value

Invisibly returns NULL. Called for its side effect.

See also

jstats for the package overview, workflow conventions, and complete function listing.

Examples

juse(community)
#> Default data frame set to: community
jdummy(Region)                       # Register, first category as reference
#> Dummy Variable Registration
#> Using default data frame: community
#> 
#>   Variable: Region
#>   Reference category: Region_North (default; change with ref =)
#>   Dummy variables: Region_South, Region_East, Region_West
#>   Cases: 103 (0 missing)
#> 
#> Note: this registration is stored for this session only.
#> To keep it across sessions, save the data frame in R format (.rds):
#>   jsave(community, "community.rds")
#> 
#> Next session, load that file to restore the registration:
#>   jload("community.rds")
#> 
jdummy(community, Region)            # The same, naming the data frame
#> Dummy Variable Registration
#>   Variable: Region
#>   Reference category: Region_North (default; change with ref =)
#>   Dummy variables: Region_South, Region_East, Region_West
#>   Cases: 103 (0 missing)
#> 
#> Note: this registration is stored for this session only.
#> To keep it across sessions, save the data frame in R format (.rds):
#>   jsave(community, "community.rds")
#> 
#> Next session, load that file to restore the registration:
#>   jload("community.rds")
#> 
jdummy(data = community, Region)     # ... or naming it as data =
#> Dummy Variable Registration
#>   Variable: Region
#>   Reference category: Region_North (default; change with ref =)
#>   Dummy variables: Region_South, Region_East, Region_West
#>   Cases: 103 (0 missing)
#> 
#> Note: this registration is stored for this session only.
#> To keep it across sessions, save the data frame in R format (.rds):
#>   jsave(community, "community.rds")
#> 
#> Next session, load that file to restore the registration:
#>   jload("community.rds")
#> 
jdummy(Region, Education)            # Register several at once
#> Dummy Variable Registration
#> Using default data frame: community
#> 
#>   Variable: Region
#>   Reference category: Region_North (default; change with ref =)
#>   Dummy variables: Region_South, Region_East, Region_West
#>   Cases: 103 (0 missing)
#> 
#>   Variable: Education
#>   Reference category: Education_Some_high_school (default; change with ref =)
#>   Dummy variables: Education_High_school_graduate, Education_Some_college, Education_Bachelor_s_degree, Education_Graduate_degree
#>   Cases: 103 (6 missing)
#> 
#> Note: registrations are stored for this session only.
#> To keep them across sessions, save the data frame in R format (.rds):
#>   jsave(community, "community.rds")
#> 
#> Next session, load that file to restore the registrations:
#>   jload("community.rds")
#> 
jdummy(Region, ref = "last")         # Last category as reference
#> Dummy Variable Registration
#> Using default data frame: community
#> 
#>   Variable: Region
#>   Reference category: Region_West
#>   Dummy variables: Region_North, Region_South, Region_East
#>   Cases: 103 (0 missing)
#> 
#> Note: this registration is stored for this session only.
#> To keep it across sessions, save the data frame in R format (.rds):
#>   jsave(community, "community.rds")
#> 
#> Next session, load that file to restore the registration:
#>   jload("community.rds")
#> 
jdummy(Region, ref = 4)              # Reference by numeric code
#> Dummy Variable Registration
#> Using default data frame: community
#> 
#>   Variable: Region
#>   Reference category: Region_West
#>   Dummy variables: Region_North, Region_South, Region_East
#>   Cases: 103 (0 missing)
#> 
#> Note: this registration is stored for this session only.
#> To keep it across sessions, save the data frame in R format (.rds):
#>   jsave(community, "community.rds")
#> 
#> Next session, load that file to restore the registration:
#>   jload("community.rds")
#> 
jdummy(Region, ref = "East")         # Reference by value label
#> Dummy Variable Registration
#> Using default data frame: community
#> 
#>   Variable: Region
#>   Reference category: Region_East
#>   Dummy variables: Region_North, Region_South, Region_West
#>   Cases: 103 (0 missing)
#> 
#> Note: this registration is stored for this session only.
#> To keep it across sessions, save the data frame in R format (.rds):
#>   jsave(community, "community.rds")
#> 
#> Next session, load that file to restore the registration:
#>   jload("community.rds")
#> 
jdummy(Region, show = TRUE)          # Show coding scheme
#> Dummy Variable Registration
#> Using default data frame: community
#> 
#>   Variable: Region
#>   Reference category: Region_East
#>   Dummy variables: Region_North, Region_South, Region_West
#>   Cases: 103 (0 missing)
#> 
#>   Dummy Coding Scheme:
#> 
#>                      Region_North  Region_South  Region_East*  Region_West
#>     ---------------  ------------  ------------  ------------  -----------
#>     1: Region_North        1             0             0            0
#>     2: Region_South        0             1             0            0
#>     3: Region_East*        0             0             1            0
#>     4: Region_West         0             0             0            1
#> 
#>     * Reference category
#> 
jdummy(Region, show = "all")         # Full scheme (for many categories)
#> Dummy Variable Registration
#> Using default data frame: community
#> 
#>   Variable: Region
#>   Reference category: Region_East
#>   Dummy variables: Region_North, Region_South, Region_West
#>   Cases: 103 (0 missing)
#> 
#>   Dummy Coding Scheme:
#> 
#>                      Region_North  Region_South  Region_East*  Region_West
#>     ---------------  ------------  ------------  ------------  -----------
#>     1: Region_North        1             0             0            0
#>     2: Region_South        0             1             0            0
#>     3: Region_East*        0             0             1            0
#>     4: Region_West         0             0             0            1
#> 
#>     * Reference category
#> 
jdummy()                             # Show all registrations
#> Dummy Variable Registrations
#> Using default data frame: community
#> 
#>   Variable: Region
#>   Reference category: 3: Region_East
#>   Dummy variables: Region_North, Region_South, Region_West
#>   Cases: 103 (0 missing)
#> 
#>   Variable: Education
#>   Reference category: 1: Education_Some_high_school (default; change with ref =)
#>   Dummy variables: Education_High_school_graduate, Education_Some_college, Education_Bachelor_s_degree, Education_Graduate_degree
#>   Cases: 103 (6 missing)
#> 
jdummy(Region, remove = TRUE)        # Remove one registration
#> Dummy registration removed for 'Region' in community.
jdummy(community, NULL)              # Clear community's dummy registrations
#> Dummy registrations cleared for community: Education.
jdummy(NULL)                         # Clear the default frame's (or ask)
#> No dummy registrations to clear for community (the default data frame).
jdummy(clear.all = TRUE)             # Clear every frame's dummy registrations
#> No dummy registrations to clear.

# juse(NULL) clears the default dataset -- not normally needed. You'd
# clear a default or registration only to undo a mistake, or -- as in
# this example -- to reset state for testing.
juse(NULL)
#> Default data frame cleared.