Allocation assessment for NPS/MS4 entities and IPS facilities

Usage

anlz_aa(yrrng, nps_data, ips_data, tbbase, corrections)

Arguments

yrrng: Integer vector of years to include, e.g. 2022:2024.
nps_data: Data frame from anlz_nps called with summ = 'basin' and summtime = 'year'. Required columns: Year, source, segment, basin, tn_load, hy_load.
ips_data: Data frame from anlz_ips_facility. Required columns: Year, Month, entity, facility, coastco, tn_load.
tbbase: data frame containing polygon areas for the combined data layer of bay segment, basin, jurisdiction, land use data, and soils, see details
corrections: Data frame with columns bay_seg, entity, ad_tons, and project_tons. Use aa_corrections as a zero-row placeholder when actual corrections are not yet available.

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 IPS operator name
entity_full: Full entity name from nps_allocations (NPS rows only)
facname: Facility name (IPS rows only)
permit: NPDES permit number (IPS rows only)
source: Allocation type: "MS4", "Nonpoint Source/MS4", or "IPS"
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
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.

NPS/MS4 path

Basin-level NPS loads from nps_data 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.

After disaggregation, loads and 1992-1994 baseline water volumes are summed across basins to the segment level. TN 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{h2o\_entity}} $$

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.

IPS path

Annual IPS facility TN loads are normalized using the same ratio:

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

where basin\_nps\_h2o is the annual NPS water load from nps_data for the same basin and year. Effective loads are summed across basins per permit per bay segment, then averaged over yrrng.

DPS (domestic wastewater) facilities are not included; they are outside the TBNMC allocation framework.

Examples

if (FALSE) { # \dontrun{
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"
)
fls <- list.files(system.file("extdata/", package = "tbeploads"),
  pattern = "ps_ind_", full.names = TRUE)
ips <- anlz_ips_facility(fls)
anlz_aa(2022:2024, nps, ips, tbbase, aa_corrections)
} # }