rencal.core.bucketed_data
rencal.core.bucketed_data contains shared histogram and distribution utilities used by bucketer-driven simulators.
The module exposes:
BucketedData: utility base class with histogram and distribution optimization helpers.VersionedColumnsNDArray: array wrapper that tracks canonical columns and transformed variants produced during resampling.
Example
Section titled “Example”# Returned from WeatherData.random_sample(...)sample = weather_data.random_sample(start, end)
# Access canonical columnbase_stream = sample.access_col(1)
# Access first transformed variant of canonical column 1variant_stream = sample.access_col(1, 1)Constructor
Section titled “Constructor”VersionedColumnsNDArray
Section titled “VersionedColumnsNDArray”class VersionedColumnsNDArray(n_raw_features: int): VersionedColumnsNDArrayTracks canonical and transformed column mappings for sampled output arrays.
Parameters
Section titled “Parameters”
Number of canonical (original) columns in the sampled matrix.n_raw_featuresint
Returns VersionedColumnsNDArray
BucketedData
Section titled “BucketedData”class BucketedData(): BucketedDataBase utility class for shared bucketer/sampling operations.
Returns BucketedData
Methods
Section titled “Methods”VersionedColumnsNDArray.update_mapping
Section titled “VersionedColumnsNDArray.update_mapping”update_mapping(canonical_col: int, j: int) -> intRegisters a transformed column index for a canonical column.
Returns int
VersionedColumnsNDArray.attach_data
Section titled “VersionedColumnsNDArray.attach_data”attach_data(data: NDArray[np.floating]) -> VersionedColumnsNDArrayAttaches final output matrix to wrapper.
Returns VersionedColumnsNDArray
Raises
RuntimeError: If data has already been attached.ValueError: If matrix dimensionality or shape is invalid.
VersionedColumnsNDArray.access_col
Section titled “VersionedColumnsNDArray.access_col”access_col(canonical_col: int, version: int = 0) -> NDArray[np.floating]Returns canonical or transformed column view.
Returns NDArray[np.floating]
Raises
RuntimeError: If matrix data is not attached.IndexError: If requested transformed version is unavailable.
BucketedData.crop_time_margins_to_full_years
Section titled “BucketedData.crop_time_margins_to_full_years”crop_time_margins_to_full_years() -> datetime.datetimeComputes unbiased historical start date with full seasonal coverage.
Returns datetime.datetime
BucketedData.get_histogram
Section titled “BucketedData.get_histogram”get_histogram( statistical_start_index: int, statistical_end_index: int, historical_data: NDArray[np.floating] | None, number_of_bins: int, ignore_zeros: bool = False,) -> NDArray[np.uint32]Computes histogram matrix for selected rows and mask columns.
Returns NDArray[np.uint32]
BucketedData.get_fast_histogram
Section titled “BucketedData.get_fast_histogram”get_fast_histogram( first_statistical_index: int, last_statistical_index: int, historical_data: NDArray[np.floating], hours_per_block: int, prefix_histograms: NDArray[np.uint32], ignore_zeros: bool = False,) -> NDArray[np.uint32]Computes histogram matrix using prefix histograms and partial-edge corrections.
Returns NDArray[np.uint32]
BucketedData.get_absolute_index_of_date
Section titled “BucketedData.get_absolute_index_of_date”get_absolute_index_of_date(date: datetime.datetime) -> tuple[int, int]Maps date to absolute hourly index range.
Returns tuple[int, int]
BucketedData.adjust_forecasted_horizon
Section titled “BucketedData.adjust_forecasted_horizon”adjust_forecasted_horizon( future_start_date: datetime.datetime, future_end_date: datetime.datetime,) -> tuple[datetime.datetime, int]Expands horizon boundary for draw-period chunking and returns hour count to trim output.
Returns tuple[datetime.datetime, int]
BucketedData.append_resampled_columns
Section titled “BucketedData.append_resampled_columns”append_resampled_columns( sample: NDArray[np.floating], rng: np.random.Generator,) -> VersionedColumnsNDArrayAppends transformed streams and returns version-aware output wrapper.
Returns VersionedColumnsNDArray
BucketedData.compute_time_margins
Section titled “BucketedData.compute_time_margins”compute_time_margins( historical_start, historical_end, data_limit_left, data_limit_right,) -> tuple[pd.Timestamp, pd.Timestamp, pd.Timestamp, pd.Timestamp]Normalizes historical margins to strict hourly/day boundaries.
Returns tuple[pd.Timestamp, pd.Timestamp, pd.Timestamp, pd.Timestamp]
BucketedData.rowwise_logsumexp
Section titled “BucketedData.rowwise_logsumexp”rowwise_logsumexp(a: NDArray[np.float64]) -> NDArray[np.float64]Computes numerically stable row-wise log(sum(exp(a))).
Returns NDArray[np.float64]
BucketedData.data_mean_and_var_under_logweights_probability
Section titled “BucketedData.data_mean_and_var_under_logweights_probability”data_mean_and_var_under_logweights_probability( data: NDArray[np.float64], logweights: NDArray[np.float64],) -> tuple[NDArray[np.float64], NDArray[np.float64]]Computes mean and variance under normalized row-wise log-weights.
Returns tuple[NDArray[np.float64], NDArray[np.float64]]
BucketedData.compute_optimized_distributions
Section titled “BucketedData.compute_optimized_distributions”compute_optimized_distributions( previous_distribution_not_normalized: NDArray[np.uint32], desired_averages: Sequence[float], observations_per_column: int | Sequence[int] | NDArray, tol: float = 1e-12, max_iter: int = 60,) -> tuple[NDArray[np.float64], NDArray[np.float64]]Optimizes tilted distributions matching desired averages.
Returns tuple[NDArray[np.float64], NDArray[np.float64]]

