Skip to content

Refactor agency crosswalk and add agency fund crosswalk #89

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jeancochrane wants to merge 12 commits into
base: 2024-data-update
Choose a base branch
from
Open

Refactor agency crosswalk and add agency fund crosswalk #89

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
524af6a
Add agency crosswalks to `agency.R` and `create_db.sql`
jeancochrane Apr 28, 2026
e15966c
Add simple data integrity checks when creating agency fund crosswalk …
jeancochrane Apr 29, 2026
11e356a
Merge branch '2024-data-update' into jeancochrane/88-refactor-agency-…
jeancochrane Apr 29, 2026
dfc374a
Update changelog to reflect new agency crosswalk schema
jeancochrane Apr 29, 2026
0acb12b
Update agency vignette to reflect new agency crosswalk schema
jeancochrane Apr 29, 2026
7b3f3b4
Update `create_db.R` script to support agency crosswalks
jeancochrane Apr 30, 2026
6f23a7d
Update DESCRIPTIOIN file with new maintainer email and bumped DB version
jeancochrane Apr 30, 2026
cde31f6
Update README for bumped DB version and agency crosswalks
jeancochrane Apr 30, 2026
8f229c3
Fix small typo in `NEWS.md`
jeancochrane Apr 30, 2026
4f57fe3
Bring back exclusion for Skokie Library fund when constructing agency…
jeancochrane Apr 30, 2026
c322ba6
Add clarifying comments and clearer code when demonstrating `agency_f…
jeancochrane Apr 30, 2026
0ff189d
Small tweaks to agency.R and agency vignette ahead of review
jeancochrane Apr 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions DESCRIPTION
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ Type: Package
Title: Calculate Cook County Property Tax Bills and Simulate Scenarios
Version: 1.1.0
Authors@R: c(
person(given = "Kyra", family = "Sturgill", email = "kyra.sturgill@cookcountyil.gov", role = c("aut", "cre")),
person(given = "Kyra", family = "Sturgill", email = "Assessor.Data@cookcountyil.gov", role = c("aut", "cre")),
Copy link
Copy Markdown
Member Author

@jeancochrane jeancochrane Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changing this from your personal email to the shared team email for the sake of privacy and durability. I don't feel strongly about it though, if you'd rather have your personal email listed we can keep it that way.

Copy link
Copy Markdown
Member

@kyrasturgill kyrasturgill May 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good idea!

person(given = "Dan", family = "Snow", role = c("aut")),
person(given = "Jean", family = "Cochrane", role = c("aut")),
person(given = "Rob", family = "Ross", role = c("aut")),
Expand Down Expand Up @@ -67,4 +67,4 @@ Remotes:
paleolimbot/geoarrow,
ropensci/tabulapdf
Config/Requires_DB_Version: 2024.0.0
Config/Wants_DB_Version: 2024.0.0-alpha.2
Config/Wants_DB_Version: 2024.0.0-alpha.3
44 changes: 21 additions & 23 deletions NEWS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,11 +41,15 @@ The main changes that the Clerk and the Treasurer made in 2024 include:
- General assistance funds
- Road and bridge funds
- Library funds
- To see the full list of agencies that changed in this manner in 2024,
run the following SQL query against the 2024 PTAXSIM database:
- To see the full list of agencies and funds that changed in this manner in
2024, run the following SQL queries against the 2024 PTAXSIM database:

```sql
SELECT * FROM agency_info WHERE agency_change_24
-- See all agencies that have changed to funds
SELECT * FROM agency_crosswalk;

