Merge pull request #614 from electricitymaps/robin/update-forecast-documentation

Make documentation for forecasts signal agnostic

Author: danuw

casdk-docs/docs/tutorial-basics/carbon-aware-webapi.md

@@ -1,8 +1,8 @@
 # Carbon Aware WebApi
 
-The Carbon Aware SDK provides an API to get the marginal carbon intensity for a
+The Carbon Aware SDK provides an API to get the carbon intensity for a
 given location and time period. The values reported in the Green Software
-Foundation's specification for marginal carbon intensity (Grams per Kilowatt
+Foundation's specification for carbon intensity (Grams per Kilowatt
 Hour).
 
 **_Highly Recommended_** - This user interface is best for when you can change
@@ -131,11 +131,11 @@ This endpoint fetches only the most recently generated forecast for all provided
 locations. It uses the "dataStartAt" and "dataEndAt" parameters to scope the
 forecasted data points (if available for those times). If no start or end time
 boundaries are provided, the entire forecast dataset is used. The scoped data
-points are used to calculate average marginal carbon intensities of the
-specified "windowSize" and the optimal marginal carbon intensity window is
+points are used to calculate average carbon intensities of the
+specified "windowSize" and the optimal carbon intensity window is
 identified.
 
-The forecast data represents what the data source predicts future marginal
+The forecast data represents what the data source predicts future
 carbon intesity values to be, not actual measured emissions data (as future
 values cannot be known).
 
@@ -154,7 +154,7 @@ Parameters:
    current forecast data points after this time. Must be within the forecast
    data point timestamps. Defaults to the latest time in the forecast data. If
    neither `dataStartAt` nor `dataEndAt` are provided, all forecasted data
-   points are used in calculating the optimal marginal carbon intensity window.
+   points are used in calculating the optimal carbon intensity window.
 4. `windowSize`: The estimated duration (in minutes) of the workload. Defaults
    to the duration of a single forecast data point.
 
