### Install popsregression via pip

Source: https://pops-uq.github.io/popsregression

Use this command to install the package. Requires Python 3.9 or higher.

```bash
pip install popsregression
```

--------------------------------

### Configure resampling_method

Source: https://pops-uq.github.io/popsregression/usage

Example of setting the resampling method and density for the hypercube posterior. Quasi-random methods like 'sobol' provide more even coverage than 'uniform'.

```python
model = POPSRegression(resampling_method="sobol", resample_density=10.0)
```

--------------------------------

### Pipeline and GridSearchCV usage

Source: https://pops-uq.github.io/popsregression/usage

Example showing how to integrate POPSRegression into a scikit-learn pipeline with PolynomialFeatures and perform hyperparameter search using GridSearchCV.

```APIDOC
## Pipeline and GridSearchCV usage

### Description
Demonstrates how to use POPSRegression within a scikit-learn pipeline and perform model selection with GridSearchCV.

### Code Example
```python
from sklearn.model_selection import GridSearchCV
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import PolynomialFeatures

pipe = make_pipeline(
    PolynomialFeatures(degree=4),
    POPSRegression(resampling_method="sobol"),
)
pipe.fit(X_train, y_train)
y_pred = pipe.predict(X_test)

search = GridSearchCV(
    pipe,
    {
        "polynomialfeatures__degree": [2, 3, 4],
        "popsregression__posterior": ["hypercube", "ensemble"],
    },
)
search.fit(X_train, y_train)
```

### Notes
- `predict` inside a pipeline returns the mean only.
- To obtain uncertainty outputs, call the estimator step directly: `pipe[-1].predict(X_transformed, return_std=True)`.
```

--------------------------------

### popsregression.__version__

Source: https://pops-uq.github.io/popsregression/api

Installed package version attribute.

```APIDOC
## popsregression.__version__

### Description
Installed package version attribute.

### Usage
import popsregression
print(popsregression.__version__)

```

--------------------------------

### Configure minimum_relative_error

Source: https://pops-uq.github.io/popsregression/usage

Examples of setting the minimum_relative_error parameter to control training point selection. A value of 0.0 keeps all points, while higher values discard points that are well-fit by the model.

```python
# Discard points fit a hundred times better than the typical point (default)
model = POPSRegression(minimum_relative_error=0.01)

# Keep every training point
model = POPSRegression(minimum_relative_error=0.0)

# Aggressive: keep only points fit worse than half the RMSE
model = POPSRegression(minimum_relative_error=0.5)
```

--------------------------------

### Initialize and fit POPSRegression

Source: https://pops-uq.github.io/popsregression

Demonstrates importing the estimator, fitting the model, and generating predictions with standard deviation.

```python
from popsregression import POPSRegression

X_train, X_test, y_train, y_test = ...

# fit_intercept=False by default
model = POPSRegression()
model.fit(X_train, y_train)

# Combined misspecification + epistemic standard deviation
y_pred, y_std = model.predict(X_test, return_std=True)
```

--------------------------------

### Run development and testing commands

Source: https://pops-uq.github.io/popsregression

Commands for running tests, linting, and building documentation during development.

```bash
pytest -vsl popsregression   # tests

pixi run test                # or, with pixi
pixi run lint
pixi run build-doc
```

--------------------------------

### Fit POPSRegression and BayesianRidge at increasing training sizes

Source: https://pops-uq.github.io/popsregression/example

Loops over N = 10, 30, 500 training points, generating deterministic data, fitting both models, and computing predictions and uncertainties. POPS uses sobol resampling with density 10.0 and returns combined std and min/max bounds; BayesianRidge uses fit_intercept=False and computes epistemic-only std from sigma_.