-- See the same change at the fund level
SELECT * FROM agency_fund_crosswalk;
```

- **Switched from three-digit to six-digit fund numbers to add a greater level
Expand Down Expand Up @@ -96,25 +100,19 @@ database and functions to handle these changes in the source data.
vignette](https://ccao-data.github.io/ptaxsim/articles/tifs.html), which
we have updated to include a TIF counterfactual with data for tax year
2024.
Comment on lines 101 to 102
Copy link
Copy Markdown
Member

@kyrasturgill kyrasturgill May 2, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just noticing in the rendered changelog there seems an unnecessary line break at tax year 2024

- **Added new `agency_info.agency_*_24` columns to handle agencies that have
changed to funds in 2024**. You can use these columns to construct a crosswalk
to analyze agencies over time, even if they changed to a fund in 2024.
- The new columns include:
- `agency_info.agency_change_24` (boolean, required): Whether the agency's
number changed in 2024, due to becoming a fund.
- `agency_info.agency_num_24` (string, optional): The agency's new number
starting in 2024. Null if the agency number did not change in 2024.
- `agency_info.agency_name_24` (string, optional): The agency's name
starting in 2024. Null if the agency number did not change in 2024.
- **Added new tables `agency_crosswalk` and `agency_fund_crosswalk` to support
tracking agencies that have changed to funds in 2024**. You can use these
tables to analyze agencies over time, even if the Clerk switched to reporting
them as funds in 2024.
- **How this change affects you**: If you maintain code that analyzes
agencies over time, and you want to update your code to include 2024 data,
you should use the `agency_info.agency_change_24` column to determine
whether the Clerk changed any of the agencies you analyze to funds in
2024. If any of your agencies have changed to funds, you will need to use
the `agency_num_24` column to join pre- and post-2024 data. See [this
vignette](https://ccao-data.github.io/ptaxsim/articles/agencies.html)
for an example using the City of Chicago Library Fund to show how to
handle this type of change.
agencies or funds over time, and you want to update your code to include
2024 data, you should use the crosswalk tables to determine whether the
Clerk changed any of the agencies or funds that interest you in 2024. If
any of your agencies or funds have changed, you will need to use
the `agency_num_final` and `fund_num_final` columns to join pre- and
post-2024 data. For an example using the City of Chicago Library Fund to
show how to handle this type of change, see the vignette [Tracking taxing
agency revenue over time](https://ccao-data.github.io/ptaxsim/articles/agencies.html).
- **Added a new column `agency_fund.fund_type_num` to handle changing fund
numbers in 2024**. In 2024, the Clerk changed their fund numbers so that
they consist of six digits instead of three, and they are no longer
Expand Down Expand Up @@ -205,8 +203,8 @@ database and functions to handle these changes in the source data.
([#77](https://github.com/ccao-data/ptaxsim/pull/77)).
- **How this change affects you**: You should read the latest version of the
vignette if you use PTAXSIM for TIF counterfactuals.
- **Added [a new
vignette](https://ccao-data.github.io/ptaxsim/articles/agencies.html)
- **Added a new vignette [Tracking taxing agency revenue over
time](https://ccao-data.github.io/ptaxsim/articles/agencies.html)
to demonstrate the correct way to analyze agencies and funds over time given
the 2024 change that switched some agencies to funds**.
([#84](https://github.com/ccao-data/ptaxsim/pull/84)).
Expand Down
32 changes: 17 additions & 15 deletions README.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -240,20 +240,22 @@ The PTAXSIM backend database contains cleaned data from the Cook County Clerk, T

### Data sources

| Table Name | Source Agency | Source Link | Ingest Script | Contains |
|------------------|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|-------------------------------------------------------------------|
| agency | Clerk | [Tax Extension - Agency Tax Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Taxing district extensions, limits, and base EAV |
| agency_info | Clerk + imputed | [Tax Extension - Agency Tax Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Taxing district name, type, and subtype |
| agency_fund | Clerk | [Tax Extension - Agency Tax Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Funds and line-items that contribute to each district's extension |
| agency_fund_info | Clerk | [Tax Extension - Agency Tax Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Fund name and whether the fund is statutorily capped |
| cpi | IDOR | [History of CPI's Used for the PTELL](https://tax.illinois.gov/localgovernments/property/cpihistory.html) | [data-raw/cpi/cpi.R](data-raw/cpi/cpi.R) | CPI-U used to calculate PTELL limits |
| eq_factor | IDOR | Manually created from [IDOR press releases](https://tax.illinois.gov/research/press-releases-archive.html) | [data-raw/eq_factor/eq_factor.R](data-raw/eq_factor/eq_factor.R) | Equalization factor applied to AV to get EAV |
| pin | Clerk + Treasurer | CLERKVALUES and TAXBILLAMOUNTS internal SQL tables | [data-raw/pin/pin.R](data-raw/pin/pin.R) | PIN-level tax code, AV, and exemptions |
| tax_code | Clerk | [Tax Extension - Tax Code Agency Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/tax_code/tax_code.R](data-raw/tax_code/tax_code.R) | Crosswalk of tax codes by district |
| tif | Clerk | [TIF Reports - Cook County Summary Reports](https://www.cookcountyclerkil.gov/property-taxes/tifs-tax-increment-financing/tif-reports) | [data-raw/tif/tif.R](data-raw/tif/tif.R) | TIF revenue, start year, and cancellation year |
| tif_crosswalk | Clerk | Manually created from TIF summary and distribution reports | [data-raw/tif/tif.R](data-raw/tif/tif.R) | Fix for data issue identified in #39 |
| tif_distribution | Clerk | [TIF Reports - Tax Increment Agency Distribution Reports](https://www.cookcountyclerkil.gov/property-taxes/tifs-tax-increment-financing/tif-reports) | [data-raw/tif/tif.R](data-raw/tif/tif.R) | TIF EAV, frozen EAV, and distribution percentage by tax code |
| pin_tif_distribution | Clerk | [TIF Reports - Tax Increment Agency Distribution Reports](https://www.cookcountyclerkil.gov/property-taxes/tifs-tax-increment-financing/tif-reports) | [data-raw/tif/tif.R](data-raw/tif/tif.R) | TIF EAV, frozen EAV, and distribution percentage by PIN |
| Table Name | Source Agency | Source Link | Ingest Script | Contains |
Copy link
Copy Markdown
Member Author

@jeancochrane jeancochrane Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The main diff here is adding rows for agency_crosswalk and agency_fund_crosswalk. The rest of it is just whitespace changes to reformat the table so that it fits agency_fund_crosswalk, which is now the longest table name in the table.

|-----------------------|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|-------------------------------------------------------------------|
| agency | Clerk | [Tax Extension - Agency Tax Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Taxing district extensions, limits, and base EAV |
| agency_info | Clerk + imputed | [Tax Extension - Agency Tax Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Taxing district name, type, and subtype |
| agency_crosswalk | Clerk + imputed | [Tax Extension - Tax Code Agency Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Mapping to handle changes to agency numbers over time |
| agency_fund | Clerk | [Tax Extension - Agency Tax Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Funds and line-items that contribute to each district's extension |
| agency_fund_info | Clerk | [Tax Extension - Agency Tax Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Fund name and whether the fund is statutorily capped |
| agency_fund_crosswalk | Clerk + imputed | [Tax Extension - Agency Tax Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Mapping to handle changes to fund numbers over time |
| cpi | IDOR | [History of CPI's Used for the PTELL](https://tax.illinois.gov/localgovernments/property/cpihistory.html) | [data-raw/cpi/cpi.R](data-raw/cpi/cpi.R) | CPI-U used to calculate PTELL limits |
| eq_factor | IDOR | Manually created from [IDOR press releases](https://tax.illinois.gov/research/press-releases-archive.html) | [data-raw/eq_factor/eq_factor.R](data-raw/eq_factor/eq_factor.R) | Equalization factor applied to AV to get EAV |
| pin | Clerk + Treasurer | CLERKVALUES and TAXBILLAMOUNTS internal SQL tables | [data-raw/pin/pin.R](data-raw/pin/pin.R) | PIN-level tax code, AV, and exemptions |
| tax_code | Clerk | [Tax Extension - Tax Code Agency Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/tax_code/tax_code.R](data-raw/tax_code/tax_code.R) | Crosswalk of tax codes by district |
| tif | Clerk | [TIF Reports - Cook County Summary Reports](https://www.cookcountyclerkil.gov/property-taxes/tifs-tax-increment-financing/tif-reports) | [data-raw/tif/tif.R](data-raw/tif/tif.R) | TIF revenue, start year, and cancellation year |
| tif_crosswalk | Clerk | Manually created from TIF summary and distribution reports | [data-raw/tif/tif.R](data-raw/tif/tif.R) | Fix for data issue identified in #39 |
| tif_distribution | Clerk | [TIF Reports - Tax Increment Agency Distribution Reports](https://www.cookcountyclerkil.gov/property-taxes/tifs-tax-increment-financing/tif-reports) | [data-raw/tif/tif.R](data-raw/tif/tif.R) | TIF EAV, frozen EAV, and distribution percentage by tax code |
| pin_tif_distribution | Clerk | [TIF Reports - Tax Increment Agency Distribution Reports](https://www.cookcountyclerkil.gov/property-taxes/tifs-tax-increment-financing/tif-reports) | [data-raw/tif/tif.R](data-raw/tif/tif.R) | TIF EAV, frozen EAV, and distribution percentage by PIN |


### Database diagram
Expand All @@ -267,7 +269,7 @@ The PTAXSIM backend database contains cleaned data from the Cook County Clerk, T
## Notes and caveats
Copy link
Copy Markdown
Member

@kyrasturgill kyrasturgill May 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know this is beyond the scope of this PR, but what are your thoughts on adding a note here about how PINs with an EAV less than $150 will have a $0 bill but our tax_bill() function does not have that behavior built in?

"For PINs that have a final taxable EAV less than $150, the Cook County Treasurer will by default set the PIN's tax bill total to $0; note that we do not incorporate this behavior in the tax_bill() function which will lead our calculations to not match the final bill total."

Or something along those lines.



- PTAXSIM's tax year 2024 update required significant changes to the database and package. Please see the PTAXSIM [changelog](https://ccao-data.github.io/ptaxsim/news) for more details.
- PTAXSIM's tax year 2024 update required significant changes to the database and package. Please see the PTAXSIM [changelog](https://ccao-data.github.io/ptaxsim/news) for more details.
- The per-district tax calculation using `tax_bill(simplify = TRUE)` for properties in transit TIFs do not match the amounts that the Treasurer reports on their tax bills. We believe the amounts we report are correct, however. See issues [#4](https://github.com/ccao-data/ptaxsim/issues/4) and [#56](https://github.com/ccao-data/ptaxsim/issues/56) for more information, as well as PR [#58](https://github.com/ccao-data/ptaxsim/pull/58).
- Special Service Area (SSA) rates must be calculated manually when creating counterfactual bills. See issue [#3](https://github.com/ccao-data/ptaxsim/issues/3) for more information.
- In rare instances, a TIF can have multiple `agency_num` identifiers (usually there's only one per TIF). The `tif_crosswalk` table determines what the "main" `agency_num` is for each TIF and pulls the name and TIF information using that identifier. See issue [GitLab #39](https://gitlab.com/ccao-data-science---modeling/packages/ptaxsim/-/issues/39) for more information.
Expand Down
8 changes: 5 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,8 @@ Table of Contents
> installation](#database-installation) for details.
>
> [**Link to PTAXSIM
> database**](https://ccao-data-public-us-east-1.s3.amazonaws.com/ptaxsim/ptaxsim-2024.0.0-alpha.2.db.bz2)
> (DB version: 2024.0.0; Last updated: 2026-04-14 22:42:59)
> database**](https://ccao-data-public-us-east-1.s3.amazonaws.com/ptaxsim/ptaxsim-2024.0.0-alpha.3.db.bz2)
> (DB version: 2024.0.0; Last updated: 2026-04-30 15:24:09)

PTAXSIM is an R package/database to approximate Cook County property tax
bills. It uses real assessment, exemption, TIF, and levy data to
Expand Down Expand Up @@ -172,7 +172,7 @@ database:

1. Download the compressed database file from the CCAO’s public S3
bucket. [Link
here](https://ccao-data-public-us-east-1.s3.amazonaws.com/ptaxsim/ptaxsim-2024.0.0-alpha.2.db.bz2).
here](https://ccao-data-public-us-east-1.s3.amazonaws.com/ptaxsim/ptaxsim-2024.0.0-alpha.3.db.bz2).
2. (Optional) Rename the downloaded database file by removing the
version number, i.e. ptaxsim-2024.0.0.db.bz2 becomes
`ptaxsim.db.bz2`.
Expand Down Expand Up @@ -660,8 +660,10 @@ data was available in mid-2020.
|----|----|----|----|----|
| agency | Clerk | [Tax Extension - Agency Tax Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Taxing district extensions, limits, and base EAV |
| agency_info | Clerk + imputed | [Tax Extension - Agency Tax Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Taxing district name, type, and subtype |
| agency_crosswalk | Clerk + imputed | [Tax Extension - Tax Code Agency Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Mapping to handle changes to agency numbers over time |
| agency_fund | Clerk | [Tax Extension - Agency Tax Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Funds and line-items that contribute to each district’s extension |
| agency_fund_info | Clerk | [Tax Extension - Agency Tax Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Fund name and whether the fund is statutorily capped |
| agency_fund_crosswalk | Clerk + imputed | [Tax Extension - Agency Tax Rate Reports](https://www.cookcountyclerkil.gov/property-taxes/tax-extension-and-rates) | [data-raw/agency/agency.R](data-raw/agency/agency.R) | Mapping to handle changes to fund numbers over time |
| cpi | IDOR | [History of CPI’s Used for the PTELL](https://tax.illinois.gov/localgovernments/property/cpihistory.html) | [data-raw/cpi/cpi.R](data-raw/cpi/cpi.R) | CPI-U used to calculate PTELL limits |
| eq_factor | IDOR | Manually created from [IDOR press releases](https://tax.illinois.gov/research/press-releases-archive.html) | [data-raw/eq_factor/eq_factor.R](data-raw/eq_factor/eq_factor.R) | Equalization factor applied to AV to get EAV |
| pin | Clerk + Treasurer | CLERKVALUES and TAXBILLAMOUNTS internal SQL tables | [data-raw/pin/pin.R](data-raw/pin/pin.R) | PIN-level tax code, AV, and exemptions |
Expand Down
Loading
Loading