From 9dac902bc0a1437059c3c378c04717632d9d4a9f Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Thu, 16 Apr 2026 12:20:37 -0500 Subject: [PATCH 01/16] Add rough draft of a changelog --- CHANGELOG.md | 119 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..a394b5e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,119 @@ +# Changelog + +## 1.1.0 + +### Background + +This release features a significant number of changes to the database schema +and to package functions to accommodate changes that the Clerk and the +Treasurer made to the data they report in 2024. Source data from the Clerk and +the Treasurer forms the core of the PTAXSIM database, so any changes they make +need to be reflected in this package, too. + +The Clerk and the Treasurer changed their data reporting this past year because +they both completed a migration from a legacy AS/400 mainframe system to a +new integrated property tax system of record. + +Read on for a detailed description of the changes we made to the PTAXSIM +database and functions to handle these changes in the source data. + +### Breaking changes + +- **Added new `agency.agency_*_24` columns to handle changing agency numbers + in 2024**. + - The new columns include: + - `agency.agency_change_24` (boolean, required): Whether the agency's + number changed in 2024. + - `agency.agency_num_24` (string, optional): The agency's new number + starting in 2024. Null if the agency number did not change in 2024. + - `agency.agency_name_24` (string, optional): The agency's name starting in + 2024. Null if the agency number did not change 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 will need to use these new columns to handle changes to + agency numbers. (_TK: Link to vignette_) +- **Added a new column `agency_fund.fund_type_num` to handle changing fund + numbers in 2024**. Prior to 2024, fund numbers (`agency_fund.fund_num`) + consisted of three digits, and funds with the same `fund_num` in different + agencies always referred to the same type of fund. In 2024, the Clerk changed + their fund numbers so that they consist of six digits, and are no longer + guaranteed to refer to the same type of fund across agencies. However, the + first three digits of a fund number are still guaranteed to refer to a + consistent fund "type", so we introduced a new column + `agency_fund.fund_type_num` to represent this new notion of a "fund type". + - **How this change affects you**: If you use `agency_fund.fund_num` to + track certain types of funds across agencies, you will need to switch to + `agency_fund.fund_type_num`. +- **Changed the `agency_fund_info` table so that it is now unique by + `(agency_num, fund_num)` instead of `(fund_num)`**. As mentioned above, + fund identifiers are no longer consistent across agencies. As a result, we + have changed the `agency_fund_info` table so that it includes `agency_num` + in its primary key. + - **How this change affects you**: If you use the `agency_fund_info` table + and treat it as unique by `fund_num`, you will need to update your + code to add `agency_num` when joining to this table. +- **Added a new table `pin_tif_distribution` and associated lookup function + `lookup_pin_tif()` to handle a methodological change to the TIF + revenue share calculation.** + - `lookup_pin_tif()` will never return rows with `year < 2024`. + - `lookup_tif()` will never return rows with `year > 2024`. + - **How this change affects you**: + - Update `tax_bill()` function calls in TIF counterfactuals to pass in + `pin_tif_dt` for years starting in 2024 +- **Dropped a few columns that the Clerk has removed from its agency reports**. + - These columns are: + - `agency_fund.ptell_reduced_ind` (PTELL-reduced levy indicator) + - `agency.reduction_type` (PTELL-reduced levy type) + + - `agency.total_non_cap_ext` (Total non-capped extension for an agency) + - **How this change affects you**: If you use any of the columns listed + above, you will need to remove them from your code. +- **Consolidated non-Cook County EAV columns into a new column + `agency.cty_overlap_eav`**. + - These columns have been removed and their values are now included in the + `agency.cty_overlap_eav` column: + - `agency.cty_dupage_eav` + - `agency.cty_lake_eav` + - `agency.cty_will_eav` + - `agency.cty_kane_eav` + - `agency.cty_mchenry_eav` + - `agency.cty_dekalb_eav` + - `agency.cty_grundy_eav` + - `agency.cty_kankakee_eav` + - `agency.cty_kendall_eav` + - `agency.cty_lasalle_eav` + - `agency.cty_livingston_eav` + +### Improvements + +- **Added a new exemption column `pin.exe_vet_dis_100`**. This column + corresponds to the new 100% disability level for the [Veterans with + Disabilities Exemption](https://www.cookcountyassessoril.gov/veterans-disabilities-exemption). + The lookup function `lookup_pin()` now returns this column. + - **How this change affects you**: You may use this column if you would + like to analyze this exemption. +- **Added a new column `agency.authority_num`**. We expect this column to be + more useful in future years when the Clerk continues migrating from the + core "Agency" entity to the "Authority" entity. + - **How this change affects you**: We recommend ignoring this column for + now, because it is currently duplicative of `agency_num` and we don't + have full confidence in our understanding of the Clerk's plans for this + column in the future. However, it remains available if you are interested + in investigating it. +- **Added support for pre-release database versions**. The code now supports + database versions with pre-release suffixes like `2024.0.0-alpha.1` to + indicate database versions that are unreleased but available for testing. + - **How this change affects you**: This change will not affect you as a + PTAXSIM user. It is only useful for PTAXSIM maintainers and beta testers. +- **Updated the TIF vignette to demonstrate the correct way to handle the new + TIF revenue share calcluation** ([#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 analysis. + +### Bug fixes + +- **Lowered the memory usage of the `pin_geometry` extraction script** + ([#67](https://github.com/ccao-data/ptaxsim/pull/67)). This script previously + struggled to complete on our 160gb server. It now runs correctly. + - **How this change affects you**: This change will not affect you as a + PTAXSIM user. It is only useful for PTAXSIM maintainers. From 4c20cc21cb84f21c9db3a9b73a0dbe3c24f86394 Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Thu, 16 Apr 2026 17:04:06 -0500 Subject: [PATCH 02/16] Sketch out some more detail on Clerk/Treasurer changes for 2024 --- CHANGELOG.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a394b5e..f50186f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,10 @@ ### Background -This release features a significant number of changes to the database schema +This release adds support for tax year 2024. It is intended for use with the +`2024.0.x` database version. + +The release also features a significant number of changes to the database schema and to package functions to accommodate changes that the Clerk and the Treasurer made to the data they report in 2024. Source data from the Clerk and the Treasurer forms the core of the PTAXSIM database, so any changes they make @@ -14,6 +17,18 @@ The Clerk and the Treasurer changed their data reporting this past year because they both completed a migration from a legacy AS/400 mainframe system to a new integrated property tax system of record. +The main changes that the Clerk and the Treasurer made in 2024 include: + +- **Changed agency numbers to enable reporting some funds as agencies**. +- **Switched from three-digit to six-digit fund numbers to support new types + of funds**. The new types of funds are primarily bond series. +- **Changed the TIF revenue share calculation so that it is performed at the + PIN-level rather than the tax-code-level**. This means that TIF increment is + now calculated based on the difference between the frozen and current taxable + EAV for each individual PIN in a TIF, rather than the frozen and current + taxable EAV of the tax code as a whole. +- **Removed a number of minor columns from reports**. + Read on for a detailed description of the changes we made to the PTAXSIM database and functions to handle these changes in the source data. From 6219748bb6a11a768e623b491f0d483b07a33786 Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Mon, 20 Apr 2026 11:34:43 -0500 Subject: [PATCH 03/16] Clean up changelog --- CHANGELOG.md | 104 ++++++++++++++++++++++++++++++++++----------------- 1 file changed, 70 insertions(+), 34 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f50186f..e88d78b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,13 +21,23 @@ The main changes that the Clerk and the Treasurer made in 2024 include: - **Changed agency numbers to enable reporting some funds as agencies**. - **Switched from three-digit to six-digit fund numbers to support new types - of funds**. The new types of funds are primarily bond series. + of funds**. Prior to 2024, fund numbers (`agency_fund.fund_num`) + consisted of three digits, and funds with the same `fund_num` in different + agencies always referred to the same type of fund. In 2024, the Clerk changed + their fund numbers so that they consist of six digits, and they are no longer + guaranteed to refer to the same type of fund across agencies. The new types + of funds that this change supports are primarily bond series. - **Changed the TIF revenue share calculation so that it is performed at the PIN-level rather than the tax-code-level**. This means that TIF increment is now calculated based on the difference between the frozen and current taxable EAV for each individual PIN in a TIF, rather than the frozen and current taxable EAV of the tax code as a whole. -- **Removed a number of minor columns from reports**. +- **Removed a number of minor columns from agency reports**. None of these + columns were used in any core PTAXSIM functions, so we expect that their + absence will not affect most users. +- **Added a new "authority number" for each agency in agency reports**. So far, + authority numbers appear to have a 1:1 relationship to agency numbers, though + we expect this may change in future years. Read on for a detailed description of the changes we made to the PTAXSIM database and functions to handle these changes in the source data. @@ -35,7 +45,8 @@ database and functions to handle these changes in the source data. ### Breaking changes - **Added new `agency.agency_*_24` columns to handle changing agency numbers - in 2024**. + in 2024**. You can use these columns to construct a crosswalk to analyze + agencies over time, even if their agency number changed in 2024. - The new columns include: - `agency.agency_change_24` (boolean, required): Whether the agency's number changed in 2024. @@ -46,43 +57,55 @@ database and functions to handle these changes in the source data. - **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 will need to use these new columns to handle changes to - agency numbers. (_TK: Link to vignette_) + agency numbers. See this vignette for a demonstration of how to + use the new columns to construct a crosswalk for agency numbers + across years: _TK: Link to vignette_ - **Added a new column `agency_fund.fund_type_num` to handle changing fund - numbers in 2024**. Prior to 2024, fund numbers (`agency_fund.fund_num`) - consisted of three digits, and funds with the same `fund_num` in different - agencies always referred to the same type of fund. In 2024, the Clerk changed - their fund numbers so that they consist of six digits, and are no longer + 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 guaranteed to refer to the same type of fund across agencies. However, the first three digits of a fund number are still guaranteed to refer to a consistent fund "type", so we introduced a new column - `agency_fund.fund_type_num` to represent this new notion of a "fund type". + `agency_fund.fund_type_num` to represent the notion of a "fund type" that + is consistent across agencies. - **How this change affects you**: If you use `agency_fund.fund_num` to - track certain types of funds across agencies, you will need to switch to - `agency_fund.fund_type_num`. + track specific types of funds across agencies, you will need to switch to + using `agency_fund.fund_type_num` for that purpose. - **Changed the `agency_fund_info` table so that it is now unique by - `(agency_num, fund_num)` instead of `(fund_num)`**. As mentioned above, - fund identifiers are no longer consistent across agencies. As a result, we - have changed the `agency_fund_info` table so that it includes `agency_num` + `(agency_num, fund_num)` instead of `(fund_num)`**. Since fund numbers are + no longer consistent across agencies, we can't use them as the exclusive basis + for the `agency_fund_info` table anymore. To handle this change, we have + altered the `agency_fund_info` table so that it includes `agency_num` in its primary key. - **How this change affects you**: If you use the `agency_fund_info` table and treat it as unique by `fund_num`, you will need to update your code to add `agency_num` when joining to this table. - **Added a new table `pin_tif_distribution` and associated lookup function - `lookup_pin_tif()` to handle a methodological change to the TIF - revenue share calculation.** - - `lookup_pin_tif()` will never return rows with `year < 2024`. - - `lookup_tif()` will never return rows with `year > 2024`. - - **How this change affects you**: - - Update `tax_bill()` function calls in TIF counterfactuals to pass in - `pin_tif_dt` for years starting in 2024 + `lookup_pin_tif()` to handle the methodological change to the TIF + revenue share calculation.** The `tax_bill()` function also accepts an + optional `pin_tif_dt` argument that you can use for post-2024 TIF + counterfactuals. + - Note that there are now two different TIF lookup functions, each of + which applies to a different set of years: + - `lookup_pin_tif()` will only return rows where `year >= 2024`. + - `lookup_tif()` will only return rows where `year < 2024`. + - **How this change affects you**: If you maintain any TIF counterfactuals, + you will need to update your use of the `tax_bill()` function to pass in + an altered `pin_tif_dt` for any tax years that you analyze beyond 2023. + For an example of this type of change, see the [Tinkering with TIFs + 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. - **Dropped a few columns that the Clerk has removed from its agency reports**. - - These columns are: + - The dropped columns are: - `agency_fund.ptell_reduced_ind` (PTELL-reduced levy indicator) - `agency.reduction_type` (PTELL-reduced levy type) - - `agency.total_non_cap_ext` (Total non-capped extension for an agency) - - **How this change affects you**: If you use any of the columns listed - above, you will need to remove them from your code. + - **How this change affects you**: If you use any of the columns listed + above, you will need to remove them from your code. Feel free to [open an + issue](https://github.com/ccao-data/ptaxsim/issues/new) to ask for help + replacing these columns; we're interested to know if and how PTAXSIM users + are using them. - **Consolidated non-Cook County EAV columns into a new column `agency.cty_overlap_eav`**. - These columns have been removed and their values are now included in the @@ -98,6 +121,11 @@ database and functions to handle these changes in the source data. - `agency.cty_kendall_eav` - `agency.cty_lasalle_eav` - `agency.cty_livingston_eav` + - **How this change affects you**: If you use any of the columns listed + above, you will need to remove them from your code. If `cty_overlap_eav` + does not work for your purposes, [open an + issue](https://github.com/ccao-data/ptaxsim/issues/new) and we'll do our + best to help you update your analysis. ### Improvements @@ -106,7 +134,7 @@ database and functions to handle these changes in the source data. Disabilities Exemption](https://www.cookcountyassessoril.gov/veterans-disabilities-exemption). The lookup function `lookup_pin()` now returns this column. - **How this change affects you**: You may use this column if you would - like to analyze this exemption. + like to analyze this new exemption. - **Added a new column `agency.authority_num`**. We expect this column to be more useful in future years when the Clerk continues migrating from the core "Agency" entity to the "Authority" entity. @@ -116,19 +144,27 @@ database and functions to handle these changes in the source data. column in the future. However, it remains available if you are interested in investigating it. - **Added support for pre-release database versions**. The code now supports - database versions with pre-release suffixes like `2024.0.0-alpha.1` to - indicate database versions that are unreleased but available for testing. - - **How this change affects you**: This change will not affect you as a - PTAXSIM user. It is only useful for PTAXSIM maintainers and beta testers. -- **Updated the TIF vignette to demonstrate the correct way to handle the new - TIF revenue share calcluation** ([#77](https://github.com/ccao-data/ptaxsim/pull/77)) + database versions with pre-release suffixes like `2024.0.0-alpha.1`. + Databases tagged with pre-release versions are unreleased but available for + testing. + - **How this change affects you**: This change will not affect most PTAXSIM + users. It is only useful for PTAXSIM maintainers and pre-release testers. +- **Updated the [Tinkering with TIFs + vignette](https://ccao-data.github.io/ptaxsim/articles/tifs.html) to + demonstrate the correct way to handle the new TIF revenue share calcluation** + ([#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 to demonstrate the correct way to handle agency + numbers that changed in 2024 (_TK: Link to vignette_)** + ([#84](https://github.com/ccao-data/ptaxsim/pull/84)). - **How this change affects you**: You should read the latest version of the - vignette if you use PTAXSIM for TIF analysis. + vignette if you use PTAXSIM to analyze specific agencies over time. ### Bug fixes - **Lowered the memory usage of the `pin_geometry` extraction script** ([#67](https://github.com/ccao-data/ptaxsim/pull/67)). This script previously - struggled to complete on our 160gb server. It now runs correctly. + struggled to complete on our 160gb server. It now executes without any issues. - **How this change affects you**: This change will not affect you as a PTAXSIM user. It is only useful for PTAXSIM maintainers. From b257d0593b1694c7090cbafa2571a67f7f1f6721 Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Mon, 20 Apr 2026 11:44:02 -0500 Subject: [PATCH 04/16] Rename CHANGELOG.md to NEWS.md and reformat to follow pkgdown standard --- CHANGELOG.md => NEWS.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) rename CHANGELOG.md => NEWS.md (99%) diff --git a/CHANGELOG.md b/NEWS.md similarity index 99% rename from CHANGELOG.md rename to NEWS.md index e88d78b..70c5a2a 100644 --- a/CHANGELOG.md +++ b/NEWS.md @@ -1,8 +1,6 @@ -# Changelog +# ptasxim 1.1.0 -## 1.1.0 - -### Background +## Background This release adds support for tax year 2024. It is intended for use with the `2024.0.x` database version. @@ -42,7 +40,7 @@ The main changes that the Clerk and the Treasurer made in 2024 include: Read on for a detailed description of the changes we made to the PTAXSIM database and functions to handle these changes in the source data. -### Breaking changes +## Breaking changes - **Added new `agency.agency_*_24` columns to handle changing agency numbers in 2024**. You can use these columns to construct a crosswalk to analyze @@ -127,7 +125,7 @@ database and functions to handle these changes in the source data. issue](https://github.com/ccao-data/ptaxsim/issues/new) and we'll do our best to help you update your analysis. -### Improvements +## Improvements - **Added a new exemption column `pin.exe_vet_dis_100`**. This column corresponds to the new 100% disability level for the [Veterans with @@ -161,7 +159,7 @@ database and functions to handle these changes in the source data. - **How this change affects you**: You should read the latest version of the vignette if you use PTAXSIM to analyze specific agencies over time. -### Bug fixes +## Bug fixes - **Lowered the memory usage of the `pin_geometry` extraction script** ([#67](https://github.com/ccao-data/ptaxsim/pull/67)). This script previously From 27686985af1f1064439c6c1d48cc1de114daafdb Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Mon, 20 Apr 2026 12:08:15 -0500 Subject: [PATCH 05/16] Two tiny fixes to NEWS.md ahead of review --- NEWS.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/NEWS.md b/NEWS.md index 70c5a2a..c3e86d4 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# ptasxim 1.1.0 +# ptaxsim 1.1.0 ## Background @@ -52,12 +52,12 @@ database and functions to handle these changes in the source data. starting in 2024. Null if the agency number did not change in 2024. - `agency.agency_name_24` (string, optional): The agency's name starting in 2024. Null if the agency number did not change 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 will need to use these new columns to handle changes to - agency numbers. See this vignette for a demonstration of how to - use the new columns to construct a crosswalk for agency numbers - across years: _TK: Link to vignette_ + - **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 will need to use these new columns to handle changes to + agency numbers. See this vignette for a demonstration of how to + use the new columns to construct a crosswalk for agency numbers + across years: _TK: Link to vignette_ - **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 From 36192dd7eabcf826ed53510229f3987f09899092 Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Thu, 23 Apr 2026 12:08:59 -0500 Subject: [PATCH 06/16] Clean up the description of the agency -> fund change in `NEWS.md` --- NEWS.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/NEWS.md b/NEWS.md index c3e86d4..5a43a73 100644 --- a/NEWS.md +++ b/NEWS.md @@ -17,7 +17,29 @@ new integrated property tax system of record. The main changes that the Clerk and the Treasurer made in 2024 include: -- **Changed agency numbers to enable reporting some funds as agencies**. +- **Changed a small number of agencies to funds**. An example is the City of + Chicago library fund, whose agency number (`030210001`) had a non-zero levy + in the `agency` table in 2023, but has a $0 levy in 2024. Instead, the library + fund's levy is listed in the `agency_fund` table for 2024 using the agency + number for the City of Chicago (`030210000`). By reporting this kind of levy + as a fund underneath a parent agency rather than an independent agency, the + format of the Clerk's data is now more similar to the format that + agencies like the City of Chicago use for their own internal accounting. + - In 2024, only 78 agencies were affected by this change, representing + roughly 4% of all agencies. All of the changed agencies fit into one + of the following categories: + - Mental health districts + - Public health funds + - 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: + +```sql +SELECT * FROM agency_info WHERE agency_change_24 +``` + - **Switched from three-digit to six-digit fund numbers to support new types of funds**. Prior to 2024, fund numbers (`agency_fund.fund_num`) consisted of three digits, and funds with the same `fund_num` in different From 0c52c66cfefc918331bdd140a9df80bf3220e0ca Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Thu, 23 Apr 2026 12:56:41 -0500 Subject: [PATCH 07/16] Added more detail to six-digit fund numbers bullet in `NEWS.md` --- NEWS.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/NEWS.md b/NEWS.md index 5a43a73..7caffcb 100644 --- a/NEWS.md +++ b/NEWS.md @@ -40,13 +40,19 @@ The main changes that the Clerk and the Treasurer made in 2024 include: SELECT * FROM agency_info WHERE agency_change_24 ``` -- **Switched from three-digit to six-digit fund numbers to support new types - of funds**. Prior to 2024, fund numbers (`agency_fund.fund_num`) +- **Switched from three-digit to six-digit fund numbers to add a greater level + of detail to funds**. Prior to 2024, fund numbers (`agency_fund.fund_num`) consisted of three digits, and funds with the same `fund_num` in different agencies always referred to the same type of fund. In 2024, the Clerk changed their fund numbers so that they consist of six digits, and they are no longer - guaranteed to refer to the same type of fund across agencies. The new types - of funds that this change supports are primarily bond series. + guaranteed to refer to the same type of fund across agencies. + - To see the full list of funds that are new in 2024, run the following + query against the 2024 PTAXSIM database: + +```sql +SELECT * FROM agency_fund_info WHERE fund_num NOT LIKE '%000' +``` + - **Changed the TIF revenue share calculation so that it is performed at the PIN-level rather than the tax-code-level**. This means that TIF increment is now calculated based on the difference between the frozen and current taxable From 61f5b9694170f0359b42926f818f14177c5a7fab Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Thu, 23 Apr 2026 13:06:55 -0500 Subject: [PATCH 08/16] Cleaned up TIF section and moved it to the top of the 1.1.0 announcement in `NEWS.md` --- NEWS.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/NEWS.md b/NEWS.md index 7caffcb..1a241e4 100644 --- a/NEWS.md +++ b/NEWS.md @@ -17,6 +17,14 @@ new integrated property tax system of record. The main changes that the Clerk and the Treasurer made in 2024 include: +- **Changed the TIF revenue share calculation so that it is performed at the + PIN-level rather than the tax-code-level**. This means that TIF increment is + now calculated based on the difference between the frozen and current taxable + EAV _for each individual PIN in a TIF_, rather than the difference between the + frozen and current taxable EAV of its tax code as a whole. As a result of this + change, a TIF can now have a positive increment even if the total taxable EAV + of its tax code has declined since its establishment, as long as individual + PINs within the tax code have experienced EAV growth during that time. - **Changed a small number of agencies to funds**. An example is the City of Chicago library fund, whose agency number (`030210001`) had a non-zero levy in the `agency` table in 2023, but has a $0 levy in 2024. Instead, the library @@ -53,11 +61,6 @@ SELECT * FROM agency_info WHERE agency_change_24 SELECT * FROM agency_fund_info WHERE fund_num NOT LIKE '%000' ``` -- **Changed the TIF revenue share calculation so that it is performed at the - PIN-level rather than the tax-code-level**. This means that TIF increment is - now calculated based on the difference between the frozen and current taxable - EAV for each individual PIN in a TIF, rather than the frozen and current - taxable EAV of the tax code as a whole. - **Removed a number of minor columns from agency reports**. None of these columns were used in any core PTAXSIM functions, so we expect that their absence will not affect most users. From 7ed99ce15c06ad279e4f4b2d95ffaa64404fc91e Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Thu, 23 Apr 2026 13:09:25 -0500 Subject: [PATCH 09/16] Fix table reference for `agency_info.agency_*_24` fields in `NEWS.md` --- NEWS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/NEWS.md b/NEWS.md index 1a241e4..7b704d5 100644 --- a/NEWS.md +++ b/NEWS.md @@ -73,9 +73,9 @@ database and functions to handle these changes in the source data. ## Breaking changes -- **Added new `agency.agency_*_24` columns to handle changing agency numbers - in 2024**. You can use these columns to construct a crosswalk to analyze - agencies over time, even if their agency number changed in 2024. +- **Added new `agency_info.agency_*_24` columns to handle changing agency + numbers in 2024**. You can use these columns to construct a crosswalk to + analyze agencies over time, even if their agency number changed in 2024. - The new columns include: - `agency.agency_change_24` (boolean, required): Whether the agency's number changed in 2024. From c0bd0387924cd3eeda8d46cdfb9ae8f65e0efabd Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Thu, 23 Apr 2026 13:26:44 -0500 Subject: [PATCH 10/16] Apply Kyra's small suggestions from code review Co-authored-by: Kyra Sturgill <49281603+kyrasturgill@users.noreply.github.com> --- NEWS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/NEWS.md b/NEWS.md index 7b704d5..d37e95d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -98,7 +98,7 @@ database and functions to handle these changes in the source data. `agency_fund.fund_type_num` to represent the notion of a "fund type" that is consistent across agencies. - **How this change affects you**: If you use `agency_fund.fund_num` to - track specific types of funds across agencies, you will need to switch to + track specific funds across agencies, you will need to switch to using `agency_fund.fund_type_num` for that purpose. - **Changed the `agency_fund_info` table so that it is now unique by `(agency_num, fund_num)` instead of `(fund_num)`**. Since fund numbers are @@ -129,7 +129,7 @@ database and functions to handle these changes in the source data. - The dropped columns are: - `agency_fund.ptell_reduced_ind` (PTELL-reduced levy indicator) - `agency.reduction_type` (PTELL-reduced levy type) - - `agency.total_non_cap_ext` (Total non-capped extension for an agency) + - `agency.total_reduced_levy` (PTELL reduced levy total) - **How this change affects you**: If you use any of the columns listed above, you will need to remove them from your code. Feel free to [open an issue](https://github.com/ccao-data/ptaxsim/issues/new) to ask for help From 2a2cb193a6c6e4f0ba04fdd2e236ab923b8c37fc Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Thu, 23 Apr 2026 13:28:59 -0500 Subject: [PATCH 11/16] Reworded `agency_*_24` note in "Breaking changes" section in `News.md` to match "Background" section --- NEWS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/NEWS.md b/NEWS.md index d37e95d..fbfc053 100644 --- a/NEWS.md +++ b/NEWS.md @@ -73,12 +73,12 @@ database and functions to handle these changes in the source data. ## Breaking changes -- **Added new `agency_info.agency_*_24` columns to handle changing agency - numbers in 2024**. You can use these columns to construct a crosswalk to - analyze agencies over time, even if their agency number changed in 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.agency_change_24` (boolean, required): Whether the agency's - number changed in 2024. + number changed in 2024, due to becoming a fund. - `agency.agency_num_24` (string, optional): The agency's new number starting in 2024. Null if the agency number did not change in 2024. - `agency.agency_name_24` (string, optional): The agency's name starting in From cec005236906fd3c843a7af469eae9838ddfa324 Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Thu, 23 Apr 2026 13:30:48 -0500 Subject: [PATCH 12/16] Move `pin_tif_distribution` note to top of "Breaking changes" section in `NEWS.md` to match "Background" section --- NEWS.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/NEWS.md b/NEWS.md index fbfc053..9b2e27b 100644 --- a/NEWS.md +++ b/NEWS.md @@ -73,6 +73,22 @@ database and functions to handle these changes in the source data. ## Breaking changes +- **Added a new table `pin_tif_distribution` and associated lookup function + `lookup_pin_tif()` to handle the methodological change to the TIF + revenue share calculation.** The `tax_bill()` function now also accepts an + optional `pin_tif_dt` argument that you can use for post-2024 TIF + counterfactuals. + - Note that there are now two different TIF lookup functions, each of + which applies to a different set of years: + - `lookup_pin_tif()` will only return rows where `year >= 2024`. + - `lookup_tif()` will only return rows where `year < 2024`. + - **How this change affects you**: If you maintain any TIF counterfactuals, + you will need to update your use of the `tax_bill()` function to pass in + an altered `pin_tif_dt` for any tax years that you analyze beyond 2023. + For an example of this type of change, see the [Tinkering with TIFs + 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. - **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. @@ -109,22 +125,6 @@ database and functions to handle these changes in the source data. - **How this change affects you**: If you use the `agency_fund_info` table and treat it as unique by `fund_num`, you will need to update your code to add `agency_num` when joining to this table. -- **Added a new table `pin_tif_distribution` and associated lookup function - `lookup_pin_tif()` to handle the methodological change to the TIF - revenue share calculation.** The `tax_bill()` function also accepts an - optional `pin_tif_dt` argument that you can use for post-2024 TIF - counterfactuals. - - Note that there are now two different TIF lookup functions, each of - which applies to a different set of years: - - `lookup_pin_tif()` will only return rows where `year >= 2024`. - - `lookup_tif()` will only return rows where `year < 2024`. - - **How this change affects you**: If you maintain any TIF counterfactuals, - you will need to update your use of the `tax_bill()` function to pass in - an altered `pin_tif_dt` for any tax years that you analyze beyond 2023. - For an example of this type of change, see the [Tinkering with TIFs - 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. - **Dropped a few columns that the Clerk has removed from its agency reports**. - The dropped columns are: - `agency_fund.ptell_reduced_ind` (PTELL-reduced levy indicator) From fc6ecf7992979ec6ad35e58d6794b51daa2aa8e0 Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Thu, 23 Apr 2026 17:26:42 -0500 Subject: [PATCH 13/16] Clarify reason behind 2024 fund number format change in `NEWS.md` --- NEWS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/NEWS.md b/NEWS.md index 9b2e27b..bf4a0cd 100644 --- a/NEWS.md +++ b/NEWS.md @@ -51,9 +51,9 @@ SELECT * FROM agency_info WHERE agency_change_24 - **Switched from three-digit to six-digit fund numbers to add a greater level of detail to funds**. Prior to 2024, fund numbers (`agency_fund.fund_num`) consisted of three digits, and funds with the same `fund_num` in different - agencies always referred to the same type of fund. In 2024, the Clerk changed - their fund numbers so that they consist of six digits, and they are no longer - guaranteed to refer to the same type of fund across agencies. + agencies always had the same `fund_name`. In 2024, the Clerk changed their + fund numbers so that they consist of six digits, and they are no longer + guaranteed to share the same name across agencies. - To see the full list of funds that are new in 2024, run the following query against the 2024 PTAXSIM database: @@ -108,7 +108,7 @@ database and functions to handle these changes in the source data. - **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 - guaranteed to refer to the same type of fund across agencies. However, the + guaranteed to refer to the same `fund_name` across agencies. However, the first three digits of a fund number are still guaranteed to refer to a consistent fund "type", so we introduced a new column `agency_fund.fund_type_num` to represent the notion of a "fund type" that From a5dbb86f882d272396fbcf499bf97ed90fee59ff Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Fri, 24 Apr 2026 14:46:00 -0500 Subject: [PATCH 14/16] Add links and more agency -> fund detail to `NEWS.md` --- NEWS.md | 41 ++++++++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/NEWS.md b/NEWS.md index bf4a0cd..cf7ea66 100644 --- a/NEWS.md +++ b/NEWS.md @@ -74,14 +74,17 @@ database and functions to handle these changes in the source data. ## Breaking changes - **Added a new table `pin_tif_distribution` and associated lookup function - `lookup_pin_tif()` to handle the methodological change to the TIF - revenue share calculation.** The `tax_bill()` function now also accepts an - optional `pin_tif_dt` argument that you can use for post-2024 TIF + [`lookup_pin_tif()`](https://ccao-data.github.io/ptaxsim/reference/lookup_pin_tif.html) + to handle the methodological change to the TIF revenue share calculation**. + The [`tax_bill()`](https://ccao-data.github.io/ptaxsim/reference/tax_bill.html) + function now also accepts an optional `pin_tif_dt` argument that you can use for post-2024 TIF counterfactuals. - Note that there are now two different TIF lookup functions, each of which applies to a different set of years: - - `lookup_pin_tif()` will only return rows where `year >= 2024`. - - `lookup_tif()` will only return rows where `year < 2024`. + - [`lookup_pin_tif()`](https://ccao-data.github.io/ptaxsim/reference/lookup_pin_tif.html) + will only return rows where `year >= 2024`. + - [`lookup_tif()`](https://ccao-data.github.io/ptaxsim/reference/lookup_tif.html) + will only return rows where `year < 2024`. - **How this change affects you**: If you maintain any TIF counterfactuals, you will need to update your use of the `tax_bill()` function to pass in an altered `pin_tif_dt` for any tax years that you analyze beyond 2023. @@ -100,11 +103,14 @@ database and functions to handle these changes in the source data. - `agency.agency_name_24` (string, optional): The agency's name starting in 2024. Null if the agency number did not change 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 will need to use these new columns to handle changes to - agency numbers. See this vignette for a demonstration of how to - use the new columns to construct a crosswalk for agency numbers - across years: _TK: Link to vignette_ + agencies over time, and you want to update your code to include 2024 data, + you should use the `agency.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. - **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 @@ -161,7 +167,9 @@ database and functions to handle these changes in the source data. - **Added a new exemption column `pin.exe_vet_dis_100`**. This column corresponds to the new 100% disability level for the [Veterans with Disabilities Exemption](https://www.cookcountyassessoril.gov/veterans-disabilities-exemption). - The lookup function `lookup_pin()` now returns this column. + The lookup function + [`lookup_pin()`](https://ccao-data.github.io/ptaxsim/reference/lookup_pin.html) + now returns this column. - **How this change affects you**: You may use this column if you would like to analyze this new exemption. - **Added a new column `agency.authority_num`**. We expect this column to be @@ -184,11 +192,14 @@ 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 to demonstrate the correct way to handle agency - numbers that changed in 2024 (_TK: Link to vignette_)** +- **Added [a new + vignette](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)). - - **How this change affects you**: You should read the latest version of the - vignette if you use PTAXSIM to analyze specific agencies over time. + - **How this change affects you**: You should read the vignette if you use + PTAXSIM to analyze specific agencies over time so that you understand how + to update your code. ## Bug fixes From 30f01dfb54fc8d718b55afb8c5299888c5fbd8ac Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Fri, 24 Apr 2026 15:40:59 -0500 Subject: [PATCH 15/16] Add extra clarity for fund number docs in `NEWS.md` --- NEWS.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/NEWS.md b/NEWS.md index cf7ea66..3a8814d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -53,7 +53,11 @@ SELECT * FROM agency_info WHERE agency_change_24 consisted of three digits, and funds with the same `fund_num` in different agencies always had the same `fund_name`. In 2024, the Clerk changed their fund numbers so that they consist of six digits, and they are no longer - guaranteed to share the same name across agencies. + guaranteed to share the same name across agencies. The Clerk also added many + new six-digit funds that were previously aggregated into larger three-digit + funds. For these new six-digit funds, the first three digits of the fund + number always matches the three-digit number for the aggregate fund that + existed prior to 2024. - To see the full list of funds that are new in 2024, run the following query against the 2024 PTAXSIM database: @@ -122,6 +126,15 @@ database and functions to handle these changes in the source data. - **How this change affects you**: If you use `agency_fund.fund_num` to track specific funds across agencies, you will need to switch to using `agency_fund.fund_type_num` for that purpose. +- **Appended three trailing zeros (`000`) to all fund numbers in `agency_fund` + and `agency_fund_info` for years prior to 2024**. This change is necessary + in order to align three-digit pre-2024 fund numbers with their new six-digit + representations in 2024. + - **How this change affects you**: If you maintain code that references + specific three-digit `fund_num` values, you will need to update these + values to append three trailing zeros. Alternatively, you could update + your code to reference `fund_type_num` instead of `fund_num`, per the + bullet point above. - **Changed the `agency_fund_info` table so that it is now unique by `(agency_num, fund_num)` instead of `(fund_num)`**. Since fund numbers are no longer consistent across agencies, we can't use them as the exclusive basis From 5596ac732ba5c86992fbc7c35a67349521e67f5c Mon Sep 17 00:00:00 2001 From: Jean Cochrane Date: Fri, 24 Apr 2026 15:50:21 -0500 Subject: [PATCH 16/16] Fix table references for `agency_*_24` columns in `NEWS.md` --- NEWS.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/NEWS.md b/NEWS.md index 3a8814d..5734a69 100644 --- a/NEWS.md +++ b/NEWS.md @@ -100,18 +100,18 @@ database and functions to handle these changes in the source data. 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.agency_change_24` (boolean, required): Whether the agency's + - `agency_info.agency_change_24` (boolean, required): Whether the agency's number changed in 2024, due to becoming a fund. - - `agency.agency_num_24` (string, optional): The agency's new number + - `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. - - `agency.agency_name_24` (string, optional): The agency's name starting in - 2024. Null if the agency number did not change 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.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 + 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.