```python
from sklearn.linear_model import BayesianRidge
from sklearn.preprocessing import PolynomialFeatures

from popsregression import POPSRegression

for n_samples in [10, 30, 500]:
    # Generate training data (no noise — purely deterministic)
    x_train = np.sort(
        np.append(rng.uniform(-1, 1, n_samples), np.linspace(-1, 1, 2)) * 10
    )
    y_train = target_function(x_train)

    poly = PolynomialFeatures(degree=4, include_bias=True)
    X_train = poly.fit_transform(x_train.reshape(-1, 1))
    X_test = poly.fit_transform(x_test.reshape(-1, 1))

    # POPS Regression: mean, combined std, and min/max posterior bounds
    pops = POPSRegression(resampling_method="sobol", resample_density=10.0)
    pops.fit(X_train, y_train)
    y_pred, y_std, y_max, y_min = pops.predict(
        X_test, return_std=True, return_bounds=True
    )

    # BayesianRidge (epistemic uncertainty only, excluding aleatoric alpha_)
    br = BayesianRidge(fit_intercept=False)
    br.fit(X_train, y_train)
    br_pred = br.predict(X_test)
    br_epistemic_std = np.sqrt(np.sum(np.dot(X_test, br.sigma_) * X_test, axis=1))
```

--------------------------------

### POPSRegression basic usage

Source: https://pops-uq.github.io/popsregression/api

Demonstrates initializing the POPSRegression model, fitting it to synthetic data, and performing a prediction.

```python
>>> import numpy as np
>>> from popsregression import POPSRegression
>>> rng = np.random.RandomState(0)
>>> X = np.array([[1, 1], [1, 2], [2, 2], [2, 3]])
>>> y = np.dot(X, np.array([1, 2])) + 0.01 * rng.randn(4)
>>> reg = POPSRegression()
>>> reg.fit(X, y)
POPSRegression()
>>> reg.predict(np.array([[3, 5]]))
array([...])
```

--------------------------------

### Import POPSRegression

Source: https://pops-uq.github.io/popsregression/api

Import the main estimator class from the popsregression package.

```python
from popsregression import POPSRegression
```

--------------------------------

### POPSRegression constructor

Source: https://pops-uq.github.io/popsregression/api

The constructor for the POPSRegression estimator, which includes parameters for BayesianRidge convergence, prior distributions, and POPS-specific uncertainty estimation settings.

```python
POPSRegression(
    *,
    max_iter=300,
    tol=0.001,
    alpha_1=1e-06,
    alpha_2=1e-06,
    lambda_1=1e-06,
    lambda_2=1e-06,
    alpha_init=None,
    lambda_init=None,
    compute_score=False,
    fit_intercept=False,
    copy_X=True,
    verbose=False,
    mode_threshold=1e-08,
    resample_density=1.0,
    resampling_method="uniform",
    percentile_clipping=0.0,
    minimum_relative_error=0.01,
    posterior="hypercube",
    leverage_percentile="deprecated"
)
```

--------------------------------

### Fit POPSRegression with sample weights

Source: https://pops-uq.github.io/popsregression/usage

Pass sample weights to fit; they are forwarded to the underlying BayesianRidge fit and to the preprocessing used for POPS corrections.

```python
model.fit(X_train, y_train, sample_weight=w)

```

--------------------------------

### POPSRegression constructor

Source: https://pops-uq.github.io/popsregression/usage

The POPSRegression class constructor accepts all BayesianRidge parameters plus POPS-specific parameters. This snippet shows how to instantiate the model with various parameter combinations.

```APIDOC
## POPSRegression

### Description
Creates a POPSRegression model. All BayesianRidge parameters (max_iter, tol, alpha_1, alpha_2, lambda_1, lambda_2, alpha_init, lambda_init, compute_score, fit_intercept, copy_X, verbose) are accepted and forwarded. POPS-specific parameters control the posterior construction and sampling.

### Parameters
- **posterior** (string) - Optional - Default: 'hypercube' - 'hypercube' fits a PCA-aligned box to the pointwise corrections and resamples it; 'ensemble' uses the raw corrections as samples.
- **minimum_relative_error** (float) - Optional - Default: 0.01 - Relative residual threshold for selecting training points.
- **resampling_method** (string) - Optional - Default: 'uniform' - 'uniform', 'sobol', 'latin' or 'halton'; hypercube posterior only.
- **resample_density** (float) - Optional - Default: 1.0 - Posterior samples per training point; the count is floored at 100.
- **percentile_clipping** (float) - Optional - Default: 0.0 - Percentile trimmed from each end of the hypercube bounds, in [0, 50].
- **mode_threshold** (float) - Optional - Default: 1e-8 - Relative eigenvalue cutoff setting the effective dimension of the hypercube.

### Example
```python
# Discard points fit a hundred times better than the typical point (default)
model = POPSRegression(minimum_relative_error=0.01)

