Skip to contents

The pipeline is driven by two kinds of reference data: crosswalks (curated lookup tables shipped as package data) and word lists (character vectors shipped as package data used by the regex-based cleaning steps).

Crosswalks

The five crosswalks are package data (title.xwalk, title.patterns, title.taxonomy, status.codes, ceo.thesaurus). Their source is the CSV tables in data-raw/crosswalks/ of the source repository: edit a table, then run data-raw/crosswalks/build-crosswalks.R to rebuild the package data. (Until October 2026 the crosswalks were kept in a Google Sheet; it is retired, and an export of every tab is archived in data-raw/crosswalks/archive/.)

Title standardization (get_title_xwalk())

Maps every observed title variant to a canonical title.standard, plus a strata / strata.label for board sub-roles. Used in step 07, standardize_titles().

xwalk <- get_title_xwalk()
dim(xwalk)
#> [1] 9301    4
head(xwalk, 8)
#>                title.variant title.standard strata strata.label
#> 1                                  NO TITLE                    
#> 2               AAA DIRECTOR       DIRECTOR                    
#> 3 AAC ATHLETE REPRESENTATIVE   BOARD MEMBER                    
#> 4              AAFP DELEGATE   BOARD MEMBER                    
#> 5               AAJ DELEGATE   BOARD MEMBER                    
#> 6               AAJ GOVERNOR   BOARD MEMBER                    
#> 7              AAJ PRESIDENT   BOARD MEMBER                    
#> 8            AAMD LEADERSHIP   BOARD MEMBER

Title patterns (get_title_patterns())

Head rules for titles the standardization crosswalk does not list: a title whose longest known prefix or suffix has a rule maps to that rule’s title.standard (title.match is pattern). Each rule records its support (titles it was learned from) and precision. Used in step 07, standardize_titles().

pat <- get_title_patterns()
dim(pat)
#> [1] 110   6
head(pat, 6)
#>   position      head title.standard     rule support precision
#> 1   prefix    ACTIVE   BOARD MEMBER majority       6     0.833
#> 2   prefix  ADVISORY   BOARD MEMBER majority       8     1.000
#> 3   prefix AFFILIATE   BOARD MEMBER majority       5     1.000
#> 4   prefix     ALPHA   BOARD MEMBER majority      16     1.000
#> 5   prefix       ALT   BOARD MEMBER majority      11     1.000
#> 6   prefix ALTERNATE   BOARD MEMBER majority      16     0.875

Title taxonomy (get_title_taxonomy())

Maps each canonical title.standard to its taxonomy dimensions: functional domain.category / domain.label, the BLS SOC occupation codes, and its role. A title is either an employee level or a board role:

  • emp.level:
    • CEO: the top staff job.
    • OFFICER: C-suite, vice presidents, deputies.
    • MANAGER: directors of departments, managers.
    • PROFESSIONAL: non-managerial jobs often reported for their pay, such as physicians, lawyers, professors and coaches.
    • STAFF: everything else.
  • board.role: CHAIR, VICE CHAIR, SECRETARY, SECRETARY TREASURER, TREASURER or MEMBER. Board titles map to six standards, BOARD PRESIDENT through BOARD MEMBER; the combined secretary-treasurer office is kept whole.

The legacy flags (ceo, c.level, mgr, spec, board, pres, …) are derived from these two columns. dir.vp is retired. Used in step 08, categorize_titles().

tax <- get_title_taxonomy()
dim(tax)
#> [1] 377  22
head(tax[, c("title.standard", "domain.label", "soc.label",
             "emp.level", "board.role")], 8)
#>             title.standard     domain.label
#> 1               ACCOUNTANT          finance
#> 2      ACCOUNTING DIRECTOR          finance
#> 3                    ACTOR arts and history
#> 4                  ACTUARY          finance
#> 5   ADMINISTRATION OFFICER   administration
#> 6 ADMINISTRATIVE ASSISTANT   administration
#> 7            ADMINISTRATOR   administration
#> 8       ADOPTION COUNSELOR  social services
#>                                   soc.label    emp.level board.role
#> 1                  Accountants and Auditors PROFESSIONAL           
#> 2                        Financial Managers      MANAGER           
#> 3                                    Actors PROFESSIONAL           
#> 4                                 Actuaries PROFESSIONAL           
#> 5                                                  STAFF           
#> 6 Secretaries and Administrative Assistants        STAFF           
#> 7          Administrative Services Managers      MANAGER           
#> 8                                Counselors        STAFF
table(tax$emp.level)
#> 
#>                       CEO      MANAGER      OFFICER PROFESSIONAL        STAFF 
#>           15            8          109          114           35           96
table(tax$board.role)
#> 
#>                                   CHAIR              MEMBER           SECRETARY 
#>                 371                   1                   1                   1 
#> SECRETARY TREASURER           TREASURER          VICE CHAIR 
#>                   1                   1                   1

Status codes (get_status_codes())

Maps status-qualifier variants (e.g. ACTING, EMERITUS, INTERIM) to a standardized status.qualifier (e.g. INTERIM, FORMER). Used in step 06, gen_status_codes().

