Rationalize unsimplified transit TIF output for `tax_bill()`

[jeancochrane]

As a rookie, I was confused by a three design choices in the tax_bill() output related to transit TIFs when simplify = FALSE in the course of reviewing #58:

1. transit_tif_to_dist has a different meaning compared to the other transit_tif_to_{x} columns at the agency level

At the agency level, the transit_tif_to_cps and transit_tif_to_tif columns both represent the amount that the agency's portion of the tax bill contributes to the various recipients of transit TIF revenue (in this case, CPS and the TIF, respectively) while transit_tif_to_dist represents the amount that the agency receives from the bill's contribution to the total pot of TIF revenue. This is because CPS is excluded from the pot of revenue that the TIF distributes to non-CPS agencies proportionate to their share of the composite tax rate (the second chained operation below):

ptaxsim/R/tax_bill.R

Lines 230 to 241 in f687a70

	# Assign the remaining 20% to each district, then divvy up CPS's 20%
	# proportionate to each district's tax rate
	dt[
	(in_rpm_tif),
	rpm_tif_to_dist := (final_tax_to_tif - rpm_tif_to_cps) * 0.2
	][
	(in_rpm_tif),
	rpm_tif_to_dist :=
	rpm_tif_to_dist + rpm_tif_to_dist[agency_num == "044060000"] *
	(agency_tax_rate / sum(agency_tax_rate[agency_num != "044060000"])),
	by = .(year, pin)
	]

As a result, final_tax_to_tif is not equal to transit_tif_to_tif + transit_tif_to_cps + transit_tif_to_dist at the agency level. (It is equivalent when aggregated to the PIN level, which we've found to be more important for the analyses we run anyway.) I found this fact to be counterintuitive, and it also surprised me that there is not another way of reproducing the component parts of final_tax_to_tif for transit TIFs at the agency level without knowing the package internals or the statute.

2. transit_tif_to_dist has a different meaning for CPS compared to other agencies

As mentioned above, for all agencies except CPS, transit_tif_to_dist represents the amount that the agency receives from the bill's contribution to the total pot of TIF revenue. However, in the specific case of CPS, transit_tif_to_dist is always $0, and if you want to know the amount that CPS receives from the bill's contribution to the total pot of TIF revenue then you have to know to sum across transit_tif_to_cps for every agency in that PIN's bill.

ptaxsim/R/tax_bill.R

Lines 243 to 245 in f687a70

	# Set CPS share that goes back to districts to 0, since they have their own
	# special distribution
	dt[in_rpm_tif & agency_num == "044060000", rpm_tif_to_dist := 0]

3. final_tax_to_dist does not include CPS's share of transit TIF revenue

Recall that final_tax_to_dist is equal to tax_amt_post_exe - final_tax_to_tif + transit_tif_to_dist -- in plain English, that's the total amount that the agency raises before considering the TIF (tax_amt_post_exe) minus the agency's contribution to the TIF (final_tax_to_tif) plus any revenue that the agency receives from transit TIF distribution (transit_tif_to_dist).

ptaxsim/R/tax_bill.R

Lines 257 to 258 in f687a70

	dt[, final_tax_to_dist :=
	round(tax_amt_post_exe - final_tax_to_tif + rpm_tif_to_dist, 2)]

Due to issue 2 described above, transit_tif_to_dist does not actually include the revenue that CPS receives from transit TIF distribution, and is always $0 in the case of CPS. Hence, for CPS, final_tax_to_dist does not include CPS's share of transit TIF revenue, and so it is not comparable to final_tax_to_dist for other agencies.

Recommended changes

I think we could make the unsimplified output of tax_bill() more intuitive in the transit TIF case if we made the following changes:

1. Add a new column to preserve the agency's contribution to the non-CPS transit TIF distribution. This new column would be in addition to the column we currently call transit_tif_to_dist, which would continue to represent the amount that the agency receives from the non-CPS transit TIF distribution. This would allow users to easily back out the component parts of final_tax_to_tif by summing across the three transit_tif_to_{x} fields representing the contribution of the agency's portion of the bil to the transit TIF. The final data model might look something like this:
   • transit_tif_to_tif: The amount that this agency's portion of the bill contributes to the post-distribution transit TIF (no change)
   • transit_tif_to_cps: The amount that this agency's portion of the bill contributes to the CPS distribution of the transit TIF (no change)
   • transit_tif_to_non_cps_dists: The amount that this agency's portion of the bill contributes to the non-CPS distribution of the transit TIF (new column)
   • transit_tif_to_dist: The amount that this agency receives from the non-CPS distribution of the transit TIF (no change)
2. Set transit_tif_to_dist equal to the sum of transit_tif_to_cps across all agencies in the bill for the specific case of CPS. This would make transit_tif_to_dist comparable for all agencies, including CPS, allowing users to easily aggregate the column without handling the special CPS case.
3. Include CPS's share of transit TIF distribution in final_tax_to_dist. This would make final_tax_to_dist comparable across all agencies, including CPS, allowing users to aggregate the column.

These changes would likely increase the complexity of the simplify = TRUE case, since that conditional branch would have to perform extra work to separate out the CPS transit TIF distribution into its own line item. However, we already treat that as a special case in the code, so it wouldn't be a substantial change in complexity, and I also think it's better to place the burden of complexity on the code rather than on the user of the function output.