Rgram
Skip to content
RgramStatistical parameters

Statistical parameter reference

This guide explains the statistical meaning, defaults and practical effects of Rgram's parameters. The quick start provides introductory examples, and the advanced guide describes implementation contracts. Ordinary fits use all supplied rows. Cross-validation and bootstrap resampling run only when explicitly requested, and neither estimator sorts client observations or query rows.

Rgram is primarily intended to explore one numeric feature-response relationship at a time. Its univariate scope is intentional: choose a feature and response, inspect their fitted curve and local support, and repeat for other features or explicitly selected subgroups. Each curve summarizes a pairwise association without adjusting for other variables or modeling interactions. Multivariate prediction is outside the current scope.

The quantities being estimated

A regressogram partitions the feature x into bins and calculates one statistic of the response y per bin. With agg="mean", it estimates a piecewise-constant regression mean. Other aggregations change the target: a median estimates a central response, a quantile estimates a response percentile, and a sum estimates a bin total. A sum or count is sensitive to bin occupancy and is not a conditional mean.

A kernel smoother combines nearby responses with distance-dependent weights. With regression="local_constant", its prediction is sum(w_i * y_i) / sum(w_i), where w_i = sample_weight_i * K((x_i - query) / h) and h is the fitted bandwidth. Local-linear regression instead fits a weighted line around each query and returns its value at that query.

More bins or a smaller bandwidth usually allow more detail but make estimates more sensitive to sample noise. Fewer bins or a larger bandwidth pool more observations and can hide real changes. These are modeling choices rather than data-cleaning operations.

Training inputs and observation weights

Parameter Meaning and consequences
X This is the single numeric explanatory feature. Its units determine the units of bin width and kernel bandwidth. Rescaling it requires corresponding changes to manually specified widths.
y This is the numeric response to summarize or predict. Predictions from a mean, median or quantile remain in its units; variance is in squared response units.
data=None Supply a pandas DataFrame, Polars DataFrame or LazyFrame to select x and y by column name. This changes input selection, not the statistical model.
sample_weight=None By default every observation has equal weight. Supplied finite, nonnegative weights express relative influence during fitting; at least one must be positive. Zero-weight observations remain in stored data and row counts. Weights do not automatically define survey inference or replicate observations.

For regressograms, a weighted mean divides the weighted response total by total weight, while a weighted sum does not divide. Multiplying every weight by the same positive constant therefore leaves a weighted mean unchanged but scales a weighted sum. Other named aggregations reject supplied weights; define their convention explicitly with a weighted callback. The smoother normalizes weights, so a common positive weight scale leaves predictions unchanged. Automatic bin boundaries and bandwidth rules use feature values without observation weighting, including features belonging to zero-weight rows.

Regressogram parameters

