Rgram
Skip to content
RgramAggregations

Aggregations and custom reducers

Regressogram.agg and each optional descriptive ci endpoint accept named statistics, native Polars expression functions, or the adapters below.

Named reductions

Name Unweighted meaning With observation weights
mean Arithmetic mean Weighted mean, undefined at zero total mass.
sum Response total Sum of weight × response; zero at zero mass.
median Median Requires an explicit weighted callback.
min, max Extremal observed response Requires an explicit weighted callback.
count Number of non-null responses (all fitted responses are validated) Requires an explicit weighted callback.
std, var Polars sample standard deviation/variance with ddof=1; singleton gives null/unsupported Requires an explicit weighted callback.
first, last Response in original within-bin row order Requires an explicit weighted callback.

Callbacks must return one real numeric scalar per bin, or one Polars scalar reduction expression for native callbacks. NaN is an explicit missing estimate; infinity and nonscalar outputs are rejected. A bare callable means a native Polars-expression callback, not an automatically detected NumPy function.

Factory functions

rgram.array_aggregation

[source]
rgram.array_aggregation(
    func,
    *,
    weighted=False,
)

Wrap a NumPy/Python scalar function for agg or a ci endpoint.

Parameters

func callable

Callback func(values), or func(values, weights) with weighted=True.

weighted bool, default=False

Whether the callback explicitly accepts paired observation weights.

Returns

adapter ArrayAggregation

Cloneable reducer, retaining the callable and weighting option.

Examples

>>> import numpy as np
>>> from rgram import Regressogram, array_aggregation
>>> model = Regressogram(n_bins=1, agg=array_aggregation(np.median))
>>> model.fit([0., 1., 2.], [1., 3., 9.]).predict([1.])
array([3.])

rgram.weighted_aggregation

[source]
rgram.weighted_aggregation(func)

Wrap a native weighted Polars scalar reduction.

Parameters

func callable

Callback func(values_expr, weights_expr) returning a Polars expression.

Returns

adapter WeightedAggregation

Cloneable native reducer. With no fitting weights, the adapter uses ones.

Examples

>>> from rgram import Regressogram, weighted_aggregation
>>> reducer = weighted_aggregation(lambda values, weights:
...     (values * weights).sum() / weights.sum())
>>> model = Regressogram(n_bins=1, agg=reducer)
>>> model.fit([0., 1.], [2., 8.], sample_weight=[1., 2.]).predict([0.5])
array([6.])

rgram.quantile

[source]
rgram.quantile(
    q,
    *,
    interpolation='linear',
)

Create an unweighted native Polars quantile reducer.

Parameters

q float

Probability in [0, 1]. Validated when the reducer is evaluated.

interpolation str, default='linear'

nearest, higher, lower, midpoint, linear, or equiprobable, passed to Polars.

Returns

reducer Quantile

Cloneable quantile callable for agg or either descriptive ci endpoint.

Examples

>>> from rgram import Regressogram, quantile
>>> model = Regressogram(n_bins=1, agg=quantile(0.5))
>>> model.fit([0., 1., 2.], [1., 3., 9.]).predict([1.])
array([3.])

Returned adapter objects

These classes are importable from rgram.aggregation. The factories are the recommended way to create them. Their parameters participate in cloning and nested tuning, for example model.set_params(agg__q=0.9) followed by refitting. A custom callback must implement any desired zero-mass or weighted-quantile convention explicitly; the library does not infer it.

rgram.aggregation.ArrayAggregation

[source]
class rgram.aggregation.ArrayAggregation(
    func,
    *,
    weighted=False,
)

Adapt a numeric callback to a cloneable per-bin scalar reduction.

Parameters

func callable

Function returning one real numeric scalar from values, or values and weights when weighted=True. Receives independent arrays in bin-row order.

weighted bool, default=False

Explicitly require a two-argument callback. If fitting weights are absent, the callback receives ones. Unweighted callbacks reject supplied weights.

Notes

Usually constructed with array_aggregation. No values are sorted, filtered, or imputed. Callback exceptions propagate. NaN marks unsupported results; infinity is rejected by Regressogram. This adapter inherits sklearn get_params/set_params.

Methods

Method Purpose
call Apply the numeric callback to independent input copies.
get_metadata_routing Get metadata routing of this object.
get_params Get parameters for this estimator.
set_params Set the parameters of this estimator.

call

[source]
rgram.aggregation.ArrayAggregation.__call__(values, weights=None)

Apply the numeric callback to independent input copies.

Parameters

values array-like

Responses in one bin.

weights array-like or None, default=None

Paired influence weights. A weighted adapter uses ones when absent.

Returns

value float

One real scalar. Nonscalar, complex, and imprecisely converted integer callback results raise ValueError.

get_metadata_routing

