Augment docstrings

PRASCore/src/Results/Flow.jl

@@ -1,12 +1,31 @@
 """
     Flow
 
-Flow metric represents the flow between interfaces at timestamps
-in a FlowResult with a (interfaces, timestamps) matrix API.
-
-Separate samples are averaged together into mean and std values.
-
-See [`FlowSamples`](@ref) for all flow samples.
+The `Flow` result specification reports the estimated average flow across
+transmission `Interfaces`, producing a `FlowResult`.
+
+A `FlowResult` can be indexed by a directional `Pair` of region names and a
+timestamp to retrieve a tuple of sample mean and standard deviation, estimating
+the average net flow magnitude and direction relative to the given directed
+interface in that timestep. For a query of `"Region A" => "Region B"`, if
+estimated average flow was from A to B, the reported value would be positive,
+while if average flow was in the reverse direction, from B to A, the value
+would be negative.
+
+Example:
+
+```julia
+flows, =
+    assess(sys, SequentialMonteCarlo(samples=1000), Flow())
+
+flow_mean, flow_std =
+    flows["Region A" => "Region B", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]
+flow2_mean, flow2_std =
+    flows["Region B" => "Region A", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]
+@assert flow_mean == -flow2_mean
+```
+
+See [`FlowSamples`](@ref) for sample-level flow results.
 """
 struct Flow <: ResultSpec end
 

PRASCore/src/Results/FlowSamples.jl

@@ -1,11 +1,33 @@
 """
     FlowSamples
 
-Flow samples represent the flow between interfaces at timestamps, which has
-not been averaged across different samples. This presents a
-3D matrix API (interfaces, timestamps, samples).
+The `FlowSamples` result specification reports the sample-level magnitude and
+direction of power flows across `Interfaces`, producing a `FlowSamplesResult`.
 
-See [`Flow`](@ref) for sample-averaged flow data.
+A `FlowSamplesResult` can be indexed by a directional `Pair` of region names and a
+timestamp to retrieve a vector of sample-level net flow magnitudes and
+directions relative to the given directed interface in that timestep. For a
+query of `"Region A" => "Region B"`, if flow in one sample was from A to B, the
+reported value would be positive, while if flow was in the reverse direction,
+from B to A, the value would be negative.
+
+Example:
+
+```julia
+flows, =
+    assess(sys, SequentialMonteCarlo(samples=10), FlowSamples())
+
+samples = flows["Region A" => "Region B", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]
+
+@assert samples isa Vector{Float64}
+@assert length(samples) == 10
+
+samples2 = flows["Region B" => "Region A", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]
+
+@assert samples == -samples2
+```
+
+See [`Flow`](@ref) for estimated average flow results.
 """
 struct FlowSamples <: ResultSpec end
 

PRASCore/src/Results/GeneratorAvailability.jl

@@ -1,10 +1,26 @@
 """
     GeneratorAvailability
 
-Generator availability represents the availability of generators at timestamps
-in a GeneratorAvailabilityResult with a (generators, timestamps, samples) matrix API.
+The `GeneratorAvailability` result specification reports the sample-level
+discrete availability of `Generators`, producing a `GeneratorAvailabilityResult`.
 
-No averaging occurs.
+A `GeneratorAvailabilityResult` can be indexed by generator name and
+timestamp to retrieve a vector of sample-level availability states for
+the unit in the given timestep. States are provided as a boolean with
+`true` indicating that the unit is available and `false` indicating that
+it's unavailable.
+
+Example:
+
+```julia
+genavail, =
+    assess(sys, SequentialMonteCarlo(samples=10), GeneratorAvailability())
+
+samples = genavail["MyGenerator123", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]
+
+@assert samples isa Vector{Bool}
+@assert length(samples) == 10
+```
 """
 struct GeneratorAvailability <: ResultSpec end
 

PRASCore/src/Results/GeneratorStorageAvailability.jl

@@ -1,10 +1,27 @@
 """
     GeneratorStorageAvailability
 
-Generator storage availability represents the availability of generatorstorage resources at timestamps
-in a GeneratorStorageAvailabilityResult with a (generatorstorages, timestamps, samples) matrix API.
+The `GeneratorStorageAvailability` result specification reports the sample-level
+discrete availability of `GeneratorStorages`, producing a
+`GeneratorStorageAvailabilityResult`.
 
-No averaging occurs
+A `GeneratorStorageAvailabilityResult` can be indexed by generator-storage
+name and timestamp to retrieve a vector of sample-level availability states for
+the unit in the given timestep. States are provided as a boolean with
+`true` indicating that the unit is available and `false` indicating that
+it's unavailable.
+
+Example:
+
+```julia
+genstoravail, =
+    assess(sys, SequentialMonteCarlo(samples=10), GeneratorStorageAvailability())
+
+samples = genstoravail["MyGenerator123", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]
+
+@assert samples isa Vector{Bool}
+@assert length(samples) == 10
+```
 """
 struct GeneratorStorageAvailability <: ResultSpec end
 

