Models

This page documents the models module.

---

ordboost.models

Ordinal Gradient Boosting Classifier compatible with scikit-learn.

OrdBoostClassifier

Bases: BaseEstimator, ClassifierMixin

Ordinal Gradient Boosting Classifier based on cumulative binary edge models.

Parameters:

Name	Type	Description	Default
loss	str	The loss function to use in the binary base estimator.	"log_loss"
learning_rate	float	The learning rate for gradient boosting.	0.1
max_iter	int	The maximum number of iterations (trees) for each binary classifier.	100
max_depth	int | None	The maximum depth of each tree.	None
min_samples_leaf	int	The minimum number of samples per leaf in binary trees.	20
l2_regularization	float	L2 regularization parameter for binary trees.	0.0
monotonicity	(running_max, isotonic)	Method used to enforce monotonicity across cumulative edge probabilities.	"running_max"
n_jobs	int	Number of parallel jobs to run when fitting binary edge classifiers.	-1
random_state	int | None	Pseudo-random number generator seed for reproducibility.	None
**kwargs	dict[str, Any]	Additional keyword arguments passed directly to HistGradientBoostingClassifier (e.g., categorical_features, early_stopping, interaction_cst).	{}

Attributes:

Name	Type	Description
classes_	ndarray	A 1D array containing sorted unique ordinal class labels.
estimators_	list of HistGradientBoostingClassifier	List containing fitted binary edge estimators.
n_features_in_	int	Number of features seen during fit.

Methods:

Name	Description
get_params	Get parameters for this estimator, including dynamically passed kwargs.
set_params	Set the parameters of this estimator.
fit	Fit the ordinal gradient boosting model.
predict_proba	Predict class probability mass functions (PMF) for X.
predict_dist	Predict probability mass distributions wrapped in a DiscretePredictiveDistribution.
predict	Predict point estimates (median or expected value) for X.

Source code in ordboost/models.py

