Skip to content

DOC Improved clarity, consistency and formatting for fastica/FastICA docstrings #23309

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
May 23, 2022
Merged

DOC Improved clarity, consistency and formatting for fastica/FastICA docstrings #23309

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b46dace
Improved clarity, consistency and formatting for FastICA docstrings
Micky774 May 8, 2022
8e33404
Updated wording
Micky774 May 12, 2022
917f084
Merge branch 'main' into docstring_format
Micky774 May 12, 2022
9ac8d73
Merge branch 'main' into docstring_format
Micky774 May 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 34 additions & 28 deletions sklearn/decomposition/_fastica.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,22 +180,23 @@ def fastica(
`n_features` is the number of features.

n_components : int, default=None
Number of components to extract. If None no dimension reduction
is performed.
Number of components to use. If None is passed, all are used.

algorithm : {'parallel', 'deflation'}, default='parallel'
Apply a parallel or deflational FASTICA algorithm.
Specify which algorithm to use for FastICA.

whiten : str or bool, default="warn"
Specify the whitening strategy to use.
If 'arbitrary-variance' (default), a whitening with variance arbitrary is used.
If 'unit-variance', the whitening matrix is rescaled to ensure that each
recovered source has unit variance.
If False, the data is already considered to be whitened, and no
whitening is performed.

- If 'arbitrary-variance' (default), a whitening with variance
arbitrary is used.
- If 'unit-variance', the whitening matrix is rescaled to ensure that
each recovered source has unit variance.
- If False, the data is already considered to be whitened, and no
whitening is performed.

.. deprecated:: 1.1
From version 1.3, `whiten='unit-variance'` will be used by default.
Starting in v1.3, `whiten='unit-variance'` will be used by default.
`whiten=True` is deprecated from 1.1 and will raise ValueError in 1.3.
Use `whiten=arbitrary-variance` instead.

Expand All @@ -206,10 +207,10 @@ def fastica(
You can also provide your own function. It should return a tuple
containing the value of the function, and of its derivative, in the
point. The derivative should be averaged along its last dimension.
Example:
Example::

def my_g(x):
return x ** 3, np.mean(3 * x ** 2, axis=-1)
def my_g(x):
return x ** 3, (3 * x ** 2).mean(axis=-1)

fun_args : dict, default=None
Arguments to send to the functional form.
Expand All @@ -219,13 +220,13 @@ def my_g(x):
max_iter : int, default=200
Maximum number of iterations to perform.

tol : float, default=1e-04
tol : float, default=1e-4
A positive scalar giving the tolerance at which the
un-mixing matrix is considered to have converged.

w_init : ndarray of shape (n_components, n_components), default=None
Initial un-mixing array of dimension (n.comp,n.comp).
If None (default) then an array of normal r.v.'s is used.
Initial un-mixing array. If `w_init=None`, then an array of values
drawn from a normal distribution is used.

random_state : int, RandomState instance or None, default=None
Used to initialize ``w_init`` when not specified, with a
Expand Down Expand Up @@ -332,18 +333,20 @@ class FastICA(_ClassNamePrefixFeaturesOutMixin, TransformerMixin, BaseEstimator)
Number of components to use. If None is passed, all are used.

algorithm : {'parallel', 'deflation'}, default='parallel'
Apply parallel or deflational algorithm for FastICA.
Specify which algorithm to use for FastICA.

whiten : str or bool, default="warn"
Specify the whitening strategy to use.
If 'arbitrary-variance' (default), a whitening with variance arbitrary is used.
If 'unit-variance', the whitening matrix is rescaled to ensure that each
recovered source has unit variance.
If False, the data is already considered to be whitened, and no
whitening is performed.

- If 'arbitrary-variance' (default), a whitening with variance
arbitrary is used.
- If 'unit-variance', the whitening matrix is rescaled to ensure that
each recovered source has unit variance.
- If False, the data is already considered to be whitened, and no
whitening is performed.

.. deprecated:: 1.1
From version 1.3 whiten='unit-variance' will be used by default.
Starting in v1.3, `whiten='unit-variance'` will be used by default.
`whiten=True` is deprecated from 1.1 and will raise ValueError in 1.3.
Use `whiten=arbitrary-variance` instead.

Expand All @@ -353,24 +356,27 @@ class FastICA(_ClassNamePrefixFeaturesOutMixin, TransformerMixin, BaseEstimator)
or 'cube'.
You can also provide your own function. It should return a tuple
containing the value of the function, and of its derivative, in the
point. Example::
point. The derivative should be averaged along its last dimension.
Example::

def my_g(x):
return x ** 3, (3 * x ** 2).mean(axis=-1)

fun_args : dict, default=None
Arguments to send to the functional form.
If empty and if fun='logcosh', fun_args will take value
If empty or None and if fun='logcosh', fun_args will take value
{'alpha' : 1.0}.

max_iter : int, default=200
Maximum number of iterations during fit.

tol : float, default=1e-4
Tolerance on update at each iteration.
A positive scalar giving the tolerance at which the
un-mixing matrix is considered to have converged.

w_init : ndarray of shape (n_components, n_components), default=None
The mixing matrix to be used to initialize the algorithm.
Initial un-mixing array. If `w_init=None`, then an array of values
drawn from a normal distribution is used.

random_state : int, RandomState instance or None, default=None
Used to initialize ``w_init`` when not specified, with a
Expand Down Expand Up @@ -486,14 +492,14 @@ def _fit(self, X, compute_sources=False):

if self._whiten == "warn":
warnings.warn(
"From version 1.3 whiten='unit-variance' will be used by default.",
"Starting in v1.3, whiten='unit-variance' will be used by default.",
FutureWarning,
)
self._whiten = "arbitrary-variance"

if self._whiten is True:
warnings.warn(
"From version 1.3 whiten=True should be specified as "
"Starting in v1.3, whiten=True should be specified as "
"whiten='arbitrary-variance' (its current behaviour). This "
"behavior is deprecated in 1.1 and will raise ValueError in 1.3.",
FutureWarning,
Expand Down
6 changes: 3 additions & 3 deletions sklearn/decomposition/tests/test_fastica.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ def test_fastica_return_dtypes(global_dtype):

# FIXME remove filter in 1.3
@pytest.mark.filterwarnings(
"ignore:From version 1.3 whiten='unit-variance' will be used by default."
"ignore:Starting in v1.3, whiten='unit-variance' will be used by default."
)
@pytest.mark.parametrize("add_noise", [True, False])
def test_fastica_simple(add_noise, global_random_seed, global_dtype):
Expand Down Expand Up @@ -353,7 +353,7 @@ def test_inverse_transform(

# FIXME remove filter in 1.3
@pytest.mark.filterwarnings(
"ignore:From version 1.3 whiten='unit-variance' will be used by default."
"ignore:Starting in v1.3, whiten='unit-variance' will be used by default."
)
def test_fastica_errors():
n_features = 3
Expand Down Expand Up @@ -398,7 +398,7 @@ def test_fastica_whiten_default_value_deprecation(ica):
"""
rng = np.random.RandomState(0)
X = rng.random_sample((100, 10))
with pytest.warns(FutureWarning, match=r"From version 1.3 whiten="):
with pytest.warns(FutureWarning, match=r"Starting in v1.3, whiten="):
ica.fit(X)
assert ica._whiten == "arbitrary-variance"

Expand Down