Skip to content

glassbox.models.linear_model

Linear regression and classification models.

BaseLinearModel 

BaseLinearModel(
    learning_rate=0.01,
    max_epochs=1000,
    tol=1e-06,
    schedule=CONSTANT,
)

Bases: BaseModel

Abstract base class for linear models trained with gradient-based optimization.

Parameters:

Name Type Description Default
learning_rate float

Initial learning rate used by the optimizer.

 0.01
max_epochs int

Maximum number of optimization epochs.

 1000
tol float

Convergence tolerance used by stopping criteria.

 1e-6
schedule LearningSchedule

Strategy used to update the learning rate across epochs.

 LearningSchedule.CONSTANT

Initialize shared linear-model hyperparameters and learned coefficients.

Parameters:

Name Type Description Default
learning_rate float

Initial learning rate used by the optimizer.

 0.01
max_epochs int

Maximum number of optimization epochs.

 1000
tol float

Convergence tolerance used by stopping criteria.

 1e-6
schedule LearningSchedule

Strategy used to update the learning rate across epochs.

 LearningSchedule.CONSTANT
Source code in glassbox/models/linear_model/_base.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def __init__(
    self,
    learning_rate: float = 0.01,
    max_epochs: int = 1000,
    tol: float = 1e-6,
    schedule: LearningSchedule = LearningSchedule.CONSTANT,
) -> None:
    """
    Initialize shared linear-model hyperparameters and learned coefficients.

    Parameters
    ----------
    learning_rate : float, default=0.01
        Initial learning rate used by the optimizer.
    max_epochs : int, default=1000
        Maximum number of optimization epochs.
    tol : float, default=1e-6
        Convergence tolerance used by stopping criteria.
    schedule : LearningSchedule, default=LearningSchedule.CONSTANT
        Strategy used to update the learning rate across epochs.
    """
    if learning_rate <= 0:
        raise ValueError("learning_rate must be strictly positive")
    if max_epochs <= 0:
        raise ValueError("max_epochs must be strictly positive")
    if tol < 0:
        raise ValueError("tol must be non-negative")

    self.learning_rate = learning_rate
    self.max_epochs = max_epochs
    self.tol = tol
    self.schedule = schedule
    self.weights: np.ndarray = np.array([])
    self.bias: float = 0.0

fit abstractmethod 

fit(X, y)

Fit the linear model to training data.

Parameters:

Name Type Description Default
X ndarray

Training feature matrix of shape (n_samples, n_features).

 required
y ndarray

Training target vector of shape (n_samples,).

 required

Returns:

Type Description
Self

The fitted model instance.
Source code in glassbox/models/linear_model/_base.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
@abstractmethod
def fit(self, X: np.ndarray, y: np.ndarray) -> Self:
    """
    Fit the linear model to training data.

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

    Returns
    -------
    Self
        The fitted model instance.
    """
    raise NotImplementedError

predict abstractmethod 

predict(X, **kwargs)

Predict target values for input samples.

Parameters:

Name Type Description Default
X ndarray

Input feature matrix of shape (n_samples, n_features).

 required
**kwargs Any

Additional keyword arguments for prediction.

 {}

Returns:

Type Description
ndarray

Predicted values of shape (n_samples,).
Source code in glassbox/models/linear_model/_base.py 
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
@abstractmethod
def predict(self, X: np.ndarray, **kwargs: Any) -> np.ndarray:
    """
    Predict target values for input samples.

    Parameters
    ----------
    X : np.ndarray
        Input feature matrix of shape (n_samples, n_features).
    **kwargs : Any
        Additional keyword arguments for prediction.

    Returns
    -------
    np.ndarray
        Predicted values of shape (n_samples,).
    """
    raise NotImplementedError

LearningSchedule

Bases: Enum

Learning rate scheduling strategies for linear models.

Attributes:

Name Type Description
CONSTANT LearningSchedule

Keep the learning rate fixed across epochs.
TIME_DECAY LearningSchedule

Decrease the learning rate proportionally with epoch growth.
EXPONENTIAL LearningSchedule

Decrease the learning rate exponentially over epochs.

LinearRegression 

LinearRegression(
    learning_rate=0.01,
    max_epochs=1000,
    tol=1e-06,
    schedule=CONSTANT,
)

Bases: BaseLinearModel

Linear regression model.

