diff --git a/src/production_variable_cost_curve.jl b/src/production_variable_cost_curve.jl index b64ed486f..f3b1dd471 100644 --- a/src/production_variable_cost_curve.jl +++ b/src/production_variable_cost_curve.jl @@ -83,7 +83,7 @@ The default units for the x-axis are MW and can be specified with `power_units`. value_curve::T "(default: natural units (MW)) The units for the x-axis of the curve" power_units::UnitSystem = UnitSystem.NATURAL_UNITS - "Either a fixed value for fuel cost or the key to a fuel cost time series" + "Either a fixed value for fuel cost or the [`TimeSeriesKey`](@ref) to a fuel cost time series" fuel_cost::Union{Float64, TimeSeriesKey} "(default of 0) Additional proportional Variable Operation and Maintenance Cost in \$/(power_unit h) represented as a [`LinearCurve`](@ref)" diff --git a/src/static_time_series.jl b/src/static_time_series.jl index 8ed0feca6..50975c9ee 100644 --- a/src/static_time_series.jl +++ b/src/static_time_series.jl @@ -1,3 +1,11 @@ +""" +Supertype for static time series, which has one value per time point + +Current concrete subtypes are: +- [`SingleTimeSeries`](@ref) + +See also: [`Forecast`](@ref) +""" abstract type StaticTimeSeries <: TimeSeriesData end Base.length(ts::StaticTimeSeries) = length(get_data(ts)) diff --git a/src/system_data.jl b/src/system_data.jl index f58975614..894dbc318 100644 --- a/src/system_data.jl +++ b/src/system_data.jl @@ -452,7 +452,7 @@ function iterate_supplemental_attributes_with_time_series( end """ -Returns an iterator of TimeSeriesData instances attached to the system. +Returns an iterator of `TimeSeriesData` instances attached to the system. Note that passing a filter function can be much slower than the other filtering parameters because it reads time series data from media. @@ -465,6 +465,13 @@ Call `collect` on the result to get an array. - `filter_func = nothing`: Only return time_series for which this returns true. - `type = nothing`: Only return time_series with this type. - `name = nothing`: Only return time_series matching this value. + +See also: [`get_time_series_multiple` from an individual component or attribute](@ref get_time_series_multiple( + owner::TimeSeriesOwners, + filter_func = nothing; + type = nothing, + name = nothing, +)) """ function get_time_series_multiple( data::SystemData, diff --git a/src/time_series_interface.jl b/src/time_series_interface.jl index 20c5c901d..b842d3a91 100644 --- a/src/time_series_interface.jl +++ b/src/time_series_interface.jl @@ -43,7 +43,14 @@ Does not apply a scaling factor multiplier. - `features...`: User-defined tags that differentiate multiple time series arrays for the same component attribute, such as different arrays for different scenarios or years -See also: [`get_time_series_array`](@ref), [`get_time_series_values`](@ref). +See also: [`get_time_series_array`](@ref), [`get_time_series_values`](@ref), +[`get_time_series` by key](@ref get_time_series( + owner::TimeSeriesOwners, + key::TimeSeriesKey, + start_time::Union{Nothing, Dates.DateTime} = nothing, + len::Union{Nothing, Int} = nothing, + count::Union{Nothing, Int} = nothing, +)) """ function get_time_series( ::Type{T}, @@ -86,6 +93,16 @@ Does not apply a scaling factor multiplier. of forecast windows starting at `start_time` to return. Defaults to all available. - `features...`: User-defined tags that differentiate multiple time series arrays for the same component attribute, such as different arrays for different scenarios or years + +See also: [`get_time_series` by name](@ref get_time_series( + ::Type{T}, + owner::TimeSeriesOwners, + name::AbstractString; + start_time::Union{Nothing, Dates.DateTime} = nothing, + len::Union{Nothing, Int} = nothing, + count::Union{Nothing, Int} = nothing, + features..., +) where {T <: TimeSeriesData}) """ function get_time_series( owner::TimeSeriesOwners, @@ -120,6 +137,13 @@ Call `collect` on the result to get an array. - `filter_func = nothing`: Only return time_series for which this returns true. - `type = nothing`: Only return time_series with this type. - `name = nothing`: Only return time_series matching this value. + +See also: [`get_time_series_multiple` from a `System`](@ref get_time_series_multiple( + data::SystemData, + filter_func = nothing; + type = nothing, + name = nothing, +)) """ function get_time_series_multiple( owner::TimeSeriesOwners, @@ -210,7 +234,20 @@ features...,) where {T <: TimeSeriesData}), len::Union{Nothing, Int} = nothing, features..., ) where {T <: TimeSeriesData}), - [`get_time_series`](@ref) +[`get_time_series_array` from a `StaticTimeSeriesCache`](@ref get_time_series_array( + owner::TimeSeriesOwners, + time_series::StaticTimeSeries, + start_time::Union{Nothing, Dates.DateTime} = nothing; + len::Union{Nothing, Int} = nothing, + ignore_scaling_factors = false, +)), +[`get_time_series_array` from a `ForecastCache`](@ref get_time_series_array( + owner::TimeSeriesOwners, + forecast::Forecast, + start_time::Dates.DateTime; + len = nothing, + ignore_scaling_factors = false, +)) """ function get_time_series_array( ::Type{T}, @@ -271,7 +308,23 @@ See also [`get_time_series_values`](@ref get_time_series_values( forecast::Forecast, start_time::Union{Nothing, Dates.DateTime} = nothing; len::Union{Nothing, Int} = nothing, -)), [`ForecastCache`](@ref). +)), [`ForecastCache`](@ref), +[`get_time_series_array` by name from storage](@ref get_time_series_array( + ::Type{T}, + owner::TimeSeriesOwners, + name::AbstractString; + start_time::Union{Nothing, Dates.DateTime} = nothing, + len::Union{Nothing, Int} = nothing, + ignore_scaling_factors = false, + features..., +) where {T <: TimeSeriesData}), +[`get_time_series_array` from a `StaticTimeSeriesCache`](@ref get_time_series_array( + owner::TimeSeriesOwners, + time_series::StaticTimeSeries, + start_time::Union{Nothing, Dates.DateTime} = nothing; + len::Union{Nothing, Int} = nothing, + ignore_scaling_factors = false, +)) """ function get_time_series_array( owner::TimeSeriesOwners, @@ -301,7 +354,23 @@ factor multiplier by default. See also: [`get_time_series_values`](@ref get_time_series_values(owner::TimeSeriesOwners, time_series::StaticTimeSeries, start_time::Union{Nothing, Dates.DateTime} = nothing; len::Union{Nothing, Int} = nothing, ignore_scaling_factors = false)), [`get_time_series_timestamps`](@ref get_time_series_timestamps(owner::TimeSeriesOwners, time_series::StaticTimeSeries, start_time::Union{Nothing, Dates.DateTime} = nothing; len::Union{Nothing, Int} = nothing,)), -[`StaticTimeSeriesCache`](@ref). +[`StaticTimeSeriesCache`](@ref), +[`get_time_series_array` by name from storage](@ref get_time_series_array( + ::Type{T}, + owner::TimeSeriesOwners, + name::AbstractString; + start_time::Union{Nothing, Dates.DateTime} = nothing, + len::Union{Nothing, Int} = nothing, + ignore_scaling_factors = false, + features..., +) where {T <: TimeSeriesData}), +[`get_time_series_array` from a `ForecastCache`](@ref get_time_series_array( + owner::TimeSeriesOwners, + forecast::Forecast, + start_time::Dates.DateTime; + len = nothing, + ignore_scaling_factors = false, +)) """ function get_time_series_array( owner::TimeSeriesOwners, @@ -352,7 +421,19 @@ See also: [`get_time_series_array`](@ref get_time_series_array( start_time::Union{Nothing, Dates.DateTime} = nothing, len::Union{Nothing, Int} = nothing, ignore_scaling_factors = false, -features...,) where {T <: TimeSeriesData}) +features...,) where {T <: TimeSeriesData}), +[`get_time_series_timestamps` from a `StaticTimeSeriesCache`](@ref get_time_series_timestamps( + owner::TimeSeriesOwners, + time_series::StaticTimeSeries, + start_time::Union{Nothing, Dates.DateTime} = nothing; + len::Union{Nothing, Int} = nothing, +)), +[`get_time_series_timestamps` from a `ForecastCache`](@ref get_time_series_timestamps( + owner::TimeSeriesOwners, + forecast::Forecast, + start_time::Union{Nothing, Dates.DateTime} = nothing; + len::Union{Nothing, Int} = nothing, +)) """ function get_time_series_timestamps( ::Type{T}, @@ -397,7 +478,21 @@ See also: [`get_time_series_array`](@ref get_time_series_array( start_time::Dates.DateTime; len::Union{Nothing, Int} = nothing, ignore_scaling_factors = false, -)), [`ForecastCache`](@ref). +)), [`ForecastCache`](@ref), +[`get_time_series_timestamps` by name from storage](@ref get_time_series_timestamps( + ::Type{T}, + owner::TimeSeriesOwners, + name::AbstractString; + start_time::Union{Nothing, Dates.DateTime} = nothing, + len::Union{Nothing, Int} = nothing, + features..., +) where {T <: TimeSeriesData}), +[`get_time_series_timestamps` from a `StaticTimeSeriesCache`](@ref get_time_series_timestamps( + owner::TimeSeriesOwners, + time_series::StaticTimeSeries, + start_time::Union{Nothing, Dates.DateTime} = nothing; + len::Union{Nothing, Int} = nothing, +)) """ function get_time_series_timestamps( owner::TimeSeriesOwners, @@ -428,7 +523,21 @@ See also: [`get_time_series_array`](@ref get_time_series_array( len::Union{Nothing, Int} = nothing, ignore_scaling_factors = false, )), [`get_time_series_values`](@ref get_time_series_values(owner::TimeSeriesOwners, time_series::StaticTimeSeries, start_time::Union{Nothing, Dates.DateTime} = nothing; len::Union{Nothing, Int} = nothing, ignore_scaling_factors = false)), -[`StaticTimeSeriesCache`](@ref). +[`StaticTimeSeriesCache`](@ref), +[`get_time_series_timestamps` by name from storage](@ref get_time_series_timestamps( + ::Type{T}, + owner::TimeSeriesOwners, + name::AbstractString; + start_time::Union{Nothing, Dates.DateTime} = nothing, + len::Union{Nothing, Int} = nothing, + features..., +) where {T <: TimeSeriesData}), +[`get_time_series_timestamps` from a `ForecastCache`](@ref get_time_series_timestamps( + owner::TimeSeriesOwners, + forecast::Forecast, + start_time::Union{Nothing, Dates.DateTime} = nothing; + len::Union{Nothing, Int} = nothing, +)) """ function get_time_series_timestamps( owner::TimeSeriesOwners, @@ -478,7 +587,21 @@ See also: [`get_time_series_array`](@ref get_time_series_array( len::Union{Nothing, Int} = nothing, features..., ) where {T <: TimeSeriesData}), -[`get_time_series`](@ref) +[`get_time_series`](@ref), +[`get_time_series_values` from a `StaticTimeSeriesCache`](@ref get_time_series_values( + owner::TimeSeriesOwners, + time_series::StaticTimeSeries, + start_time::Union{Nothing, Dates.DateTime} = nothing; + len::Union{Nothing, Int} = nothing, + ignore_scaling_factors = false, +)), +[`get_time_series_values` from a `ForecastCache`](@ref get_time_series_values( + owner::TimeSeriesOwners, + forecast::Forecast, + start_time::Dates.DateTime; + len::Union{Nothing, Int} = nothing, + ignore_scaling_factors = false, +)) """ function get_time_series_values( ::Type{T}, @@ -527,7 +650,23 @@ See also: [`get_time_series_array`](@ref get_time_series_array( forecast::Forecast, start_time::Union{Nothing, Dates.DateTime} = nothing; len::Union{Nothing, Int} = nothing, -)), [`ForecastCache`](@ref). +)), [`ForecastCache`](@ref), +[`get_time_series_values` by name from storage](@ref get_time_series_values( + ::Type{T}, + owner::TimeSeriesOwners, + name::AbstractString; + start_time::Union{Nothing, Dates.DateTime} = nothing, + len::Union{Nothing, Int} = nothing, + ignore_scaling_factors = false, + features..., +) where {T <: TimeSeriesData}), +[`get_time_series_values` from a `StaticTimeSeriesCache`](@ref get_time_series_values( + owner::TimeSeriesOwners, + time_series::StaticTimeSeries, + start_time::Union{Nothing, Dates.DateTime} = nothing; + len::Union{Nothing, Int} = nothing, + ignore_scaling_factors = false, +)) """ function get_time_series_values( owner::TimeSeriesOwners, @@ -567,7 +706,23 @@ See also: [`get_time_series_array`](@ref get_time_series_array( len::Union{Nothing, Int} = nothing, ignore_scaling_factors = false, )), [`get_time_series_timestamps`](@ref get_time_series_timestamps(owner::TimeSeriesOwners, time_series::StaticTimeSeries, start_time::Union{Nothing, Dates.DateTime} = nothing; len::Union{Nothing, Int} = nothing,)), -[`StaticTimeSeriesCache`](@ref). +[`StaticTimeSeriesCache`](@ref), +[`get_time_series_values` by name from storage](@ref get_time_series_values( + ::Type{T}, + owner::TimeSeriesOwners, + name::AbstractString; + start_time::Union{Nothing, Dates.DateTime} = nothing, + len::Union{Nothing, Int} = nothing, + ignore_scaling_factors = false, + features..., +) where {T <: TimeSeriesData}), +[`get_time_series_values` from a `ForecastCache`](@ref get_time_series_values( + owner::TimeSeriesOwners, + forecast::Forecast, + start_time::Dates.DateTime; + len::Union{Nothing, Int} = nothing, + ignore_scaling_factors = false, +)) """ function get_time_series_values( owner::TimeSeriesOwners, diff --git a/src/time_series_storage.jl b/src/time_series_storage.jl index 112934639..a1c3f4755 100644 --- a/src/time_series_storage.jl +++ b/src/time_series_storage.jl @@ -4,13 +4,13 @@ Abstract type for time series storage implementations. All subtypes must implement: - - clear_time_series! - - deserialize_time_series - - get_compression_settings - - get_num_time_series - - remove_time_series! - - serialize_time_series! - - Base.isempty + - `clear_time_series!` + - `deserialize_time_series` + - `get_compression_settings` + - `get_num_time_series` + - `remove_time_series!` + - `serialize_time_series!` + - `Base.isempty` """ abstract type TimeSeriesStorage end diff --git a/src/time_series_structs.jl b/src/time_series_structs.jl index ae023407d..f8b6c32e1 100644 --- a/src/time_series_structs.jl +++ b/src/time_series_structs.jl @@ -1,9 +1,17 @@ const TimeSeriesOwners = Union{InfrastructureSystemsComponent, SupplementalAttribute} -# Required methods: -# - get_name -# - get_time_series_type -# The default methods rely on the field names name and time_series_type. +""" +Supertype for keys that can be used to access a desired time series dataset + +Concrete subtypes: +- [`StaticTimeSeriesKey`](@ref) +- [`ForecastKey`](@ref) + +Required methods: +- `get_name` +- `get_time_series_type` +The default methods rely on the field names `name` and `time_series_type`. +""" abstract type TimeSeriesKey <: InfrastructureSystemsType end get_name(key::TimeSeriesKey) = key.name @@ -24,6 +32,11 @@ function deserialize_struct(T::Type{<:TimeSeriesKey}, data::Dict) return T(; vals...) end +""" +A unique key to identify and retrieve a [`StaticTimeSeries`](@ref) + +See: [`get_time_series_keys`](@ref) and [`get_time_series(::TimeSeriesOwners, ::TimeSeriesKey)`](@ref). +""" @kwdef struct StaticTimeSeriesKey <: TimeSeriesKey time_series_type::Type{<:StaticTimeSeries} name::String @@ -44,6 +57,11 @@ function make_time_series_key(metadata::StaticTimeSeriesMetadata) ) end +""" +A unique key to identify and retrieve a [`Forecast`](@ref) + +See: [`get_time_series_keys`](@ref) and [`get_time_series(::TimeSeriesOwners, ::TimeSeriesKey)`](@ref). +""" @kwdef struct ForecastKey <: TimeSeriesKey time_series_type::Type{<:Forecast} name::String diff --git a/src/utils/logging.jl b/src/utils/logging.jl index 2dd0fce72..08881dce9 100644 --- a/src/utils/logging.jl +++ b/src/utils/logging.jl @@ -317,7 +317,13 @@ Base.flush(logger::FileLogger) = flush(logger.logger.stream) Base.close(logger::FileLogger) = close(logger.logger.stream) """ -Opens a file logger using Logging.SimpleLogger. +Opens a file logger using `Logging.SimpleLogger`. + +# Arguments + - `func::Function` + - `filename::String`: logger filename + - `level=Logging.Info`: optional, to change the minimum logging level + - `mode = "w+"`: Optional, to designate write mode # Example @@ -584,7 +590,7 @@ function set_group_level!(logger::MultiLogger, group::Symbol, level::Base.LogLev end """ -Set the minimum log levels for multiple groups. Refer to [`set_group_level`](@ref) for more +Set the minimum log levels for multiple groups. Refer to [`set_group_level!`](@ref) for more information. """ function set_group_levels!(logger::MultiLogger, group_levels::Dict{Symbol, Base.LogLevel}) diff --git a/src/utils/recorder_events.jl b/src/utils/recorder_events.jl index 6c34070f7..64becd40a 100644 --- a/src/utils/recorder_events.jl +++ b/src/utils/recorder_events.jl @@ -1,3 +1,6 @@ +""" +Supertype for recorder events +""" abstract type AbstractRecorderEvent end get_common(event::AbstractRecorderEvent) = event.common diff --git a/src/value_curve.jl b/src/value_curve.jl index 1ffcf3e5e..2602d262c 100644 --- a/src/value_curve.jl +++ b/src/value_curve.jl @@ -1,7 +1,12 @@ """ Supertype that represents a unitless cost curve -Concrete options are [listed here.](@ref value_curve_library) +Concrete subtypes are: +- [`LinearCurve`](@ref) +- [`QuadraticCurve`](@ref) +- [`PiecewisePointCurve`](@ref) +- [`PiecewiseIncrementalCurve`](@ref) +- [`PiecewiseAverageCurve`](@ref) """ abstract type ValueCurve{T <: FunctionData} end