API

TimeSamplers.create_TimeSampler Function

create_TimeSampler(date_vector, t_step, sampler_func = mean, skip_sampling = false)

Create one or more temporal sampling/aggregation objects (TimeSample) for a given target time step.

Arguments

• date_vector: A vector of Dates.TimeType values (e.g. Date or DateTime) that define the time axis to be aggregated.

• t_step: The target sampling/aggregation specification. Common forms:

  • ::Union{String, Symbol}: A name that resolves to a time-sampler type in TimeSampler (e.g. "TimeDay" / :TimeDay).

  • ::TimeSampleMethod: A concrete method instance (e.g. TimeDay()), used via multiple dispatch.

• sampler_func: Function to apply per group (defaults to mean).

• skip_sampling: If true, return nothing for samplers that would be a no-op (defaults to false).

Returns

• Vector{Union{Nothing, TimeSample}}: Time-sampling/aggregation objects, with nothing entries when skip_sampling=true.

Examples

julia> using TimeSamplers, Dates

julia> dates = collect(Date(2000, 1, 1):Day(1):Date(2000, 1, 10))
10-element Vector{Date}:
 2000-01-01
 2000-01-02
 2000-01-03
 2000-01-04
 2000-01-05
 2000-01-06
 2000-01-07
 2000-01-08
 2000-01-09
 2000-01-10

julia> daily_sampler = create_TimeSampler(dates, TimeDay())
1-element Vector{TimeSample{Vector{UnitRange{Int64}}, typeof(Statistics.mean)}}:
 TimeSample{Vector{UnitRange{Int64}}, typeof(Statistics.mean)}(UnitRange{Int64}[1:1, 2:2, 3:3, 4:4, 5:5, 6:6, 7:7, 8:8, 9:9, 10:10], Statistics.mean)

julia> monthly_sampler = create_TimeSampler(dates, "TimeMonth")
1-element Vector{TimeSample{Vector{UnitRange{Int64}}, typeof(Statistics.mean)}}:
 TimeSample{Vector{UnitRange{Int64}}, typeof(Statistics.mean)}(UnitRange{Int64}[1:10], Statistics.mean)

julia> anomaly_sampler = create_TimeSampler(dates, TimeDayAnomaly())
2-element Vector{TimeSample{Vector{UnitRange{Int64}}, typeof(Statistics.mean)}}:
 TimeSample{Vector{UnitRange{Int64}}, typeof(Statistics.mean)}(UnitRange{Int64}[1:1, 2:2, 3:3, 4:4, 5:5, 6:6, 7:7, 8:8, 9:9, 10:10], Statistics.mean)
 TimeSample{Vector{UnitRange{Int64}}, typeof(Statistics.mean)}(UnitRange{Int64}[1:10], Statistics.mean)

Code

function create_TimeSampler end


function create_TimeSampler(date_vector, t_step::Union{String, Symbol}, sampler_func=mean, skip_sampling=false)
    return create_TimeSampler(date_vector, get_TimeSampler(t_step), sampler_func, skip_sampling)
end

function create_TimeSampler(date_vector, t_step::Union{String, Symbol}, sampler_func=mean, skip_sampling=false)
    return create_TimeSampler(date_vector, get_TimeSampler(t_step), sampler_func, skip_sampling)
end

function create_TimeSampler(date_vector, ::TimeMean, sampler_func=mean, skip_sampling=false)
    stepvectime = getTimeArray([1:length(date_vector)], getTypeOfTimeIndexArray())
    mean_agg = TimeSample(stepvectime, sampler_func)
    return [mean_agg,]
end

function create_TimeSampler(date_vector, ::TimeDay, sampler_func=mean, skip_sampling=false)
    stepvectime = getIndicesForTimeGroups(day.(date_vector))
    day_agg = TimeSample(stepvectime, sampler_func)
    if skip_sampling
        day_agg = nothing
    end
    return [day_agg,]
end

function create_TimeSampler(date_vector, ::TimeDayAnomaly, sampler_func=mean, skip_sampling=false)
    day_agg = create_TimeSampler(date_vector, TimeDay(), sampler_func, skip_sampling)
    mean_agg = create_TimeSampler(date_vector, TimeMean(), sampler_func)
    return [day_agg[1], mean_agg[1]]
end

function create_TimeSampler(date_vector, ::TimeDayIAV, sampler_func=mean, skip_sampling=false)
    days = dayofyear.(date_vector)
    day_aggr = create_TimeSampler(date_vector, TimeDay(), sampler_func, skip_sampling)
    daysMsc = unique(days)
    daysMsc_inds = [findall(==(dd), days) for dd in daysMsc]
    daysIav_inds = [getTimeArray(daysMsc_inds[d], getTypeOfTimeIndexArray()) for d in days]
    dayIav_agg = TimeSample(daysIav_inds, sampler_func)
    return [day_aggr[1], dayIav_agg]