Parameter and default What it does and how to interpret it
binning="dist" "dist" uses feature quantiles to seek roughly equal observation counts per cell, so widths vary. Ties can prevent equal counts and reduce the number of cells. "width" uses equally spaced boundaries. "none" groups identical feature values. "int" groups by truncation toward zero, so -1.8 belongs to group -1; stored features remain unchanged.
agg="mean" This selects the response statistic calculated within each bin. Choose a supported name, a native Polars expression callback, or an explicit numeric callback adapter. The result must be one real numeric scalar per bin.
ci=None This optionally supplies two aggregations for descriptive lower and upper endpoints. For example, ci=(quantile(0.1), quantile(0.9)) describes the bin's central response spread. These endpoints are not automatically confidence limits, and Rgram does not sort or statistically calibrate arbitrary endpoint functions.
n_bins=None For "dist" and "width", None is the same as "auto". A positive integer requests a fixed count; named rules are explained below. "cv" explicitly requests held-out prediction-error selection. This parameter does not apply to "none" or "int".
bin_width=None Set a positive width in feature units with binning="width" and n_bins=None. Boundaries start at the training minimum; the final cell can cover a shorter part of the observed range. Smaller widths provide finer resolution and can create empty cells.
max_bins=512 This bounds allocation for width/dist binning. Automatic counts are capped with a warning. Excessive explicit counts or manual widths requiring too many cells raise. Increasing the limit permits more detail and memory use; it does not improve accuracy by itself.
min_samples_bin=5 This limits the default distribution-bin count to at most max(1, n // min_samples_bin) and also limits the automatically generated CV candidate range. It is a count-selection heuristic, not a guarantee that every bin contains this many observations. It does not enforce a minimum for explicit counts, other named rules or width-auto selection.
cv=5 This controls validation folds only when n_bins="cv". An integer uses shuffled K-fold membership. A splitter or explicit train/test index iterable defines a different validation design. More folds require more fits and do not guarantee a better model.
bin_candidates=None For n_bins="cv", supply positive integer counts to compare. By default, up to 12 approximately geometrically spaced counts are generated between 1 and min(max_bins, max(1, n // min_samples_bin)). Candidate counts can still be reduced by ties during fitting.
random_state=0 This seeds the shuffled integer-fold CV design. It has no effect on an ordinary fit and does not configure a separately supplied splitter's randomness.
extrapolation="clip" Outside the training feature range, eligible binning modes use an edge-bin assignment and warn; the query coordinate is not changed. "nan" returns missing estimates and "raise" rejects the query. Exact-value grouping with binning="none" still has no estimate for unseen values.
unsupported="nan" Empty cells, undefined zero-weight means and nonfinite estimates produce NaN with a warning. "raise" rejects unsupported predictions instead. Every query retains its position when predictions are returned.

Bin-count rules

Here n is the number of training rows, R is the feature range, IQR is its interquartile range and ceil rounds upward. Width-derived counts are ceil(R / width) before the documented caps and boundary handling. Named count rules can also be used with distribution binning; in that case they choose the count while feature quantiles still determine the boundaries.

n_bins choice Calculation and interpretation
None or "auto", with binning="dist" Start with ceil(n**(1/3)), then apply the average-occupancy and count limits. This is a feature-only heuristic for quantile bins, not an optimization against y.
None or "auto", with binning="width" Use the larger Freedman-Diaconis or Sturges count. This balances a feature-spread rule with a sample-size rule.
"fd" Freedman-Diaconis uses width 2 * IQR / n**(1/3). Its scale uses the middle half of the features, although the full feature range still affects the resulting count.
"scott" Scott uses width std(x, ddof=0) * (24 * sqrt(pi) / n)**(1/3). Unlike the IQR rule, its scale is sensitive to extreme feature values. This is a histogram-width rule, distinct from the kernel bandwidth rule with the same name.
"sturges" Use ceil(log2(n) + 1). The count grows slowly and does not adapt to feature spread or response structure.
"sqrt" Use ceil(sqrt(n)). This simple sample-size rule ignores feature spread and response structure.
"rice" Use ceil(2 * n**(1/3)). This is another sample-size-only rule.
"cv" Compare candidate counts using held-out, unweighted mean squared prediction error with full prediction coverage required in every fold. This is the only built-in count choice that evaluates responses during selection.

Constant features produce one cell. Zero-width spread rules fall back to Sturges for nonconstant features. Automatic counts are limited by the sample count and max_bins; explicit distribution counts cannot exceed the sample count after adjustment. Repeated quantile boundaries may reduce the fitted count, with a warning. Inspect n_bins_, bin_edges_ and bins_ to see the actual partition. The standard histogram formulas are also described in the NumPy reference; the distribution-auto heuristic and fallback policies above describe Rgram's implementation.

Aggregation and quantile parameters

Choice or parameter Statistical meaning
"mean" This is the arithmetic average, or weighted average when weights are supplied. It responds to extreme response values.
"median" This is the middle response value, averaging the two middle values when needed. It is less sensitive to extreme response magnitudes than the mean.
"min" and "max" These return the observed response extremes in each bin. They describe sample extremes, not population bounds.
"sum" and "count" These return the response total and observation count respectively. Count includes zero-weight rows when used without supplied weights; named count rejects supplied weights to avoid an ambiguous convention.
"std" and "var" These use sample standard deviation and variance with denominator n_bin - 1. A singleton bin cannot supply that estimate. They describe response dispersion, not the standard error of a fitted mean.
"first" and "last" These select responses by original within-bin row order. Reordering the input can intentionally change these statistics.
array_aggregation(func, weighted=False) func(values) receives copied NumPy values and returns a scalar. The weighted flag defaults to False. With weighted=True, it receives (values, weights) and must implement the desired weighting convention. Missing supplied weights become ones.
weighted_aggregation(func) func(values_expr, weights_expr) receives two Polars expressions and returns a scalar reduction expression. It defines the weighted statistic explicitly.
quantile(q, interpolation="linear") q ranges from 0 to 1: 0.5 is a median and 0.9 is the 90th percentile. This helper is unweighted. interpolation specifies how a percentile falls between observed response values; it is not interpolation between feature bins.

For the quantile helper, "linear" blends the neighboring ordered responses at fractional rank q * (n_bin - 1). "lower" and "higher" select the lower or upper rank, "nearest" selects the nearest rank, and "midpoint" averages the neighboring responses. "equiprobable" selects the empirical inverse-CDF rank, corresponding to ceil(n_bin * q) - 1 clipped to valid zero-based indices. These choices can differ substantially in small bins. Computing an order statistic may order temporary values; it never reorders the client's observation records.

Aggregation helper classes

The helpers above construct configurable callable objects. You can also instantiate their classes directly from rgram.aggregation. Every constructor setting is listed here; the same meanings apply to the corresponding factory function.

Class Setting and default Effect
ArrayAggregation func (required) Numeric reducer called with a copied NumPy response array; it must return one real scalar.
ArrayAggregation weighted=False With False, call func(values). With True, call func(values, weights) and implement weighting explicitly; absent observation weights are replaced by ones.
WeightedAggregation func (required) Native reducer called with response and weight Polars expressions; return a scalar reduction expression that implements your weighting convention.
Quantile q (required) Response percentile as a fraction in [0, 1]; 0.5 gives a median. This reducer is unweighted.
Quantile interpolation="linear" Choose how fractional ranks are resolved using the interpolation options explained above. This affects response percentiles within a bin.

For example, quantile(0.9) constructs Quantile(q=0.9), and array_aggregation(func, weighted=True) constructs ArrayAggregation(func=func, weighted=True). The objects support estimator parameter inspection and cloning, including nested settings such as agg__q. See the aggregation reference for executable examples.

KernelSmoother parameters

Parameter and default What it does and how to interpret it
bandwidth="silverman" Choose "silverman" or "scott" for a feature-only rule, or "manual" to supply a width. These rules do not optimize regression prediction error or perform CV.
bandwidth_value=None With bandwidth="manual", provide a finite positive width in feature units. It is unused by the automatic rules. For a compact kernel, this is the support radius before multiplying by bandwidth_adjust.
bandwidth_adjust=1.0 Multiply the selected width by this finite positive factor. A value of 2 doubles the bandwidth; 0.5 halves it. It applies to manual and automatic widths. Refit after changing it.
kernel="epanechnikov" This chooses the distance-to-weight function listed below. The same numeric bandwidth can produce different weight concentration for different kernels. A custom callable receives a Polars expression of signed normalized distances and must return one finite, nonnegative weight per distance.
regression="local_constant" "local_constant" computes a weighted average. "local_linear" fits a local slope as well, allowing linear trends near a boundary but potentially producing negative prediction coefficients and predictions outside the observed response range.
singular="constant" If a local-linear slope cannot be identified numerically, fall back to a local constant and warn. "raise" rejects that fallback. Too few distinct positively weighted feature values can cause this condition.
unsupported="nan" Queries without positive numerical kernel weight retain their rows with NaN predictions and a warning. "raise" fails instead. Narrow compact kernels are particularly likely to leave unsupported gaps.
extrapolation="allow" Evaluate the kernel at actual outside-range queries and warn. "nan" returns missing predictions and "raise" rejects them. A finite extrapolated prediction does not establish statistical reliability.
algorithm="auto" This is a computation setting. Already-sorted training features with a built-in compact kernel use exact neighbor windows; other inputs use brute force. "neighbors" requires eligible input, while "brute" forces dense blocks. No option sorts input, and both paths target the same estimate.
batch_size=128 This bounds the number of queries processed together by brute force, subject to an additional pair-count memory bound. It controls temporary memory, not statistical smoothness.
n_eval_samples=100 This controls the evenly spaced query count for predict_grid(). It increases plotting resolution, not training information or model complexity. It does not affect predict(x_eval).

Rgram's Silverman bandwidth is 0.9 * min(s, IQR / 1.34) * n**(-1/5), where s is sample standard deviation (ddof=1) and the IQR uses Polars' default nearest quantiles. A zero IQR uses positive s instead and warns. Scott uses 1.06 * s * n**(-1/5). Both then multiply by bandwidth_adjust. All feature rows contribute to these unweighted rules. Constant or singleton features require an explicit manual bandwidth. Inspect bandwidth_ for the final value.

Kernel choices

Let u = (x_i - query) / bandwidth_ and a = abs(u). These are proportional weight shapes; multiplicative normalization constants cancel when computing regression weights. Compact kernels have zero weight outside a <= 1.

Kernel Weight shape and practical effect
"epanechnikov" The shape is max(1 - u**2, 0). It decreases quadratically from the center to zero at the support boundary.
"uniform" Every observation with a <= 1 gets the same distance weight. An observation's influence changes abruptly when it enters or leaves the window.
"triangular" The shape is max(1 - a, 0). Influence decreases linearly with distance.
"cosine" The shape is cos(pi * u / 2) for a < 1, and zero elsewhere. It tapers continuously to the support boundary.
"biweight" The shape is (1 - u**2)**2 inside the support. It downweights near-boundary observations more strongly than Epanechnikov at the same bandwidth.
"tricube" The shape is (1 - a**3)**3 inside the support. It has a relatively flat center and tapers to zero at the edge.
"gaussian" The shape is exp(-u**2 / 2). Every finite distance has mathematical support, although extreme numerical tails can underflow. The bandwidth is a scale, not a cutoff radius.
"logistic" The shape is exp(-a) / (1 + exp(-a))**2. It has infinite mathematical support with slower-decaying tails than Gaussian.

Changing the kernel changes relative influence and may warrant changing bandwidth as well. No kernel is guaranteed to be best for every regression dataset. The interactive example examples/kernel_explorer.py lets you inspect the curve and weights together without altering the training rows.

Optional cross-validation parameters

CoverageSearchCV selects a parameter combination by pooled held-out mean squared error (MSE). MSE averages squared prediction errors, so large errors receive greater weight than small ones. Its scoring is unweighted even when fitting uses observation weights. Each fold must satisfy a separate prediction-coverage requirement, preventing an unsupported prediction from silently disappearing from model selection.

Parameter and default What it controls
estimator This is the model to clone for each candidate and fold. Candidate fits retain its support, extrapolation and error policies.
param_grid This maps estimator parameter names to candidate sequences, or supplies a list of such mappings. Combinations are compared exhaustively; more combinations multiply computation.
cv=5 An integer requests shuffled K-fold validation. Supply a group-aware splitter for grouped observations or a temporal splitter for time dependence. An iterable of explicit train/test indices is also accepted. Ordinary estimator fitting does not use this parameter unless a search is requested.
min_coverage=1.0 This is the minimum fraction of finite predictions required in every validation fold, in (0, 1]. Lowering it permits scoring only supported rows, which can favor a model that avoids difficult cases. It is not a confidence level.
random_state=0 This fixes integer-fold random membership for reproducibility. It does not seed supplied splitters or arbitrary randomness in the estimator.
groups=None, in fit Supply one group label per training row with an explicit group-aware splitter. Labels do not configure integer CV automatically; that combination raises.
sample_weight=None, in fit Weights are aligned and sliced with each training subset and passed to fitting. Validation MSE still gives each supported validation observation equal weight.

The winning estimator is refit on all rows in original order. best_score_ is negative MSE, so higher values are better; cv_results_["mean_test_mse"] is positive MSE, so lower values are better. Inspect coverage, min_fold_coverage, eligible and cv_splits_ alongside error. Search errors propagate, and an all-ineligible search raises. A selected model's validation score is not an independent final test score.

Bootstrap interval parameters

Both estimators expose predict_interval. Its target is the fitted curve statistic: a mean with mean aggregation, or the chosen alternative statistic. It returns pointwise confidence intervals, not intervals for individual future observations and not a simultaneous confidence band over the whole curve. A nominal 95% level describes intended repeated-sampling coverage under the inferential assumptions, not a guarantee for a particular fitted interval.

Parameter and default What it controls and what changes when increased
X These are the query locations where bounds are computed. More locations increase work and draw-storage memory; their order and duplicates are preserved.
confidence_level=0.95 Choose a number strictly between 0 and 1. For percentile intervals, 0.95 selects the 2.5th and 97.5th percentiles of bootstrap predictions. Increasing the level generally widens the interval.
n_resamples=200 This is the number of bootstrap refits, an integer of at least 2. Increasing it improves Monte Carlo stability and increases runtime and memory. It does not remove smoothing bias or repair inappropriate independence assumptions.
random_state=None An integer makes the resampling sequence reproducible. None leaves it unseeded. This seed is independent of an estimator's CV seed.
method="percentile" Use bootstrap prediction quantiles directly. "basic" reflects those quantiles around the original estimate: if quantiles are L and U, bounds are 2 * estimate - U and 2 * estimate - L. Basic bounds can lie outside the statistic's natural range.
resampling="iid" This resamples paired feature, response and weight rows with replacement and assumes independent observations from a random design. "groups" resamples whole groups; "blocks" resamples contiguous moving blocks in the original training order.
groups=None With resampling="groups", supply one nonmissing label per original training row and at least two distinct groups. Groups are the independent sampling units; rows within a group can be dependent. This option is rejected for other resampling modes.
block_size=None With resampling="blocks", supply an integer from 2 to n_samples - 1. Larger blocks retain longer within-block dependence but provide fewer blocks per resample. The caller must supply meaningfully ordered data; Rgram never sorts it. Stationarity and an appropriate dependence length matter.
min_valid_fraction=1.0 This sets the fraction of bootstrap draws that must produce finite predictions at a query, in (0, 1], with at least two valid draws required. Lowering it permits quantiles conditional on valid draws and changes the interpretation. It is distinct from both confidence level and CV coverage.

The bootstrap holds selected bandwidths and bin counts fixed, but refits regressogram boundaries on each draw. It does not include tuning uncertainty or correct smoothing bias. Unsupported draws remain counted in n_valid and bootstrap_coverage; insufficiently supported query bounds are NaN. Strict estimator errors still propagate. Resamples can be unsorted, so explicit neighbor-only evaluation can fail; algorithm="auto" accommodates this without sorting. Percentile and basic definitions are described in the SciPy bootstrap reference.

Prediction and diagnostic controls

Parameter or diagnostic Meaning
kind="prediction", in get_weights Return coefficients that combine training responses into predictions. "kernel" returns normalized nonnegative kernel/observation weights. Local-linear prediction coefficients can be negative; local-constant coefficients match kernel weights.
n_neighbors This counts training observations with positive numerical kernel/observation weight at a query. It does not count all observations within a radius if some have zero weight.
effective_n This is 1 / sum(normalized_kernel_weights**2). Equal weights on ten observations give 10; concentrated weights give a smaller value. It is a weight-concentration diagnostic, not degrees of freedom or a confidence interval.
supported and in_training_range These distinguish having a finite estimate from querying within the observed feature range. Neither is a measure of prediction accuracy.
local_linear_fallback This identifies queries that used a local constant because a local-linear slope was singular or numerically unresolved.

Warnings use Python's standard warning filters rather than statistical constructor parameters. Unsorted input warns by default but is not rearranged. Suppressing a warning changes message presentation only; it does not change the estimator, support policy or data handling.