sc <- get_status_codes()
dim(sc)
#> [1] 293   2
head(sc, 8)
#>   status.variant status.qualifier
#> 1      AS NEEDED         AT LARGE
#> 2       AT LARGE         AT LARGE
#> 3       AT-LARGE         AT LARGE
#> 4          PROXY         AT LARGE
#> 5          AT LG         AT LARGE
#> 6        CURRENT          CURRENT
#> 7     EX OFFICIO        EXOFFICIO
#> 8     EX-OFFICIO        EXOFFICIO

CEO thesaurus (get_ceo_thesaurus())

Chief-executive titles by organization type: a post adjutant, a club’s general manager, a union’s business manager. Each entry is a regular expression on the cleaned title for one org_type, with its pay and hours thresholds. Some entries list the titles they outrank. Others (not_ceo) mark titles never made CEO on a stipend, such as a lodge secretary. Used in step 09, resolve_roles(). See Step 09 for where the organization type comes from.

th <- get_ceo_thesaurus()
dim(th)
#> [1] 13  7
th[, c("org_type", "title_pattern", "effect", "min_hours", "min_pay")]
#>      org_type
#> 1    veterans
#> 2    veterans
#> 3   fraternal
#> 4        club
#> 5        club
#> 6        coop
#> 7       trust
#> 8       union
#> 9  university
#> 10   ministry
#> 11       fire
#> 12       fire
#> 13   cemetery
#>                                                                                 title_pattern
#> 1                                                                              \\bADJUTANT\\b
#> 2                  \\b(TREASURER|FINANCE OFFICER|QUARTERMASTER|TRUSTEE|SECRETARY|ADJUTANT)\\b
#> 3                                                        \\b(SECRETARY|RECORDER|TREASURER)\\b
#> 4                                                     \\b(GENERAL MANAGER|CLUB MANAGER|GM)\\b
#> 5                                              \\b(POOL|SNACK|CANTEEN|BAR|GROUNDS) MANAGER\\b
#> 6                                                                  \\b(GENERAL MANAGER|GM)\\b
#> 7                                         ^(FUND |PLAN |TRUST |BENEFITS? )?A?D?MINISTRATOR\\b
#> 8                                                            \\b(BUSINESS MANAGER|BUS MGR)\\b
#> 9                                                                               ^PRESIDENT\\b
#> 10 ^(SENIOR |LEAD |GENERAL |HEAD )?PASTOR\\b|\\bBISHOP\\b|\\bOVERSEER\\b|^RABBI\\b|^RECTOR\\b
#> 11                                                             ^(FIRE )?CHIEF$|^FIRE CHIEF\\b
#> 12                                                                \\b(SECRETARY|TREASURER)\\b
#> 13                                                                       \\bSUPERINTENDENT\\b
#>     effect min_hours min_pay
#> 1      ceo        20   25000
#> 2  not_ceo        35   30000
#> 3  not_ceo        35   40000
#> 4      ceo        20   25000
#> 5  not_ceo        NA   25000
#> 6      ceo        20   25000
#> 7      ceo        20   25000
#> 8      ceo        20   25000
#> 9      ceo        20   50000
#> 10     ceo        20       0
#> 11     ceo        20   25000
#> 12 not_ceo        35   40000
#> 13 not_ceo        NA       1

Word lists (package data)

These character vectors are lazy-loaded package datasets used by the regex cleaning steps. Load any of them with data().

Dataset Used in Purpose
date.words remove_dates() (02) month/date tokens to detect and strip
number.words gen_status_codes() (06) number words removed from titles
likely.titles standardize_conj() (03) recognizable titles for split detection
likely.subjects fix_of() (05) subjects that follow “of” in a title
possible.titles fix_of() (05) candidate title tokens
former.words not used FORMER variants; superseded by status.codes
future.words not used FUTURE variants; superseded by status.codes
interim.words not used INTERIM variants; superseded by status.codes
regional.words not used REGIONAL variants; superseded by status.codes
possible.regional.list not used candidate regional tokens
data(number.words)
head(number.words, 12)
#>  [1] "ONE"    "TWO"    "THREE"  "FOUR"   "FIVE"   "SIX"    "SEVEN"  "EIGHT" 
#>  [9] "NINE"   "TEN"    "ELEVEN" "TWELVE"

data(likely.titles)
head(likely.titles, 12)
#>  [1] "PRESIDENT"   "CEO"         "DIRECTOR\\b" "CHAIR"       "TRUSTEE\\b" 
#>  [6] "TREASURER"   "SECRETARY"   "OFFICER"     "COUNSEL"     "FOUNDER"    
#> [11] "PUBLISHER"   "EDITOR\\b"

Demo data

Dataset Description
tinypartvii ~81k raw Part VII rows (10,000 orgs) in the modern schema, ready for standardize_df().
raw.titles A small vector of raw title strings for quick experiments.
data(tinypartvii)
str(tinypartvii[, 1:8], vec.len = 1)
#> 'data.frame':    81309 obs. of  8 variables:
#>  $ EIN2            : chr  "EIN-72-1424183" ...
#>  $ OBJECTID        : chr  "OID-202400189349300715" ...
#>  $ ORG_EIN         : chr  "721424183" ...
#>  $ ORG_NAME_L1     : chr  "MU TAU INC" ...
#>  $ ORG_NAME_L2     : chr  "" ...
#>  $ RETURN_AMENDED_X: chr  "FALSE" ...
#>  $ RETURN_GROUP_X  : chr  "FALSE" ...
#>  $ RETURN_PARTIAL_X: chr  "FALSE" ...