end

function create_TimeSampler(date_vector, ::TimeDayMSC, sampler_func=mean, skip_sampling=false)
    days = dayofyear.(date_vector)
    daysMsc = unique(days)
    days_ind = [getTimeArray(findall(==(dd), days), getTypeOfTimeIndexArray()) for dd in daysMsc]
    dat_msc_agg = TimeSample(days_ind, sampler_func)
    return [dat_msc_agg,]
end

function create_TimeSampler(date_vector, ::TimeDayMSCAnomaly, sampler_func=mean, skip_sampling=false)
    dat_msc_agg = create_TimeSampler(date_vector, TimeDayMSC(), sampler_func, skip_sampling)
    mean_agg = create_TimeSampler(date_vector, TimeMean(), sampler_func)
    return [dat_msc_agg[1], mean_agg[1]]
end

function create_TimeSampler(date_vector, ::TimeHour, sampler_func=mean, skip_sampling=false)
    stepvectime = getIndicesForTimeGroups(hour.(date_vector))
    hour_agg = TimeSample(stepvectime, sampler_func)
    if skip_sampling
        hour_agg = nothing
    end
    return [hour_agg,]
end

function create_TimeSampler(date_vector, ::TimeHourAnomaly, sampler_func=mean, skip_sampling=false)
    hour_agg = create_TimeSampler(date_vector, TimeHour(), sampler_func, skip_sampling)
    mean_agg = create_TimeSampler(date_vector, TimeMean(), sampler_func)
    return [hour_agg[1], mean_agg[1]]
end

function create_TimeSampler(date_vector, ::TimeHourDayMean, sampler_func=mean, skip_sampling=false)
    hours = hour.(date_vector)
    hours_day = unique(hours)
    t_hour_msc_agg = TimeSample([getTimeArray(findall(==(hh), hours), getTypeOfTimeIndexArray()) for hh in hours_day], sampler_func)
    return [t_hour_msc_agg,]
end

function create_TimeSampler(date_vector, ::TimeMonth, sampler_func=mean, skip_sampling=false)
    stepvectime = getIndicesForTimeGroups(month.(date_vector))
    month_agg = TimeSample(stepvectime, sampler_func)
    return [month_agg,]
end

function create_TimeSampler(date_vector, ::TimeMonthAnomaly, sampler_func=mean, skip_sampling=false)
    month_agg = create_TimeSampler(date_vector, TimeMonth(), sampler_func, skip_sampling)
    mean_agg = create_TimeSampler(date_vector, TimeMean(), sampler_func)
    return [month_agg[1], mean_agg[1]]
end

function create_TimeSampler(date_vector, ::TimeMonthIAV, sampler_func=mean, skip_sampling=false)
    months = month.(date_vector) # month for each time step, size = number of time steps
    month_aggr = create_TimeSampler(date_vector, TimeMonth(), sampler_func, skip_sampling) #to get the month per month, size = number of months
    months_series = Int.(view(months, month_aggr[1])) # aggregate the months per time step
    monthsMsc = unique(months) # get unique months
    monthsMsc_inds = [findall(==(mm), months) for mm in monthsMsc] # all timesteps per unique month
    monthsIav_inds = [getTimeArray(monthsMsc_inds[mm], getTypeOfTimeIndexArray()) for mm in months_series] # repeat monthlymsc indices for each month in time range
    monthIav_agg = TimeSample(monthsIav_inds, sampler_func) # generate aggregator
    return [month_aggr[1], monthIav_agg]
end

function create_TimeSampler(date_vector, ::TimeMonthMSC, sampler_func=mean, skip_sampling=false)
    months = month.(date_vector)
    monthsMsc = unique(months)
    t_month_msc_agg = TimeSample([getTimeArray(findall(==(mm), months), getTypeOfTimeIndexArray()) for mm in monthsMsc], sampler_func)
    return [t_month_msc_agg,]
end

function create_TimeSampler(date_vector, ::TimeMonthMSCAnomaly, sampler_func=mean, skip_sampling=false)
    t_month_msc_agg = create_TimeSampler(date_vector, TimeMonthMSC(), sampler_func, skip_sampling)
    mean_agg = create_TimeSampler(date_vector, TimeMean(), sampler_func)
    return [t_month_msc_agg[1], mean_agg[1]]
end

