8000 DOC Update docs guideline regarding docstring formatting (#18243) · thomasjpfan/scikit-learn@266a11b · GitHub
[go: up one dir, main page]
Skip to content

Commit 266a11b

Browse files
glemaitreogriseljeremiedbb
authored
DOC Update docs guideline regarding docstring formatting (scikit-learn#18243)
Co-authored-by: Olivier Grisel <olivier.grisel@ensta.org> Co-authored-by: Jérémie du Boisberranger <34657725+jeremiedbb@users.noreply.github.com>
1 parent 22cd233 commit 266a11b

File tree

6 files changed

+48
-27
lines changed

6 files changed

+48
-27
lines changed

‎doc/developers/contributing.rst

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -779,6 +779,8 @@ Finally, follow the formatting rules below to make it consistently good:
779779

780780
sample_weight : array-like of shape (n_samples,), default=None
781781

782+
multioutput_array : ndarray of shape (n_samples, n_classes) or list of such arrays
783+
782784
In general have the following in mind:
783785

784786
1. Use Python basic types. (``bool`` instead of ``boolean``)
@@ -792,10 +794,18 @@ Finally, follow the formatting rules below to make it consistently good:
792794
5. Specify ``dataframe`` when "frame-like" features are being used, such
793795
as the column names.
794796
6. When specifying the data type of a list, use ``of`` as a delimiter:
795-
``list of int``.
797+
``list of int``. When the parameter supports arrays giving details
798+
about the shape and/or data type and a list of such arrays, you can
799+
use one of ``array-like of shape (n_samples,) or list of such arrays``.
796800
7. When specifying the dtype of an ndarray, use e.g. ``dtype=np.int32``
797801
after defining the shape:
798-
``ndarray of shape (n_samples,), dtype=np.int32``.
802+
``ndarray of shape (n_samples,), dtype=np.int32``. You can specify
803+
multiple dtype as a set:
804+
``array-like of shape (n_samples,), dtype={np.float64, np.float32}``.
805+
If one wants to mention arbitrary precision, use `integral` and
806+
`floating` rather than the Python dtype `int` and `float`. When both
807+
`int` and `floating` are supported, there is no need to specify the
808+
dtype.
799809
8. When the default is ``None``, ``None`` only needs to be specified at the
800810
end with ``default=None``. Be sure to include in the docstring, what it
801811
means for the parameter or attribute to be ``None``.

‎doc/glossary.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -255,6 +255,13 @@ General Concepts
255255
or vectorizing. Our estimators do not work with struct arrays, for
256256
instance.
257257

258+
Our documentation can sometimes give information about the dtype
259+
precision, e.g. `np.int32`, `np.int64`, etc. When the precision is
260+
provided, it refers to the NumPy dtype. If an arbitrary precision is
261+
used, the documentation will refer to dtype `integer` or `floating`.
262+
Note that in this case, the precision can be platform dependent.
263+
The `numeric` dtype refers to accepting both `integer` and `floating`.
264+
258265
TODO: Mention efficiency and precision issues; casting policy.
259266

260267
duck typing

‎examples/model_selection/plot_learning_curve.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ def plot_learning_curve(estimator, title, X, y, axes=None, ylim=None, cv=None,
7777
``-1`` means using all processors. See :term:`Glossary <n_jobs>`
7878
for more details.
7979
80-
train_sizes : array-like of shape (n_ticks,), dtype={int, float}
80+
train_sizes : array-like of shape (n_ticks,)
81< 8000 /code>81
Relative or absolute numbers of training examples that will be used to
8282
generate the learning curve. If the ``dtype`` is float, it is regarded
8383
as a fraction of the maximum size of the training set (that is

‎sklearn/dummy.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -64,13 +64,13 @@ class DummyClassifier(MultiOutputMixin, ClassifierMixin, BaseEstimator):
6464
6565
Attributes
6666
----------
67-
classes_ : ndarray of shape (n_classes,) or list thereof
67+
classes_ : ndarray of shape (n_classes,) or list of such arrays
6868
Class labels for each output.
6969
7070
n_classes_ : int or list of int
7171
Number of label for each output.
7272
73-
class_prior_ : ndarray of shape (n_classes,) or list thereof
73+
class_prior_ : ndarray of shape (n_classes,) or list of such arrays
7474
Probability of each class for each output.
7575
7676
n_outputs_ : int
@@ -272,7 +272,7 @@ def predict_proba(self, X):
272272
273273
Returns
274274
-------
275-
P : ndarray of shape (n_samples, n_classes) or list thereof
275+
P : ndarray of shape (n_samples, n_classes) or list of such arrays
276276
Returns the probability of the sample for each class in
277277
the model, where classes are ordered arithmetically, for each
278278
output.
@@ -335,7 +335,7 @@ def predict_log_proba(self, X):
335335
336336
Returns
337337
-------
338-
P : ndarray of shape (n_samples, n_classes) or list thereof
338+
P : ndarray of shape (n_samples, n_classes) or list of such arrays
339339
Returns the log probability of the sample for each class in
340340
the model, where classes are ordered arithmetically for each
341341
output.

‎sklearn/linear_model/_least_angle.py

Lines changed: 21 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -864,21 +864,22 @@ class Lars(MultiOutputMixin, RegressorMixin, LinearModel):
864864
865865
Attributes
866866
----------
867-
alphas_ : array-like of shape (n_alphas + 1,) or list of thereof of \
868-
shape (n_targets,)
867+
alphas_ : array-like of shape (n_alphas + 1,) or list of such arrays
869868
Maximum of covariances (in absolute value) at each iteration.
870869
``n_alphas`` is either ``max_iter``, ``n_features`` or the
871870
number of nodes in the path with ``alpha >= alpha_min``, whichever
872-
is smaller.
871+
is smaller. If this is a list of array-like, the length of the outer
872+
list is `n_targets`.
873873
874-
active_ : list of shape (n_alphas,) or list of thereof of shape \
875-
(n_targets,)
874+
active_ : list of shape (n_alphas,) or list of such lists
876875
Indices of active variables at the end of the path.
876+
If this is a list of list, the length of the outer list is `n_targets`.
877877
878-
coef_path_ : array-like of shape (n_features, n_alphas + 1) or list of \
879-
thereof of shape (n_targets,)
878+
coef_path_ : array-like of shape (n_features, n_alphas + 1) or list \
879+
of such arrays
880880
The varying values of the coefficients along the path. It is not
881-
present if the ``fit_path`` parameter is ``False``.
881+
present if the ``fit_path`` parameter is ``False``. If this is a list
882+
of array-like, the length of the outer list is `n_targets`.
882883
883884
coef_ : array-like of shape (n_features,) or (n_targets, n_features)
884885
Parameter vector (w in the formulation formula).
@@ -1121,21 +1122,23 @@ class LassoLars(Lars):
11211122
11221123
Attributes
11231124
----------
1124-
alphas_ : array-like of shape (n_alphas + 1,) or list of thereof of shape \
1125-
(n_targets,)
1125+
alphas_ : array-like of shape (n_alphas + 1,) or list of such arrays
11261126
Maximum of covariances (in absolute value) at each iteration.
11271127
``n_alphas`` is either ``max_iter``, ``n_features`` or the
11281128
number of nodes in the path with ``alpha >= alpha_min``, whichever
1129-
is smaller.
1129+
is smaller. If this is a list of array-like, the length of the outer
1130+
list is `n_targets`.
11301131
1131-
active_ : list of length n_alphas or list of thereof of shape (n_targets,)
1132+
active_ : list of length n_alphas or list of such lists
11321133
Indices of active variables at the end of the path.
1134+
If this is a list of list, the length of the outer list is `n_targets`.
11331135
1134-
coef_path_ : array-like of shape (n_features, n_alphas + 1) or list of \
1135-
thereof of shape (n_targets,)
1136+
coef_path_ : array-like of shape (n_features, n_alphas + 1) or list \
1137+
of such arrays
11361138
If a list is passed it's expected to be one of n_targets such arrays.
11371139
The varying values of the coefficients along the path. It is not
1138-
present if the ``fit_path`` parameter is ``False``.
1140+
present if the ``fit_path`` parameter is ``False``. If this is a list
1141+
of array-like, the length of the outer list is `n_targets`.
11391142
11401143
coef_ : array-like of shape (n_features,) or (n_targets, n_features)
11411144
Parameter vector (w in the formulation formula).
@@ -1382,8 +1385,9 @@ class LarsCV(Lars):
13821385
13831386
Attributes
13841387
----------
1385-
active_ : list of length n_alphas or list of thereof of shape (n_targets,)
1388+
active_ : list of length n_alphas or list of such lists
13861389
Indices of active variables at the end of the path.
1390+
If this is a list of lists, the outer list length is `n_targets`.
13871391
13881392
coef_ : array-like of shape (n_features,)
13891393
parameter vector (w in the formulation formula)
@@ -1775,7 +1779,7 @@ class LassoLarsIC(LassoLars):
17751779
alpha_ : float
17761780
the alpha parameter chosen by the information criterion
17771781
1778-
alphas_ : array-like of shape (n_alphas + 1,) or list thereof
1782+
alphas_ : array-like of shape (n_alphas + 1,) or list of such arrays
17791783
Maximum of covariances (in absolute value) at each iteration.
17801784
``n_alphas`` is either ``max_iter``, ``n_features`` or the
17811785
number of nodes in the path with ``alpha >= alpha_min``, whichever

‎sklearn/preprocessing/_discretization.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,7 @@ def fit(self, X, y=None):
139139
140140
Parameters
141141
----------
142-
X : array-like of shape (n_samples, n_features), dtype={int, float}
142+
X : array-like of shape (n_samples, n_features)
143143
Data to be discretized.
144144
145145
y : None
@@ -276,7 +276,7 @@ def transform(self, X):
276276
277277
Parameters
278278
----------
279-
X : array-like of shape (n_samples, n_features), dtype={int, float}
279+
X : array-like of shape (n_samples, n_features)
280280
Data to be discretized.
281281
282282
Returns
@@ -326,7 +326,7 @@ def inverse_transform(self, Xt):
326326
327327
Parameters
328328
----------
329-
Xt : array-like of shape (n_samples, n_features), dtype={int, float}
329+
Xt : array-like of shape (n_samples, n_features)
330330
Transformed data in the binned space.
331331
332332
Returns

0 commit comments

Comments
 (0)
0