[inherited API]
rgram.aggregation.ArrayAggregation.get_metadata_routing()

Get metadata routing of this object.

Please check metadata routing guide on how the routing mechanism works.

Returns

routing MetadataRequest

A sklearn.utils.metadata_routing.MetadataRequest encapsulating routing information.

get_params

[inherited API]
rgram.aggregation.ArrayAggregation.get_params(deep=True)

Get parameters for this estimator.

Parameters

deep bool, default=True

If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns

params dict

Parameter names mapped to their values.

set_params

[inherited API]
rgram.aggregation.ArrayAggregation.set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as sklearn.pipeline.Pipeline). The latter have parameters of the form <component>__<parameter> so that it's possible to update each component of a nested object.

Parameters

**params dict

Estimator parameters.

Returns

self estimator instance

Estimator instance.

rgram.aggregation.WeightedAggregation

[source]
class rgram.aggregation.WeightedAggregation(
    func,
)

Adapt a native Polars weighted reduction.

Parameters

func callable

Function accepting (values_expr, weights_expr) and returning one scalar reduction as a Polars expression. Usually use weighted_aggregation.

Notes

Without supplied weights, nonmissing values receive unit weights. The adapter inherits sklearn get_params/set_params and is cloneable.

Methods

Method Purpose
call Build the weighted Polars reduction expression.
get_metadata_routing Get metadata routing of this object.
get_params Get parameters for this estimator.
set_params Set the parameters of this estimator.

call

[source]
rgram.aggregation.WeightedAggregation.__call__(values, weights=None)

Build the weighted Polars reduction expression.

Parameters

values polars.Expr

Expression selecting bin responses.

weights polars.Expr or None, default=None

Weight expression. None gives unit weights for nonmissing values.

Returns

expression polars.Expr

The expression returned by func; Regressogram checks the result type.

get_metadata_routing

[inherited API]
rgram.aggregation.WeightedAggregation.get_metadata_routing()

Get metadata routing of this object.

Please check metadata routing guide on how the routing mechanism works.

Returns

routing MetadataRequest

A sklearn.utils.metadata_routing.MetadataRequest encapsulating routing information.

get_params

[inherited API]
rgram.aggregation.WeightedAggregation.get_params(deep=True)

Get parameters for this estimator.

Parameters

deep bool, default=True

If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns

params dict

Parameter names mapped to their values.

set_params

[inherited API]
rgram.aggregation.WeightedAggregation.set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as sklearn.pipeline.Pipeline). The latter have parameters of the form <component>__<parameter> so that it's possible to update each component of a nested object.

Parameters

**params dict

Estimator parameters.

Returns

self estimator instance

Estimator instance.

rgram.aggregation.Quantile

[source]
class rgram.aggregation.Quantile(
    q,
    *,
    interpolation='linear',
)

Cloneable Polars quantile reduction with explicit interpolation.

Parameters

q float

Quantile probability in [0, 1], excluding booleans.

interpolation str, default='linear'

One of nearest, higher, lower, midpoint, linear, equiprobable. Passed directly to Polars quantile.

Notes

Usually constructed with quantile. Observation weights are unsupported; choose an explicit weighted adapter if you require weighted quantiles. Inherits sklearn get_params/set_params.

Methods

Method Purpose
call Build an unweighted quantile expression.
get_metadata_routing Get metadata routing of this object.
get_params Get parameters for this estimator.
set_params Set the parameters of this estimator.

call

[source]
rgram.aggregation.Quantile.__call__(values)

Build an unweighted quantile expression.

Parameters

values polars.Expr

Expression selecting bin responses.

Returns

expression polars.Expr

Quantile reduction with the configured probability and interpolation.

Raises

ValueError

If q or interpolation is invalid.

get_metadata_routing

[inherited API]
rgram.aggregation.Quantile.get_metadata_routing()

Get metadata routing of this object.

Please check metadata routing guide on how the routing mechanism works.

Returns

routing MetadataRequest

A sklearn.utils.metadata_routing.MetadataRequest encapsulating routing information.

get_params

[inherited API]
rgram.aggregation.Quantile.get_params(deep=True)

Get parameters for this estimator.

Parameters

deep bool, default=True

If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns

params dict

Parameter names mapped to their values.

set_params

[inherited API]
rgram.aggregation.Quantile.set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as sklearn.pipeline.Pipeline). The latter have parameters of the form <component>__<parameter> so that it's possible to update each component of a nested object.

Parameters

**params dict

Estimator parameters.

Returns

self estimator instance

Estimator instance.

A callback may transform its independent input copies, but Rgram adds no sorting or filtering around it. Named reducers and adapters with importable top-level callbacks can be pickled. Lambdas and closures may not work with standard pickle.

Implementation source: aggregation.py.