PowerAnalytics

Column metadata key whose value, if any, is additional information to be passed to aggregation functions. Values of nothing are equivalent to absence of the entry.

Name of the column that represents the time axis in computed DataFrames

Column metadata key whose value signifies whether the column is metadata. Metadata columns are excluded from get_data_cols and similar and can be used to represent things like a time aggregation.

Name of a column that represents whole-of-Results data

Name of a column that represents whole-of-System data

Time series Metrics defined on ComponentSelectors.

ComponentSelectorTimedMetrics implemented by evaluating a function on each Component.

Arguments

• name::String: the name of the Metric
• eval_fn: a function with signature (::IS.Results, ::Component; start_time::Union{Nothing, DateTime}, len::Union{Int, Nothing}) that returns a DataFrame representing the results for that Component
• component_agg_fn: optional, a function to aggregate results between Components/ComponentSelectors, defaults to sum
• time_agg_fn: optional, a function to aggregate results across time, defaults to sum
• component_meta_agg_fn: optional, a callable to aggregate metadata across components, defaults to sum
• time_meta_agg_fn: optional, a callable to aggregate metadata across time, defaults to sum
• eval_zero: optional and rarely filled in, specifies what to do in the case where there are no components to contribute to a particular group; defaults to nothing, in which case the data is filled in from the identity element of component_agg_fn

ComponentSelectorTimedMetrics implemented without drilling down to the base Components, just call the eval_fn directly.

Arguments

• name::String: the name of the Metric
• eval_fn: a callable with signature (::IS.Results, ::Union{ComponentSelector, Component}; start_time::Union{Nothing, DateTime}, len::Union{Int, Nothing}) that returns a DataFrame representing the results for that Component
• time_agg_fn: optional, a callable to aggregate results across time, defaults to sum
• time_meta_agg_fn: optional, a callable to aggregate metadata across time, defaults to sum

The basic type for all Metrics.

Timeless Metrics with a single value per IS.Results instance

Arguments

- `name::String`: the name of the `Metric`
- `eval_fn`: a callable with signature `(::IS.Results,)` that returns a `DataFrame`
  representing the results

Time series Metrics defined on Systems.

Arguments

• name::String: the name of the Metric
• eval_fn: a callable with signature (::IS.Results; start_time::Union{Nothing, DateTime}, len::Union{Int, Nothing}) that returns a DataFrame representing the results
• time_agg_fn: optional, a callable to aggregate results across time, defaults to sum
• time_meta_agg_fn: optional, a callable to aggregate metadata across time, defaults to sum

Time series Metrics.

Scalar-in-time Metrics.

Given a DataFrame like that produced by compute_all, group by a function of the time axis, apply a reduction, and report the resulting aggregation indexed by the first timestamp in each group.

Arguments

• df::DataFrames.AbstractDataFrame: the DataFrame to operate upon
• groupby_fn = nothing: a callable that can be passed a DateTime; two rows will be in the same group iff their timestamps produce the same result under groupby_fn. Note that groupby_fn = month puts January 2023 and January 2024 into the same group whereas groupby_fn=(x -> (year(x), month(x))) does not.
• groupby_col::Union{Nothing, AbstractString, Symbol} = nothing: specify a column name to report the result of groupby_fn in the output DataFrame, or nothing to not
• agg_fn = nothing: by default, the aggregation function (sum/mean/etc.) is specified by the Metric, which is read from the metadata of each column. If this metadata isn't found, one can specify a default aggregation function like sum here; if nothing, an error will be thrown.

Re-categorizes data according to an aggregation dictionary

• makes no guarantee of complete data collection *

Example

aggregation = PA.make_fuel_dictionary(results_uc.system)
categorize_data(gen_uc.data, aggregation)

Given a list of metrics and a function that applies to their results to produce one result, create a new metric that computes the sub-metrics and applies the function to produce its own result.

Arguments

• name::String: the name of the new Metric
• reduce_fn: a callable that takes one value from each of the input Metrics and returns a single value that will be the result of this Metric. "Value" means a vector (not a DataFrame) in the case of TimedMetrics and a scalar for TimelessMetrics.
• metrics: the input Metrics. It is currently not possible to combine TimedMetrics with TimelessMetrics, though it is possible to combine ComponentSelectorTimedMetrics with SystemTimedMetrics.