class OrdBoostClassifier(BaseEstimator, ClassifierMixin):
    """Ordinal Gradient Boosting Classifier based on cumulative binary edge models.

    Parameters
    ----------
    loss : str, default="log_loss"
        The loss function to use in the binary base estimator.
    learning_rate : float, default=0.1
        The learning rate for gradient boosting.
    max_iter : int, default=100
        The maximum number of iterations (trees) for each binary classifier.
    max_depth : int | None, default=None
        The maximum depth of each tree.
    min_samples_leaf : int, default=20
        The minimum number of samples per leaf in binary trees.
    l2_regularization : float, default=0.0
        L2 regularization parameter for binary trees.
    monotonicity : {"running_max", "isotonic"}, default="running_max"
        Method used to enforce monotonicity across cumulative edge probabilities.
    n_jobs : int, default=-1
        Number of parallel jobs to run when fitting binary edge classifiers.
    random_state : int | None, default=None
        Pseudo-random number generator seed for reproducibility.
    **kwargs : dict[str, Any]
        Additional keyword arguments passed directly to `HistGradientBoostingClassifier`
        (e.g., `categorical_features`, `early_stopping`, `interaction_cst`).

    Attributes
    ----------
    classes_ : np.ndarray
        A 1D array containing sorted unique ordinal class labels.
    estimators_ : list of HistGradientBoostingClassifier
        List containing fitted binary edge estimators.
    n_features_in_ : int
        Number of features seen during `fit`.

    Methods
    -------
    get_params(deep)
        Get parameters for this estimator, including dynamically passed kwargs.
    set_params(**param)
        Set the parameters of this estimator.
    fit(X, y)
        Fit the ordinal gradient boosting model.
    predict_proba(X)
        Predict class probability mass functions (PMF) for X.
    predict_dist(X)
        Predict probability mass distributions wrapped in a `DiscretePredictiveDistribution`.
    predict(X)
        Predict point estimates (median or expected value) for X.

    """

    def __init__(
        self,
        loss: str = "log_loss",
        learning_rate: float = 0.1,
        max_iter: int = 100,
        max_depth: int | None = None,
        min_samples_leaf: int = 20,
        l2_regularization: float = 0.0,
        monotonicity: Literal["running_max", "isotonic"] = "running_max",
        n_jobs: int = -1,
        random_state: int | None = None,
        **kwargs: Any,
    ) -> None:
        self.loss = loss
        self.learning_rate = learning_rate
        self.max_iter = max_iter
        self.max_depth = max_depth
        self.min_samples_leaf = min_samples_leaf
        self.l2_regularization = l2_regularization
        self.monotonicity = monotonicity
        self.n_jobs = n_jobs
        self.random_state = random_state
        self.kwargs = kwargs

        self.estimators_: list[HistGradientBoostingClassifier] | None = None

    def get_params(self, deep: bool = True) -> dict[str, Any]:
        """Get parameters for this estimator, including dynamically passed kwargs.

        Parameters
        ----------
        deep : bool, default=True
            If True, will return the parameters for this estimator and
            contained sub-objects that are estimators.

        Returns
        -------
        params : dict
            Parameter names mapped to their values.

        """
        # Fetch standard explicit parameters from BaseEstimator
        params = super().get_params(deep=deep)

        # Remove raw 'kwargs' dictionary entry if BaseEstimator captured it
        params.pop("kwargs", None)

        # Merge extra kwargs directly into top-level parameter dictionary
        if hasattr(self, "kwargs") and isinstance(self.kwargs, dict):
            params.update(self.kwargs)

        return params

    def set_params(self, **params: Any) -> "OrdBoostClassifier":
        """Set the parameters of this estimator.

        Parameters
        ----------
        **params : dict
            Estimator parameters.

        Returns
        -------
        self : OrdBoostClassifier
            Estimator instance.

        """
        if not params:
            return self

        # Separate explicit init fields from additional kwargs
        valid_params = self._get_param_names()

        if not hasattr(self, "kwargs") or self.kwargs is None:
            self.kwargs = {}

        for key, value in params.items():
            if key in valid_params:
                setattr(self, key, value)
            else:
                self.kwargs[key] = value

        return self

    def _fit_single_edge(
        self,
        base_estimator: HistGradientBoostingClassifier,
        X: np.ndarray,
        y_binary: np.ndarray,
    ) -> HistGradientBoostingClassifier:
        """Fit a cloned binary edge estimator for a specific threshold P(Y <= c_k).

        Parameters
        ----------
        base_estimator : HistGradientBoostingClassifier
            The un-fitted base estimator template to clone and fit.
        X : np.ndarray
            Training feature matrix of shape (n_samples, n_features).
        y_binary : np.ndarray
            Binary target array of shape (n_samples,) indicating whether y <= c_k.

        Returns
        -------
        HistGradientBoostingClassifier
            Fitted binary classifier instance for the specified threshold.

        """
        estimator = cast(
            HistGradientBoostingClassifier,
            clone(base_estimator),
        )
        estimator.fit(X, y_binary)
        return estimator

    def fit(self, X: ArrayLike, y: ArrayLike) -> "OrdBoostClassifier":
        """Fit the ordinal gradient boosting model on training data.

        Parameters
        ----------
        X : {array-like, sparse matrix} of shape (n_samples, n_features)
            Training vector data.
        y : array-like of shape (n_samples,)
            Target values (ordinal class labels).

        Returns
        -------
        OrdBoostClassifier
            The fitted estimator instance.

        """
        X_arr, y_arr = check_X_y(X, y, ensure_2d=True)
        self.n_features_in_ = X_arr.shape[1]

        unique_classes = np.unique(y_arr)
        if len(unique_classes) < 2:
            raise ValueError(
                "OrdBoostClassifier requires at least 2 unique classes in y."
            )

        self.classes_ = np.sort(unique_classes)
        n_classes = len(self.classes_)

        if self.monotonicity not in ("running_max", "isotonic"):
            raise ValueError(
                f"Invalid monotonicity method '{self.monotonicity}'. "
                f"Must be 'running_max' or 'isotonic'."
            )

        # Merge explicit hyperparameters with additional kwargs
        base_params = {
            "loss": self.loss,
            "learning_rate": self.learning_rate,
            "max_iter": self.max_iter,
            "max_depth": self.max_depth,
            "min_samples_leaf": self.min_samples_leaf,
            "l2_regularization": self.l2_regularization,
            "random_state": self.random_state,
            **self.kwargs,
        }

        base_estimator = HistGradientBoostingClassifier(**base_params)

        binary_targets = [
            (y_arr <= self.classes_[k]).astype(int) for k in range(n_classes - 1)
        ]

        fitted_estimators = Parallel(n_jobs=self.n_jobs)(
            delayed(self._fit_single_edge)(base_estimator, X_arr, y_binary)
            for y_binary in binary_targets
        )

        self.estimators_ = cast(
            list[HistGradientBoostingClassifier], list(fitted_estimators)
        )
        return self

    def _enforce_monotonicity(self, cum_probs: np.ndarray) -> np.ndarray:
        """Enforce non-decreasing cumulative probabilities along edge thresholds.

        Parameters
        ----------
        cum_probs : np.ndarray
            2D array of shape (n_samples, n_edges) containing raw, unadjusted
            cumulative edge probability predictions.

        Returns
        -------
        np.ndarray
            2D array of shape (n_samples, n_edges) with monotonic non-decreasing
            cumulative probabilities across columns.

        """
        if self.monotonicity == "running_max":
            return np.maximum.accumulate(cum_probs, axis=1)

        from sklearn.isotonic import IsotonicRegression

        n_samples, n_edges = cum_probs.shape
        monotonic_probs = np.empty_like(cum_probs)
        x_grid = np.arange(n_edges)

        for i in range(n_samples):
            iso = IsotonicRegression(y_min=0.0, y_max=1.0, increasing=True)
            monotonic_probs[i] = iso.fit_transform(x_grid, cum_probs[i])

        return monotonic_probs

    def predict_proba(self, X: Any) -> np.ndarray:
        """Predict probability mass function (PMF) for each sample.

        Parameters
        ----------
        X : {array-like, sparse matrix} of shape (n_samples, n_features)
            Input features.

        Returns
        -------
        np.ndarray
            2D float array of shape (n_samples, n_classes) containing class probabilities.

        """
        check_is_fitted(self, attributes=["classes_", "estimators_", "n_features_in_"])
        X_arr = check_array(X, ensure_2d=True)

        if self.estimators_ is None:
            raise NotFittedError("The estimator instance is not fitted yet.")

        n_samples = X_arr.shape[0]
        n_classes = len(self.classes_)
        n_edges = n_classes - 1

        cum_probs = np.empty((n_samples, n_edges), dtype=float)

        for k, estimator in enumerate(self.estimators_):
            prob_le = estimator.predict_proba(X_arr)[:, 1]
            cum_probs[:, k] = prob_le

        cum_probs_mono = self._enforce_monotonicity(cum_probs)

        full_cdf = np.hstack([cum_probs_mono, np.ones((n_samples, 1), dtype=float)])
        full_cdf = np.clip(full_cdf, 0.0, 1.0)

        pmf = np.empty((n_samples, n_classes), dtype=float)
        pmf[:, 0] = full_cdf[:, 0]
        pmf[:, 1:] = np.diff(full_cdf, axis=1)

        pmf = np.clip(pmf, 0.0, None)
        sums = pmf.sum(axis=1, keepdims=True)
        sums[sums == 0.0] = 1.0
        pmf = pmf / sums

        return pmf

    def predict_dist(self, X: ArrayLike) -> DiscretePredictiveDistribution:
        """Predict probability distribution wrapped in a `DiscretePredictiveDistribution`.

        Parameters
        ----------
        X : {array-like, sparse matrix} of shape (n_samples, n_features)
            Input features.

        Returns
        -------
        DiscretePredictiveDistribution
            Distribution object encapsulating predicted PMFs and class labels.
        """
        pmf = self.predict_proba(X)
        return DiscretePredictiveDistribution(pmf=pmf, classes=self.classes_)

    def predict(
        self, X: ArrayLike, method: Literal["median", "mean"] = "median"
    ) -> np.ndarray:
        """Predict target class point estimates for X.

        Parameters
        ----------
        X : {array-like, sparse matrix} of shape (n_samples, n_features)
            Input features.
        method : {"median", "mean"}, default="median"
            Point prediction strategy:
            - "median": Returns 50th percentile ordinal class level.
            - "mean": Returns the expected value of the distribution.

        Returns
        -------
        np.ndarray
            1D array of predicted values in physical target units.

        """
        dist = self.predict_dist(X)
        if method == "median":
            return dist.median()
        elif method == "mean":
            return dist.mean()
        else:
            raise ValueError(
                f"Invalid prediction method '{method}'. Must be 'median' or 'mean'."
            )

