rbg-ml 0.1.0__py3-none-any.whl

rbg/Classification/KNN.py

@@ -0,0 +1,178 @@
+import numpy as np
+from rbg.Classification.classifier import Classifier
+
+class KNN(Classifier):
+    """K-nearest neighbors classifier for categorical labels."""
+
+    def __init__(self, labels=None, k=3, reference_class = None):
+        """Initialize the classifier with class labels and the number of neighbors.
+
+        Args:
+            labels: Unique class labels supported by the classifier.
+            k: Number of nearest neighbors used to classify each observation.
+                Defaults to 3.
+            reference_class: Reference label used to initialize the base
+                classifier.
+
+        Raises:
+            ValueError: If the class labels or reference label are invalid,
+                as defined by the base classifier.
+        """
+        Classifier.__init__(self, labels, reference_class)
+        self.set_params(k)
+
+    def set_params(self, k):
+        """Set the number of nearest neighbors.
+
+        Args:
+            k: Positive integer specifying the number of neighbors to consider.
+
+        Returns:
+            The classifier instance, allowing method chaining.
+
+        Raises:
+            ValueError: If k is not a positive integer or is a boolean.
+        """
+        if isinstance(k, bool) == False:
+            if isinstance(k, int) and k>0:
+                self.k = k
+            else:
+                raise ValueError("k must be a positive integer.")
+        else:
+            raise ValueError("k must be a positive integer.")
+        return self
+
+    def get_params(self):
+        """Return the current classifier parameters.
+
+        Returns:
+            Dictionary containing k, the number of nearest neighbors.
+        """
+        return {"k": self.k}
+
+    def fit(self, X,y):
+        """Store the training data after validating their format and contents.
+
+        Args:
+            X: Numerical training feature matrix of shape
+                (n_samples, n_features). All values must be finite.
+            y: One-dimensional array of class labels of shape (n_samples,).
+                All labels must belong to the set declared at initialization.
+
+        Raises:
+            ValueError: If X or y has an invalid dimension, X contains
+                non-numerical or non-finite values, y contains unknown labels,
+                the numbers of observations do not match, the data are empty,
+                or X has no features.
+        """
+        self._fit_done = False
+
+        X = np.asarray(X)
+        y = np.asarray(y)
+
+        if X.ndim != 2:
+            raise ValueError("X must be two-dimensional.")
+        if np.issubdtype(X.dtype, np.number) == False:
+            raise ValueError("X must be a numerical array.")
+        else:
+            if np.isfinite(X).all() == False:
+                raise ValueError("X must have only finite values.")
+        if y.ndim != 1:
+            raise ValueError("y must be one-dimensional.")
+        if X.shape[0] != y.shape[0]:
+            raise ValueError("The data do not match.")
+        if X.shape[0] == 0 or y.shape[0] == 0 or y.size == 0:
+            raise ValueError("X and y must not be empty.")
+        if X.shape[1] == 0:
+            raise ValueError("X must have at least one feature.")
+        if self._labels is None:
+            self._set_labels(np.unique(y))
+        elif not np.isin(y, self._labels).all():
+            raise ValueError("y contains unknown class labels.")
+
+        self._X_train = X
+        self._y_train = y
+        self._fit_done = True
+
+    def predict(self, X):
+        """Predict class labels using the majority vote of the nearest neighbors.
+
+        For each observation, calculate the Euclidean distances to the training
+        observations, select the k nearest neighbors, and assign the most
+        frequent class among their labels.
+
+        Args:
+            X: Numerical feature matrix of shape
+                (n_new_samples, n_features). The number of features must match
+                the training data, and all values must be finite.
+
+        Returns:
+            Array of predicted class labels of shape (n_new_samples,).
+
+        Raises:
+            ValueError: If the model has not been fitted, X has an invalid
+                dimension, contains non-numerical or non-finite values, is
+                empty, or has a different number of features from the
+                training data.
+        """
+        if self._fit_done == False:
+            raise ValueError("The model must be trained before prediction.")
+
+        X = np.asarray(X)
+
+        if X.ndim != 2:
+            raise ValueError("X must be two-dimensional.")
+        if np.issubdtype(X.dtype, np.number) == False:
+            raise ValueError("X must be a numerical array.")
+        else:
+            if np.isfinite(X).all() == False:
+                raise ValueError("X must have only finite values.")
+        if X.shape[0] == 0:
+            raise ValueError("X must not be empty.")
+        if X.shape[1] != self._X_train.shape[1]:
+            raise ValueError("X must be the same number of features as the training X.") 
+
+        def min_distance(x, k):
+            """Return the indices of the k training observations closest to x.
+
+            Args:
+                x: Feature vector of a single observation.
+                k: Number of nearest neighbors to select.
+
+            Returns:
+                Indices of the k training observations with the smallest
+                Euclidean distances to x.
+            """
+            dist = [sum((x[i]-amostra[i])**2 for i in range(len(x)))**(1/2) for amostra in self._X_train]
+            indice = np.argsort(dist)[:k]
+            return indice
+
+        def class_neighbors(indice):
+            """Retrieve the class labels of the selected neighbors.
+
+            Args:
+                indice: Indices of the selected training observations.
+
+            Returns:
+                Array of class labels corresponding to the selected neighbors.
+            """
+            neighbors = self._y_train[indice]
+            return neighbors
+
+        prediction = [class_neighbors(min_distance(x, self.k)) for x in X]
+
+        def final_class(prediction):
+            """Determine the most frequent class among the neighbors.
+
+            Args:
+                prediction: Array of class labels assigned to the neighbors.
+
+            Returns:
+                Class label with the highest frequency. Ties are resolved by
+                selecting the first class returned by np.unique.
+            """
+            labels, counts = np.unique(prediction, return_counts=True)
+            return labels[np.argmax(counts)]
+
+        predicted_labels = np.array([final_class(neighbors) for neighbors in prediction])
+        return predicted_labels

