From 32445aba964f8e8f86a63fb2601f39a35863fd2d Mon Sep 17 00:00:00 2001 From: Nikita Titov Date: Mon, 30 Aug 2021 22:13:59 +0300 Subject: [PATCH] [docs][python] Refer to functions as callable in docstrings (#4575) --- python-package/lightgbm/basic.py | 10 +++++----- python-package/lightgbm/callback.py | 14 +++++++------- python-package/lightgbm/dask.py | 24 ++++++++++++------------ python-package/lightgbm/engine.py | 12 ++++++------ python-package/lightgbm/sklearn.py | 8 ++++---- 5 files changed, 34 insertions(+), 34 deletions(-) diff --git a/python-package/lightgbm/basic.py b/python-package/lightgbm/basic.py index 387bdcc6b8ae..2bb4c367cc1f 100644 --- a/python-package/lightgbm/basic.py +++ b/python-package/lightgbm/basic.py @@ -1130,7 +1130,7 @@ def __init__(self, data, label=None, reference=None, Parameters ---------- - data : str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, Sequence, list of Sequences or list of numpy arrays + data : str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, Sequence, list of Sequence or list of numpy array Data source of Dataset. If str or pathlib.Path, it represents the path to a text file (CSV, TSV, or LibSVM) or a LightGBM Dataset binary file. label : list, numpy 1-D array, pandas Series / one-column DataFrame or None, optional (default=None) @@ -1260,9 +1260,9 @@ def _init_from_sample( Parameters ---------- - sample_data : list of numpy arrays + sample_data : list of numpy array Sample data for each column. - sample_indices : list of numpy arrays + sample_indices : list of numpy array Sample data row index for each column. sample_cnt : int Number of samples. @@ -1774,7 +1774,7 @@ def create_valid(self, data, label=None, weight=None, group=None, Parameters ---------- - data : str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, Sequence, list of Sequences or list of numpy arrays + data : str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, Sequence, list of Sequence or list of numpy array Data source of Dataset. If str or pathlib.Path, it represents the path to a text file (CSV, TSV, or LibSVM) or a LightGBM Dataset binary file. label : list, numpy 1-D array, pandas Series / one-column DataFrame or None, optional (default=None) @@ -2241,7 +2241,7 @@ def get_data(self): Returns ------- - data : str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, Sequence, list of Sequences or list of numpy arrays or None + data : str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, Sequence, list of Sequence or list of numpy array or None Raw data used in the Dataset construction. """ if self.handle is None: diff --git a/python-package/lightgbm/callback.py b/python-package/lightgbm/callback.py index 0585d889c7d1..d32454add7b2 100644 --- a/python-package/lightgbm/callback.py +++ b/python-package/lightgbm/callback.py @@ -61,7 +61,7 @@ def print_evaluation(period: int = 1, show_stdv: bool = True) -> Callable: Returns ------- - callback : function + callback : callable The callback that prints the evaluation results every ``period`` iteration(s). """ def _callback(env: CallbackEnv) -> None: @@ -84,7 +84,7 @@ def record_evaluation(eval_result: Dict[str, Dict[str, List[Any]]]) -> Callable: Returns ------- - callback : function + callback : callable The callback that records the evaluation history into the passed dictionary. """ if not isinstance(eval_result, dict): @@ -114,16 +114,16 @@ def reset_parameter(**kwargs: Union[list, Callable]) -> Callable: Parameters ---------- - **kwargs : value should be list or function + **kwargs : value should be list or callable List of parameters for each boosting round - or a customized function that calculates the parameter in terms of + or a callable that calculates the parameter in terms of current number of round (e.g. yields learning rate decay). If list lst, parameter = lst[current_round]. - If function func, parameter = func(current_round). + If callable func, parameter = func(current_round). Returns ------- - callback : function + callback : callable The callback that resets the parameter after the first iteration. """ def _callback(env: CallbackEnv) -> None: @@ -167,7 +167,7 @@ def early_stopping(stopping_rounds: int, first_metric_only: bool = False, verbos Returns ------- - callback : function + callback : callable The callback that activates early stopping. """ best_score = [] diff --git a/python-package/lightgbm/dask.py b/python-package/lightgbm/dask.py index b0884cbfbb70..4bcb24a21399 100644 --- a/python-package/lightgbm/dask.py +++ b/python-package/lightgbm/dask.py @@ -435,13 +435,13 @@ def _train( of evals_result_ and best_score_ will be 'not_evaluated'. eval_names : list of str, or None, optional (default=None) Names of eval_set. - eval_sample_weight : list of Dask Arrays or Dask Series, or None, optional (default=None) + eval_sample_weight : list of Dask Array or Dask Series, or None, optional (default=None) Weights for each validation set in eval_set. eval_class_weight : list of dict or str, or None, optional (default=None) Class weights, one dict or str for each validation set in eval_set. - eval_init_score : list of Dask Arrays or Dask Series, or None, optional (default=None) + eval_init_score : list of Dask Array or Dask Series, or None, optional (default=None) Initial model score for each validation set in eval_set. - eval_group : list of Dask Arrays or Dask Series, or None, optional (default=None) + eval_group : list of Dask Array or Dask Series, or None, optional (default=None) Group/query for each validation set in eval_set. eval_metric : str, callable, list or None, optional (default=None) If str, it should be a built-in evaluation metric to use. @@ -1194,9 +1194,9 @@ def fit( sample_weight_shape="Dask Array or Dask Series of shape = [n_samples] or None, optional (default=None)", init_score_shape="Dask Array or Dask Series of shape = [n_samples] or None, optional (default=None)", group_shape="Dask Array or Dask Series or None, optional (default=None)", - eval_sample_weight_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)", - eval_init_score_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)", - eval_group_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)" + eval_sample_weight_shape="list of Dask Array or Dask Series, or None, optional (default=None)", + eval_init_score_shape="list of Dask Array or Dask Series, or None, optional (default=None)", + eval_group_shape="list of Dask Array or Dask Series, or None, optional (default=None)" ) # DaskLGBMClassifier does not support group, eval_group, early_stopping_rounds. @@ -1371,9 +1371,9 @@ def fit( sample_weight_shape="Dask Array or Dask Series of shape = [n_samples] or None, optional (default=None)", init_score_shape="Dask Array or Dask Series of shape = [n_samples] or None, optional (default=None)", group_shape="Dask Array or Dask Series or None, optional (default=None)", - eval_sample_weight_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)", - eval_init_score_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)", - eval_group_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)" + eval_sample_weight_shape="list of Dask Array or Dask Series, or None, optional (default=None)", + eval_init_score_shape="list of Dask Array or Dask Series, or None, optional (default=None)", + eval_group_shape="list of Dask Array or Dask Series, or None, optional (default=None)" ) # DaskLGBMRegressor does not support group, eval_class_weight, eval_group, early_stopping_rounds. @@ -1538,9 +1538,9 @@ def fit( sample_weight_shape="Dask Array or Dask Series of shape = [n_samples] or None, optional (default=None)", init_score_shape="Dask Array or Dask Series of shape = [n_samples] or None, optional (default=None)", group_shape="Dask Array or Dask Series or None, optional (default=None)", - eval_sample_weight_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)", - eval_init_score_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)", - eval_group_shape="list of Dask Arrays or Dask Series, or None, optional (default=None)" + eval_sample_weight_shape="list of Dask Array or Dask Series, or None, optional (default=None)", + eval_init_score_shape="list of Dask Array or Dask Series, or None, optional (default=None)", + eval_group_shape="list of Dask Array or Dask Series, or None, optional (default=None)" ) # DaskLGBMRanker does not support eval_class_weight or early stopping diff --git a/python-package/lightgbm/engine.py b/python-package/lightgbm/engine.py index fbaac0b6a7c9..934e14eddde2 100644 --- a/python-package/lightgbm/engine.py +++ b/python-package/lightgbm/engine.py @@ -50,7 +50,7 @@ def train( Data to be trained on. num_boost_round : int, optional (default=100) Number of boosting iterations. - valid_sets : list of Datasets, or None, optional (default=None) + valid_sets : list of Dataset, or None, optional (default=None) List of data to be evaluated on during training. valid_names : list of str, or None, optional (default=None) Names of ``valid_sets``. @@ -76,7 +76,7 @@ def train( If you want to get i-th row preds in j-th class, the access way is score[j * num_data + i] and you should group grad and hess in this way as well. - feval : callable, list of callable functions, or None, optional (default=None) + feval : callable, list of callable, or None, optional (default=None) Customized evaluation function. Each evaluation function should accept two parameters: preds, train_data, and return (eval_name, eval_result, is_higher_better) or list of such tuples. @@ -147,7 +147,7 @@ def train( learning_rates : list, callable or None, optional (default=None) List of learning rates for each boosting round - or a customized function that calculates ``learning_rate`` + or a callable that calculates ``learning_rate`` in terms of current number of round (e.g. yields learning rate decay). keep_training_booster : bool, optional (default=False) Whether the returned Booster will be used to keep training. @@ -156,7 +156,7 @@ def train( When your model is very large and cause the memory error, you can try to set this param to ``True`` to avoid the model conversion performed during the internal call of ``model_to_string``. You can still use _InnerPredictor as ``init_model`` for future continue training. - callbacks : list of callables, or None, optional (default=None) + callbacks : list of callable, or None, optional (default=None) List of callback functions that are applied at each iteration. See Callbacks in Python API for more information. @@ -472,7 +472,7 @@ def cv(params, train_set, num_boost_round=100, If you want to get i-th row preds in j-th class, the access way is score[j * num_data + i] and you should group grad and hess in this way as well. - feval : callable, list of callable functions, or None, optional (default=None) + feval : callable, list of callable, or None, optional (default=None) Customized evaluation function. Each evaluation function should accept two parameters: preds, train_data, and return (eval_name, eval_result, is_higher_better) or list of such tuples. @@ -528,7 +528,7 @@ def cv(params, train_set, num_boost_round=100, Results are not affected by this parameter, and always contain std. seed : int, optional (default=0) Seed used to generate the folds (passed to numpy.random.seed). - callbacks : list of callables, or None, optional (default=None) + callbacks : list of callable, or None, optional (default=None) List of callback functions that are applied at each iteration. See Callbacks in Python API for more information. eval_train_metric : bool, optional (default=False) diff --git a/python-package/lightgbm/sklearn.py b/python-package/lightgbm/sklearn.py index 9fd2759a0e06..0e195af6b1e8 100644 --- a/python-package/lightgbm/sklearn.py +++ b/python-package/lightgbm/sklearn.py @@ -253,7 +253,7 @@ def __call__(self, preds, dataset): Large values could be memory consuming. Consider using consecutive integers starting from zero. All negative values in categorical features will be treated as missing values. The output cannot be monotonically constrained with respect to a categorical feature. - callbacks : list of callback functions, or None, optional (default=None) + callbacks : list of callable, or None, optional (default=None) List of callback functions that are applied at each iteration. See Callbacks in Python API for more information. init_model : str, pathlib.Path, Booster, LGBMModel or None, optional (default=None) @@ -737,9 +737,9 @@ def _get_meta_data(collection, name, i): sample_weight_shape="array-like of shape = [n_samples] or None, optional (default=None)", init_score_shape="array-like of shape = [n_samples] or None, optional (default=None)", group_shape="array-like or None, optional (default=None)", - eval_sample_weight_shape="list of arrays, or None, optional (default=None)", - eval_init_score_shape="list of arrays, or None, optional (default=None)", - eval_group_shape="list of arrays, or None, optional (default=None)" + eval_sample_weight_shape="list of array, or None, optional (default=None)", + eval_init_score_shape="list of array, or None, optional (default=None)", + eval_group_shape="list of array, or None, optional (default=None)" ) + "\n\n" + _lgbmmodel_doc_custom_eval_note def predict(self, X, raw_score=False, start_iteration=0, num_iteration=None,