Find Maximum Seasonal Block — seasonal

This function identifies the contiguous block of time steps (with wrapping at the end of the profile) that contributes the highest percentage of the total value over the full cycle (e.g., a year). For each possible starting point, the function computes the sum over the next `block_length` time steps, converts that sum into a percentage of the total, and returns the block with the highest percentage.

Usage

seasonal_block(profile, block_length)

Arguments

profile: A numeric vector representing non-negative values across a regular time cycle (e.g., daily rainfall over a year).
block_length: An integer specifying the number of consecutive time steps in the block.

Value

A list with the following components:

max_percentage: The maximum percentage of the total value contained in any block.
peak_season_start: The starting index of the block with the maximum percentage.
peak_season_end: The ending index of the block with the maximum percentage.

Details

The function iterates over each possible starting index and calculates the sum of the values over the next `block_length` time steps. If the block extends beyond the end of the vector, the counting wraps around to the beginning.

Examples

# Generate a seasonal pattern using a Fourier-based prediction
seasonal_pattern <- fourier_predict(
  coef = c(0.3, -0.3, 0.3, 0, -0.3, 0.3, 0),
  t = 1:365,
  floor = 0
)

# Plot the seasonal pattern
plot(seasonal_pattern, t = "l")

# Identify the seasonal block with maximum contribution over a 90-day period
identify_season <- seasonal_block(
  profile = seasonal_pattern$profile,
  block_length = 30 * 3
)
print(identify_season$max_percentage)
#> [1] 66.95732
abline(v = c(identify_season$peak_season_start, identify_season$peak_season_end))