Skip to content

rencal.core.bucketer

rencal.core.bucketer provides the base class for calendar-aware bucket sampling of historical draw periods.

Bucketer partitions the year into custom date buckets (defined by ordered ShortDate boundaries), optionally separates dates into categories, and precomputes lookup tables used by random_sample() to draw consecutive historical periods.

import datetime as dt
import random
from rencal.simulation.intermittent_bucketer import IntermittentBucketer
bucketer = IntermittentBucketer(
historical_start_date=dt.datetime(1990, 1, 1),
historical_end_date=dt.datetime(2025, 12, 31),
draw_period=7,
)
sample_starts = bucketer.random_sample(
future_start_date=dt.datetime(2027, 1, 1),
future_end_date=dt.datetime(2027, 2, 1),
rng_python=random.Random(22),
)
class Bucketer(
historical_start_date: datetime.datetime,
historical_end_date: datetime.datetime,
categories: int,
draw_period: int,
bucket_definition: list[ShortDate],
): Bucketer

Builds bucket/category lookup structures used by sampling operations.

  • historical_start_date datetime.datetime

    Midnight timestamp for the first historical day available for sampling.

  • historical_end_date datetime.datetime

    Midnight timestamp for the last historical day available for sampling.

  • categories int

    Number of category partitions used by subclass-specific filtering logic.

  • draw_period int

    Number of consecutive days represented by one sampled draw.

  • bucket_definition list[ShortDate]

    Strictly increasing list of bucket boundaries that partitions the year.

Returns Bucketer

Raises

  • TypeError: If bucket definition is not a list.
  • ValueError: If date ordering or bucket constraints are invalid.
bucket_of(start_of_draw_period: datetime.datetime) -> int

Returns bucket index for a draw period start date.

  • start_of_draw_period datetime.datetime

    Start date for the candidate draw period.

Returns int

assign_category(date: datetime.datetime) -> int

Abstract hook for mapping dates to category indices.

  • date datetime.datetime

    Start date for the candidate draw period.

Raises NotImplementedError

tabulate_date_info(date: datetime.datetime) -> list

Abstract hook for storing per-date lookup metadata.

  • date datetime.datetime

    Start date for the candidate draw period.

Raises NotImplementedError

populate_buckets() -> None

Populates historical and future lookup structures.

Returns None

random_sample(
future_start_date: datetime.datetime,
future_end_date: datetime.datetime,
rng_python,
) -> list[datetime.datetime]

Samples historical draw-period start dates to cover a future horizon.

  • future_start_date datetime.datetime

    Inclusive start of the target future period.

  • future_end_date datetime.datetime

    Inclusive end of the target future period.

  • rng_python random.Random

    RNG used to select indices from each category/bucket pool.

Returns list[datetime.datetime]

Start date (midnight) of historical data coverage.

Type datetime.datetime

End date (midnight) of historical data coverage.

Type datetime.datetime

Number of category partitions used in additional date filtering.

Type int

Number of continuous days sampled per draw.

Type int

Sorted short-date partition defining year buckets.

Type list[ShortDate]

Nested category/bucket lookup populated with historical draw start dates.

Type dict[int, dict[int, list[datetime.datetime]]]

Memoized lookup table for date metadata and bucket assignments.

Type dict[datetime.datetime, list]