BazerData.jl

TimeShift.jl (9687B)

---

 # --------------------------------------------------------------------------------------------------
 # most of this code was copied from @FuZhiyu PanelShift.jl package
 # --------------------------------------------------------------------------------------------------
 
 
 # --------------------------------------------------------------------------------------------------
 # Shared validation for tlag/tlead
 function _validate_tshift_args(x, t_vec; n=nothing, checksorted=true, verbose=false)
     if isnothing(n)
         n = oneunit(t_vec[1] - t_vec[1])
         verbose && ((t_vec[1] isa Date) ? (@info "Default date gap inferred ... $n") :
             (@info "Default gap inferred ... $n"))
     elseif eltype(t_vec) == Date
         verbose && @info "No checks on increment argument n for type Date ... "
     else
         !(n isa typeof(t_vec[1]-t_vec[1])) &&
             error("Time gap type does not match time variable: typeof(n)=$(typeof(n)) != eltype(vec)=$(eltype(t_vec))")
     end
 
     checksorted && !issorted(t_vec; lt = (<=)) && error("time vector not sorted (order is strict)!")
     !(n > zero(n)) && error("shift value has to be positive!")
 
     N = length(t_vec)
     (length(x) != N) && error("value and time vector have different lengths!")
 
     return n, N
 end
 
 
 # Linear scan on native types (integers — already fast)
 function _scan_lag!(x_shift, x, t_vec, n, N)
     j = 0
     @inbounds for i in 1:N
         target = t_vec[i] - n
         while j < N && t_vec[j + 1] <= target
             j += 1
         end
         if j > 0 && t_vec[j] == target
             x_shift[i] = x[j]
         end
     end
     return x_shift
 end
 
 function _scan_lead!(x_shift, x, t_vec, n, N)
     j = 0
     @inbounds for i in 1:N
         target = t_vec[i] + n
         if target > t_vec[N]
             break
         end
         while j < N && t_vec[j + 1] < target
             j += 1
         end
         if j + 1 <= N && t_vec[j + 1] == target
             x_shift[i] = x[j + 1]
         end
     end
     return x_shift
 end
 
 
 # Pre-computed Int64 scan for Date types.
 # Date arithmetic (especially Month/Year) is expensive; converting to Int64
 # first keeps the hot scan loop in pure integer comparisons.
 function _scan_lag_int64!(x_shift, x, t_vec, n, N)
     int_times   = Vector{Int64}(undef, N)
     int_targets = Vector{Int64}(undef, N)
     @inbounds for i in 1:N
         int_times[i]   = Dates.value(t_vec[i])
         int_targets[i] = Dates.value(t_vec[i] - n)
     end
     j = 0
     @inbounds for i in 1:N
         target = int_targets[i]
         while j < N && int_times[j + 1] <= target
             j += 1
         end
         if j > 0 && int_times[j] == target
             x_shift[i] = x[j]
         end
     end
     return x_shift
 end
 
 function _scan_lead_int64!(x_shift, x, t_vec, n, N)
     int_times   = Vector{Int64}(undef, N)
     int_targets = Vector{Int64}(undef, N)
     @inbounds for i in 1:N
         int_times[i]   = Dates.value(t_vec[i])
         int_targets[i] = Dates.value(t_vec[i] + n)
     end
     j = 0
     @inbounds for i in 1:N
         target = int_targets[i]
         if target > int_times[N]
             break
         end
         while j < N && int_times[j + 1] < target
             j += 1
         end
         if j + 1 <= N && int_times[j + 1] == target
             x_shift[i] = x[j + 1]
         end
     end
     return x_shift
 end
 # --------------------------------------------------------------------------------------------------
 
 
 # --------------------------------------------------------------------------------------------------
 """
     tlag(x, t_vec; n = nothing, checksorted = true, verbose = false)
 
 Create a lagged version of array `x` based on time vector `t_vec`, where each element is shifted
 backward in time by a specified amount `n`.
 
 # Arguments
 - `x`: Array of values to be lagged
 - `t_vec`: Vector of time points corresponding to each element in `x`
 
 # Keyword Arguments
 - `n`: Time gap for lagging. If `nothing` (default), uses the minimal unit difference between time points.
 - `checksorted`: If `true` (default), verifies that `t_vec` is sorted in ascending order
 - `verbose`: If `true`, prints informational messages about the process
 
 # Returns
 - An array of the same length as `x` where each element is the value of `x` from `n` time units ago,
   or `missing` if no corresponding past value exists
 
 # Notes
 - Time vectors must be strictly sorted (ascending order)
 - The time gap `n` must be positive
 - For `Date` types, no type checking is performed on `n`
 - Elements at the beginning will be `missing` if they don't have values from `n` time units ago
 - See PanelShift.jl for original implementation
 
 # Errors
 - If `t_vec` is not sorted and `checksorted=true`
 - If `n` is not positive
 - If `x` and `t_vec` have different lengths
 - If `n` has a type that doesn't match the difference type of `t_vec`
 
 # Examples
 ```jldoctest
 julia> tlag([1, 2, 3], [1, 2, 3], n = 1)
 3-element Vector{Union{Missing, Int64}}:
   missing
  1
  2
 ```
 
 """
 function tlag(x, t_vec;
     n = nothing,
     checksorted = true,
     verbose = false,
     )
 
     isempty(t_vec) && return Array{Union{Missing, eltype(x)}}(missing, 0)
 
     n, N = _validate_tshift_args(x, t_vec; n=n, checksorted=checksorted, verbose=verbose)
 
     x_shift = Array{Union{Missing, eltype(x)}}(missing, N)
 
     # Month/Year arithmetic is expensive; pre-compute Int64 targets for those.
     # Day and integer arithmetic is cheap; scan directly.
     if n isa Dates.OtherPeriod
         _scan_lag_int64!(x_shift, x, t_vec, n, N)
     else
         _scan_lag!(x_shift, x, t_vec, n, N)
     end
 
     return x_shift
 end
 # --------------------------------------------------------------------------------------------------
 
 
 # --------------------------------------------------------------------------------------------------
 """
     tlead(x, t_vec; n = nothing, checksorted = true, verbose = false)
 
 Create a leading version of array `x` based on time vector `t_vec`, where each element is shifted
 forward in time by a specified amount `n`.
 
 # Arguments
 - `x`: Array of values to be led
 - `t_vec`: Vector of time points corresponding to each element in `x`
 
 # Keyword Arguments
 - `n`: Time gap for leading. If `nothing` (default), uses the minimal unit difference between time points.
 - `checksorted`: If `true` (default), verifies that `t_vec` is sorted in ascending order
 - `verbose`: If `true`, prints informational messages about the process
 
 # Returns
 - An array of the same length as `x` where each element is the value of `x` from `n` time units in the future,
   or `missing` if no corresponding future value exists
 
 # Notes
 - Time vectors must be strictly sorted (ascending order)
 - The time gap `n` must be positive
 - For `Date` types, no type checking is performed on `n`
 - Elements at the end will be `missing` if they don't have values from `n` time units in the future
 - See PanelShift.jl for original implementation
 
 # Errors
 - If `t_vec` is not sorted and `checksorted=true`
 - If `n` is not positive
 - If `x` and `t_vec` have different lengths
 - If `n` has a type that doesn't match the difference type of `t_vec`
 
 # Examples
 ```jldoctest
 julia> tlead([1, 2, 3], [8, 9, 10], n = 1)
 3-element Vector{Union{Missing, Int64}}:
  2
  3
   missing
 ```
 
 """
 function tlead(x, t_vec;
     n = nothing,
     checksorted = true,
     verbose = false,
     )
 
     isempty(t_vec) && return Array{Union{Missing, eltype(x)}}(missing, 0)
 
     n, N = _validate_tshift_args(x, t_vec; n=n, checksorted=checksorted, verbose=verbose)
 
     x_shift = Array{Union{Missing, eltype(x)}}(missing, N)
 
     if n isa Dates.OtherPeriod
         _scan_lead_int64!(x_shift, x, t_vec, n, N)
     else
         _scan_lead!(x_shift, x, t_vec, n, N)
     end
 
     return x_shift
 end
 # --------------------------------------------------------------------------------------------------
 
 
 # --------------------------------------------------------------------------------------------------
 """
     tshift(x, t_vec; n = nothing, kwargs...)
 
 Create a shifted version of array `x` based on time vector `t_vec`, where each element is shifted
 by a specified amount `n`. Acts as a unified interface to `tlag` and `tlead`.
 
 # Arguments
 - `x`: Array of values to be shifted
 - `t_vec`: Vector of time points corresponding to each element in `x`
 
 # Keyword Arguments
 - `n`: Time gap for shifting. If positive, performs a lag operation (backward in time);
        if negative, performs a lead operation (forward in time).
        If `nothing` (default), defaults to a lag operation with minimal unit difference.
 - `kwargs...`: Additional keyword arguments passed to either `tlag` or `tlead`
 
 # Returns
 - An array of the same length as `x` where each element is the value of `x` shifted by `n` time units,
   or `missing` if no corresponding value exists at that time point
 
 # Notes
 - Positive `n` values call `tlag` (backward shift in time)
 - Negative `n` values call `tlead` (forward shift in time)
 - If `n` is not specified, issues a warning and defaults to a lag operation
 
 # Examples
 ```jldoctest
 julia> tshift([1, 2, 3], [-3, -2, -1], n = 1)
 3-element Vector{Union{Missing, Int64}}:
   missing
  1
  2
 
 julia> tshift([1, 2, 3], [-3, -2, -1], n = -1)
 3-element Vector{Union{Missing, Int64}}:
  2
  3
   missing
 
 ```
 
 See also: [`tlag`](@ref), [`tlead`](@ref)
 """
 function tshift(x, t_vec; n=nothing, kwargs...)
 
     if isnothing(n)
         @warn "shift not specified ... defaulting to lag"
         n = oneunit(t_vec[1] - t_vec[1])
     end
 
     if n > zero(n)
         return tlag(x, t_vec, n=n; kwargs...)
     else
         return tlead(x, t_vec, n=-n; kwargs...)
     end
 end
 # --------------------------------------------------------------------------------------------------