Toggle Menu
Prev Up Next

scikit-learn 1.3.2
Other versions

Please cite us if you use the software.

# `sklearn.decomposition`.dict_learning_online

sklearn.decomposition.dict_learning_online(X, n_components=2, *, alpha=1, n_iter='deprecated', max_iter=None, return_code=True, dict_init=None, callback=None, batch_size=256, verbose=False, shuffle=True, n_jobs=None, method='lars', iter_offset='deprecated', random_state=None, return_inner_stats='deprecated', inner_stats='deprecated', return_n_iter='deprecated', positive_dict=False, positive_code=False, method_max_iter=1000, tol=0.001, max_no_improvement=10)

  Solve a dictionary learning matrix factorization problem online.

  Finds the best dictionary and the corresponding sparse code for approximating the data matrix X by solving:

      (U^*, V^*) = argmin 0.5 || X - U V ||_Fro^2 + alpha * || U ||_1,1
                   (U,V)
                   with || V_k ||_2 = 1 for all  0 <= k < n_components

  where V is the dictionary and U is the sparse code. ||.||_Fro stands for the Frobenius norm and ||.||_1,1 stands for the entry-wise matrix norm which is the sum of the absolute values of all the entries in the matrix. This is accomplished by repeatedly iterating over mini-batches by slicing the input data.

  Read more in the User Guide.

  Parameters:
    X ndarray of shape (n_samples, n_features)

      Data matrix.

    n_components int or None, default=2

      Number of dictionary atoms to extract. If None, then `n_components` is set to `n_features`.

    alpha float, default=1

      Sparsity controlling parameter.

    n_iter int, default=100

      Number of mini-batch iterations to perform.

      Deprecated since version 1.1: `n_iter` is deprecated in 1.1 and will be removed in 1.4. Use `max_iter` instead.

    max_iter int, default=None

      Maximum number of iterations over the complete dataset before stopping independently of any early stopping criterion heuristics. If `max_iter` is not None, `n_iter` is ignored.

      New in version 1.1.

    return_code bool, default=True

      Whether to also return the code U or just the dictionary `V`.

    dict_init ndarray of shape (n_components, n_features), default=None

      Initial values for the dictionary for warm restart scenarios. If `None`, the initial values for the dictionary are created with an SVD decomposition of the data via `randomized_svd`.

    callback callable, default=None

      A callable that gets invoked at the end of each iteration.

    batch_size int, default=256

      The number of samples to take in each batch.

      Changed in version 1.3: The default value of `batch_size` changed from 3 to 256 in version 1.3.

    verbose bool, default=False

      To control the verbosity of the procedure.

    shuffle bool, default=True

      Whether to shuffle the data before splitting it in batches.

    n_jobs int, default=None

      Number of parallel jobs to run. `None` means 1 unless in a `joblib.parallel_backend` context. `-1` means using all processors. See Glossary for more details.

    method{‘lars’, ‘cd’}, default=’lars’

      - `'lars'`: uses the least angle regression method to solve the lasso problem (`linear_model.lars_path`);

      - `'cd'`: uses the coordinate descent method to compute the Lasso solution (`linear_model.Lasso`). Lars will be faster if the estimated components are sparse.

    iter_offset int, default=0

      Number of previous iterations completed on the dictionary used for initialization.

      Deprecated since version 1.1: `iter_offset` serves internal purpose only and will be removed in 1.4.

    random_state int, RandomState instance or None, default=None

      Used for initializing the dictionary when `dict_init` is not specified, randomly shuffling the data when `shuffle` is set to `True`, and updating the dictionary. Pass an int for reproducible results across multiple function calls. See Glossary.

    return_inner_stats bool, default=False

      Return the inner statistics A (dictionary covariance) and B (data approximation). Useful to restart the algorithm in an online setting. If `return_inner_stats` is `True`, `return_code` is ignored.

      Deprecated since version 1.1: `return_inner_stats` serves internal purpose only and will be removed in 1.4.

    inner_stats tuple of (A, B) ndarrays, default=None

      Inner sufficient statistics that are kept by the algorithm. Passing them at initialization is useful in online settings, to avoid losing the history of the evolution. `A` `(n_components, n_components)` is the dictionary covariance matrix. `B` `(n_features, n_components)` is the data approximation matrix.

      Deprecated since version 1.1: `inner_stats` serves internal purpose only and will be removed in 1.4.

    return_n_iter bool, default=False

      Whether or not to return the number of iterations.

      Deprecated since version 1.1: `return_n_iter` will be removed in 1.4 and n_iter will never be returned.

    positive_dict bool, default=False

      Whether to enforce positivity when finding the dictionary.

      New in version 0.20.

    positive_code bool, default=False

      Whether to enforce positivity when finding the code.

      New in version 0.20.

    method_max_iter int, default=1000

      Maximum number of iterations to perform when solving the lasso problem.

      New in version 0.22.

    tol float, default=1e-3

      Control early stopping based on the norm of the differences in the dictionary between 2 steps. Used only if `max_iter` is not None.

      To disable early stopping based on changes in the dictionary, set `tol` to 0.0.

      New in version 1.1.

    max_no_improvement int, default=10

      Control early stopping based on the consecutive number of mini batches that does not yield an improvement on the smoothed cost function. Used only if `max_iter` is not None.

      To disable convergence detection based on cost function, set `max_no_improvement` to None.

      New in version 1.1.

  Returns:
    code ndarray of shape (n_samples, n_components),

      The sparse code (only returned if `return_code=True`).

    dictionary ndarray of shape (n_components, n_features),

      The solutions to the dictionary learning problem.

    n_iter int

      Number of iterations run. Returned only if `return_n_iter` is set to `True`.

  See also

  `dict_learning`

    Solve a dictionary learning matrix factorization problem.

  `DictionaryLearning`

    Find a dictionary that sparsely encodes data.

  `MiniBatchDictionaryLearning`

    A faster, less accurate, version of the dictionary learning algorithm.

  `SparsePCA`

    Sparse Principal Components Analysis.

  `MiniBatchSparsePCA`

    Mini-batch Sparse Principal Components Analysis.