fit(X, y)

Fit the ordinal gradient boosting model on training data.

Parameters:

Name	Type	Description	Default
X	array-like, sparse matrix	Training vector data.	array-like
y	array-like of shape (n_samples,)	Target values (ordinal class labels).	required

Returns:

Type	Description
OrdBoostClassifier	The fitted estimator instance.

Source code in ordboost/models.py

def fit(self, X: ArrayLike, y: ArrayLike) -> "OrdBoostClassifier":
    """Fit the ordinal gradient boosting model on training data.

    Parameters
    ----------
    X : {array-like, sparse matrix} of shape (n_samples, n_features)
        Training vector data.
    y : array-like of shape (n_samples,)
        Target values (ordinal class labels).

    Returns
    -------
    OrdBoostClassifier
        The fitted estimator instance.

    """
    X_arr, y_arr = check_X_y(X, y, ensure_2d=True)
    self.n_features_in_ = X_arr.shape[1]

    unique_classes = np.unique(y_arr)
    if len(unique_classes) < 2:
        raise ValueError(
            "OrdBoostClassifier requires at least 2 unique classes in y."
        )

    self.classes_ = np.sort(unique_classes)
    n_classes = len(self.classes_)

    if self.monotonicity not in ("running_max", "isotonic"):
        raise ValueError(
            f"Invalid monotonicity method '{self.monotonicity}'. "
            f"Must be 'running_max' or 'isotonic'."
        )

    # Merge explicit hyperparameters with additional kwargs
    base_params = {
        "loss": self.loss,
        "learning_rate": self.learning_rate,
        "max_iter": self.max_iter,
        "max_depth": self.max_depth,
        "min_samples_leaf": self.min_samples_leaf,
        "l2_regularization": self.l2_regularization,
        "random_state": self.random_state,
        **self.kwargs,
    }

    base_estimator = HistGradientBoostingClassifier(**base_params)

    binary_targets = [
        (y_arr <= self.classes_[k]).astype(int) for k in range(n_classes - 1)
    ]

    fitted_estimators = Parallel(n_jobs=self.n_jobs)(
        delayed(self._fit_single_edge)(base_estimator, X_arr, y_binary)
        for y_binary in binary_targets
    )

    self.estimators_ = cast(
        list[HistGradientBoostingClassifier], list(fitted_estimators)
    )
    return self

get_params(deep=True)

Get parameters for this estimator, including dynamically passed kwargs.

Parameters:

Name	Type	Description	Default
deep	bool	If True, will return the parameters for this estimator and contained sub-objects that are estimators.	True

Returns:

Name	Type	Description
params	dict	Parameter names mapped to their values.

Source code in ordboost/models.py