Compute the given metric on the groups of the given ComponentSelector within the given set of results, returning a DataFrame with a DateTime column and a data column for each group. Exclude components marked as not available.

Arguments

• metric::ComponentTimedMetric: the metric to compute
• results::IS.Results: the results from which to fetch data
• selector::ComponentSelector: the ComponentSelector on whose subselectors to compute the metric
• start_time::Union{Nothing, DateTime} = nothing: the time at which the resulting time series should begin
• len::Union{Int, Nothing} = nothing: the number of steps in the resulting time series

Compute the given metric on the given component within the given set of results, returning a DataFrame with a DateTime column and a data column labeled with the component's name.

Arguments

• metric::ComponentTimedMetric: the metric to compute
• results::IS.Results: the results from which to fetch data
• comp::Component: the component on which to compute the metric
• start_time::Union{Nothing, DateTime} = nothing: the time at which the resulting time series should begin
• len::Union{Int, Nothing} = nothing: the number of steps in the resulting time series

Compute the given metric on the given component within the given set of results, returning a DataFrame with a DateTime column and a data column labeled with the component's name. Exclude components marked as not available.

Arguments

• metric::CustomTimedMetric: the metric to compute
• results::IS.Results: the results from which to fetch data
• comp::Component: the component on which to compute the metric
• start_time::Union{Nothing, DateTime} = nothing: the time at which the resulting time series should begin
• len::Union{Int, Nothing} = nothing: the number of steps in the resulting time series

Convenience method for compute_all; returns compute(metric, results)

Compute the given metric on the given set of results, returning a DataFrame with a single cell. Exclude components marked as not available.

Arguments

• metric::ResultsTimelessMetric: the metric to compute
• results::IS.Results: the results from which to fetch data

Convenience method for compute_all; returns compute(metric, results; kwargs...)

Compute the given metric on the System associated with the given set of results, returning a DataFrame with a DateTime column and a data column.

Arguments

• metric::SystemTimedMetric: the metric to compute
• results::IS.Results: the results from which to fetch data
• start_time::Union{Nothing, DateTime} = nothing: the time at which the resulting time series should begin
• len::Union{Int, Nothing} = nothing: the number of steps in the resulting time series

For each (metric, selector, col_name) tuple in zip(metrics, selectors, col_names), call compute and collect the results in a DataFrame with a single DateTime column. All selectors must yield exactly one group.

Arguments

• results::IS.Results: the results from which to fetch data
• metrics::Vector{<:TimedMetric}: the metrics to compute
• selectors: either a scalar or vector of Nothing/Component/ComponentSelector: the selectors on which to compute the metrics, or nothing for system/results metrics; broadcast if scalar
• col_names::Union{Nothing, Vector{<:Union{Nothing, AbstractString}}} = nothing: a vector of names for the columns of ouput data. Entries of nothing default to the result of metric_selector_to_string; names = nothing is equivalent to an entire vector of nothing
• kwargs...: pass through to each compute call

For each (metric, colname) tuple in `zip(metrics, colnames), call [compute`](@ref) and collect the results in a DataFrame.

Arguments

• results::IS.Results: the results from which to fetch data
• metrics::Vector{<:TimelessMetric}: the metrics to compute
• selectors: either a scalar or vector of Nothing/Component/ComponentSelector: the selectors on which to compute the metrics, or nothing for system/results metrics; broadcast if scalar
• col_names::Union{Nothing, Vector{<:Union{Nothing, AbstractString}}} = nothing: a vector of names for the columns of ouput data. Entries of nothing default to the result of metric_selector_to_string; names = nothing is equivalent to an entire vector of nothing
  • kwargs...: pass through to each compute call

For each (metric, selector, col_name) tuple in computations, call compute and collect the results in a DataFrame with a single DateTime column. All selectors must yield exactly one group.

Arguments