PRASCore/src/Results/GeneratorStorageEnergy.jl

@@ -1,15 +1,27 @@
 """
     GeneratorStorageEnergy
 
-Generator storage energy represents state-of-charge of generatorstorage
-resources at timestamps in a StorageEnergyResult with a (generatorstorages, timestamps)
-matrix API.
+The `GeneratorStorageEnergy` result specification reports the average state of
+charge of `GeneratorStorages`, producing a `GeneratorStorageEnergyResult`.
 
-Separate samples are averaged together into mean and std values.
+A `GeneratorStorageEnergyResult` can be indexed by generator-storage device
+name and a timestamp to retrieve a tuple of sample mean and standard deviation,
+estimating the average energy level for the given generator-storage device in
+that timestep.
 
-See [`GeneratorStorageEnergySamples`](@ref) for all generator storage energy samples.
+Example:
 
-See [`StorageEnergy`](@ref) for storage energy.
+```julia
+genstorenergy, =
+    assess(sys, SequentialMonteCarlo(samples=1000), GeneratorStorageEnergy())
+
+soc_mean, soc_std =
+    genstorenergy["MyGeneratorStorage123", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]
+```
+See [`GeneratorStorageEnergySamples`](@ref) for sample-level generator-storage
+states of charge.
+
+See [`StorageEnergy`](@ref) for average storage states of charge.
 """
 struct GeneratorStorageEnergy <: ResultSpec end
 

PRASCore/src/Results/GeneratorStorageEnergySamples.jl

@@ -1,11 +1,28 @@
 """
     GeneratorStorageEnergySamples
 
-Generator storage energy samples represent the state-of-charge of generatorstorage
-resources at timestamps, which has not been averaged across different samples.
-This presents a 3D matrix API (generatorstorages, timestamps, samples).
+The `GeneratorStorageEnergySamples` result specification reports the
+sample-level state of charge of `GeneratorStorages`, producing a
+`GeneratorStorageEnergySamplesResult`.
 
-See [`GeneratorStorageEnergy`](@ref) for sample-averaged generator storage energy.
+A `GeneratorStorageEnergySamplesResult` can be indexed by generator-storage
+device name and a timestamp to retrieve a vector of sample-level charge states
+for the device in the given timestep.
+
+Example:
+
+```julia
+genstorenergy, =
+    assess(sys, SequentialMonteCarlo(samples=10), GeneratorStorageEnergySamples())
+
+samples = genstorenergy["MyGeneratorStorage123", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]
+
+@assert samples isa Vector{Float64}
+@assert length(samples) == 10
+```
+
+See [`GeneratorStorageEnergy`](@ref) for estimated average generator-storage
+state of charge.
 """
 struct GeneratorStorageEnergySamples <: ResultSpec end
 

PRASCore/src/Results/LineAvailability.jl

@@ -1,10 +1,26 @@
 """
     LineAvailability
 
-Line availability represents the availability of lines at timestamps
-in a LineAvailabilityResult with a (lines, timestamps, samples) matrix API.
+The `LineAvailability` result specification reports the sample-level
+discrete availability of `Lines`, producing a `LineAvailabilityResult`.
 
-No averaging occurs.
+A `LineAvailabilityResult` can be indexed by line name and
+timestamp to retrieve a vector of sample-level availability states for
+the unit in the given timestep. States are provided as a boolean with
+`true` indicating that the unit is available and `false` indicating that
+it's unavailable.
+
+Example:
+
+```julia
+lineavail, =
+    assess(sys, SequentialMonteCarlo(samples=10), LineAvailability())
+
+samples = lineavail["MyLine123", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]
+
+@assert samples isa Vector{Bool}
+@assert length(samples) == 10
+```
 """
 struct LineAvailability <: ResultSpec end
 

PRASCore/src/Results/Shortfall.jl

