10000 DOC Fix doc of defaults in sklearn.utils.validation.py by franslarsson · Pull Request #18048 · scikit-learn/scikit-learn · GitHub
[go: up one dir, main page]
Skip to content

DOC Fix doc of defaults in sklearn.utils.validation.py #18048

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 3 commits into from
Aug 1, 2020
Merged

DOC Fix doc of defaults in sklearn.utils.validation.py #18048

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1650d8d
update docstring
franslarsson Jul 31, 2020
d24976f
minor updates to docstring
franslarsson Jul 31, 2020
d9b6a01
Update docstring according to review
franslarsson Aug 1, 2020
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
109 changes: 56 additions & 53 deletions sklearn/utils/validation.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,15 +33,15 @@


def _deprecate_positional_args(f):
"""Decorator for methods that issues warnings for positional arguments
"""Decorator for methods that issues warnings for positional arguments.

Using the keyword-only argument syntax in pep 3102, arguments after the
* will issue a warning when passed as a positional argument.

Parameters
----------
f : function
function to check arguments on
f : callable
Function to check arguments on.
"""
sig = signature(f)
kwonly_args = []
Expand Down Expand Up @@ -109,9 +109,9 @@ def assert_all_finite(X, *, allow_nan=False):

Parameters
----------
X : array or sparse matrix
X : {ndarray, sparse matrix}

allow_nan : bool
allow_nan : bool, default=False
"""
_assert_all_finite(X.data if sp.issparse(X) else X, allow_nan)

Expand All @@ -132,7 +132,7 @@ def as_float_array(X, *, copy=True, force_all_finite=True):
If True, a copy of X will be created. If False, a copy may still be
returned if X's dtype is not a floating point type.

force_all_finite : boolean or 'allow-nan', default=True
force_all_finite : bool or 'allow-nan', default=True
Whether to raise an error on np.inf, np.nan, pd.NA in X. The
possibilities are:

Expand All @@ -149,8 +149,8 @@ def as_float_array(X, *, copy=True, force_all_finite=True):

Returns
-------
XT : {array, sparse matrix}
An array of type float
XT : {ndarray, sparse matrix}
An array of type float.
"""
if isinstance(X, np.matrix) or (not isinstance(X, np.ndarray)
and not sp.issparse(X)):
Expand All @@ -170,7 +170,7 @@ def as_float_array(X, *, copy=True, force_all_finite=True):


def _is_arraylike(x):
"""Returns whether the input is array-like"""
"""Returns whether the input is array-like."""
return (hasattr(x, '__len__') or
hasattr(x, 'shape') or
hasattr(x, '__array__'))
Expand Down Expand Up @@ -263,7 +263,7 @@ def _make_indexable(iterable):

Parameters
----------
iterable : {list, dataframe, array, sparse} or None
iterable : {list, dataframe, ndarray, sparse matrix} or None
Object to be converted to an indexable iterable.
"""
if sp.issparse(iterable):
Expand All @@ -284,7 +284,7 @@ def indexable(*iterables):