def get_params(self, deep: bool = True) -> dict[str, Any]:
    """Get parameters for this estimator, including dynamically passed kwargs.

    Parameters
    ----------
    deep : bool, default=True
        If True, will return the parameters for this estimator and
        contained sub-objects that are estimators.

    Returns
    -------
    params : dict
        Parameter names mapped to their values.

    """
    # Fetch standard explicit parameters from BaseEstimator
    params = super().get_params(deep=deep)

    # Remove raw 'kwargs' dictionary entry if BaseEstimator captured it
    params.pop("kwargs", None)

    # Merge extra kwargs directly into top-level parameter dictionary
    if hasattr(self, "kwargs") and isinstance(self.kwargs, dict):
        params.update(self.kwargs)

    return params

predict(X, method='median')

Predict target class point estimates for X.

Parameters:

Name	Type	Description	Default
X	array-like, sparse matrix	Input features.	array-like
method	(median, mean)	Point prediction strategy: - "median": Returns 50th percentile ordinal class level. - "mean": Returns the expected value of the distribution.	"median"

Returns:

Type	Description
ndarray	1D array of predicted values in physical target units.

Source code in ordboost/models.py

def predict(
    self, X: ArrayLike, method: Literal["median", "mean"] = "median"
) -> np.ndarray:
    """Predict target class point estimates for X.

    Parameters
    ----------
    X : {array-like, sparse matrix} of shape (n_samples, n_features)
        Input features.
    method : {"median", "mean"}, default="median"
        Point prediction strategy:
        - "median": Returns 50th percentile ordinal class level.
        - "mean": Returns the expected value of the distribution.

    Returns
    -------
    np.ndarray
        1D array of predicted values in physical target units.

    """
    dist = self.predict_dist(X)
    if method == "median":
        return dist.median()
    elif method == "mean":
        return dist.mean()
    else:
        raise ValueError(
            f"Invalid prediction method '{method}'. Must be 'median' or 'mean'."
        )

predict_dist(X)

Predict probability distribution wrapped in a DiscretePredictiveDistribution.

Parameters:

Name	Type	Description	Default
X	array-like, sparse matrix	Input features.	array-like

Returns:

Type	Description
DiscretePredictiveDistribution	Distribution object encapsulating predicted PMFs and class labels.

Source code in ordboost/models.py

def predict_dist(self, X: ArrayLike) -> DiscretePredictiveDistribution:
    """Predict probability distribution wrapped in a `DiscretePredictiveDistribution`.

    Parameters
    ----------
    X : {array-like, sparse matrix} of shape (n_samples, n_features)
        Input features.

    Returns
    -------
    DiscretePredictiveDistribution
        Distribution object encapsulating predicted PMFs and class labels.
    """
    pmf = self.predict_proba(X)
    return DiscretePredictiveDistribution(pmf=pmf, classes=self.classes_)

predict_proba(X)

Predict probability mass function (PMF) for each sample.

Parameters:

Name	Type	Description	Default
X	array-like, sparse matrix	Input features.	array-like

Returns:

Type	Description
ndarray	2D float array of shape (n_samples, n_classes) containing class probabilities.

Source code in ordboost/models.py

def predict_proba(self, X: Any) -> np.ndarray:
    """Predict probability mass function (PMF) for each sample.

    Parameters
    ----------
    X : {array-like, sparse matrix} of shape (n_samples, n_features)
        Input features.

    Returns
    -------
    np.ndarray
        2D float array of shape (n_samples, n_classes) containing class probabilities.

    """
    check_is_fitted(self, attributes=["classes_", "estimators_", "n_features_in_"])
    X_arr = check_array(X, ensure_2d=True)

    if self.estimators_ is None:
        raise NotFittedError("The estimator instance is not fitted yet.")

    n_samples = X_arr.shape[0]
    n_classes = len(self.classes_)
    n_edges = n_classes - 1

    cum_probs = np.empty((n_samples, n_edges), dtype=float)

    for k, estimator in enumerate(self.estimators_):
        prob_le = estimator.predict_proba(X_arr)[:, 1]
        cum_probs[:, k] = prob_le

    cum_probs_mono = self._enforce_monotonicity(cum_probs)

    full_cdf = np.hstack([cum_probs_mono, np.ones((n_samples, 1), dtype=float)])
    full_cdf = np.clip(full_cdf, 0.0, 1.0)

    pmf = np.empty((n_samples, n_classes), dtype=float)
    pmf[:, 0] = full_cdf[:, 0]
    pmf[:, 1:] = np.diff(full_cdf, axis=1)

    pmf = np.clip(pmf, 0.0, None)
    sums = pmf.sum(axis=1, keepdims=True)
    sums[sums == 0.0] = 1.0
    pmf = pmf / sums

    return pmf

set_params(**params)

Set the parameters of this estimator.

Parameters:

Name	Type	Description	Default
**params	dict	Estimator parameters.	{}

Returns:

Name	Type	Description
self	OrdBoostClassifier	Estimator instance.

Source code in ordboost/models.py