@@ -1,12 +1,43 @@
 """
     Shortfall
 
-Shortfall metric represents lost load at regions and timesteps
-in ShortfallResult with a (regions, timestamps) matrix API.
+The `Shortfall` result specification reports expectation-based resource
+adequacy risk metrics such as EUE and LOLE, producing a `ShortfallResult`.
 
-Separate samples are averaged together into mean and std values.
+A `ShortfallResult` can be directly indexed by a region name and a timestamp to retrieve a tuple of sample mean and standard deviation, estimating
+ the average unserved energy in that region and timestep. However, in most
+cases it's simpler to use [`EUE`](@ref) and [`LOLE`](@ref) constructors to
+directly retrieve standard risk metrics.
 
-See [`ShortfallSamples`](@ref) for all shortfall samples.
+Example:
+
+```julia
+shortfall, =
+    assess(sys, SequentialMonteCarlo(samples=1000), Shortfall())
+
+period = ZonedDateTime(2020, 1, 1, 0, tz"UTC")
+
+# Unserved energy mean and standard deviation
+sf_mean, sf_std = shortfall["Region A", period]
+
+# System-wide risk metrics
+eue = EUE(shortfall)
+lole = LOLE(shortfall)
+
+# Regional risk metrics
+regional_eue = EUE(shortfall, "Region A")
+regional_lole = LOLE(shortfall, "Region A")
+
+# Period-specific risk metrics
+period_eue = EUE(shortfall, period)
+period_lolp = LOLE(shortfall, period)
+
+# Region- and period-specific risk metrics
+period_eue = EUE(shortfall, "Region A", period)
+period_lolp = LOLE(shortfall, "Region A", period)
+```
+
+See [`ShortfallSamples`](@ref) for recording sample-level shortfall results.
 """
 struct Shortfall <: ResultSpec end
 
@@ -86,11 +117,6 @@ end
 
 accumulatortype(::Shortfall) = ShortfallAccumulator
 
-"""
-    ShortfallResult
-
-Matrix-like data structure for storing shortfall means
-"""
 struct ShortfallResult{N, L, T <: Period, E <: EnergyUnit} <:
        AbstractShortfallResult{N, L, T}
     nsamples::Union{Int, Nothing}

PRASCore/src/Results/ShortfallSamples.jl

@@ -1,10 +1,45 @@
 """
     ShortfallSamples
 
-ShortfallSamples metric represents lost load at regions and timesteps
-in ShortfallSamplesResult with a (regions, timestamps, samples) matrix API.
+The `ShortfallSamples` result specification reports sample-level unserved energy outcomes, producing a `ShortfallSamplesResult`.
 
-See [`Shortfall`](@ref) for averaged shortfall samples.
+A `ShortfallSamplesResult` can be directly indexed by a region name and a
+timestamp to retrieve a vector of sample-level unserved energy results in that
+region and timestep. [`EUE`](@ref) and [`LOLE`](@ref) constructors can also
+be used to retrieve standard risk metrics.
+
+Example:
+
+```julia
+shortfall, =
+    assess(sys, SequentialMonteCarlo(samples=10), ShortfallSamples())
+
+period = ZonedDateTime(2020, 1, 1, 0, tz"UTC")
+
+samples = shortfall["Region A", period]
+
+@assert samples isa Vector{Float64}
+@assert length(samples) == 10
+
+# System-wide risk metrics
+eue = EUE(shortfall)
+lole = LOLE(shortfall)
+
+# Regional risk metrics
+regional_eue = EUE(shortfall, "Region A")
+regional_lole = LOLE(shortfall, "Region A")
+
+# Period-specific risk metrics
+period_eue = EUE(shortfall, period)
+period_lolp = LOLE(shortfall, period)
+
+# Region- and period-specific risk metrics
+period_eue = EUE(shortfall, "Region A", period)
+period_lolp = LOLE(shortfall, "Region A", period)
+```
+
+See [`Shortfall`](@ref) for average shortfall outcomes, which require much
+less memory to store.
 """
 struct ShortfallSamples <: ResultSpec end
 

PRASCore/src/Results/StorageAvailability.jl

@@ -1,10 +1,26 @@
 """
     StorageAvailability
 
-Storage availability represents the availability of storage resources at timestamps
-in a StorageAvailabilityResult with a (storages, timestamps, samples) matrix API.
+The `StorageAvailability` result specification reports the sample-level
+discrete availability of `Storages`, producing a `StorageAvailabilityResult`.
 
-No averaging occurs.
+A `StorageAvailabilityResult` can be indexed by storage device name and
+a timestamp to retrieve a vector of sample-level availability states for
+the unit in the given timestep. States are provided as a boolean with
+`true` indicating that the unit is available and `false` indicating that
+it's unavailable.
+
+Example:
+
+```julia
+storavail, =
+    assess(sys, SequentialMonteCarlo(samples=10), StorageAvailability())
+
+samples = storavail["MyStorage123", ZonedDateTime(2020, 1, 1, 0, tz"UTC")]
+
+@assert samples isa Vector{Bool}
+@assert length(samples) == 10
+```
 """
 struct StorageAvailability <: ResultSpec end