function create_TimeSampler(date_vector, ::TimeYear, sampler_func=mean, skip_sampling=false)
    stepvectime = getTimeArray(getIndicesForTimeGroups(year.(date_vector)), getTypeOfTimeIndexArray())
    year_agg = TimeSample(stepvectime, sampler_func)
    return [year_agg,]
end

function create_TimeSampler(date_vector, ::TimeYearAnomaly, sampler_func=mean, skip_sampling=false)
    year_agg = create_TimeSampler(date_vector, TimeYear(), sampler_func, skip_sampling)
    mean_agg = create_TimeSampler(date_vector, TimeMean(), sampler_func)
    return [year_agg[1], mean_agg[1]]
end

function create_TimeSampler(date_vector, ::TimeAllYears, sampler_func=mean, skip_sampling=false)
    stepvectime = getTimeArray([1:length(date_vector)], getTypeOfTimeIndexArray())
    all_agg = TimeSample(stepvectime, sampler_func)
    return [all_agg,]
end

function create_TimeSampler(date_vector, ::TimeFirstYear, sampler_func=mean, skip_sampling=false)
    years = year.(date_vector)
    first_year = minimum(years)
    year_inds = getIndexForSelectedYear(years, first_year)
    year_agg = TimeSample(year_inds, sampler_func)
    return [year_agg,]
end

function create_TimeSampler(date_vector, ::TimeRandomYear, sampler_func=mean, skip_sampling=false)
    years = year.(date_vector)
    random_year = rand(unique(years))
    year_inds = getIndexForSelectedYear(years, random_year)
    year_agg = TimeSample(year_inds, sampler_func)
    return [year_agg,]
end

function create_TimeSampler(date_vector, ::TimeShuffleYears, sampler_func=mean, skip_sampling=false)
    years = year.(date_vector)
    unique_years = unique(years)
    shuffled_unique_years = sample(unique_years, length(unique_years), replace=false)
    year_inds = getIndexForSelectedYear.(Ref(years), shuffled_unique_years)
    year_agg = TimeSample(year_inds, sampler_func)
    return [year_agg,]
end

TimeSamplers.do_time_sampling Function

do_time_sampling(dat, time_samplers, sampling/aggregation_type)
do_time_sampling(dat, time_samplers)

a temporal sampling/aggregation function to aggregate the data using a vector of aggregators

Arguments:

• dat: a data array/vector to aggregate

• time_samplers: a vector of time aggregator structs with indices and function to do sampling/aggregation

• sampling/aggregation_type: a type defining the type of sampling/aggregation to be done as follows:

  • ::TimeNoDiff: a type defining that the aggregator does not require removing/reducing values from original time series

  • ::TimeDiff: a type defining that the aggregator requires removing/reducing values from original time series. First aggregator aggregates the main time series, second aggregator aggregates to the time series to be removed.

  • ::TimeIndexed: a type defining that the aggregator requires indexing the original time series

If sampling/aggregation_type is omitted, it defaults to TimeNoDiff().

Examples

julia> using TimeSamplers, Dates

julia> dates = collect(Date(2000, 1, 1):Day(1):Date(2000, 1, 5))
5-element Vector{Date}:
 2000-01-01
 2000-01-02
 2000-01-03
 2000-01-04
 2000-01-05

julia> data = [1.0, 2.0, 3.0, 4.0, 5.0]
5-element Vector{Float64}:
 1.0
 2.0
 3.0
 4.0
 5.0

julia> samplers = create_TimeSampler(dates, TimeDay())
1-element Vector{TimeSample{Vector{UnitRange{Int64}}, typeof(Statistics.mean)}}:
 TimeSample{Vector{UnitRange{Int64}}, typeof(Statistics.mean)}(UnitRange{Int64}[1:1, 2:2, 3:3, 4:4, 5:5], Statistics.mean)

julia> do_time_sampling(data, samplers)
5-element Vector{Float64}:
 1.0
 2.0
 3.0
 4.0
 5.0

julia> anomaly_samplers = create_TimeSampler(dates, TimeDayAnomaly())
2-element Vector{TimeSample{Vector{UnitRange{Int64}}, typeof(Statistics.mean)}}:
 TimeSample{Vector{UnitRange{Int64}}, typeof(Statistics.mean)}(UnitRange{Int64}[1:1, 2:2, 3:3, 4:4, 5:5], Statistics.mean)
 TimeSample{Vector{UnitRange{Int64}}, typeof(Statistics.mean)}(UnitRange{Int64}[1:5], Statistics.mean)