def set_params(self, **params: Any) -> "OrdBoostClassifier":
    """Set the parameters of this estimator.

    Parameters
    ----------
    **params : dict
        Estimator parameters.

    Returns
    -------
    self : OrdBoostClassifier
        Estimator instance.

    """
    if not params:
        return self

    # Separate explicit init fields from additional kwargs
    valid_params = self._get_param_names()

    if not hasattr(self, "kwargs") or self.kwargs is None:
        self.kwargs = {}

    for key, value in params.items():
        if key in valid_params:
            setattr(self, key, value)
        else:
            self.kwargs[key] = value

    return self

OrdBoostRegressor

Bases: BaseEstimator, RegressorMixin

Ordinal Gradient Boosting Regressor for continuous target outcomes.

Discretizes continuous targets into ordinal bins, fits an underlying cumulative binary OrdBoostClassifier, and maps predicted probability distributions back to continuous target space using a fitted bin mapper.

Parameters:

Name	Type	Description	Default
n_bins	int	Number of discrete bins to construct if bin_edges is None.	20
bin_edges	ArrayLike of shape (n_bins + 1,)	Monotonically increasing boundaries defining continuous bin intervals.	None
bin_strategy	(quantile, uniform)	Strategy used to define automatic bin boundaries when bin_edges is None.	"quantile"
mapper	(median, mean, quantile, uniform, continuous)	Bin mapping strategy instance or string shortcut used to convert predicted PMFs back to continuous predictions.	"median"
mapper_kwargs	dict[str, Any] | None	Optional keyword arguments passed when instantiating string-shortcut mappers.	None
learning_rate	float	Learning rate for gradient boosting.	0.1
max_iter	int	Maximum number of iterations (trees) per cumulative edge model.	100
max_depth	int | None	Maximum depth of each tree.	None
min_samples_leaf	int	Minimum number of samples per leaf.	20
l2_regularization	float	L2 regularization parameter.	0.0
monotonicity	(running_max, isotonic)	Cumulative probability monotonicity enforcement method.	"running_max"
n_jobs	int	Number of parallel jobs to run when fitting edge classifiers.	-1
random_state	int | None	Random state seed.	None
**kwargs	dict[str, Any]	Additional arguments passed to underlying HistGradientBoostingClassifier.	{}

Attributes:

Name	Type	Description
bin_edges_	ndarray	1D float array of shape (n_bins + 1,) containing resolved bin edges.
classifier_	OrdBoostClassifier	Fitted underlying ordinal gradient boosting classifier.
mapper_	BaseBinMapper	Fitted bin mapper instance.
n_features_in_	int	Number of features seen during fit.

Methods:

Name	Description
get_params	Get parameters for this estimator, including dynamically passed kwargs.
set_params	Set the parameters of this estimator.
fit	Fit the continuous ordinal gradient boosting regressor.
predict_dist	Predict continuous cumulative distribution functions wrapped in a distribution.
predict	Predict continuous target point estimates.

Source code in ordboost/models.py