rbg/Classification/LDA.py

@@ -0,0 +1,187 @@
+import numpy as np
+from rbg.Classification import Classifier
+
+class LDA(Classifier):
+    """Linear discriminant analysis classifier for categorical labels.
+
+    Assumes that all classes share a common covariance matrix and uses
+    class-specific means and prior probabilities to discriminate between
+    classes.
+    """
+
+    def __init__(self, labels, reference_class=None):
+        """Initialize the classifier with the supported class labels.
+
+        Args:
+            labels: Unique class labels supported by the classifier.
+            reference_class: Reference label used to initialize the base
+                classifier.
+        """
+        Classifier.__init__(self, labels, reference_class)
+
+    def fit(self, X, y):
+        """Estimate class means and the shared covariance matrix from training data.
+
+        Args:
+            X: Numerical training feature matrix of shape
+                (n_samples, n_features). All values must be finite.
+            y: One-dimensional array of class labels of shape (n_samples,).
+                All labels must belong to the set declared at initialization.
+
+        Raises:
+            ValueError: If X or y has an invalid dimension, X contains
+                non-numerical or non-finite values, y contains unknown labels,
+                the numbers of observations do not match, X is empty or has no
+                features, fewer than two classes are present, there are not
+                enough samples to estimate the covariance matrix, or the
+                estimated covariance matrix is singular.
+        """
+        self._fit_done = False
+
+        X = np.asarray(X)
+        y = np.asarray(y)
+
+        if X.ndim != 2:
+            raise ValueError("X must be two-dimensional.")
+        if np.issubdtype(X.dtype, np.number) == False:
+            raise ValueError("X must be a numerical array.")
+        else:
+            if np.isfinite(X).all() == False:
+                raise ValueError("X must have only finite values.")
+        if y.ndim != 1:
+            raise ValueError("y must be one-dimensional.")
+        if not np.isin(y, self._labels).all():
+            raise ValueError("y contains unknown class labels.")
+        if X.shape[0] != y.shape[0]:
+            raise ValueError("The data do not match.")
+        if X.shape[0] == 0:
+            raise ValueError("X must not be empty.")
+        if X.shape[1] == 0:
+            raise ValueError("X must have at least one feature.")
+
+        self.labels = np.unique(y)
+        if self.labels.size < 2:
+            raise ValueError("y must be at least two classes.")
+        if X.shape[0] <= self.labels.size:
+            raise ValueError("There must be more samples to estimate covariance.")
+
+        self._X_train = X
+        self._y_train = y
+
+        self._covariance = self.cov_matrix()
+        if np.linalg.matrix_rank(self._covariance) < self._covariance.shape[0]:
+            raise ValueError("The covariance matrix is singular.")
+
+        self._fit_done = True
+
+    def mean_array(self, k):
+        """Calculate the mean feature vector for a given class.
+
+        Args:
+            k: Class label for which the mean is calculated.
+
+        Returns:
+            Mean feature vector of shape (n_features,) for class k.
+
+        Raises:
+            ValueError: If the specified class has no training samples.
+        """
+        x_k = self._X_train[self._y_train == k]
+        if x_k.shape[0] == 0:
+            raise ValueError("The class must have training samples.")
+        mean_k = np.mean(x_k, axis = 0)
+        return mean_k
+
+    def cov_matrix(self):
+        """Estimate the pooled covariance matrix across all training classes.
+
+        Computes the sum of the within-class scatter matrices divided by the
+        total number of observations minus the number of observed classes.
+
+        Returns:
+            Pooled covariance matrix of shape (n_features, n_features).
+        """
+        matriz = np.zeros((self._X_train.shape[1], self._X_train.shape[1]))
+        detours = [self._X_train[self._y_train == k] - self.mean_array(k) for k in self.labels]
+        products = [detour.T @ detour for detour in detours]
+        matriz = np.sum(np.stack(products), axis=0)/(self._y_train.size - self.labels.size)
+        return matriz
+
+    def prior(self, k):
+        """Calculate the empirical prior probability of a given class.
+
+        Args:
+            k: Class label for which the prior probability is calculated.
+
+        Returns:
+            Proportion of training observations belonging to class k.
+        """
+        sum_k = (self._y_train == k).sum()
+        prior_k = sum_k/self._y_train.size
+        return prior_k
+
+    def k_functions(self, k):
+        """Construct the linear discriminant function for a given class.
+
+        The discriminant combines the class mean, the inverse of the shared
+        covariance matrix, and the logarithm of the empirical class prior.
+
+        Args:
+            k: Class label for which the discriminant function is constructed.
+
+        Returns:
+            Callable that evaluates the discriminant function for a feature
+            vector x.
+        """
+        def function_discriminant(x):
+            """Evaluate the linear discriminant score for a feature vector.
+
+            Args:
+                x: Feature vector of shape (n_features,).
+
+            Returns:
+                Discriminant score for class k.
+            """
+            function = (x.T @ np.linalg.inv(self._covariance) @ self.mean_array(k) 
+                    - 1/2 * self.mean_array(k).T @ np.linalg.inv(self._covariance)
+                    @ self.mean_array(k) + np.log(self.prior(k)))
+            return function
+        return function_discriminant
+
+    def predict(self, X):
+        """Predict class labels by maximizing the linear discriminant scores.
+
+        For each observation, evaluates the discriminant function of every
+        observed training class and selects the class with the highest score.
+
+        Args:
+            X: Numerical feature matrix of shape
+                (n_new_samples, n_features). The number of features must match
+                the training data, and all values must be finite.
+
+        Returns:
+            Array of predicted class labels of shape (n_new_samples,).
+
+        Raises:
+            ValueError: If the model has not been fitted, X has an invalid
+                dimension, contains non-numerical or non-finite values, is
+                empty, or has a different number of features from the
+                training data.
+        """
+        X = np.asarray(X)
+        if self._fit_done == False:
+            raise ValueError("The model must be trained before prediction.")
+        if X.ndim != 2:
+            raise ValueError("X must be two-dimensional.")
+        if np.issubdtype(X.dtype, np.number) == False:
+            raise ValueError("X must be a numerical array.")
+        else:
+            if np.isfinite(X).all() == False:
+                raise ValueError("X must have only finite values.")
+        if X.shape[0] == 0:
+            raise ValueError("X must not be empty.")
+        if X.shape[1] != self._X_train.shape[1]:
+            raise ValueError("X must be the same number of features as the training X.") 
+
+        functions_class = np.array([self.labels[np.argmax([self.k_functions(k)(x) for k in self.labels])]for x in X])
+        return functions_class