# Keep every training point
model = POPSRegression(minimum_relative_error=0.0)

# Aggressive: keep only points fit worse than half the RMSE
model = POPSRegression(minimum_relative_error=0.5)

# Use sobol resampling
model = POPSRegression(resampling_method="sobol", resample_density=10.0)
```
```

--------------------------------

### fit(X, y, sample_weight=None)

Source: https://pops-uq.github.io/popsregression/api

Fit the POPS regression model to the training data. This method trains the model on the provided features and target values, optionally with sample weights.

```APIDOC
## fit(X, y, sample_weight=None)

### Description
Fit the POPS regression model.

### Method
fit

### Parameters
- **X** (array-like of shape (n_samples, n_features)) - Required - Training data.
- **y** (array-like of shape (n_samples,)) - Required - Target values.
- **sample_weight** (array-like of shape (n_samples,)) - Optional - Individual weights for each sample. Default: None

### Returns
- **self** (object) - Returns the instance itself.
```

--------------------------------

### Compare posterior types: ensemble and hypercube

Source: https://pops-uq.github.io/popsregression/example

Loops over the two posterior forms ('ensemble' and 'hypercube') with uniform resampling, density 10.0, and minimum_relative_error=0.0 to keep all training points in the posterior estimate.

```python
for posterior in ["ensemble", "hypercube"]:
    pops = POPSRegression(
        posterior=posterior,
        resampling_method="uniform",
        resample_density=10.0,
        minimum_relative_error=0.0,
    )
    pops.fit(X_train, y_train)
    y_pred, y_std, y_max, y_min = pops.predict(
        X_test, return_std=True, return_bounds=True
    )
```

--------------------------------

### POPSRegression configuration

Source: https://pops-uq.github.io/popsregression/usage

Configuration options for POPSRegression, including fit_intercept handling and sample weights.

```APIDOC
## POPSRegression configuration

### Description
Configuration options for POPSRegression, including fit_intercept handling and sample weights.

### fit_intercept
- Default: False
- When set to True, a constant column is appended to X (rather than centering the data) so that the intercept participates in the POPS posterior and carries its own misspecification uncertainty. The same column is appended automatically at prediction time.
- If the design matrix already contains a bias column (e.g., PolynomialFeatures(include_bias=True)), keep fit_intercept=False.

### Example
```python
model = POPSRegression(fit_intercept=True)
```

### Sample weights
Weights are passed through to the underlying BayesianRidge fit and to the preprocessing used for the POPS corrections.

### Example
```python
model.fit(X_train, y_train, sample_weight=w)
```
```

--------------------------------

### predict(X, return_std=False, return_bounds=False, return_epistemic_std=False)

Source: https://pops-uq.github.io/popsregression/api

Predict using the POPS regression model. In addition to the standard return_std from BayesianRidge, this method can return prediction bounds (min/max over the posterior) and epistemic-only uncertainty.

```APIDOC
## predict(X, return_std=False, return_bounds=False, return_epistemic_std=False)

### Description
Predict using the POPS regression model. In addition to the standard return_std from BayesianRidge, this method can return prediction bounds (min/max over the posterior) and epistemic-only uncertainty.

### Method
predict

### Parameters
- **X** (array-like of shape (n_samples, n_features)) - Required - Samples to predict for.
- **return_std** (bool) - Optional - If True, return the combined (misspecification + epistemic) standard deviation. Default: False
- **return_bounds** (bool) - Optional - If True, return the max and min predictions over the POPS posterior samples. Default: False
- **return_epistemic_std** (bool) - Optional - If True, return the epistemic-only standard deviation (from sigma_, excluding misspecification). Default: False

### Returns
- **y_mean** (ndarray of shape (n_samples,)) - Predicted mean values.
- **y_std** (ndarray of shape (n_samples,)) - Combined standard deviation. Only returned if return_std=True.
- **y_max** (ndarray of shape (n_samples,)) - Upper bound from posterior samples. Only returned if return_bounds=True.
- **y_min** (ndarray of shape (n_samples,)) - Lower bound from posterior samples. Only returned if return_bounds=True.
- **y_epistemic_std** (ndarray of shape (n_samples,)) - Epistemic-only standard deviation. Only returned if return_epistemic_std=True.
```