@@ -163,7 +163,7 @@ https://<server_name>/emissions/forecasts/current?location=northeurope&dataStart
 ```
 
 The response is an array of forecasts (one per requested location) with their
-optimal marginal carbon intensity windows.
+optimal carbon intensity windows.
 
 ```json
 [
@@ -202,7 +202,7 @@ optimal marginal carbon intensity windows.
 ### POST emissions/forecasts/batch
 
 This endpoint takes a batch of requests for historical forecast data, fetches
-them, and calculates the optimal marginal carbon intensity windows for each
+them, and calculates the optimal carbon intensity windows for each
 using the same parameters available to the '/emissions/forecasts/current'
 endpoint.
 
@@ -227,7 +227,7 @@ Parameters:
      to the duration of a single forecast data point
 
 If neither `dataStartAt` nor `dataEndAt` are provided, all forecasted data
-points are used in calculating the optimal marginal carbon intensity window.
+points are used in calculating the optimal carbon intensity window.
 
 ```json
 [
@@ -249,7 +249,7 @@ points are used in calculating the optimal marginal carbon intensity window.
 ```
 
 The response is an array of forecasts (one per requested location) with their
-optimal marginal carbon intensity windows.
+optimal carbon intensity windows.
 
 ```json
 [
@@ -310,7 +310,7 @@ https://<server_name>/emissions/average-carbon-intensity?location=eastus&startTi
 ```
 
 The response is a single object that contains the information about the request
-and the average marginal carbon intensity
+and the average carbon intensity
 
 ```json
 {
@@ -330,7 +330,7 @@ location and time period.
 This endpoint only supports batching across a single location with different
 time boundaries. If multiple locations are provided, an error is returned. For
 each item in the request array, the application returns a corresponding object
-containing the location, time boundaries, and average marginal carbon intensity.
+containing the location, time boundaries, and average carbon intensity.
 
 Parameters:
 
@@ -364,7 +364,7 @@ Parameters:
 ```
 
 The response is an array of CarbonIntensityDTO objects which each have a
-location, start time, end time, and the average marginal carbon intensity over
+location, start time, end time, and the average carbon intensity over
 that time period.
 
 ```json

casdk-docs/docs/tutorial-extras/carbon-aware-library.md

@@ -1,8 +1,8 @@
 # Carbon Aware Library
 
-The Carbon Aware SDK provides a C\# Client Library to get the marginal carbon
+The Carbon Aware SDK provides a C\# Client Library to get the carbon
 intensity for a given location and time period. The values reported in the Green
-Software Foundation's specification for marginal carbon intensity (Grams per
+Software Foundation's specification for carbon intensity (Grams per
 Kilowatt Hour).
 
 **_Recommended_** - This user interface is best for when you need a consumable
@@ -247,8 +247,7 @@ var data =  await this._emissionsHandler.GetAverageCarbonIntensityAsync(
 );
 ```
 
-The response is a single double value representing the calculated average
-marginal carbon intensity g/kWh.
+The response is a single double value representing the calculated average carbon intensity g/kWh.
 
 ```csharp
 345.434
@@ -269,11 +268,11 @@ This function fetches only the most recently generated forecast for all provided
 locations. It uses the "dataStartAt" and "dataEndAt" parameters to scope the
 forecasted data points (if available for those times). If no start or end time
 boundaries are provided, the entire forecast dataset is used. The scoped data
-points are used to calculate average marginal carbon intensities of the
-specified "windowSize" and the optimal marginal carbon intensity window is
+points are used to calculate average carbon intensities of the
+specified "windowSize" and the optimal carbon intensity window is
 identified.
 
-The forecast data represents what the data source predicts future marginal
+The forecast data represents what the data source predicts future
 carbon intensity values to be, not actual measured emissions data (as future
 values cannot be known).
 
@@ -292,7 +291,7 @@ Parameters:
    current forecast data points after this time. Must be within the forecast
    data point timestamps. Defaults to the latest time in the forecast data. If
    neither `dataStartAt` nor `dataEndAt` are provided, all forecasted data
-   points are used in calculating the optimal marginal carbon intensity window.
+   points are used in calculating the optimal carbon intensity window.
 4. `windowSize`: The estimated duration (in minutes) of the workload. Defaults
    to the duration of a single forecast data point.
 
@@ -306,7 +305,7 @@ var data = await this._forecastHandler.GetCurrentForecastAsync(
 ```
 
 The response is an array of `EmissionsForecast` objects (one per requested
-location) with their optimal marginal carbon intensity windows.
+location) with their optimal carbon intensity windows.
 
 ```csharp
 [
@@ -347,7 +346,7 @@ location) with their optimal marginal carbon intensity windows.
 ### GetForecastByDateAsync
 
 This function takes a requests for historical forecast data, fetches it, and
-calculates the optimal marginal carbon intensity window. This endpoint is useful
+calculates the optimal carbon intensity window. This endpoint is useful
 for back-testing what one might have done in the past, if they had access to the
 current forecast at the time.
 
@@ -367,7 +366,7 @@ Parameters:
    to the duration of a single forecast data point
 
 If neither `dataStartAt` nor `dataEndAt` are provided, all forecasted data
-points are used in calculating the optimal marginal carbon intensity window.
+points are used in calculating the optimal carbon intensity window.
 
 ```csharp
 var data = await this._forecastHandler.GetForecastByDateAsync(
@@ -379,7 +378,7 @@ var data = await this._forecastHandler.GetForecastByDateAsync(
 );
 ```
 
-The response is an `EmissionsForecast` object with the optimal marginal carbon
+The response is an `EmissionsForecast` object with the optimal carbon
 intensity window.
 
 ```csharp

src/CarbonAware.WebApi/src/Controllers/CarbonAwareController.cs

@@ -88,21 +88,21 @@ public async Task<IActionResult> GetEmissionsDataForLocationByTime(
     }
 
     /// <summary>
-    ///   Retrieves the most recent forecasted data and calculates the optimal marginal carbon intensity window.
+    ///   Retrieves the most recent forecasted data and calculates the optimal carbon intensity window.
     /// </summary>
     /// <param name="parameters">The request object <see cref="EmissionsForecastCurrentParametersDTO"/></param>
     /// <remarks>
     ///   This endpoint fetches only the most recently generated forecast for all provided locations.  It uses the "dataStartAt" and 
     ///   "dataEndAt" parameters to scope the forecasted data points (if available for those times). If no start or end time 
-    ///   boundaries are provided, the entire forecast dataset is used. The scoped data points are used to calculate average marginal 
-    ///   carbon intensities of the specified "windowSize" and the optimal marginal carbon intensity window is identified.
+    ///   boundaries are provided, the entire forecast dataset is used. The scoped data points are used to calculate average 
+    ///   carbon intensities of the specified "windowSize" and the optimal carbon intensity window is identified.
     ///
-    ///   The forecast data represents what the data source predicts future marginal carbon intensity values to be, 
+    ///   The forecast data represents what the data source predicts future carbon intensity values to be, 
     ///   not actual measured emissions data (as future values cannot be known).
     ///
     ///   This endpoint is useful for determining if there is a more carbon-optimal time to use electricity predicted in the future.
     /// </remarks>
-    /// <returns>An array of forecasts (one per requested location) with their optimal marginal carbon intensity windows.</returns>
+    /// <returns>An array of forecasts (one per requested location) with their optimal carbon intensity windows.</returns>
     /// <response code="200">Returns the requested forecast objects</response>
     /// <response code="400">Returned if any of the input parameters are invalid</response>
     /// <response code="500">Internal server error</response>
@@ -126,14 +126,14 @@ public async Task<IActionResult> GetCurrentForecastData([FromQuery] EmissionsFor
     /// </summary>
     /// <remarks>
     /// This endpoint takes a batch of requests for historical forecast data, fetches them, and calculates the optimal 
-    /// marginal carbon intensity windows for each using the same parameters available to the '/emissions/forecasts/current'
+    /// carbon intensity windows for each using the same parameters available to the '/emissions/forecasts/current'
     /// endpoint.
     ///
     /// This endpoint is useful for back-testing what one might have done in the past, if they had access to the 
     /// current forecast at the time.
     /// </remarks>
     /// <param name="requestedForecasts"> Array of requested forecasts.</param>
-    /// <returns>An array of forecasts with their optimal marginal carbon intensity window.</returns>
+    /// <returns>An array of forecasts with their optimal carbon intensity window.</returns>
     /// <response code="200">Returns the requested forecast objects</response>
     /// <response code="400">Returned if any of the input parameters are invalid</response>
     /// <response code="500">Internal server error</response>
@@ -169,7 +169,7 @@ public async Task<IActionResult> BatchForecastDataAsync([FromBody] IEnumerable<E
     /// </remarks>
     /// <param name="parameters">The request object <see cref="CarbonIntensityParametersDTO"/></param>
     /// <returns>A single object that contains the location, time boundaries and average carbon intensity value.</returns>
-    /// <response code="200">Returns a single object that contains the information about the request and the average marginal carbon intensity</response>
+    /// <response code="200">Returns a single object that contains the information about the request and the average carbon intensity</response>
     /// <response code="400">Returned if any of the requested items are invalid</response>
     /// <response code="500">Internal server error</response>
     [Produces("application/json", "application/json; charset=utf-8")]
@@ -202,11 +202,11 @@ public async Task<IActionResult> GetAverageCarbonIntensity([FromQuery] CarbonInt
     /// </summary>
     /// <remarks>
     /// The application only supports batching across a single location with different time boundaries. If multiple locations are provided, an error is returned.
-    /// For each item in the request array, the application returns a corresponding object containing the location, time boundaries, and average marginal carbon intensity. 
+    /// For each item in the request array, the application returns a corresponding object containing the location, time boundaries, and average carbon intensity. 
     /// </remarks>
-    /// <param name="requestedCarbonIntensities"> Array of inputs where each contains a "location", "startDate", and "endDate" for which to calculate average marginal carbon intensity. </param>
-    /// <returns>An array of CarbonIntensityDTO objects which each have a location, start time, end time, and the average marginal carbon intensity over that time period.</returns>
-    /// <response code="200">Returns an array of objects where each contains location, time boundaries and the corresponding average marginal carbon intensity</response>
+    /// <param name="requestedCarbonIntensities"> Array of inputs where each contains a "location", "startDate", and "endDate" for which to calculate average carbon intensity. </param>
+    /// <returns>An array of CarbonIntensityDTO objects which each have a location, start time, end time, and the average carbon intensity over that time period.</returns>
+    /// <response code="200">Returns an array of objects where each contains location, time boundaries and the corresponding average carbon intensity</response>
     /// <response code="400">Returned if any of the requested items are invalid</response>
     /// <response code="500">Internal server error</response>
     [Produces("application/json", "application/json; charset=utf-8")]

src/CarbonAware.WebApi/src/Models/CarbonIntensityDTO.cs

@@ -22,7 +22,7 @@ public record CarbonIntensityDTO
     [JsonPropertyName("endTime")]
     public DateTimeOffset? EndTime { get => _endTime; set => _endTime = value?.ToUniversalTime(); }
 
-    /// <summary>Value of the marginal carbon intensity in grams per kilowatt-hour.</summary>
+    /// <summary>Value of the carbon intensity in grams per kilowatt-hour.</summary>
     /// <example>345.434</example>
     [JsonPropertyName("carbonIntensity")]
     public double CarbonIntensity { get; set; }

src/GSF.CarbonAware/src/Handlers/IForecastHandler.cs

@@ -5,7 +5,7 @@ namespace GSF.CarbonAware.Handlers;
 public interface IForecastHandler
 {
     /// <summary>
-    /// Retrieves the most recent forecasted data and calculates the optimal marginal carbon intensity window.
+    /// Retrieves the most recent forecasted data and calculates the optimal carbon intensity window.
     /// </summary>
     /// <param name="locations">Array of locations where the workflow is run (ex: ["eastus", "westus"])</param>
     /// <param name="dataStartAt">Start time boundary of forecasted data points. Ignores current forecast data points before this time (ex: 2022-03-01T15:30:00Z)</param>
@@ -15,13 +15,13 @@ public interface IForecastHandler
     Task<IEnumerable<EmissionsForecast>> GetCurrentForecastAsync(string[] locations, DateTimeOffset? dataStartAt = null, DateTimeOffset? dataEndAt = null, int? windowSize = null);
 
     /// <summary>
-    /// Retrieves the historical forecasted data for the given date range and calculates the optimal marginal carbon intensity window.
+    /// Retrieves the historical forecasted data for the given date range and calculates the optimal carbon intensity window.
     /// </summary>
     /// <param name="location">String location where the workflow is run (ex: "eastus")</param>
     /// <param name="dataStartAt">Start time boundary of forecasted data points. Ignores current forecast data points before this time (ex: 2022-03-01T15:30:00Z)</param>
     /// <param name="dataEndAt">End time boundary of forecasted data points. Ignores current forecast data points after this time (ex: 2022-03-01T18:30:00Z)</param> 
     /// <param name="requestedAt">The timestamp used to access the most recently generated forecast as of that time. (ex: 2022-03-01T18:30:00Z)</param>
     /// <param name="windowSize">The estimated duration (in minutes) of the workload.</param>
-    /// <returns>An <see cref="EmissionsForecast"/> with the optimal marginal carbon intensity window.</returns>
+    /// <returns>An <see cref="EmissionsForecast"/> with the optimal carbon intensity window.</returns>
     Task<EmissionsForecast> GetForecastByDateAsync(string location, DateTimeOffset? dataStartAt = null, DateTimeOffset? dataEndAt = null, DateTimeOffset? requestedAt = null, int? windowSize = null);
 }