Skip to contents

resolve roles from checkboxes, pay, and title

Source: R/09-conditional-logic.R
resolve_roles.Rd

Adds role columns to the output of categorize_titles(). The rules were developed and checked against a hand-labeled sample in synthid/dev (06_role_cascade_prototype.R, 10_role_passes.R). They work in three layers:

  1. Position, per row: the filer's checkboxes come first. The title and pay are used when a paid executive title outranks a missing officer box, and on 990-EZ returns, which have no checkboxes.

    • The trustee box means board.

    • The officer box means officer.

    • Both boxes mean board_officer (a working board).

    • The key-employee and highly-compensated boxes mean staff.

  2. Person. A person whose entry was split into several titles gets one position, the most senior of their rows. role.primary marks one row per person, so counts of people don't double up.

  3. Leadership, per filing:

    • A person with a CEO-level title in an officer position is the designated CEO (co-ceo when there are several, interim when flagged so).

    • Otherwise, the highest-paid plausible leader is imputed: a paid person with the officer box or a leadership title. A paid board chair who ticks the trustee box and works under 25 hours a week doesn't count.

    • If no paid person qualifies, the filing is board_governed and no CEO is named.

A board title (president, secretary, treasurer...) held by someone who works under 10 hours a week and is paid under $25,000 is a board seat, even with the officer box. Such a person is a titular officer receiving a stipend, not a paid executive. On a 990-EZ, which has no boxes, the same holds for a board title paid a small fee.

990-EZ returns have no checkboxes. For them, when the xgboost package is installed, the role comes from a model trained on full-990 people with the boxes hidden (predict_roles()): title, pay, hours and the filing's make-up. Without xgboost, or with use_model = FALSE, the rules above decide. role.method records which one.

Scored against the 316-person labeled set of 2010-12 filings (data-raw/partvii-validation/09-gold-check.R, gold-check/gold-v2.csv), the rules agree with the label for 88.8% of full-990 people. On 990-EZ people the model agrees for 92.5%, and the rules for 82.5%. On 23,931 people from organizations that switch between the forms, labeled by their full-990-year role, the model agrees for 95.0% and the rules for 92.0%.

Usage

resolve_roles(comp.data, use_model = TRUE)

Arguments

comp.data

The output of categorize_titles().

use_model

Use the no-checkbox role model for 990-EZ filings when xgboost is installed (default TRUE).

Value

comp.data with these columns added (person-level values repeat on each of the person's rows):

role.position

board, officer, board_officer, staff, or unknown

role.final

CEO, OFFICER, MANAGER, PROFESSIONAL, STAFF, or BOARD

role.board

for BOARD: CHAIR, VICE CHAIR, SECRETARY, TREASURER, or MEMBER

role.ceo

for CEO: designated, co-ceo, interim, imputed, or model

role.source

what settled the position: checkbox, title+pay, or title

role.method

rules, or model (990-EZ, xgboost installed)

role.primary

TRUE on one row per person

org.leadership

per filing: designated, imputed, model, board_governed, or no_paid