rbg/Classification/Logistic.py

@@ -0,0 +1,189 @@
+import numpy as np
+from rbg.Regression import GLM
+from rbg.Utilities import ExponentialFamily
+from .classifier import Classifier
+
+class Logistic(Classifier, GLM):
+    """Multinomial logistic classifier using a reference-class GLM.
+
+    Estimate K-1 coefficient vectors, fixing the reference-class coefficients
+    to zero. Probability columns follow self._labels, with the reference last.
+    Requires a GLM and Fisher-scoring solver supporting multivariate responses.
+    """
+
+    def __init__(self, classes=None, reference_class=None, fit_intercept=True, inference=False, *, labels=None):
+        """Configure labels and initialize the categorical GLM.
+
+        Args:
+            labels: Compatibility alias for classes.
+            classes: Optional unique class labels. If None, they are identified
+                automatically during fitting.
+            reference_class: Reference label, defaulting to the first supplied.
+            fit_intercept: Whether to estimate an intercept for each modeled class.
+            inference: Whether the GLM computes coefficient covariance during fit.
+
+        Raises:
+            ValueError: If class labels or the reference label are invalid.
+        """
+        if labels is not None:
+            if classes is not None:
+                raise ValueError("Provide only one of classes or labels.")
+            classes = labels
+        Classifier.__init__(self, classes, reference_class)
+        self._fit_intercept = fit_intercept
+        self._inference = inference
+        self._glm_initialized = False
+
+        if classes is not None:
+            GLM.__init__(self, family=self._make_family(),fit_intercept=fit_intercept, inference=inference)
+            self._glm_initialized = True
+
+    def fit(self, X,y):
+        """Encode class labels and delegate coefficient estimation to the GLM.
+
+        Args:
+            X: Feature matrix of shape (n_samples, p_features), without an
+                automatically generated intercept column.
+            y: Original class labels of shape (n_samples,).
+
+        Returns:
+            Coefficient matrix of shape (p, K-1), where p includes the intercept when enabled.
+
+        Raises:
+            ValueError: If y is not one-dimensional, contains unknown labels,
+            or training inputs fail GLM validation.
+        """
+        if hasattr(X, "to_numpy"):
+            X = X.to_numpy()
+        if hasattr(y, "to_numpy"):
+            y = y.to_numpy()
+
+        X = np.asarray(X)
+        y = np.asarray(y)
+
+        if y.ndim != 1:
+            raise ValueError("y must be one-dimensional.")
+        if X.shape[0] != y.shape[0]:
+            raise ValueError("X and y must have the same number of observations.")
+        observed_labels = np.unique(y)
+        if self._labels is None or not np.isin(observed_labels, self.labels).all():
+            labels = observed_labels if self.labels is None else np.unique(np.concatenate((self.labels, observed_labels)))
+            self._set_labels(labels, self._reference_class)
+            self._glm_initialized = False
+        if len(self._labels) < 2:
+            raise ValueError("At least two classes are required.")
+        if not self._glm_initialized:
+            GLM.__init__(self, family=self._make_family(),fit_intercept=self._fit_intercept,inference=self._inference)
+            self._glm_initialized = True
+        if not np.isin(y, self.labels).all():
+            raise ValueError("y contains unknown class labels.")
+
+        Y = (y[:,None] == self._labels[:-1][None,:]).astype(float)
+        return GLM.fit(self, X, Y)
+
+    def predict_proba(self, X):
+        """Return probabilities for all classes, including the reference.
+
+        Args:
+            X: Matrix of shape (n_new_samples, p_features), in training order.
+
+        Returns:
+            Probability matrix of shape (n_new_samples, K). Columns correspond
+            to self._labels; the final column is the reference probability.
+
+        Raises:
+            RuntimeError: If the model has not been fitted.
+            ValueError: If X has an incompatible shape.
+        """
+        if hasattr(X, "to_numpy"):
+            X = X.to_numpy()
+
+        pi = GLM.predict(self, X)
+        pi_reference = 1 - pi.sum(axis=1, keepdims=True)
+        return np.column_stack((pi, pi_reference))
+
+    def predict(self, X):
+        """Return the label with the highest probability for each observation.
+
+        Args:
+            X: Feature matrix of shape (n_new_samples, p_features).
+
+        Returns:
+            Original class labels of shape (n_new_samples,). Ties select the
+            first maximum in the stored class order.
+
+        Raises:
+            RuntimeError: If the model has not been fitted.
+            ValueError: If X has an incompatible shape.
+        """
+        pi = self.predict_proba(X)
+        return self._labels[np.argmax(pi, axis=1)]
+
+    def k_function(self, k):
+        """Return the fitted probability function for class k."""
+        if not self._fit_done:
+            raise RuntimeError("The model has not been fitted yet.")
+        matches = np.flatnonzero(self._labels == k)
+        if not matches.size:
+            raise ValueError("Unknown class label.")
+        column = int(matches[0])
+
+        def probability(X):
+            X = np.asarray(X)
+            single = X.ndim == 1
+            result = self.predict_proba(X[None, :] if single else X)[:, column]
+            return float(result[0]) if single else result
+
+        return probability
+
+    def k_coef(self, k):
+        """Return class coefficients, or zeros for the reference class."""
+        if not self._fit_done:
+            raise RuntimeError("The model has not been fitted yet.")
+        matches = np.flatnonzero(self._labels == k)
+        if not matches.size:
+            raise ValueError("Unknown class label.")
+        column = int(matches[0])
+        if column == len(self._labels) - 1:
+            return np.zeros(self._beta.shape[0])
+        return self._beta[:, column].copy()
+
+    inference = GLM.inference
+    
+    def _make_family(self):
+        """Build the categorical exponential family with dispersion fixed at one.
+
+        Returns:
+            ExponentialFamily configured with the cumulant, gradient, Hessian,
+            and inverse mean mapping for K-1 non-reference components.
+        """
+        self._K = len(self._labels)
+        def b(theta):
+            """Return log(1 + sum(exp(theta))) per row of an (n, K-1) matrix."""
+            return np.logaddexp.reduce(
+                np.column_stack((np.zeros(len(theta)), theta)), axis=1
+            )
+        def b_prime(theta):
+            """Return the (n, K-1) probabilities of the non-reference classes."""
+            pi = np.exp(theta - b(theta)[:, None])
+            return pi
+        def b_second(theta):
+            """Return Hessians diag(pi) - pi*pi.T, with shape (n, K-1, K-1)."""
+            pi = b_prime(theta)
+            n, n_components = pi.shape
+            cov_matrix = np.zeros((n, n_components, n_components))
+            for i in range(n):
+                cov_matrix[i] = np.diag(pi[i]) - np.outer(pi[i], pi[i])
+            return cov_matrix
+        def h_inverse(mu):
+            """Return log-odds relative to the reference for each row of mu.
+
+            All supplied probabilities and the remaining reference probability
+            must be strictly positive. The caller must satisfy this domain.
+            """
+            pi = mu
+            pi_reference = 1 - np.sum(pi, axis=1, keepdims=True)
+            theta = np.log(pi) - np.log(pi_reference)
+            return theta
+
+        return ExponentialFamily(b,b_prime,b_second,h_inverse)