Parameters
----------
*iterables : lists, dataframes, arrays, sparse matrices
*iterables : {lists, dataframes, ndarrays, sparse matrices}
List of objects to ensure sliceability.
"""
result = [_make_indexable(X) for X in iterables]
Expand All @@ -300,24 +300,24 @@ def _ensure_sparse_format(spmatrix, accept_sparse, dtype, copy,

Parameters
----------
spmatrix : scipy sparse matrix
spmatrix : sparse matrix
Input to validate and convert.

accept_sparse : string, boolean or list/tuple of strings
accept_sparse : str, bool or list/tuple of str
String[s] representing allowed sparse matrix formats ('csc',
'csr', 'coo', 'dok', 'bsr', 'lil', 'dia'). If the input is sparse but
not in the allowed format, it will be converted to the first listed
format. True allows the input to be any format. False means
that a sparse matrix input will raise an error.

dtype : string, type or None
dtype : str, type or None
Data type of result. If None, the dtype of the input is preserved.

copy : boolean
copy : bool
Whether a forced copy will be triggered. If copy=False, a copy might
be triggered by a conversion.

force_all_finite : boolean or 'allow-nan', default=True
force_all_finite : bool or 'allow-nan'
Whether to raise an error on np.inf, np.nan, pd.NA in X. The
possibilities are:

Expand All @@ -334,7 +334,7 @@ def _ensure_sparse_format(spmatrix, accept_sparse, dtype, copy,

Returns
-------
spmatrix_converted : scipy sparse matrix.
spmatrix_converted : sparse matrix.
Matrix that is ensured to have an allowed type.
"""
if dtype is None:
Expand Down Expand Up @@ -410,7 +410,7 @@ def check_array(array, accept_sparse=False, *, accept_large_sparse=True,
array : object
Input object to check / convert.

accept_sparse : string, boolean or list/tuple of strings, default=False
accept_sparse : str, bool or list/tuple of str, default=False
String[s] representing allowed sparse matrix formats, such as 'csc',
'csr', etc. If the input is sparse but not in the allowed format,
it will be converted to the first listed format. True allows the input
Expand All @@ -424,24 +424,24 @@ def check_array(array, accept_sparse=False, *, accept_large_sparse=True,

.. versionadded:: 0.20

dtype : string, type, list of types or None, default="numeric"
dtype : 'numeric', type, list of type or None, default='numeric'
Data type of result. If None, the dtype of the input is preserved.
If "numeric", dtype is preserved unless array.dtype is object.
If dtype is a list of types, conversion on the first type is only
performed if the dtype of the input is not in the list.

order : 'F', 'C' or None, default=None
order : {'F', 'C'} or None, default=None
Whether an array will be forced to be fortran or c-style.
When order is None (default), then if copy=False, nothing is ensured
about the memory layout of the output array; otherwise (copy=True)
the memory layout of the returned array is kept as close as possible
to the original array.

copy : boolean, default=False
copy : bool, default=False
Whether a forced copy will be triggered. If copy=False, a copy might
be triggered by a conversion.

force_all_finite : boolean or 'allow-nan', default=True
force_all_finite : bool or 'allow-nan', default=True
Whether to raise an error on np.inf, np.nan, pd.NA in array. The
possibilities are:

Expand All @@ -456,10 +456,10 @@ def check_array(array, accept_sparse=False, *, accept_large_sparse=True,
.. versionchanged:: 0.23
Accepts `pd.NA` and converts it into `np.nan`

ensure_2d : boolean, default=True
ensure_2d : bool, default=True
Whether to raise a value error if array is not 2D.

allow_nd : boolean, default=False
allow_nd : bool, default=False
Whether to allow array.ndim > 2.

ensure_min_samples : int, default=1
Expand Down Expand Up @@ -701,13 +701,13 @@ def check_X_y(X, y, accept_sparse=False, *, accept_large_sparse=True,

Parameters
----------
X : nd-array, list or sparse matrix
X : {ndarray, list, sparse matrix}
Input data.

y : nd-array, list or sparse matrix
y : {ndarray, list, sparse matrix}
Labels.

accept_sparse : string, boolean or list of string, default=False
accept_sparse : str, bool or list of str, default=False
String[s] representing allowed sparse matrix formats, such as 'csc',
'csr', etc. If the input is sparse but not in the allowed format,
it will be converted to the first listed format. True allows the input
Expand All @@ -721,20 +721,20 @@ def check_X_y(X, y, accept_sparse=False, *, accept_large_sparse=True,

.. versionadded:: 0.20

dtype : string, type, list of types or None, default="numeric"
dtype : 'numeric', type, list of type or None, default='numeric'
Data type of result. If None, the dtype of the input is preserved.
If "numeric", dtype is preserved unless array.dtype is object.
If dtype is a list of types, conversion on the first type is only
performed if the dtype of the input is not in the list.

order : 'F', 'C' or None, default=None
order : {'F', 'C'}, default=None
Whether an array will be forced to be fortran or c-style.

copy : boolean, default=False
copy : bool, default=False
Whether a forced copy will be triggered. If copy=False, a copy might
be triggered by a conversion.

force_all_finite : boolean or 'allow-nan', default=True
force_all_finite : bool or 'allow-nan', default=True
Whether to raise an error on np.inf, np.nan, pd.NA in X. This parameter
does not influence whether y can have np.inf, np.nan, pd.NA values.
The possibilities are:
Expand All @@ -750,13 +750,13 @@ def check_X_y(X, y, accept_sparse=False, *, accept_large_sparse=True,
.. versionchanged:: 0.23
Accepts `pd.NA` and converts it into `np.nan`

ensure_2d : boolean, default=True
ensure_2d : bool, default=True
Whether to raise a value error if X is not 2D.

allow_nd : boolean, default=False
allow_nd : bool, default=False
Whether to allow X.ndim > 2.

multi_output : boolean, default=False
multi_output : bool, default=False
Whether to allow 2D y (array or sparse matrix). If false, y will be
validated as a vector. y cannot have np.nan or np.inf values if
multi_output=True.
Expand All @@ -772,7 +772,7 @@ def check_X_y(X, y, accept_sparse=False, *, accept_large_sparse=True,
is originally 1D and ``ensure_2d`` is True. Setting to 0 disables
this check.

y_numeric : boolean, default=False
y_numeric : bool, default=False
Whether to ensure that y has a numeric type. If dtype of y is object,
it is converted to float64. Should only be used for regression
algorithms.
Expand Down Expand Up @@ -815,18 +815,18 @@ def check_X_y(X, y, accept_sparse=False, *, accept_large_sparse=True,

@_deprecate_positional_args
def column_or_1d(y, *, warn=False):
""" Ravel column or 1d numpy array, else raises an error
""" Ravel column or 1d numpy array, else raises an error.

Parameters
----------
y : array-like

warn : boolean, default False
warn : bool, default=False
To control display of warnings.

Returns
-------
y : array
y : ndarray

"""
y = np.asarray(y)
Expand All @@ -851,7 +851,7 @@ def check_random_state(seed):

Parameters
----------
seed : None | int | instance of RandomState
seed : None, int or instance of RandomState
If seed is None, return the RandomState singleton used by np.random.
If seed is an int, return a new RandomState instance seeded with seed.
If seed is already a RandomState instance, return it.
Expand Down Expand Up @@ -905,19 +905,22 @@ def check_symmetric(array, *, tol=1E-10, raise_warning=True,

Parameters
----------
array : nd-array or sparse matrix
array : {ndarray, sparse matrix}
Input object to check / convert. Must be two-dimensional and square,
otherwise a ValueError will be raised.
tol : float

tol : float, default=1e-10
Absolute tolerance for equivalence of arrays. Default = 1E-10.
raise_warning : boolean, default=True

raise_warning : bool, default=True
If True then raise a warning if conversion is required.
raise_exception : boolean, default=False

raise_exception : bool, default=False
If True then raise an exception if array is not symmetric.

Returns
-------
array_sym : ndarray or sparse matrix
array_sym : {ndarray, sparse matrix}
Symmetrized version of the input array, i.e. the average of array
and array.transpose(). If sparse, then duplicate entries are first
summed and zeros are eliminated.
Expand Down Expand Up @@ -964,7 +967,7 @@ def check_is_fitted(estimator, attributes=None, *, msg=None, all_or_any=all):

Parameters
----------
estimator : estimator instance.
estimator : estimator instance
estimator instance for which the check is performed.

attributes : str, list or tuple of str, default=None
Expand All @@ -975,7 +978,7 @@ def check_is_fitted(estimator, attributes=None, *, msg=None, all_or_any=all):
attribute that ends with a underscore and does not start with double
underscore.

msg : string
msg : str, default=None
The default error message is, "This %(name)s instance is not fitted
yet. Call 'fit' with appropriate arguments before using this
estimator."
Expand Down Expand Up @@ -1024,10 +1027,10 @@ def check_non_negative(X, whom):

Parameters
----------
X : array-like or sparse matrix
X : {array-like, sparse matrix}
Input data.

whom : string
whom : str
Who passed X to this function.
"""
# avoid X.min() on sparse matrix since it also sorts the indices
Expand Down Expand Up @@ -1263,7 +1266,7 @@ def _check_sample_weight(sample_weight, X, dtype=None):
sample_weight : {ndarray, Number or None}, shape (n_samples,)
Input sample weights.

X : nd-array, list or sparse matrix
X : {ndarray, list, sparse matrix}
Input data.

dtype: dtype
Expand All @@ -1275,7 +1278,7 @@ def _check_sample_weight(sample_weight, X, dtype=None):

Returns
-------
sample_weight : ndarray, shape (n_samples,)
sample_weight : ndarray of shape (n_samples,)
Validated sample weight. It is guaranteed to be "C" contiguous.
"""
n_samples = _num_samples(X)
Expand Down Expand Up @@ -1311,14 +1314,14 @@ def _allclose_dense_sparse(x, y, rtol=1e-7, atol=1e-9):

Parameters
----------
x : array-like or sparse matrix
x : {array-like, sparse matrix}
First array to compare.

y : array-like or sparse matrix
y : {array-like, sparse matrix}
Second array to compare.

rtol : float, default=1e-7
relative tolerance; see numpy.allclose
Relative tolerance; see numpy.allclose.

atol : float, default=1e-9
absolute tolerance; see numpy.allclose. Note that the default here is
Expand Down
0