AMS-I.J Methodology Walkthrough

Introduction

This vignette demonstrates how to reproduce the AMS-I.J calculations using cdmAmsIj. The methodology covers solar water heating systems that displace fossil or electric water heating. The core steps include summing useful solar thermal output, applying baseline emission factors, and accounting for auxiliary energy use.

Applicability Checks 

library(cdmAmsIj)
check_applicability_swh_capacity(capacity_mwth = 18)
## [1] TRUE
check_applicability_solar_resource(annual_irradiation_kwhm2 = 1900)
## [1] TRUE
check_applicability_backup_fraction(backup_fraction = 0.15)
## [1] TRUE

Simulated Dataset 

set.seed(123)
example_data <- simulate_ams_ij_dataset(n_sites = 4, n_periods = 6, start_year = 2024, start_month = 7)
quiet_kable(
  head(example_data),
  format = "html",
  digits = 3
)
## Warning: 'xfun::attr()' is deprecated.
## Use 'xfun::attr2()' instead.
## See help("Deprecated")
site_id monitoring_period year month day monitoring_date monitoring_label useful_heat_mwh auxiliary_energy_mwh baseline_emission_factor auxiliary_emission_factor baseline_emissions_tco2e project_emissions_tco2e emission_reductions_tco2e solar_fraction
site_1 1 2024 7 15 2024-07-15 2024-07 65.349 7.281 0.22 0.18 14.377 1.310 13.066 0.889
site_1 2 2024 8 19 2024-08-19 2024-08 36.449 5.989 0.22 0.18 8.019 1.078 6.941 0.836
site_1 3 2024 9 14 2024-09-14 2024-09 89.072 7.925 0.22 0.18 19.596 1.427 18.169 0.911
site_1 4 2024 10 3 2024-10-03 2024-10 78.536 13.487 0.22 0.18 17.278 2.428 14.850 0.828
site_1 5 2024 11 10 2024-11-10 2024-11 58.750 11.163 0.22 0.18 12.925 2.009 10.916 0.810
site_1 6 2024 12 18 2024-12-18 2024-12 42.388 6.011 0.22 0.18 9.325 1.082 8.243 0.858

The simulation includes monitoring metadata (monitoring_period, year, month, day, and monitoring_label) so that calculations can be aggregated over reporting periods while preserving site-level identifiers.

Equation Walkthrough 

useful_output <- calculate_useful_thermal_output(example_data, group_cols = "site_id")
baseline_emissions <- calculate_baseline_emissions(
  useful_output,
  baseline_emission_factor = example_data$baseline_emission_factor[1]
)
project_emissions <- calculate_project_emissions_auxiliary(
  example_data,
  energy_col = "auxiliary_energy_mwh",
  emission_factor = example_data$auxiliary_emission_factor[1],
  group_cols = "site_id"
)
emission_reductions <- calculate_emission_reductions(baseline_emissions, project_emissions)
quiet_kable(head(emission_reductions), format = "html", digits = 3)
## Warning: 'xfun::attr()' is deprecated.
## Use 'xfun::attr2()' instead.
## See help("Deprecated")
site_id useful_thermal_output_mwh baseline_emissions_tco2e project_emissions_tco2e emission_reductions_tco2e
site_1 370.543 81.520 9.334 72.185
site_2 328.906 72.359 7.758 64.601
site_3 290.930 64.005 9.047 54.957
site_4 307.547 67.660 8.862 58.798

Monitoring Period Aggregation 

period_summary <- aggregate_monitoring_periods(
  thermal_data = example_data,
  monitoring_cols = c("monitoring_label"),
  group_cols = "site_id",
  useful_energy_col = "useful_heat_mwh",
  auxiliary_energy_col = "auxiliary_energy_mwh",
  baseline_factor_col = "baseline_emission_factor",
  auxiliary_factor_col = "auxiliary_emission_factor"
)

quiet_kable(head(period_summary), format = "html", digits = 3)
## Warning: 'xfun::attr()' is deprecated.
## Use 'xfun::attr2()' instead.
## See help("Deprecated")
site_id monitoring_label baseline_emissions_tco2e project_emissions_tco2e emission_reductions_tco2e useful_thermal_output_mwh baseline_emission_factor auxiliary_emission_factor
site_1 2024-07 14.377 1.310 13.066 65.349 0.22 0.18
site_1 2024-08 8.019 1.078 6.941 36.449 0.22 0.18
site_1 2024-09 19.596 1.427 18.169 89.072 0.22 0.18
site_1 2024-10 17.278 2.428 14.850 78.536 0.22 0.18
site_1 2024-11 12.925 2.009 10.916 58.750 0.22 0.18
site_1 2024-12 9.325 1.082 8.243 42.388 0.22 0.18

Meta-Function 

estimate_emission_reductions_ams_ij(
  thermal_data = example_data,
  baseline_emission_factor = example_data$baseline_emission_factor[1],
  auxiliary_emission_factor = example_data$auxiliary_emission_factor[1],
  group_cols = "site_id"
)
## # A tibble: 4 × 5
##   site_id useful_thermal_output_…¹ baseline_emissions_t…² project_emissions_tc…³
##   <chr>                      <dbl>                  <dbl>                  <dbl>
## 1 site_1                      371.                   81.5                   9.33
## 2 site_2                      329.                   72.4                   7.76
## 3 site_3                      291.                   64.0                   9.05
## 4 site_4                      308.                   67.7                   8.86
## # ℹ abbreviated names: ¹​useful_thermal_output_mwh, ²​baseline_emissions_tco2e,
## #   ³​project_emissions_tco2e
## # ℹ 1 more variable: emission_reductions_tco2e <dbl>

Function Reference 