Source code in glassbox/models/linear_model/_base.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def __init__(
    self,
    learning_rate: float = 0.01,
    max_epochs: int = 1000,
    tol: float = 1e-6,
    schedule: LearningSchedule = LearningSchedule.CONSTANT,
) -> None:
    """
    Initialize shared linear-model hyperparameters and learned coefficients.

    Parameters
    ----------
    learning_rate : float, default=0.01
        Initial learning rate used by the optimizer.
    max_epochs : int, default=1000
        Maximum number of optimization epochs.
    tol : float, default=1e-6
        Convergence tolerance used by stopping criteria.
    schedule : LearningSchedule, default=LearningSchedule.CONSTANT
        Strategy used to update the learning rate across epochs.
    """
    if learning_rate <= 0:
        raise ValueError("learning_rate must be strictly positive")
    if max_epochs <= 0:
        raise ValueError("max_epochs must be strictly positive")
    if tol < 0:
        raise ValueError("tol must be non-negative")

    self.learning_rate = learning_rate
    self.max_epochs = max_epochs
    self.tol = tol
    self.schedule = schedule
    self.weights: np.ndarray = np.array([])
    self.bias: float = 0.0

fit 

fit(X, y)

Fit the linear regression model to training data.

Parameters:

Name Type Description Default
X ndarray

Training feature matrix of shape (n_samples, n_features).

 required
y ndarray

Training target vector of shape (n_samples,).

 required

Returns:

Type Description
Self

The fitted model instance.
Source code in glassbox/models/linear_model/linear.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
def fit(self, X: np.ndarray, y: np.ndarray) -> Self:
    """
    Fit the linear regression model to training data.

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

    Returns
    -------
    Self
        The fitted model instance.
    """
    X_arr = np.asarray(X, dtype=float)
    y_arr = np.asarray(y, dtype=float)

    if X_arr.ndim != 2:
        raise ValueError("X must be a 2D array")
    if y_arr.ndim != 1:
        raise ValueError("y must be a 1D array")
    if X_arr.shape[0] != y_arr.shape[0]:
        raise ValueError("X and y must contain the same number of samples")
    if X_arr.shape[0] == 0:
        raise ValueError("X and y cannot be empty")

    n_samples, n_features = X_arr.shape
    self.weights = np.zeros(n_features, dtype=float)
    self.bias = 0.0

    previous_loss = np.inf
    for epoch in range(self.max_epochs):
        learning_rate = self._update_learning_rate(epoch)

        predictions = X_arr @ self.weights + self.bias
        errors = predictions - y_arr

        gradient_w = (2.0 / n_samples) * (X_arr.T @ errors)
        gradient_b = 2.0 * np.mean(errors)

        self.weights -= learning_rate * gradient_w
        self.bias -= learning_rate * gradient_b

        current_loss = float(np.mean(errors**2))
        if abs(previous_loss - current_loss) <= self.tol:
            break
        previous_loss = current_loss

    return self

predict 

predict(X, **kwargs)

Predict continuous target values for input samples.

Parameters:

Name Type Description Default
X ndarray

Input feature matrix of shape (n_samples, n_features).

 required
**kwargs Any

Additional keyword arguments for prediction.

 {}

Returns:

Type Description
ndarray

Predicted values of shape (n_samples,).
Source code in glassbox/models/linear_model/linear.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def predict(self, X: np.ndarray, **kwargs: Any) -> np.ndarray:
    """
    Predict continuous target values for input samples.

    Parameters
    ----------
    X : np.ndarray
        Input feature matrix of shape (n_samples, n_features).
    **kwargs : Any
        Additional keyword arguments for prediction.

    Returns
    -------
    np.ndarray
        Predicted values of shape (n_samples,).
    """
    if self.weights.size == 0:
        raise RuntimeError("Model is not fitted yet.")

    X_arr = np.asarray(X, dtype=float)
    if X_arr.ndim != 2:
        raise ValueError("X must be a 2D array")
    if X_arr.shape[1] != self.weights.shape[0]:
        raise ValueError("X must have the same number of features used during fit")

    return X_arr @ self.weights + self.bias

LogisticRegression 

LogisticRegression(
    learning_rate=0.01,
    max_epochs=1000,
    tol=1e-06,
    schedule=CONSTANT,
)

Bases: BaseLinearModel

Logistic regression model for binary classification.

Source code in glassbox/models/linear_model/_base.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def __init__(
    self,
    learning_rate: float = 0.01,
    max_epochs: int = 1000,
    tol: float = 1e-6,
    schedule: LearningSchedule = LearningSchedule.CONSTANT,
) -> None:
    """
    Initialize shared linear-model hyperparameters and learned coefficients.

    Parameters
    ----------
    learning_rate : float, default=0.01
        Initial learning rate used by the optimizer.
    max_epochs : int, default=1000
        Maximum number of optimization epochs.
    tol : float, default=1e-6
        Convergence tolerance used by stopping criteria.
    schedule : LearningSchedule, default=LearningSchedule.CONSTANT
        Strategy used to update the learning rate across epochs.
    """
    if learning_rate <= 0:
        raise ValueError("learning_rate must be strictly positive")
    if max_epochs <= 0:
        raise ValueError("max_epochs must be strictly positive")
    if tol < 0:
        raise ValueError("tol must be non-negative")

    self.learning_rate = learning_rate
    self.max_epochs = max_epochs
    self.tol = tol
    self.schedule = schedule
    self.weights: np.ndarray = np.array([])
    self.bias: float = 0.0

