maxframe 2.4.0rc1__cp312-cp312-win32.whl

maxframe/learn/datasets/samples_generator.py

@@ -0,0 +1,628 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numbers
+from collections.abc import Iterable
+
+import numpy as np
+
+from ... import tensor as mt
+from ...tensor.utils import check_random_state
+from ..utils import shuffle as util_shuffle
+from ..utils.validation import check_array
+
+
+def make_classification(
+    n_samples=100,
+    n_features=20,
+    n_informative=2,
+    n_redundant=2,
+    n_repeated=0,
+    n_classes=2,
+    n_clusters_per_class=2,
+    weights=None,
+    flip_y=0.01,
+    class_sep=1.0,
+    hypercube=True,
+    shift=0.0,
+    scale=1.0,
+    shuffle=True,
+    random_state=None,
+):
+    """Generate a random n-class classification problem.
+
+    This initially creates clusters of points normally distributed (std=1)
+    about vertices of an ``n_informative``-dimensional hypercube with sides of
+    length ``2*class_sep`` and assigns an equal number of clusters to each
+    class. It introduces interdependence between these features and adds
+    various types of further noise to the data.
+
+    Without shuffling, ``X`` horizontally stacks features in the following
+    order: the primary ``n_informative`` features, followed by ``n_redundant``
+    linear combinations of the informative features, followed by ``n_repeated``
+    duplicates, drawn randomly with replacement from the informative and
+    redundant features. The remaining features are filled with random noise.
+    Thus, without shuffling, all useful features are contained in the columns
+    ``X[:, :n_informative + n_redundant + n_repeated]``.
+
+    Read more in the :ref:`User Guide <sample_generators>`.
+
+    Parameters
+    ----------
+    n_samples : int, optional (default=100)
+        The number of samples.
+
+    n_features : int, optional (default=20)
+        The total number of features. These comprise ``n_informative``
+        informative features, ``n_redundant`` redundant features,
+        ``n_repeated`` duplicated features and
+        ``n_features-n_informative-n_redundant-n_repeated`` useless features
+        drawn at random.
+
+    n_informative : int, optional (default=2)
+        The number of informative features. Each class is composed of a number
+        of gaussian clusters each located around the vertices of a hypercube
+        in a subspace of dimension ``n_informative``. For each cluster,
+        informative features are drawn independently from  N(0, 1) and then
+        randomly linearly combined within each cluster in order to add
+        covariance. The clusters are then placed on the vertices of the
+        hypercube.
+
+    n_redundant : int, optional (default=2)
+        The number of redundant features. These features are generated as
+        random linear combinations of the informative features.
+
+    n_repeated : int, optional (default=0)
+        The number of duplicated features, drawn randomly from the informative
+        and the redundant features.
+
+    n_classes : int, optional (default=2)
+        The number of classes (or labels) of the classification problem.
+
+    n_clusters_per_class : int, optional (default=2)
+        The number of clusters per class.
+
+    weights : list of floats or None (default=None)
+        The proportions of samples assigned to each class. If None, then
+        classes are balanced. Note that if ``len(weights) == n_classes - 1``,
+        then the last class weight is automatically inferred.
+        More than ``n_samples`` samples may be returned if the sum of
+        ``weights`` exceeds 1.
+
+    flip_y : float, optional (default=0.01)
+        The fraction of samples whose class are randomly exchanged. Larger
+        values introduce noise in the labels and make the classification
+        task harder.
+
+    class_sep : float, optional (default=1.0)
+        The factor multiplying the hypercube size.  Larger values spread
+        out the clusters/classes and make the classification task easier.
+
+    hypercube : boolean, optional (default=True)
+        If True, the clusters are put on the vertices of a hypercube. If
+        False, the clusters are put on the vertices of a random polytope.
+
+    shift : float, array of shape [n_features] or None, optional (default=0.0)
+        Shift features by the specified value. If None, then features
+        are shifted by a random value drawn in [-class_sep, class_sep].
+
+    scale : float, array of shape [n_features] or None, optional (default=1.0)
+        Multiply features by the specified value. If None, then features
+        are scaled by a random value drawn in [1, 100]. Note that scaling
+        happens after shifting.
+
+    shuffle : boolean, optional (default=True)
+        Shuffle the samples and the features.
+
+    random_state : int, RandomState instance or None (default)
+        Determines random number generation for dataset creation. Pass an int
+        for reproducible output across multiple function calls.
+        See :term:`Glossary <random_state>`.
+
+    Returns
+    -------
+    X : tensor of shape [n_samples, n_features]
+        The generated samples.
+
+    y : tensor of shape [n_samples]
+        The integer labels for class membership of each sample.
+
+    Notes
+    -----
+    The algorithm is adapted from Guyon [1] and was designed to generate
+    the "Madelon" dataset.
+
+    References
+    ----------
+    .. [1] I. Guyon, "Design of experiments for the NIPS 2003 variable
+           selection benchmark", 2003.
+
+    See also
+    --------
+    make_blobs: simplified variant
+    make_multilabel_classification: unrelated generator for multilabel tasks
+    """
+    from sklearn.datasets._samples_generator import _generate_hypercube
+
+    generator = check_random_state(random_state)
+    np_generator = generator.to_numpy()
+
+    # Count features, clusters and samples
+    if n_informative + n_redundant + n_repeated > n_features:
+        raise ValueError(
+            "Number of informative, redundant and repeated "
+            "features must sum to less than the number of total"
+            " features"
+        )
+    # Use log2 to avoid overflow errors
+    if n_informative < np.log2(n_classes * n_clusters_per_class):
+        raise ValueError(
+            "n_classes * n_clusters_per_class must"
+            " be smaller or equal 2 ** n_informative"
+        )
+    if weights and len(weights) not in [n_classes, n_classes - 1]:
+        raise ValueError("Weights specified but incompatible with number of classes.")
+
+    n_useless = n_features - n_informative - n_redundant - n_repeated
+    n_clusters = n_classes * n_clusters_per_class
+
+    if weights and len(weights) == (n_classes - 1):
+        weights = weights + [1.0 - sum(weights)]
+
+    if weights is None:
+        weights = [1.0 / n_classes] * n_classes
+        weights[-1] = 1.0 - sum(weights[:-1])
+
+    # Distribute samples among clusters by weight
+    n_samples_per_cluster = [
+        int(n_samples * weights[k % n_classes] / n_clusters_per_class)
+        for k in range(n_clusters)
+    ]
+
+    for i in range(n_samples - sum(n_samples_per_cluster)):
+        n_samples_per_cluster[i % n_clusters] += 1
+
+    # Initialize X and y
+    X = mt.zeros((n_samples, n_features))
+    y = mt.zeros(n_samples, dtype=np.dtype(int))
+
+    # Build the polytope whose vertices become cluster centroids
+    centroids = _generate_hypercube(n_clusters, n_informative, np_generator).astype(
+        float, copy=False
+    )
+    centroids *= 2 * class_sep
+    centroids -= class_sep
+    if not hypercube:
+        centroids *= np_generator.rand(n_clusters, 1)
+        centroids *= np_generator.rand(1, n_informative)
+
+    # Initially draw informative features from the standard normal
+    X[:, :n_informative] = generator.randn(n_samples, n_informative)
+
+    # Create each cluster; a variant of make_blobs
+    stop = 0
+    for k, centroid in enumerate(centroids):
+        start, stop = stop, stop + n_samples_per_cluster[k]
+        y[start:stop] = k % n_classes  # assign labels
+        X_k = X[start:stop, :n_informative]  # slice a view of the cluster
+
+        A = 2 * generator.rand(n_informative, n_informative) - 1
+        X_k[...] = mt.dot(X_k, A)  # introduce random covariance
+
+        X_k += centroid  # shift the cluster to a vertex
+
+    # Create redundant features
+    if n_redundant > 0:
+        B = 2 * generator.rand(n_informative, n_redundant) - 1
+        X[:, n_informative : n_informative + n_redundant] = mt.dot(
+            X[:, :n_informative], B
+        )
+
+    # Repeat some features
+    if n_repeated > 0:
+        n = n_informative + n_redundant
+        indices = ((n - 1) * generator.rand(n_repeated) + 0.5).astype(mt.intp)
+        X[:, n : n + n_repeated] = X[:, indices]
+
+    # Fill useless features
+    if n_useless > 0:
+        X[:, -n_useless:] = generator.randn(n_samples, n_useless)
+
+    # Randomly replace labels
+    if flip_y >= 0.0:
+        flip_mask = generator.rand(n_samples) < flip_y
+        y = mt.where(flip_mask, generator.randint(n_classes, size=len(y)), y)
+
+    # Randomly shift and scale
+    if shift is None:
+        shift = (2 * generator.rand(n_features) - 1) * class_sep
+    X += shift
+
+    if scale is None:
+        scale = 1 + 100 * generator.rand(n_features)
+    X *= scale
+
+    if shuffle:
+        # Randomly permute samples
+        X, y = util_shuffle(X, y, random_state=generator, axes=(0, 1))
+
+    return X, y
+
+
+def make_regression(
+    n_samples=100,
+    n_features=100,
+    *,
+    n_informative=10,
+    n_targets=1,
+    bias=0.0,
+    effective_rank=None,
+    tail_strength=0.5,
+    noise=0.0,
+    shuffle=True,
+    coef=False,
+    random_state=None,
+):
+    """Generate a random regression problem.
+
+    The input set can either be well conditioned (by default) or have a low
+    rank-fat tail singular profile. See :func:`make_low_rank_matrix` for
+    more details.
+
+    The output is generated by applying a (potentially biased) random linear
+    regression model with `n_informative` nonzero regressors to the previously
+    generated input and some gaussian centered noise with some adjustable
+    scale.
+
+    Read more in the :ref:`User Guide <sample_generators>`.
+
+    Parameters
+    ----------
+    n_samples : int, default=100
+        The number of samples.
+
+    n_features : int, default=100
+        The number of features.
+
+    n_informative : int, default=10
+        The number of informative features, i.e., the number of features used
+        to build the linear model used to generate the output.
+
+    n_targets : int, default=1
+        The number of regression targets, i.e., the dimension of the y output
+        vector associated with a sample. By default, the output is a scalar.
+
+    bias : float, default=0.0
+        The bias term in the underlying linear model.
+
+    effective_rank : int, default=None
+        if not None:
+            The approximate number of singular vectors required to explain most
+            of the input data by linear combinations. Using this kind of
+            singular spectrum in the input allows the generator to reproduce
+            the correlations often observed in practice.
+        if None:
+            The input set is well conditioned, centered and gaussian with
+            unit variance.
+
+    tail_strength : float, default=0.5
+        The relative importance of the fat noisy tail of the singular values
+        profile if `effective_rank` is not None. When a float, it should be
+        between 0 and 1.
+
+    noise : float, default=0.0
+        The standard deviation of the gaussian noise applied to the output.
+
+    shuffle : bool, default=True
+        Shuffle the samples and the features.
+
+    coef : bool, default=False
+        If True, the coefficients of the underlying linear model are returned.
+
+    random_state : int, RandomState instance or None, default=None
+        Determines random number generation for dataset creation. Pass an int
+        for reproducible output across multiple function calls.
+        See :term:`Glossary <random_state>`.
+
+    Returns
+    -------
+    X : tensor of shape (n_samples, n_features)
+        The input samples.
+
+    y : tensor of shape (n_samples,) or (n_samples, n_targets)
+        The output values.
+
+    coef : tensor of shape (n_features,) or (n_features, n_targets)
+        The coefficient of the underlying linear model. It is returned only if
+        coef is True.
+    """
+    n_informative = min(n_features, n_informative)
+    generator = check_random_state(random_state)
+
+    if effective_rank is None:
+        # Randomly generate a well conditioned input set
+        X = generator.randn(n_samples, n_features)
+
+    else:
+        # Randomly generate a low rank, fat tail input set
+        X = make_low_rank_matrix(
+            n_samples=n_samples,
+            n_features=n_features,
+            effective_rank=effective_rank,
+            tail_strength=tail_strength,
+            random_state=generator,
+        )
+
+    # Generate a ground truth model with only n_informative features being non
+    # zeros (the other features are not correlated to y and should be ignored
+    # by a sparsifying regularizers such as L1 or elastic net)
+    ground_truth = mt.zeros((n_features, n_targets))
+    ground_truth[:n_informative, :] = 100 * generator.rand(n_informative, n_targets)
+
+    y = mt.dot(X, ground_truth) + bias
+
+    # Add noise
+    if noise > 0.0:
+        y += generator.normal(scale=noise, size=y.shape)
+
+    # Randomly permute samples and features
+    if shuffle:
+        X, y = util_shuffle(X, y, random_state=generator)
+
+        indices = mt.arange(n_features)
+        generator.shuffle(indices)
+        X[:, :] = X[:, indices]
+        ground_truth = ground_truth[indices]
+
+    y = mt.squeeze(y)
+
+    if coef:
+        return X, y, mt.squeeze(ground_truth)
+
+    else:
+        return X, y
+
+
+def make_blobs(
+    n_samples=100,
+    n_features=2,
+    centers=None,
+    cluster_std=1.0,
+    center_box=(-10.0, 10.0),
+    shuffle=True,
+    random_state=None,
+):
+    """Generate isotropic Gaussian blobs for clustering.
+
+    Read more in the :ref:`User Guide <sample_generators>`.
+
+    Parameters
+    ----------
+    n_samples : int or array-like, optional (default=100)
+        If int, it is the total number of points equally divided among
+        clusters.
+        If array-like, each element of the sequence indicates
+        the number of samples per cluster.
+
+    n_features : int, optional (default=2)
+        The number of features for each sample.
+
+    centers : int or array of shape [n_centers, n_features], optional
+        (default=None)
+        The number of centers to generate, or the fixed center locations.
+        If n_samples is an int and centers is None, 3 centers are generated.
+        If n_samples is array-like, centers must be
+        either None or an array of length equal to the length of n_samples.
+
+    cluster_std : float or sequence of floats, optional (default=1.0)
+        The standard deviation of the clusters.
+
+    center_box : pair of floats (min, max), optional (default=(-10.0, 10.0))
+        The bounding box for each cluster center when centers are
+        generated at random.
+
+    shuffle : boolean, optional (default=True)
+        Shuffle the samples.
+
+    random_state : int, RandomState instance or None (default)
+        Determines random number generation for dataset creation. Pass an int
+        for reproducible output across multiple function calls.
+        See :term:`Glossary <random_state>`.
+
+    Returns
+    -------
+    X : tensor of shape [n_samples, n_features]
+        The generated samples.
+
+    y : tensor of shape [n_samples]
+        The integer labels for cluster membership of each sample.
+
+    Examples
+    --------
+    >>> from maxframe.learn.datasets import make_blobs
+    >>> X, y = make_blobs(n_samples=10, centers=3, n_features=2,
+    ...                   random_state=0)
+    >>> print(X.shape)
+    (10, 2)
+    >>> y
+    array([0, 0, 1, 0, 2, 2, 2, 1, 1, 0])
+    >>> X, y = make_blobs(n_samples=[3, 3, 4], centers=None, n_features=2,
+    ...                   random_state=0)
+    >>> print(X.shape)
+    (10, 2)
+    >>> y
+    array([0, 1, 2, 0, 2, 2, 2, 1, 1, 0])
+
+    See also
+    --------
+    make_classification: a more intricate variant
+    """
+    from ..utils.checks import AssertAllFinite
+
+    generator = check_random_state(random_state)
+
+    if isinstance(n_samples, numbers.Integral):
+        # Set n_centers by looking at centers arg
+        if centers is None:
+            centers = 3
+
+        if isinstance(centers, numbers.Integral):
+            n_centers = centers
+            centers = generator.uniform(
+                center_box[0], center_box[1], size=(n_centers, n_features)
+            )
+
+        else:
+            centers = check_array(centers)
+            n_features = centers.shape[1]
+            n_centers = centers.shape[0]
+
+    else:
+        # Set n_centers by looking at [n_samples] arg
+        n_centers = len(n_samples)
+        if centers is None:
+            centers = generator.uniform(
+                center_box[0], center_box[1], size=(n_centers, n_features)
+            )
+        try:
+            assert len(centers) == n_centers
+        except TypeError:
+            raise ValueError(
+                f"Parameter `centers` must be array-like. Got {centers!r} instead"
+            )
+        except AssertionError:
+            raise ValueError(
+                "Length of `n_samples` not consistent"
+                f" with number of centers. Got n_samples = {n_samples} "
+                f"and centers = {centers}"
+            )
+        else:
+            centers = check_array(centers)
+            n_features = centers.shape[1]
+
+    # stds: if cluster_std is given as list, it must be consistent
+    # with the n_centers
+    if hasattr(cluster_std, "__len__") and len(cluster_std) != n_centers:
+        if isinstance(centers.op, AssertAllFinite):
+            centers = centers.op.inputs[0]
+        raise ValueError(
+            "Length of `clusters_std` not consistent with "
+            f"number of centers. Got centers = {centers} "
+            f"and cluster_std = {cluster_std}"
+        )
+
+    if isinstance(cluster_std, numbers.Real):
+        cluster_std = mt.full(len(centers), cluster_std)
+
+    X = []
+    y = []
+
+    if isinstance(n_samples, Iterable):
+        n_samples_per_center = n_samples
+    else:
+        n_samples_per_center = [int(n_samples // n_centers)] * n_centers
+
+        for i in range(n_samples % n_centers):
+            n_samples_per_center[i] += 1
+
+    for i, (n, std) in enumerate(zip(n_samples_per_center, cluster_std)):
+        if n == 0:
+            continue
+        X.append(generator.normal(loc=centers[i], scale=std, size=(n, n_features)))
+        y += [i] * n
+
+    X = mt.concatenate(X)
+    y = mt.array(y)
+
+    if shuffle:
+        X, y = util_shuffle(X, y, random_state=generator)
+
+    return X, y
+
+
+def make_low_rank_matrix(
+    n_samples=100,
+    n_features=100,
+    effective_rank=10,
+    tail_strength=0.5,
+    random_state=None,
+    chunk_size=None,
+):
+    """Generate a mostly low rank matrix with bell-shaped singular values
+
+    Most of the variance can be explained by a bell-shaped curve of width
+    effective_rank: the low rank part of the singular values profile is::
+
+        (1 - tail_strength) * exp(-1.0 * (i / effective_rank) ** 2)
+
+    The remaining singular values' tail is fat, decreasing as::
+
+        tail_strength * exp(-0.1 * i / effective_rank).
+
+    The low rank part of the profile can be considered the structured
+    signal part of the data while the tail can be considered the noisy
+    part of the data that cannot be summarized by a low number of linear
+    components (singular vectors).
+
+    This kind of singular profiles is often seen in practice, for instance:
+     - gray level pictures of faces
+     - TF-IDF vectors of text documents crawled from the web
+
+    Read more in the :ref:`User Guide <sample_generators>`.
+
+    Parameters
+    ----------
+    n_samples : int, optional (default=100)
+        The number of samples.
+
+    n_features : int, optional (default=100)
+        The number of features.
+
+    effective_rank : int, optional (default=10)
+        The approximate number of singular vectors required to explain most of
+        the data by linear combinations.
+
+    tail_strength : float between 0.0 and 1.0, optional (default=0.5)
+        The relative importance of the fat noisy tail of the singular values
+        profile.
+
+    random_state : int, RandomState instance or None (default)
+        Determines random number generation for dataset creation. Pass an int
+        for reproducible output across multiple function calls.
+        See :term:`Glossary <random_state>`.
+
+    chunk_size : int or tuple of int or tuple of ints, optional
+        Desired chunk size on each dimension
+
+    Returns
+    -------
+    X : array of shape [n_samples, n_features]
+        The matrix.
+    """
+    generator = check_random_state(random_state)
+    n = min(n_samples, n_features)
+
+    # Random (ortho normal) vectors
+    u, _ = mt.linalg.qr(generator.randn(n_samples, n, chunk_size=chunk_size))
+    v, _ = mt.linalg.qr(generator.randn(n_features, n, chunk_size=chunk_size))
+
+    # Index of the singular values
+    singular_ind = mt.arange(n, dtype=mt.float64, chunk_size=chunk_size)
+
+    # Build the singular profile by assembling signal and noise components
+    low_rank = (1 - tail_strength) * mt.exp(-1.0 * (singular_ind / effective_rank) ** 2)
+    tail = tail_strength * mt.exp(-0.1 * singular_ind / effective_rank)
+    s = mt.identity(n) * (low_rank + tail)
+
+    return mt.dot(mt.dot(u, s), v.T)

maxframe/learn/linear_model/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from ._lin_reg import LinearRegression