Resample Daily Weather Dates Using Annual KNN and Markov Chain Logic

Resamples daily precipitation and temperature sequences by combining:

• annual K-nearest-neighbor (KNN) selection of observed years,

• a three-state Markov chain for wet and dry spell persistence,

• daily KNN resampling on precipitation and temperature anomalies.

The function supports both calendar-year and water-year simulations. The regime is inferred automatically from `year_start_month`: if `year_start_month == 1`, calendar-year logic is used; otherwise, water-year logic is assumed.

Usage

resample_weather_dates(
  sim_annual_precip,
  obs_annual_precip,
  obs_daily_precip,
  obs_daily_temp,
  year_start,
  n_years,
  obs_dates_df,
  sim_dates_df,
  year_start_month = 1,
  annual_knn_n = 100,
  wet_q = 0.2,
  extreme_q = 0.8,
  dry_spell_factor = rep(1, 12),
  wet_spell_factor = rep(1, 12),
  seed = NULL
)

Arguments

sim_annual_precip

Numeric vector of length `n_years`. Synthetic annual precipitation totals generated by the annual model (e.g., WARM), indexed by simulated year.

obs_annual_precip

Numeric vector. Observed annual precipitation totals corresponding to historical water years.

obs_daily_precip

Numeric vector. Observed daily precipitation values (no leap days), aligned with `obs_dates_df`.

obs_daily_temp

Numeric vector. Observed daily temperature values (no leap days), aligned with `obs_dates_df`.

year_start

Integer. First simulation year (calendar year if `year_start_month == 1`, otherwise first water year).

n_years

Integer. Number of simulated years.

obs_dates_df

Data frame containing observed date information. Must include columns `date`, `month`, `day`, and `wyear`.

sim_dates_df

Data frame containing simulated date information (no leap days). Must include columns `month`, `day`, and `wyear`.

year_start_month

Integer in 1:12. First month of the simulation year. Use 1 for calendar-year simulations, or another month for water-year simulations.

annual_knn_n

Integer. Number of historical years sampled in the annual KNN step.

wet_q

Numeric between 0 and 1. Quantile used to define the wet threshold for daily precipitation states.

extreme_q

Numeric between 0 and 1. Quantile used to define the very wet (extreme) precipitation threshold.

dry_spell_factor

Numeric vector of length 12. Monthly adjustment factors controlling dry spell persistence in the Markov chain.

wet_spell_factor

Numeric vector of length 12. Monthly adjustment factors controlling wet spell persistence in the Markov chain.

seed

Optional integer. Base random seed for reproducibility.

Value

A `Date` vector of length equal to `nrow(sim_dates_df)`, giving the resampled observed dates corresponding to each simulated day.

Details

For each simulated year, a subset of observed water years is selected using annual KNN matching against `sim_annual_precip`. Daily weather is then generated sequentially:

1. The first day of each simulated year is sampled from observed days matching the simulated month and day.

2. Subsequent days are generated using a Markov chain to simulate wet and dry states.

3. Conditional on the simulated state, candidate observed days are selected using calendar constraints and expanded search windows.

4. A daily KNN step on precipitation and temperature anomalies is used to select the next-day weather values.

In calendar-year mode (`year_start_month == 1`), transitions that cross December to January are explicitly excluded to avoid cross-year contamination.