--------------------------------

### Integrate POPSRegression with scikit-learn pipelines and GridSearchCV

Source: https://pops-uq.github.io/popsregression/usage

Demonstrates using POPSRegression within a scikit-learn pipeline and performing hyperparameter optimization with GridSearchCV. Note that pipeline predict calls return the mean only; use the estimator step directly for uncertainty outputs.

```python
from sklearn.model_selection import GridSearchCV
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import PolynomialFeatures

pipe = make_pipeline(
    PolynomialFeatures(degree=4),
    POPSRegression(resampling_method="sobol"),
)
pipe.fit(X_train, y_train)
y_pred = pipe.predict(X_test)

search = GridSearchCV(
    pipe,
    {
        "polynomialfeatures__degree": [2, 3, 4],
        "popsregression__posterior": ["hypercube", "ensemble"],
    },
)
search.fit(X_train, y_train)
```

--------------------------------

### Fit POPSRegression with scikit-learn API

Source: https://pops-uq.github.io/popsregression/usage

Construct a POPSRegression model and fit it on an explicit design matrix X_train and target y_train. The estimator expects features to be pre-generated; use PolynomialFeatures or a pipeline for polynomial fits.

```python
import numpy as np
from popsregression import POPSRegression

model = POPSRegression()
model.fit(X_train, y_train)      # X: (n_samples, n_features), y: (n_samples,)

```

--------------------------------

### POPSRegression.fit(X, y)

Source: https://pops-uq.github.io/popsregression/api

Fits the POPSRegression model to the training data. This method estimates the posterior distribution of the weights and the noise precision.

```APIDOC
## POPSRegression.fit(X, y)

### Description
Fits the POPSRegression model to the training data. This method estimates the posterior distribution of the weights and the noise precision.

### Method
fit

### Parameters
- **X** (array-like of shape (n_samples, n_features)) - Required - Training data.
- **y** (array-like of shape (n_samples,)) - Required - Target values.

### Returns
- **self** (POPSRegression) - The fitted estimator.

### Example
```python
>>> import numpy as np
>>> from popsregression import POPSRegression
>>> rng = np.random.RandomState(0)
>>> X = np.array([[1, 1], [1, 2], [2, 2], [2, 3]])
>>> y = np.dot(X, np.array([1, 2])) + 0.01 * rng.randn(4)
>>> reg = POPSRegression()
>>> reg.fit(X, y)
POPSRegression()
```
```

--------------------------------

### Define target function and test data

Source: https://pops-uq.github.io/popsregression/example

Creates a misspecified target function that a 4th-degree polynomial cannot perfectly reproduce, and generates test points over the range [-11, 11].

```python
import numpy as np

rng = np.random.RandomState(42)


def target_function(x):
    return (x**3 + 0.01 * x**4) * 0.1 + np.sin(x) * x * 10.0


x_test = np.linspace(-11, 11, 200)
y_test = target_function(x_test)
```

--------------------------------

### Predict with POPSRegression and return flags

Source: https://pops-uq.github.io/popsregression/usage

predict returns the mean by default. Each flag appends further arrays in a fixed order: y_mean, y_std, y_max, y_min, y_epistemic_std. With no flags, a single array is returned instead of a tuple.

```python
y_pred = model.predict(X_test)

```

```python
y_pred, y_std = model.predict(X_test, return_std=True)

```

```python
y_pred, y_std, y_max, y_min = model.predict(
    X_test, return_std=True, return_bounds=True
)

```

```python
y_pred, y_std, y_max, y_min, y_epistemic_std = model.predict(
    X_test,
    return_std=True,
    return_bounds=True,
    return_epistemic_std=True,
)

```

--------------------------------

### POPSRegression.fit

Source: https://pops-uq.github.io/popsregression/usage

Fit the POPSRegression model to training data. The estimator expects an explicit design matrix X and target vector y. Optional sample weights can be provided.

