Merge pull request #219 from NREL/develop

Create and export easiur_data function

CHANGELOG.md

@@ -23,6 +23,11 @@ Classify the change according to the following categories:
     ### Deprecated
     ### Removed
 
+## v0.31.0
+### Added
+- Created and exported easiur_data function (returns health emissions costs and escalations) for the API to be able to call for it's easiur_costs endpoint
+- Added docstrings for easiur_data and emissions_profiles
+
 ## v0.30.0
 ### Added
 - `Generator` input **fuel_higher_heating_value_kwh_per_gal**, which defaults to the constant KWH_PER_GAL_DIESEL

Project.toml

@@ -1,7 +1,7 @@
 name = "REopt"
 uuid = "d36ad4e8-d74a-4f7a-ace1-eaea049febf6"
 authors = ["Nick Laws", "Hallie Dunham <[email protected]>", "Bill Becker <[email protected]>", "Bhavesh Rathod <[email protected]>", "Alex Zolan <[email protected]>", "Amanda Farthing <[email protected]>"]
-version = "0.30.0"
+version = "0.31.0"
 
 [deps]
 ArchGDAL = "c9ce4bd3-c3d5-55b8-8973-c0e20141b8c3"

src/REopt.jl

@@ -49,7 +49,8 @@ export
     get_steam_turbine_defaults_size_class,
     simulated_load,
     get_absorption_chiller_defaults,
-    emissions_profiles
+    emissions_profiles,
+    easiur_data
 
 import HTTP
 import JSON

src/core/electric_utility.jl

@@ -374,10 +374,25 @@ function region_name_to_abbr(region_name)
     return get(lookup, region_name, "")
 end
 
-#TODO: add docstring
-function emissions_profiles(; latitude, longitude, time_steps_per_hour=1)
+"""
+    emissions_profiles(; latitude::Real, longitude::Real, time_steps_per_hour::Int=1)
+
+This function gets CO2, NOx, SO2, and PM2.5 grid emission rate profiles (1-year time series) from the AVERT dataset.
+    
+This function is used for the /emissions_profile endpoint in the REopt API, in particular 
+    for the webtool to display grid emissions defaults before running REopt, 
+    but is also generally an external way to access AVERT data without running REopt.
+"""
+function emissions_profiles(; latitude::Real, longitude::Real, time_steps_per_hour::Int=1)
     region_abbr, meters_to_region = region_abbreviation(latitude, longitude)
     emissions_region = region_abbr_to_name(region_abbr)
+    if isnothing(region_abbr)
+        return Dict{String, Any}(
+                "error"=>
+                "Could not look up AVERT emissions region within 5 miles from point ($(latitude), $(longitude)).
+                Location is likely invalid or well outside continental US, AK and HI."
+            )
+    end
     response_dict = Dict{String, Any}(
         "region_abbr" => region_abbr,
         "region" => emissions_region,

src/core/financial.jl

@@ -471,3 +471,37 @@ Convert Geodetic (lon, lat) to LCP (x, y) in CAMx 148x112 grid
 function g2l(lon::Real, lat::Real; datum::String="NAD83")
     return l2g(lon, lat, inverse=true, datum=datum)
 end
+
+"""
+    easiur_data(; latitude::Real, longitude::Real, inflation::Real)
+
+This function gets NOx, SO2, and PM2.5 costs (for grid and on-site emissions) and cost escalation rates from the EASIUR dataset.
+    
+This function is used for the /easiur_costs endpoint in the REopt API, in particular 
+    for the webtool to display health emissions cost/escalation defaults before running REopt, 
+    but is also generally an external way to access EASIUR data without running REopt.
+"""
+function easiur_data(; latitude::Real, longitude::Real, inflation::Real)
+        grid_costs = easiur_costs(latitude, longitude, "grid")
+        if isnothing(grid_costs)
+            return Dict{String, Any}(
+                    "error"=>
+                    "Could not look up EASIUR health cost data from point ($latitude,$longitude). 
+                    Location is likely invalid or outside the CAMx grid."
+                )
+        end
+        onsite_costs = easiur_costs(latitude, longitude, "onsite")
+        escalation = easiur_escalation_rates(latitude, longitude, inflation)
+        response_dict = Dict{String, Any}(
+            "units_costs" => "US dollars per metric ton",
+            "description_costs" => "Health costs of emissions from the grid and on-site fuel burn, as reported by the EASIUR model.",
+            "units_escalation" => "nominal annual fraction",
+            "description_escalation" => "Annual nominal escalation rate of public health costs of emissions.",
+        )
+        for ekey in ["NOx", "SO2", "PM25"]
+            response_dict[ekey*"_grid_cost_per_tonne"] = grid_costs[ekey]
+            response_dict[ekey*"_onsite_fuelburn_cost_per_tonne"] = onsite_costs[ekey]
+            response_dict[ekey*"_cost_escalation_rate_fraction"] = escalation[ekey]
+        end
+        return response_dict
+end