class OrdBoostRegressor(BaseEstimator, RegressorMixin):
    """Ordinal Gradient Boosting Regressor for continuous target outcomes.

    Discretizes continuous targets into ordinal bins, fits an underlying cumulative
    binary OrdBoostClassifier, and maps predicted probability distributions back
    to continuous target space using a fitted bin mapper.

    Parameters
    ----------
    n_bins : int, default=20
        Number of discrete bins to construct if `bin_edges` is None.
    bin_edges : ArrayLike of shape (n_bins + 1,), optional
        Monotonically increasing boundaries defining continuous bin intervals.
    bin_strategy : {"quantile", "uniform"}, default="quantile"
        Strategy used to define automatic bin boundaries when `bin_edges` is None.
    mapper : {"median", "mean", "quantile", "uniform", "continuous"} or BaseBinMapper, default="median"
        Bin mapping strategy instance or string shortcut used to convert predicted
        PMFs back to continuous predictions.
    mapper_kwargs : dict[str, Any] | None, default=None
        Optional keyword arguments passed when instantiating string-shortcut
        mappers.
    learning_rate : float, default=0.1
        Learning rate for gradient boosting.
    max_iter : int, default=100
        Maximum number of iterations (trees) per cumulative edge model.
    max_depth : int | None, default=None
        Maximum depth of each tree.
    min_samples_leaf : int, default=20
        Minimum number of samples per leaf.
    l2_regularization : float, default=0.0
        L2 regularization parameter.
    monotonicity : {"running_max", "isotonic"}, default="running_max"
        Cumulative probability monotonicity enforcement method.
    n_jobs : int, default=-1
        Number of parallel jobs to run when fitting edge classifiers.
    random_state : int | None, default=None
        Random state seed.
    **kwargs : dict[str, Any]
        Additional arguments passed to underlying `HistGradientBoostingClassifier`.

    Attributes
    ----------
    bin_edges_ : np.ndarray
        1D float array of shape (n_bins + 1,) containing resolved bin edges.
    classifier_ : OrdBoostClassifier
        Fitted underlying ordinal gradient boosting classifier.
    mapper_ : BaseBinMapper
        Fitted bin mapper instance.
    n_features_in_ : int
        Number of features seen during `fit`.

    Methods
    -------
    get_params(deep)
        Get parameters for this estimator, including dynamically passed kwargs.
    set_params(**param)
        Set the parameters of this estimator.
    fit(X, y)
        Fit the continuous ordinal gradient boosting regressor.
    predict_dist(X)
        Predict continuous cumulative distribution functions wrapped in a distribution.
    predict(X, method="mean")
        Predict continuous target point estimates.

    """

    def __init__(
        self,
        n_bins: int = 20,
        bin_edges: Union[ArrayLike, None] = None,
        bin_strategy: Literal["quantile", "uniform"] = "quantile",
        mapper: Union[
            Literal["median", "mean", "quantile", "uniform", "continuous"],
            BaseBinMapper,
            None,
        ] = "median",
        mapper_kwargs: Union[dict[str, Any], None] = None,
        learning_rate: float = 0.1,
        max_iter: int = 100,
        max_depth: Union[int, None] = None,
        min_samples_leaf: int = 20,
        l2_regularization: float = 0.0,
        monotonicity: Literal["running_max", "isotonic"] = "running_max",
        n_jobs: int = -1,
        random_state: Union[int, None] = None,
        **kwargs: Any,
    ) -> None:
        self.n_bins = n_bins
        self.bin_edges = bin_edges
        self.bin_strategy = bin_strategy
        self.mapper = mapper
        self.mapper_kwargs = mapper_kwargs
        self.learning_rate = learning_rate
        self.max_iter = max_iter
        self.max_depth = max_depth
        self.min_samples_leaf = min_samples_leaf
        self.l2_regularization = l2_regularization
        self.monotonicity: Literal["running_max", "isotonic"] = monotonicity
        self.n_jobs = n_jobs
        self.random_state = random_state
        self.kwargs = kwargs

    def get_params(self, deep: bool = True) -> dict[str, Any]:
        """Get parameters for this estimator, including dynamically passed kwargs.

        Parameters
        ----------
        deep : bool, default=True
            If True, will return the parameters for this estimator and
            contained sub-objects that are estimators.

        Returns
        -------
        params : dict
            Parameter names mapped to their values.

        """
        # Fetch standard explicit parameters from BaseEstimator
        params = super().get_params(deep=deep)

        # Remove raw 'kwargs' dictionary entry if BaseEstimator captured it
        params.pop("kwargs", None)

        # Merge extra kwargs directly into top-level parameter dictionary
        if hasattr(self, "kwargs") and isinstance(self.kwargs, dict):
            params.update(self.kwargs)

        return params

    def set_params(self, **params: Any) -> "OrdBoostRegressor":
        """Set the parameters of this estimator.

        Parameters
        ----------
        **params : dict
            Estimator parameters.

        Returns
        -------
        self : OrdBoostRegressor
            Estimator instance.

        """
        if not params:
            return self

        # Separate explicit init fields from additional kwargs
        valid_params = self._get_param_names()

        if not hasattr(self, "kwargs") or self.kwargs is None:
            self.kwargs = {}

        for key, value in params.items():
            if key in valid_params:
                setattr(self, key, value)
            else:
                self.kwargs[key] = value

        return self

    def _compute_bin_edges(self, y: np.ndarray) -> np.ndarray:
        """Compute or validate continuous target bin boundary edges.

        Parameters
        ----------
        y : np.ndarray
            1D float array of continuous target values used to compute automatic
            bin edges when `bin_edges` is None.

        Returns
        -------
        np.ndarray
            1D float array containing strictly monotonically increasing bin edge
            thresholds.

        Raises
        ------
        ValueError
            If `bin_edges` is not 1D, has fewer than 2 elements, or is not strictly
            monotonically increasing.
            If `n_bins` is less than 2.
            If `bin_strategy` is invalid.

        """
        if self.bin_edges is not None:
            edges = np.asarray(self.bin_edges, dtype=float)
            if edges.ndim != 1 or len(edges) < 2:
                raise ValueError(
                    "Expected 'bin_edges' to be a 1D array with >= 2 edges."
                )
            if np.any(np.diff(edges) <= 0.0):
                raise ValueError(
                    "'bin_edges' must be strictly monotonically increasing."
                )
            return edges

        if self.n_bins < 2:
            raise ValueError("Parameter 'n_bins' must be >= 2.")

        if self.bin_strategy == "quantile":
            quantiles = np.linspace(0.0, 1.0, self.n_bins + 1)
            edges = np.quantile(y, quantiles)
            # Ensure unique edges if duplicates occur in dense regions
            edges = np.unique(edges)
            if len(edges) < 2:
                edges = np.linspace(np.min(y), np.max(y), self.n_bins + 1)
        elif self.bin_strategy == "uniform":
            edges = np.linspace(np.min(y), np.max(y), self.n_bins + 1)
        else:
            raise ValueError(f"Invalid bin_strategy '{self.bin_strategy}'.")

        return edges

    def _resolve_mapper(self) -> BaseBinMapper:
        """Resolve string shortcut or clone provided mapper and assign resolved
        bin edges.

        Returns
        -------
        BaseBinMapper
            An un-fitted mapper instance configured with `bin_edges_`
            ready for fitting.

        Raises
        ------
        ValueError
            If `mapper` is an invalid string shortcut or not an instance
            of `BaseBinMapper`.

        """
        from ordboost.mappers import (
            ContinuousBinMapper,
            EmpiricalMeanBinMapper,
            EmpiricalMedianBinMapper,
            QuantileBinMapper,
            UniformBinMapper,
        )

        mapper_map: dict[str, type[BaseBinMapper]] = {
            "median": EmpiricalMedianBinMapper,
            "mean": EmpiricalMeanBinMapper,
            "quantile": QuantileBinMapper,
            "uniform": UniformBinMapper,
            "continuous": ContinuousBinMapper,
        }

        extra_kwargs = self.mapper_kwargs or {}

        if self.mapper is None or self.mapper == "median":
            mapper_obj = EmpiricalMedianBinMapper(
                bin_edges=self.bin_edges_, **extra_kwargs
            )
        elif isinstance(self.mapper, str):
            if self.mapper not in mapper_map:
                raise ValueError(
                    f"Unknown mapper shortcut '{self.mapper}'. "
                    f"Supported options are: {list(mapper_map.keys())}"
                )
            mapper_cls = mapper_map[self.mapper]
            mapper_obj = mapper_cls(bin_edges=self.bin_edges_, **extra_kwargs)
        elif isinstance(self.mapper, BaseBinMapper):
            mapper_obj = cast(BaseBinMapper, clone(self.mapper))
            mapper_obj.bin_edges = self.bin_edges_
        else:
            raise ValueError(
                "Expected 'mapper' to be a valid string shortcut or an instance "
                "of BaseBinMapper."
            )

        return mapper_obj

    def fit(self, X: ArrayLike, y: ArrayLike) -> "OrdBoostRegressor":
        """Fit the ordinal boosting regressor on continuous targets.

        Discretizes `y` into bins using `bin_edges_`, fits the underlying
        `OrdBoostClassifier`, and fits the resolved `mapper_` strategy.

        Parameters
        ----------
        X : ArrayLike of shape (n_samples, n_features)
            Training feature matrix.
        y : ArrayLike of shape (n_samples,)
            Continuous target vector.

        Returns
        -------
        OrdBoostRegressor
            Fitted estimator instance.

        """
        X_arr, y_arr = check_X_y(X, y, ensure_2d=True, dtype="numeric")
        self.n_features_in_ = X_arr.shape[1]

        self.bin_edges_ = self._compute_bin_edges(y_arr)
        y_binned = np.digitize(y_arr, self.bin_edges_[1:-1])

        # Fit underlying OrdBoostClassifier
        self.classifier_ = OrdBoostClassifier(
            learning_rate=self.learning_rate,
            max_iter=self.max_iter,
            max_depth=self.max_depth,
            min_samples_leaf=self.min_samples_leaf,
            l2_regularization=self.l2_regularization,
            monotonicity=self.monotonicity,
            n_jobs=self.n_jobs,
            random_state=self.random_state,
            **self.kwargs,
        )
        self.classifier_.fit(X_arr, y_binned)

        # Resolve and fit bin mapper
        self.mapper_ = self._resolve_mapper()
        self.mapper_.fit(y_continuous=y_arr, y_binned=y_binned)

        return self

    def predict_dist(self, X: ArrayLike) -> ContinuousPredictiveDistribution:
        """Predict probability distribution wrapped in ContinuousPredictiveDistribution.

        Parameters
        ----------
        X : ArrayLike of shape (n_samples, n_features)
            Input feature matrix.

        Returns
        -------
        ContinuousPredictiveDistribution
            Predicted continuous cumulative distribution object.

        """
        check_is_fitted(self, attributes=["bin_edges_", "classifier_", "mapper_"])
        X_arr = check_array(X, ensure_2d=True)
        pmf = self.classifier_.predict_proba(X_arr)
        return self.mapper_.to_continuous_dist(pmf)

    def predict(
        self, X: ArrayLike, method: Literal["mean", "median"] = "mean"
    ) -> np.ndarray:
        """Predict continuous target point estimates.

        Parameters
        ----------
        X : ArrayLike of shape (n_samples, n_features)
            Input feature matrix.
        method : {"mean", "median"}, default="mean"
            Point prediction calculation method.

        Returns
        -------
        np.ndarray
            1D float array of predicted target values.

        """
        dist = self.predict_dist(X)
        if method == "mean":
            return dist.mean()
        elif method == "median":
            return dist.median()
        else:
            raise ValueError(f"Invalid method '{method}'. Must be 'mean' or 'median'.")