• results::IS.Results: the results from which to fetch data
• computations::(Tuple{<:T, Any, Any} where T <: Union{TimedMetric, TimelessMetric})...: a list of the computations to perform, where each element is a (metric, selector, col_name)wheremetricis the metric to compute,selectoris the ComponentSelector on which to compute the metric ornothingif not relevant, andcol_name` is the name for the output column of data or nothing to use the default
  • kwargs...: pass through to each compute call

Accept a directory that contains several results subdirectories (that each contain results, problems, etc. sub-subdirectories) and construct a sorted dictionary from String to SimulationProblemResults where the keys are the subdirectory names and the values are loaded results datasets.

Arguments

• results_dir::AbstractString: the directory where results subdirectories can be found
• problem::String: the name of the problem to load (e.g., "UC", "ED")
• scenarios::Union{Vector{AbstractString}, Nothing} = nothing: a list of scenario subdirectories to load, or nothing to load all the subdirectories
• kwargs...: keyword arguments to pass through to PSI.get_decision_problem_results

Get the column's aggregation metadata; return nothing if there is none.

Get the single data column's aggregation metadata; error on multiple data columns.

Select the names of the data columns of the DataFrame, i.e., those that are not DateTime and not metadata.

Select the data columns of the DataFrame as a DataFrame without copying.

Select the data columns of the DataFrame as a Matrix with copying.

Select the data column of the DataFrame as a vector without copying, errors if more than one.

Select the DateTime column of the DataFrame as a one-column DataFrame without copying.

Select the DateTime column of the DataFrame as a Vector without copying.

If the time axes match across all the DataFrames, horizontally concatenate them and remove the duplicate time axes. If not, throw an error

Check whether a column is metadata

generators = make_fuel_dictionary(system::PSY.System, mapping::Dict{NamedTuple, String})

This function makes a dictionary of fuel type and the generators associated.

Arguments

• sys::PSY.System: the system that is used to create the results
• results::IS.Results: results

Key Words

• categories::Dict{String, NamedTuple}: if stacking by a different category is desired

Example

results = solveopmodel!(OpModel) generators = makefueldictionary(sys)

Canonical way to represent a (Metric, ComponentSelector) or (Metric, Component) pair as a string.

Use parse_generator_mapping_file to parse a generator_mapping.yaml file into a dictionary of ComponentSelector, excluding categories in the 'non_generators' list in metadata

Parse a generator_mapping.yaml file into a dictionary of ComponentSelectors and a dictionary of metadata if present

Use parse_generator_mapping_file to parse a generator_mapping.yaml file into a dictionary of all ComponentSelectors

Returns a Metric identical to the input metric except with the changes to its fields specified in the keyword arguments.

Examples

Make a variant of calc_active_power that averages across components rather than summing:

using PowerAnalytics.Metrics
calc_active_power_mean = rebuild_metric(calc_active_power; component_agg_fn = mean)
# (now calc_active_power_mean works as a standalone, callable metric)

Set the column's aggregation metadata.

Set the single data column's aggregation metadata; error on multiple data columns.

Mark a column as metadata

A version of sum that ignores a second argument, for use where aggregation metadata is at play

Compute the mean of values weighted by the corresponding entries of weights. Arguments may be vectors or vectors of vectors. A weight of 0 cancels out a value of NaN.

The various key entry types that can be used to make a PSI.OptimizationContainerKey

The various key entry types that can work with a System

The metric does not have a result for the Component/ComponentSelector/etc. on which it is being called.

aggregates and combines data into single DataFrame

Example

PG.combine_categories(gen_uc.data)

Return the generator category for this fuel and unit_type.

Return a dict where keys are a tuple of input parameters (fuel, unit_type) and values are generator types.

Parse the gentype to a type. This is done by first checking whether gentype is qualified (ModuleName.TypeName). If so, the module is fetched from the Main scope and the type name is fetched from the module. If not, we default to fetching from PowerSystems for convenience.

Convenience function to convert an EntryType to a function and make a ComponentTimedMetric from it

Sort a vector of key tuples into variables, parameters, etc. like PSI.load_results! wants

Create a PSI.OptimizationContainerKey from the given key entry type and component.

Arguments

• entry::Type{<:EntryType}: the key entry
• component (::Type{<:Union{Component, PSY.System}} or ::Type{<:Component} depending on the key type): the component type

Convenience function to convert a SystemEntryType to a function and make a SystemTimedMetric from it

Given an EntryType and a Component, fetch a single column of results

Given an EntryType that applies to the System, fetch a single column of results