fit 

fit(X, y)

Fit the logistic regression model to training data.

Parameters:

Name Type Description Default
X ndarray

Training feature matrix of shape (n_samples, n_features).

 required
y ndarray

Training target vector of shape (n_samples,).

 required

Returns:

Type Description
Self

The fitted model instance.
Source code in glassbox/models/linear_model/logistic.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def fit(self, X: np.ndarray, y: np.ndarray) -> Self:
    """
    Fit the logistic regression model to training data.

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

    Returns
    -------
    Self
        The fitted model instance.
    """
    X_arr = np.asarray(X, dtype=float)
    y_arr = np.asarray(y)

    if X_arr.ndim != 2:
        raise ValueError("X must be a 2D array")
    if y_arr.ndim != 1:
        raise ValueError("y must be a 1D array")
    if X_arr.shape[0] != y_arr.shape[0]:
        raise ValueError("X and y must contain the same number of samples")
    if X_arr.shape[0] == 0:
        raise ValueError("X and y cannot be empty")

    classes = np.unique(y_arr)
    if not np.all(np.isin(classes, np.array([0, 1]))):
        raise ValueError(f"y must contain binary labels encoded as 0 and 1, but found: {classes.tolist()}")

    y_bin = y_arr.astype(float)

    n_samples, n_features = X_arr.shape
    self.weights = np.zeros(n_features, dtype=float)
    self.bias = 0.0

    previous_loss = np.inf
    for epoch in range(self.max_epochs):
        learning_rate = self._update_learning_rate(epoch)

        logits = X_arr @ self.weights + self.bias
        probabilities = self._sigmoid(logits)
        errors = probabilities - y_bin

        gradient_w = (X_arr.T @ errors) / n_samples
        gradient_b = float(np.mean(errors))

        self.weights -= learning_rate * gradient_w
        self.bias -= learning_rate * gradient_b

        probabilities_clipped = np.clip(probabilities, 1e-15, 1.0 - 1e-15)
        current_loss = float(
            -np.mean(
                y_bin * np.log(probabilities_clipped)
                + (1.0 - y_bin) * np.log(1.0 - probabilities_clipped)
            )
        )
        if abs(previous_loss - current_loss) <= self.tol:
            break
        previous_loss = current_loss

    return self

predict 

predict(X, **kwargs)

Predict class labels for input samples.

Parameters:

Name Type Description Default
X ndarray

Input feature matrix of shape (n_samples, n_features).

 required
**kwargs Any

Additional keyword arguments for prediction.

 {}

Returns:

Type Description
ndarray

Predicted class labels of shape (n_samples,).
Source code in glassbox/models/linear_model/logistic.py 
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def predict(self, X: np.ndarray, **kwargs: Any) -> np.ndarray:
    """
    Predict class labels for input samples.

    Parameters
    ----------
    X : np.ndarray
        Input feature matrix of shape (n_samples, n_features).
    **kwargs : Any
        Additional keyword arguments for prediction.

    Returns
    -------
    np.ndarray
        Predicted class labels of shape (n_samples,).
    """
    threshold = kwargs.get("threshold", 0.5)
    if not isinstance(threshold, (int, float)):
        raise ValueError("threshold must be a numeric value")
    if threshold < 0.0 or threshold > 1.0:
        raise ValueError("threshold must be in the [0.0, 1.0] interval")

    probabilities = self.predict_proba(X)
    return (probabilities >= float(threshold)).astype(int)

predict_proba 

predict_proba(X)

Predict class probabilities for input samples.

Parameters:

Name Type Description Default
X ndarray

Input feature matrix of shape (n_samples, n_features).

 required

Returns:

Type Description
ndarray

Predicted probabilities of shape (n_samples,).
Source code in glassbox/models/linear_model/logistic.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
def predict_proba(self, X: np.ndarray) -> np.ndarray:
    """
    Predict class probabilities for input samples.

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

    Returns
    -------
    np.ndarray
        Predicted probabilities of shape (n_samples,).
    """
    if self.weights.size == 0:
        raise RuntimeError("Model is not fitted yet.")

    X_arr = np.asarray(X, dtype=float)
    if X_arr.ndim != 2:
        raise ValueError("X must be a 2D array")
    if X_arr.shape[1] != self.weights.shape[0]:
        raise ValueError("X must have the same number of features used during fit")

    logits = X_arr @ self.weights + self.bias
    return self._sigmoid(logits)