fit(X, y)

Fit the ordinal boosting regressor on continuous targets.

Discretizes y into bins using bin_edges_, fits the underlying OrdBoostClassifier, and fits the resolved mapper_ strategy.

Parameters:

Name	Type	Description	Default
X	ArrayLike of shape (n_samples, n_features)	Training feature matrix.	required
y	ArrayLike of shape (n_samples,)	Continuous target vector.	required

Returns:

Type	Description
OrdBoostRegressor	Fitted estimator instance.

Source code in ordboost/models.py

def fit(self, X: ArrayLike, y: ArrayLike) -> "OrdBoostRegressor":
    """Fit the ordinal boosting regressor on continuous targets.

    Discretizes `y` into bins using `bin_edges_`, fits the underlying
    `OrdBoostClassifier`, and fits the resolved `mapper_` strategy.

    Parameters
    ----------
    X : ArrayLike of shape (n_samples, n_features)
        Training feature matrix.
    y : ArrayLike of shape (n_samples,)
        Continuous target vector.

    Returns
    -------
    OrdBoostRegressor
        Fitted estimator instance.

    """
    X_arr, y_arr = check_X_y(X, y, ensure_2d=True, dtype="numeric")
    self.n_features_in_ = X_arr.shape[1]

    self.bin_edges_ = self._compute_bin_edges(y_arr)
    y_binned = np.digitize(y_arr, self.bin_edges_[1:-1])

    # Fit underlying OrdBoostClassifier
    self.classifier_ = OrdBoostClassifier(
        learning_rate=self.learning_rate,
        max_iter=self.max_iter,
        max_depth=self.max_depth,
        min_samples_leaf=self.min_samples_leaf,
        l2_regularization=self.l2_regularization,
        monotonicity=self.monotonicity,
        n_jobs=self.n_jobs,
        random_state=self.random_state,
        **self.kwargs,
    )
    self.classifier_.fit(X_arr, y_binned)

    # Resolve and fit bin mapper
    self.mapper_ = self._resolve_mapper()
    self.mapper_.fit(y_continuous=y_arr, y_binned=y_binned)

    return self