```APIDOC
## POPSRegression.fit

### Description
Fit the POPSRegression model to the training data. The estimator follows the scikit-learn API and expects an explicit design matrix.

### Method
fit

### Signature
model.fit(X_train, y_train, sample_weight=None)

### Parameters
- **X_train** (array-like) - Required - Training data of shape (n_samples, n_features).
- **y_train** (array-like) - Required - Target values of shape (n_samples,).
- **sample_weight** (array-like) - Optional - Sample weights passed to the underlying BayesianRidge fit and preprocessing.

### Example
```python
import numpy as np
from popsregression import POPSRegression

model = POPSRegression()
model.fit(X_train, y_train)
```
```

--------------------------------

### POPSRegression.predict(X)

Source: https://pops-uq.github.io/popsregression/api

Predicts target values for new input samples using the fitted model.

```APIDOC
## POPSRegression.predict(X)

### Description
Predicts target values for new input samples using the fitted model.

### Method
predict

### Parameters
- **X** (array-like of shape (n_samples, n_features)) - Required - Input samples.

### Returns
- **y_pred** (array-like of shape (n_samples,)) - Predicted target values.

### Example
```python
>>> reg.predict(np.array([[3, 5]]))
array([...])
```
```

--------------------------------

### POPSRegression

Source: https://pops-uq.github.io/popsregression/api

Bayesian regression for low-noise data with misspecification uncertainty. Fits a linear model using BayesianRidge and estimates weight uncertainties accounting for model misspecification using the POPS algorithm.

```APIDOC
## POPSRegression

### Description
Bayesian regression for low-noise data with misspecification uncertainty. Fits a linear model using BayesianRidge, then estimates weight uncertainties accounting for model misspecification using the POPS (Pointwise Optimal Parameter Sets) algorithm. Unlike standard Bayesian regression, the aleatoric noise precision alpha_ is not used for predictions, as it should be negligible in the low-noise regime.

### Constructor
POPSRegression(*, max_iter=300, tol=0.001, alpha_1=1e-06, alpha_2=1e-06, lambda_1=1e-06, lambda_2=1e-06, alpha_init=None, lambda_init=None, compute_score=False, fit_intercept=False, copy_X=True, verbose=False, mode_threshold=1e-08, resample_density=1.0, resampling_method="uniform", percentile_clipping=0.0, minimum_relative_error=0.01, posterior="hypercube", leverage_percentile="deprecated")

### Parameters
- **max_iter** (int) - Default: 300 - Maximum number of iterations for the BayesianRidge convergence loop.
- **tol** (float) - Default: 1e-3 - Convergence threshold. Stop the algorithm if the coefficient vector has converged.
- **alpha_1** (float) - Default: 1e-6 - Shape parameter for the Gamma distribution prior over alpha_.
- **alpha_2** (float) - Default: 1e-6 - Inverse scale (rate) parameter for the Gamma distribution prior over alpha_.
- **lambda_1** (float) - Default: 1e-6 - Shape parameter for the Gamma distribution prior over lambda_.
- **lambda_2** (float) - Default: 1e-6 - Inverse scale (rate) parameter for the Gamma distribution prior over lambda_.
- **alpha_init** (float) - Default: None - Initial value for alpha_ (precision of the noise). If None, alpha_init is 1 / Var(y).
- **lambda_init** (float) - Default: None - Initial value for lambda_ (precision of the weights). If None, lambda_init is 1.
- **compute_score** (bool) - Default: False - If True, compute the log marginal likelihood at each step.
- **fit_intercept** (bool) - Default: False - Whether to fit an intercept. If True, a constant column is appended to X (rather than centering) so that the intercept participates in the POPS posterior estimation.
- **copy_X** (bool) - Default: True - If True, X will be copied; else, it may be overwritten.
- **verbose** (bool) - Default: False - Verbose mode when fitting the model.
- **mode_threshold** (float) - Default: 1e-8 - Eigenvalue threshold (relative to max) for determining the effective dimensionality of the POPS posterior. Eigenvalues below mode_threshold * max_eigenvalue are discarded.
- **resample_density** (float) - Default: 1.0 - Number of resampled points per training point. The actual number of samples is max(100, int(resample_density * n_samples)).
- **resampling_method** (uniform, sobol, latin, halton) - Default: 'uniform' - Quasi-random sampling method for generating points within the POPS hypercube posterior.
- **percentile_clipping** (float) - Default: 0.0 - Percentile to clip from each end when determining hypercube bounds. The hypercube spans the [percentile_clipping, 100 - percentile_clipping] range. Should be between 0 and 50.
- **minimum_relative_error** (float) - Default: 0.01 - Relative residual threshold for training point selection, in units of the root-mean-square error of the mean fit. Only training points whose residual satisfies |y - X @ coef_| >= minimum_relative_error * rmse contribute to the POPS posterior; a value of 0.01 thus discards points fit a hundred times better than the typical training point. Larger values accelerate fitting by focusing on the points the model fits worst, which are the ones that carry misspecification information. Use 0.0 to keep every training point. If no point passes the threshold, all points are used.
- **posterior** (hypercube, ensemble) - Default: 'hypercube' - Form of the POPS parameter posterior: 'hypercube' fit an axis-aligned box in PCA space (default); 'ensemble' use raw pointwise corrections directly.

### Usage Example
from popsregression import POPSRegression

```

