Allocation assessment for DPS, IPS, and NPS/MS4 entities

Usage

anlz_aa(yrrng, dps_data, ips_data, ml_data, nps_data, tbbase)

Arguments

yrrng: Integer vector of length 2, start and end year, e.g., c(2022, 2024).
dps_data: Data frame from anlz_dps_facility. Required columns: Year, Month, entity, facility, coastco, tn_load.
ips_data: Data frame from anlz_ips_facility. Required columns: Year, Month, entity, facility, coastco, tn_load.
ml_data: Data frame from anlz_ml_facility. Required columns: Year, Month, entity, facility, tn_load.
nps_data: Data frame from anlz_nps called with summ = 'basin' and summtime = 'year'. Required columns: Year, source, segment, basin, tn_load, hy_load. TN loads represent NPS contributions only and are not corrected for point-source loads.
tbbase: data frame containing polygon areas for the combined data layer of bay segment, basin, jurisdiction, land use data, and soils, see details

Value

A data frame with one row per entity (NPS/MS4) or facility (IPS) per bay segment:

bay_seg: Integer bay segment identifier
segment: Bay segment name
entity: MS4 entity name or facility operator
entity_full: Full entity name from nps_allocations (NPS rows only)
facname: Facility name (IPS, DPS, and non-shared ML rows)
permit: NPDES permit number (IPS rows only)
source: Allocation type: "MS4", "Nonpoint Source/MS4", "IPS", "DPS - end of pipe", "DPS - reuse", or "ML"
alloc_pct: Fractional TN allocation (0-1)
alloc_tons: Allocation in TN tons per year
eff_load_tons: Mean hydrologically-normalized TN load (tons/yr), averaged over yrrng; equals load_tons for DPS and ML (no normalization applied)
load_tons: Mean annual TN load (tons/yr) without hydrologic normalization, averaged over yrrng
pass: Logical: eff_load_tons <= alloc_tons; NA when allocation or effective load is missing

Details

Entities present in the computed loads but absent from the allocation tables are retained in the output with NA allocation fields so that unmatched entries are visible for troubleshooting.

DPS path

DPS facility TN loads require no hydrologic normalization. Monthly loads from dps_data are summed to annual totals per facility, averaged over yrrng, and compared directly against the dps_allocations table. The join key is entity + facname + bay\_seg + source, where source distinguishes direct surface water discharge ("DPS - end of pipe") from reclaimed water reuse ("DPS - reuse"). Bay segment 5 (Boca Ciega Bay) is excluded and bayseg 6/7 are remapped to 55.

IPS path

Annual IPS facility TN loads are normalized using the ratio:

$$ \text{eff\_tn} = \text{tn\_load} \times \frac{\text{mean\_h2o\_9294}}{\text{basin\_total\_h2o}} $$

where basin\_total\_h2o is the annual total water load (NPS + DPS + IPS) for the same basin and year, matching the SAS ratio1\_2224 denominator. Effective loads are summed across basins per permit per bay segment, then averaged over yrrng.

ML path

Material loss TN loads require no hydrologic normalization. Monthly loads from ml_data are summed to annual totals per facility, averaged over yrrng, and compared against the ml_allocations table. Facilities with ishared = FALSE are assessed individually on entity + facname + bay segment. Facilities with ishared = TRUE (currently the three Mosaic facilities in Hillsborough Bay) have their loads summed to an entity + bay segment total before comparison to the single shared allocation.

NPS/MS4 path

TN loads in nps_data are NPS-only; no point-source correction is applied to the input loads. Basin-level NPS loads are disaggregated to individual MS4 entities using the output (created internally) from util_aa_npsfactors that combines tbbase, rcclucsid, and emc into:

factor_tn distributes basin TN load among land use classes.
factor_rc distributes each land use class's load among entities proportional to area × runoff coefficient.

Agricultural land use (category "Agriculture") is attributed to the aggregate entity "All" regardless of the underlying MS4 jurisdiction.

Before summing across CLUCSIDs, each entity's disaggregated TN load is scaled by (1 - conserv\_frac) using conserv_correction, which provides entity- and CLUCSID-specific fractions of area times runoff coefficient attributable to conservation land. This removes the conservation land contribution that is absent from the tbeploads-built tbbase.

After disaggregation, loads and 1992-1994 baseline water volumes are summed across basins to the segment level. TN corrections from aa_corrections (ad_tons + project_tons) are subtracted before hydrologic normalization:

$$ \text{eff\_tn} = (\text{tn\_entity} - \text{corr\_tons}) \times \frac{\text{mean\_h2o\_9294}}{\text{total\_h2o}} $$

Bay segments Terra Ceia Bay (6) and Manatee River (7) are merged into segment 55 (Remaining Lower Tampa Bay) after disaggregation, consistent with the hydro_baseline encoding and TBNMC reporting. Boca Ciega Bay (segment 5) is excluded from the allocation framework.

Examples

if (FALSE) { # \dontrun{
fls_dps <- list.files(system.file("extdata/", package = "tbeploads"),
  pattern = "ps_dom_", full.names = TRUE)
dps <- anlz_dps_facility(fls_dps)
fls_ips <- list.files(system.file("extdata/", package = "tbeploads"),
  pattern = "ps_ind_", full.names = TRUE)
ips <- anlz_ips_facility(fls_ips)
fls_ml <- list.files(system.file("extdata/", package = "tbeploads"),
  pattern = "ps_indml", full.names = TRUE)
ml <- anlz_ml_facility(fls_ml)
nps <- anlz_nps(
  yrrng  = c("2022-01-01", "2024-12-31"),
  tbbase = tbbase,
  rain   = rain,
  allwq  = allwq,
  allflo = allflo,
  vernafl = system.file("extdata/verna-raw.csv", package = "tbeploads"),
  summ     = "basin",
  summtime = "year"
)

anlz_aa(c(2022, 2024), dps, ips, ml, nps, tbbase)
} # }