get_params(deep=True)

Get parameters for this estimator, including dynamically passed kwargs.

Parameters:

Name	Type	Description	Default
deep	bool	If True, will return the parameters for this estimator and contained sub-objects that are estimators.	True

Returns:

Name	Type	Description
params	dict	Parameter names mapped to their values.

Source code in ordboost/models.py

def get_params(self, deep: bool = True) -> dict[str, Any]:
    """Get parameters for this estimator, including dynamically passed kwargs.

    Parameters
    ----------
    deep : bool, default=True
        If True, will return the parameters for this estimator and
        contained sub-objects that are estimators.

    Returns
    -------
    params : dict
        Parameter names mapped to their values.

    """
    # Fetch standard explicit parameters from BaseEstimator
    params = super().get_params(deep=deep)

    # Remove raw 'kwargs' dictionary entry if BaseEstimator captured it
    params.pop("kwargs", None)

    # Merge extra kwargs directly into top-level parameter dictionary
    if hasattr(self, "kwargs") and isinstance(self.kwargs, dict):
        params.update(self.kwargs)

    return params

predict(X, method='mean')

Predict continuous target point estimates.

Parameters:

Name	Type	Description	Default
X	ArrayLike of shape (n_samples, n_features)	Input feature matrix.	required
method	(mean, median)	Point prediction calculation method.	"mean"

Returns:

Type	Description
ndarray	1D float array of predicted target values.

Source code in ordboost/models.py

def predict(
    self, X: ArrayLike, method: Literal["mean", "median"] = "mean"
) -> np.ndarray:
    """Predict continuous target point estimates.

    Parameters
    ----------
    X : ArrayLike of shape (n_samples, n_features)
        Input feature matrix.
    method : {"mean", "median"}, default="mean"
        Point prediction calculation method.

    Returns
    -------
    np.ndarray
        1D float array of predicted target values.

    """
    dist = self.predict_dist(X)
    if method == "mean":
        return dist.mean()
    elif method == "median":
        return dist.median()
    else:
        raise ValueError(f"Invalid method '{method}'. Must be 'mean' or 'median'.")

predict_dist(X)

Predict probability distribution wrapped in ContinuousPredictiveDistribution.

Parameters:

Name	Type	Description	Default
X	ArrayLike of shape (n_samples, n_features)	Input feature matrix.	required

Returns:

Type	Description
ContinuousPredictiveDistribution	Predicted continuous cumulative distribution object.

Source code in ordboost/models.py

def predict_dist(self, X: ArrayLike) -> ContinuousPredictiveDistribution:
    """Predict probability distribution wrapped in ContinuousPredictiveDistribution.

    Parameters
    ----------
    X : ArrayLike of shape (n_samples, n_features)
        Input feature matrix.

    Returns
    -------
    ContinuousPredictiveDistribution
        Predicted continuous cumulative distribution object.

    """
    check_is_fitted(self, attributes=["bin_edges_", "classifier_", "mapper_"])
    X_arr = check_array(X, ensure_2d=True)
    pmf = self.classifier_.predict_proba(X_arr)
    return self.mapper_.to_continuous_dist(pmf)

set_params(**params)

Set the parameters of this estimator.

Parameters:

Name	Type	Description	Default
**params	dict	Estimator parameters.	{}

Returns:

Name	Type	Description
self	OrdBoostRegressor	Estimator instance.

Source code in ordboost/models.py

def set_params(self, **params: Any) -> "OrdBoostRegressor":
    """Set the parameters of this estimator.

    Parameters
    ----------
    **params : dict
        Estimator parameters.

    Returns
    -------
    self : OrdBoostRegressor
        Estimator instance.

    """
    if not params:
        return self

    # Separate explicit init fields from additional kwargs
    valid_params = self._get_param_names()

    if not hasattr(self, "kwargs") or self.kwargs is None:
        self.kwargs = {}

    for key, value in params.items():
        if key in valid_params:
            setattr(self, key, value)
        else:
            self.kwargs[key] = value

    return self