--------------------------------

### Calculate minimum_relative_error threshold

Source: https://pops-uq.github.io/popsregression/usage

The threshold condition for a training point to contribute to the POPS posterior.

```text
|y - X @ coef_|  >=  minimum_relative_error * rmse
```

--------------------------------

### Inherited methods

Source: https://pops-uq.github.io/popsregression/api

POPSRegression subclasses BayesianRidge and inherits the standard scikit-learn estimator methods unchanged.

```APIDOC
## Inherited methods

### Description
POPSRegression subclasses BayesianRidge and inherits the standard scikit-learn estimator methods unchanged.

### Methods
- **get_params(deep=True)** - Parameters of this estimator
- **set_params(**params)** - Set parameters of this estimator
- **score(X, y, sample_weight=None)** - Coefficient of determination R² of the prediction
- **get_metadata_routing()** - Metadata routing of this object

### Notes
score uses the mean prediction only; uncertainty outputs are available through predict.
```

--------------------------------

### Set fit_intercept=True in POPSRegression

Source: https://pops-uq.github.io/popsregression/usage

When fit_intercept is True, a constant column is appended to X rather than centering the data, so the intercept participates in the POPS posterior. The same column is appended automatically at prediction time.

```python
model = POPSRegression(fit_intercept=True)

```

--------------------------------

### POPSRegression.predict

Source: https://pops-uq.github.io/popsregression/usage

Predict using the fitted model. Returns the posterior mean by default. Additional flags append arrays for standard deviation, bounds, and epistemic uncertainty in a fixed order.

```APIDOC
## POPSRegression.predict

### Description
Predict using the fitted model. Returns the posterior mean by default. Additional flags append arrays for standard deviation, bounds, and epistemic uncertainty in a fixed order.

### Method
predict

### Signature
model.predict(X_test, return_std=False, return_bounds=False, return_epistemic_std=False)

### Parameters
- **X_test** (array-like) - Required - Test data of shape (n_samples, n_features).
- **return_std** (bool) - Optional - If True, appends y_std (combined misspecification + epistemic standard deviation).
- **return_bounds** (bool) - Optional - If True, appends y_max and y_min (upper and lower envelope over POPS posterior samples).
- **return_epistemic_std** (bool) - Optional - If True, appends y_epistemic_std (epistemic-only standard deviation from sigma_).

### Returns
- **y_mean** (array) - Posterior mean prediction.
- **y_std** (array) - Combined misspecification + epistemic standard deviation (if return_std=True).
- **y_max** (array) - Upper envelope over POPS posterior samples (if return_bounds=True).
- **y_min** (array) - Lower envelope over POPS posterior samples (if return_bounds=True).
- **y_epistemic_std** (array) - Epistemic-only standard deviation (if return_epistemic_std=True).

The order is always y_mean, y_std, y_max, y_min, y_epistemic_std, with omitted entries dropped. With no flags set, a single array is returned rather than a tuple.

### Example
```python
y_pred = model.predict(X_test)

y_pred, y_std = model.predict(X_test, return_std=True)

y_pred, y_std, y_max, y_min = model.predict(
    X_test, return_std=True, return_bounds=True
)

y_pred, y_std, y_max, y_min, y_epistemic_std = model.predict(
    X_test,
    return_std=True,
    return_bounds=True,
    return_epistemic_std=True,
)
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.