julia> do_time_sampling(data, anomaly_samplers, TimeDiff())
5-element Vector{Float64}:
 -2.0
 -1.0
  0.0
  1.0
  2.0

Code

function do_time_sampling end

function do_time_sampling(dat, time_samplers)
    return do_time_sampling(dat, time_samplers, TimeNoDiff())
end

function do_time_sampling(dat, time_samplers)
    return do_time_sampling(dat, time_samplers, TimeNoDiff())
end

function do_time_sampling(dat, time_samplers, ::TimeIndexed)
    return dat[first(time_samplers).indices...]
end

function do_time_sampling(dat, time_samplers, ::TimeNoDiff)
    return time_sampling(dat, first(time_samplers))
end

function do_time_sampling(dat, time_samplers, ::TimeDiff)
    dat_samp = time_sampling(dat, first(time_samplers))
    dat_samp_to_remove = time_sampling(dat, last(time_samplers))
    return dat_samp .- dat_samp_to_remove
end

TimeSamplers.get_TimeSampler Function

get_TimeSampler(aggr)

Creates and returns a time aggregator instance based on the provided sampling/aggregation.

Arguments

• aggr::Symbol: Symbol specifying the time sampling/aggregation method type name (e.g. :TimeDay)

• aggr::String: String specifying the time sampling/aggregation method type name (e.g. "TimeDay")

Returns

An instance of the corresponding TimeSampleMethod subtype.

Examples

julia> using TimeSamplers

julia> get_TimeSampler("TimeDay")
TimeDay()

julia> get_TimeSampler(:TimeMonth)
TimeMonth()

julia> get_TimeSampler("TimeYear")
TimeYear()

Notes

• A similar approach (getTypeInstanceForNamedOptions) is used in Setup for creating other named options.

Code

function get_TimeSampler end

function get_TimeSampler(aggr::Symbol)
    return get_TimeSampler(string(aggr))
end

function get_TimeSampler(aggr::Symbol)
    return get_TimeSampler(string(aggr))
end

function get_TimeSampler(aggr::String)
    # uc_first = String(aggr)
    # uc_first = toUpperCaseFirst(aggr, "Time")
    return getfield(TimeSamplers, Symbol(aggr))()
end

TimeSamplers.time_sampling Function

time_sampling(dat::AbstractArray, time_sampler::TimeSample, dim = 1)

a temporal sampling/aggregation function to aggregate the data using a given aggregator when the input data is an array

Arguments:

• dat: a data array/vector to aggregate with function for the following types:

  • ::AbstractArray: an array

  • ::SubArray: a view of an array

  • ::Nothing: a dummy type to return the input and do no sampling/aggregation data

• time_sampler: a time aggregator struct with indices and function to do sampling/aggregation

• dim: the dimension along which the sampling/aggregation should be done

Examples

julia> using TimeSamplers, Dates

julia> dates = collect(Date(2000, 1, 1):Day(1):Date(2000, 1, 5))
5-element Vector{Date}:
 2000-01-01
 2000-01-02
 2000-01-03
 2000-01-04
 2000-01-05

julia> data = [1.0, 2.0, 3.0, 4.0, 5.0]
5-element Vector{Float64}:
 1.0
 2.0
 3.0
 4.0
 5.0

julia> sampler = create_TimeSampler(dates, TimeDay())[1]
TimeSample{Vector{UnitRange{Int64}}, typeof(Statistics.mean)}(UnitRange{Int64}[1:1, 2:2, 3:3, 4:4, 5:5], Statistics.mean)

julia> time_sampling(data, sampler)
5-element Vector{Float64}:
 1.0
 2.0
 3.0
 4.0
 5.0

julia> monthly_sampler = create_TimeSampler(dates, TimeMonth())[1]
TimeSample{Vector{UnitRange{Int64}}, typeof(Statistics.mean)}(UnitRange{Int64}[1:5], Statistics.mean)

julia> time_sampling(data, monthly_sampler)
1-element Vector{Float64}:
 3.0

Code

function time_sampling end

function time_sampling(dat::AbstractArray, time_sampler::TimeSample, dim=1)
    dat = view(dat, time_sampler, dim=dim)
    return getTimeSampledArray(dat)
end

function time_sampling(dat::AbstractArray, time_sampler::TimeSample, dim=1)
    dat = view(dat, time_sampler, dim=dim)
    return getTimeSampledArray(dat)
end

function time_sampling(dat::SubArray, time_sampler::TimeSample, dim=1)
    dat = view(dat, time_sampler, dim=dim)
    return getTimeSampledArray(dat)
end

function time_sampling(dat, time_sampler::Nothing, dim=1)
    return dat
end