function_reference <- tibble::tibble(
  Function = c(
    "`calculate_useful_thermal_output()`",
    "`calculate_baseline_emissions()`",
    "`calculate_project_emissions_auxiliary()`",
    "`calculate_emission_reductions()`",
    "`aggregate_monitoring_periods()`",
    "`estimate_emission_reductions_ams_ij()`",
    "`simulate_ams_ij_dataset()`"
  ),
  Signature = c(
    "`calculate_useful_thermal_output(thermal_data, energy_col = \"useful_heat_mwh\", group_cols = NULL)`",
    "`calculate_baseline_emissions(useful_output, baseline_emission_factor, output_col = \"baseline_emissions_tco2e\")`",
    "`calculate_project_emissions_auxiliary(auxiliary_data, energy_col = \"auxiliary_energy_mwh\", emission_factor = 0, group_cols = NULL)`",
    "`calculate_emission_reductions(baseline_emissions, project_emissions, baseline_col = \"baseline_emissions_tco2e\", project_col = \"project_emissions_tco2e\", output_col = \"emission_reductions_tco2e\")`",
    "`aggregate_monitoring_periods(thermal_data, monitoring_cols = c(\"year\", \"month\"), group_cols = \"site_id\")`",
    "`estimate_emission_reductions_ams_ij(thermal_data, baseline_emission_factor, auxiliary_emission_factor = 0, group_cols = NULL)`",
    "`simulate_ams_ij_dataset(n_sites = 10, n_periods = 12, start_year = 2023, start_month = 1, mean_useful_heat_mwh = 360, sd_useful_heat_mwh = 55, baseline_emission_factor = 0.22, auxiliary_emission_factor = 0.18)`"
  ),
  Purpose = c(
    "Summed useful solar thermal output for each group or monitoring period.<br>\\(Q^{useful}_y = \\sum_i Q_{i,y}\\)",
    "Baseline emissions derived from displaced conventional water heating.<br>\\(BE_y = Q^{useful}_y \\times EF^{BL}\\)",
    "Project emissions reflecting auxiliary heating energy.<br>\\(PE_y = \\sum_i AUX_{i,y} \\times EF^{aux}_{i,y}\\)",
    "Emission reductions obtained from the difference between baseline and project emissions.<br>\\(ER_y = BE_y - PE_y\\)",
    "Monitoring-period aggregation consistent with methodology equations.<br>\\(ER_{p,y} = BE_{p,y} - PE_{p,y}\\)",
    "Meta-calculation wrapper chaining the equation helpers.<br>\\(ER_y = BE_y - PE_y\\)",
    "Data generator for examples, testing, and onboarding."
  )
)

quiet_kable(function_reference, format = "html", escape = FALSE)
## Warning: 'xfun::attr()' is deprecated.
## Use 'xfun::attr2()' instead.
## See help("Deprecated")
Function Signature Purpose
calculate_useful_thermal_output() calculate_useful_thermal_output(thermal_data, energy_col = "useful_heat_mwh", group_cols = NULL) Summed useful solar thermal output for each group or monitoring period.
Qyuseful=∑iQi,yQ^{useful}_y = \sum_i Q_{i,y}
calculate_baseline_emissions() calculate_baseline_emissions(useful_output, baseline_emission_factor, output_col = "baseline_emissions_tco2e") Baseline emissions derived from displaced conventional water heating.
BEy=Qyuseful×EFBLBE_y = Q^{useful}_y \times EF^{BL}
calculate_project_emissions_auxiliary() calculate_project_emissions_auxiliary(auxiliary_data, energy_col = "auxiliary_energy_mwh", emission_factor = 0, group_cols = NULL) Project emissions reflecting auxiliary heating energy.
PEy=∑iAUXi,y×EFi,yauxPE_y = \sum_i AUX_{i,y} \times EF^{aux}_{i,y}
calculate_emission_reductions() calculate_emission_reductions(baseline_emissions, project_emissions, baseline_col = "baseline_emissions_tco2e", project_col = "project_emissions_tco2e", output_col = "emission_reductions_tco2e") Emission reductions obtained from the difference between baseline and project emissions.
ERy=BEy−PEyER_y = BE_y - PE_y
aggregate_monitoring_periods() aggregate_monitoring_periods(thermal_data, monitoring_cols = c("year", "month"), group_cols = "site_id") Monitoring-period aggregation consistent with methodology equations.
ERp,y=BEp,y−PEp,yER_{p,y} = BE_{p,y} - PE_{p,y}
estimate_emission_reductions_ams_ij() estimate_emission_reductions_ams_ij(thermal_data, baseline_emission_factor, auxiliary_emission_factor = 0, group_cols = NULL) Meta-calculation wrapper chaining the equation helpers.
ERy=BEy−PEyER_y = BE_y - PE_y
simulate_ams_ij_dataset() simulate_ams_ij_dataset(n_sites = 10, n_periods = 12, start_year = 2023, start_month = 1, mean_useful_heat_mwh = 360, sd_useful_heat_mwh = 55, baseline_emission_factor = 0.22, auxiliary_emission_factor = 0.18) Data generator for examples, testing, and onboarding.

Workflow Overview 

## Warning: 'xfun::attr()' is deprecated.
## Use 'xfun::attr2()' instead.
## See help("Deprecated")
Step Purpose
Input solar thermal monitoring data Collect monitoring period, useful heat, auxiliary energy, and emission factor metrics.
calculate_useful_thermal_output Summarise useful solar thermal output for each site or reporting period.
calculate_baseline_emissions Apply baseline emission factors to displaced conventional energy use.
calculate_project_emissions_auxiliary Convert auxiliary energy consumption into project emissions.
calculate_emission_reductions Compare baseline and project totals to obtain emission reductions.
estimate_emission_reductions_ams_ij Return a tidy tibble with reductions and supporting diagnostics.