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:
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.
Person. A person whose entry was split into several titles gets one position, the most senior of their rows.
role.primarymarks one row per person, so counts of people don't double up.Leadership, per filing:
A person with a CEO-level title in an officer position is the
designatedCEO (co-ceowhen there are several,interimwhen 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, an unpaid president, chair or other leader working 35+ hours a week with the officer box is the
imputedCEO, when exactly one person fits.Otherwise the filing is
board_governedand no CEO is named.The CEO thesaurus (ceo.thesaurus) then applies to the organization types of
org_type_levels()(org_types()). A title that runs that kind of organization (a post adjutant, a club's general manager, a union's business manager) is thethesaurusCEO. It is named when the filing has no CEO, when its CEO was only imputed, or when its CEO's title is one the entry outranks. A stipend title (a lodge secretary) is never imputed.
A past president or president-elect (a FORMER or FUTURE status from step 06, with no date) holds a board seat (MEMBER), not the office. An imputed leader who reports hours must work at least 5 a week, unless they are a president.
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 312-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 90.1% of full-990 people. On 750
filings of 2019-2023 labeled for their chief executive
(data-raw/partvii-validation/ceo-sample/), step 09 names the right one
for 88.1%; on 126 held-out filings of the thesaurus's organization types,
81.7% (FINDINGS.md F-031 to F-034). 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%.
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, SECRETARY, TREASURER, or MEMBER
- role.ceo
for CEO: designated, co-ceo, interim, imputed, thesaurus, 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, thesaurus, imputed, model, board_governed, or no_paid
- org.type
per filing: the organization type of
org_types(), or NA- org.type.source
where
org.typecame from: supplied, codes, inferred, or none