Understanding docstrings

[CheriseCodes]

For the class TreePredictor the following docstring is given for the method predict:

"""
Predict raw values for non-binned data.

Parameters
----------
X : ndarray, shape (n_samples, n_features)
  The input samples.

known_cat_bitsets : ndarray of shape (n_categorical_features, 8)
  Array of bitsets of known categories, for each categorical feature.

f_idx_map : ndarray of shape (n_features,)
  Map from original feature index to the corresponding index in the
  known_cat_bitsets array.

Returns
-------
y : ndarray, shape (n_samples,)
  The raw predicted values.
"""

Does this mean predictor returns an ndarray or a shape or does it mean that it returns an ndarray of shape? Is it a 2d matrix?

Similarly, I am confused about what the documentation of X represents. Is it a 2d matrix or a 1d list or something else?

[jjerphan]

Hi @CheriseCodes

Does this mean predictor returns an ndarray or a shape or does it mean that it returns an ndarray of shape? Is it a 2d matrix?
Similarly, I am confused about what the documentation of X represents. Is it a 2d matrix or a 1d list or something else?

X is the data matrix, hence a 2d ndarray, and its shape is (n_samples, n_features).
Similarly, y is a 1d ndarray of shape (n_samples,).

[NicolasHug]

X : ndarray, shape (n_samples, n_features)

should have been

X : ndarray of shape (n_samples, n_features)

same for the description of y.

99% of the time, our parameters and return values aren't shapes (100% of the time when it comes to X and y.)

[alfaro96]

@NicolasHug was a little bit faster 😉.

[alfaro96]

Thank you @CheriseCodes for reaching out the scikit-learn discussion.

We are working on consistency across the documentation.

For the class TreePredictor the following docstring is given for the method predict:

"""
Predict raw values for non-binned data.

Parameters
----------
X : ndarray, shape (n_samples, n_features)
  The input samples.

known_cat_bitsets : ndarray of shape (n_categorical_features, 8)
  Array of bitsets of known categories, for each categorical feature.

f_idx_map : ndarray of shape (n_features,)
  Map from original feature index to the corresponding index in the
  known_cat_bitsets array.

Returns
-------
y : ndarray, shape (n_samples,)
  The raw predicted values.
"""

Does this mean predictor returns an ndarray or a shape or does it mean that it returns an ndarray of shape? Is it a 2d matrix?

We had used ndarray, shape (n_samples,) to refer to a ndarray of shape (n_samples,). Now, we are changing the documentation to the second option to make it more explicit.

Similarly, I am confused about what the documentation of X represents. Is it a 2d matrix or a 1d list or something else?

X is a ndarray of shape (n_samples, n_features), that is, a 2d array (or matrix).

[CheriseCodes]

Thanks for the feedback @NicolasHug @jjerphan @alfaro96 !