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.
Example
Section titled “Example”import datetime as dtimport 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),)Constructor
Section titled “Constructor”Bucketer
Section titled “Bucketer”class Bucketer( historical_start_date: datetime.datetime, historical_end_date: datetime.datetime, categories: int, draw_period: int, bucket_definition: list[ShortDate],): BucketerBuilds bucket/category lookup structures used by sampling operations.
Parameters
Section titled “Parameters”-
Midnight timestamp for the first historical day available for sampling.historical_start_datedatetime.datetime -
Midnight timestamp for the last historical day available for sampling.historical_end_datedatetime.datetime -
Number of category partitions used by subclass-specific filtering logic.categoriesint -
Number of consecutive days represented by one sampled draw.draw_periodint -
Strictly increasing list of bucket boundaries that partitions the year.bucket_definitionlist[ShortDate]
Returns Bucketer
Raises
TypeError: If bucket definition is not a list.ValueError: If date ordering or bucket constraints are invalid.
Methods
Section titled “Methods”Bucketer.bucket_of
Section titled “Bucketer.bucket_of”bucket_of(start_of_draw_period: datetime.datetime) -> intReturns bucket index for a draw period start date.
Parameters
Section titled “Parameters”
Start date for the candidate draw period.start_of_draw_perioddatetime.datetime
Returns int
Bucketer.assign_category
Section titled “Bucketer.assign_category”assign_category(date: datetime.datetime) -> intAbstract hook for mapping dates to category indices.
Parameters
Section titled “Parameters”
Start date for the candidate draw period.datedatetime.datetime
Raises NotImplementedError
Bucketer.tabulate_date_info
Section titled “Bucketer.tabulate_date_info”tabulate_date_info(date: datetime.datetime) -> listAbstract hook for storing per-date lookup metadata.
Parameters
Section titled “Parameters”
Start date for the candidate draw period.datedatetime.datetime
Raises NotImplementedError
Bucketer.populate_buckets
Section titled “Bucketer.populate_buckets”populate_buckets() -> NonePopulates historical and future lookup structures.
Returns None
Bucketer.random_sample
Section titled “Bucketer.random_sample”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.
Parameters
Section titled “Parameters”-
Inclusive start of the target future period.future_start_datedatetime.datetime -
Inclusive end of the target future period.future_end_datedatetime.datetime -
RNG used to select indices from each category/bucket pool.rng_pythonrandom.Random
Returns list[datetime.datetime]
Properties
Section titled “Properties”Bucketer.historical_start_date
Section titled “Bucketer.historical_start_date”Start date (midnight) of historical data coverage.
Type datetime.datetime
Bucketer.historical_end_date
Section titled “Bucketer.historical_end_date”End date (midnight) of historical data coverage.
Type datetime.datetime
Bucketer.categories
Section titled “Bucketer.categories”Number of category partitions used in additional date filtering.
Type int
Bucketer.draw_period
Section titled “Bucketer.draw_period”Number of continuous days sampled per draw.
Type int
Bucketer.bucket_definition
Section titled “Bucketer.bucket_definition”Sorted short-date partition defining year buckets.
Type list[ShortDate]
Bucketer.bucket_structure
Section titled “Bucketer.bucket_structure”Nested category/bucket lookup populated with historical draw start dates.
Type dict[int, dict[int, list[datetime.datetime]]]
Bucketer.lookup_structure
Section titled “Bucketer.lookup_structure”Memoized lookup table for date metadata and bucket assignments.
Type dict[datetime.datetime, list]

