[python-packages] [docs] add type hints and define 'array-like' for X, y, group in scikit-learn interface

[jameslamb]

Contributes to #3756.

I've been putting this off for a while because it's so complicated, but I think it's finally time... this PR is a first attempt at clarifying the allowed input types for the scikit-learn interface 😬

It proposes the following:

• adds type annotations on X, y, and group in fit() and predict() in the scikit-learn interface
• replaces "array-like" in scikit-learn docstrings with specific, concrete types
  • as @StrikerRUS recommended in [python-package] type hints in python package #3756 (comment)
• adds unit tests checking that all combinations of these types minimally work (run without error and produce a model well-fit to the training data)

This PR also expands the _create_data() utility function in test_sklearn.py, adding some things I wanted for this PR like:

• controlling the number of features and samples (to ensure there's enough data to get a decent fit)
• differentiating between binary and multiclass classification

How I arrived at these lists of types

I tested all of the following for X, y, and group:

• h2o datatable.Frame
• list of floats
• list of ints
• list of list of floats
• list of list of ints
• pandas Series
• pandas DataFrame
• numpy array
• scipy csc_matrix
• scipy csr_matrix

At first, I tested this like this:

import lightgbm as lgb
import scipy.sparse
from sklearn.datasets import make_regression

X, y = make_regression()

lgb.LGBMRegressor(num_iterations=5).fit(
    X,
    scipy.sparse.csr_matrix(y)
)
# ValueError: y should be a 1d array, got an array of shape () instead.

Then tried adding different combinations of types into the unit tests added in this PR.

[jameslamb]

@jmoralez @guolinke @shiyu1994 could I please get a review on this this week? I know it's complicated but I think it's an important step in the development of the Python package. Thank you.

[guolinke]

Thank you, LGTM

[jameslamb]

Thanks @guolinke !

[github-actions]

This pull request has been automatically locked since there has not been any recent activity since it was closed.
To start a new related discussion, open a new issue at https://github.com/microsoft/LightGBM/issues
including a reference to this.