Skip to content

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.
# Returned from WeatherData.random_sample(...)
sample = weather_data.random_sample(start, end)
# Access canonical column
base_stream = sample.access_col(1)
# Access first transformed variant of canonical column 1
variant_stream = sample.access_col(1, 1)
class VersionedColumnsNDArray(n_raw_features: int): VersionedColumnsNDArray

Tracks canonical and transformed column mappings for sampled output arrays.

  • n_raw_features int

    Number of canonical (original) columns in the sampled matrix.

Returns VersionedColumnsNDArray

class BucketedData(): BucketedData

Base utility class for shared bucketer/sampling operations.

Returns BucketedData

update_mapping(canonical_col: int, j: int) -> int

Registers a transformed column index for a canonical column.

Returns int

attach_data(data: NDArray[np.floating]) -> VersionedColumnsNDArray

Attaches final output matrix to wrapper.

Returns VersionedColumnsNDArray

Raises

  • RuntimeError: If data has already been attached.
  • ValueError: If matrix dimensionality or shape is invalid.
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.datetime

Computes unbiased historical start date with full seasonal coverage.

Returns datetime.datetime

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]

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]

get_absolute_index_of_date(date: datetime.datetime) -> tuple[int, int]

Maps date to absolute hourly index range.

Returns tuple[int, int]

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]

append_resampled_columns(
sample: NDArray[np.floating],
rng: np.random.Generator,
) -> VersionedColumnsNDArray

Appends transformed streams and returns version-aware output wrapper.

Returns VersionedColumnsNDArray

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]

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]]