parameters: (params, train_set, num_boost_round=100,
         folds=None, nfold=5, stratified=True, shuffle=True,
         metrics=None, fobj=None, feval=None, init_model=None,
         feature_name='auto', categorical_feature='auto',
         fpreproc=None, seed=0, callbacks=None, eval_train_metric=False,
         return_cvbooster=False)
return_statement: return dict(results)
docstring: Perform the cross-validation with given parameters.
  
      Parameters
      ----------
      params : dict
          Parameters for Booster.
      train_set : Dataset
          Data to be trained on.
      num_boost_round : int, optional (default=100)
          Number of boosting iterations.
      folds : generator or iterator of (train_idx, test_idx) tuples, scikit-learn splitter object or None, optional (default=None)
          If generator or iterator, it should yield the train and test indices for each fold.
          If object, it should be one of the scikit-learn splitter classes
          (https://scikit-learn.org/stable/modules/classes.html#splitter-classes)
          and have ``split`` method.
          This argument has highest priority over other data split arguments.
      nfold : int, optional (default=5)
          Number of folds in CV.
      stratified : bool, optional (default=True)
          Whether to perform stratified sampling.
      shuffle : bool, optional (default=True)
          Whether to shuffle before splitting data.
      metrics : str, list of str, or None, optional (default=None)
          Evaluation metrics to be monitored while CV.
          If not None, the metric in ``params`` will be overridden.
      fobj : callable or None, optional (default=None)
          Customized objective function.
          Should accept two parameters: preds, train_data,
          and return (grad, hess).
  
              preds : numpy 1-D array
                  The predicted values.
                  Predicted values are returned before any transformation,
                  e.g. they are raw margin instead of probability of positive class for binary task.
              train_data : Dataset
                  The training dataset.
              grad : list, numpy 1-D array or pandas Series
                  The value of the first order derivative (gradient) of the loss
                  with respect to the elements of preds for each sample point.
              hess : list, numpy 1-D array or pandas Series
                  The value of the second order derivative (Hessian) of the loss
                  with respect to the elements of preds for each sample point.
  
          For multi-class task, the preds is group by class_id first, then group by row_id.
          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, 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.
  
              preds : numpy 1-D array
                  The predicted values.
                  If ``fobj`` is specified, predicted values are returned before any transformation,
                  e.g. they are raw margin instead of probability of positive class for binary task in this case.
              train_data : Dataset
                  The training dataset.
              eval_name : str
                  The name of evaluation function (without whitespace).
              eval_result : float
                  The eval result.
              is_higher_better : bool
                  Is eval result higher better, e.g. AUC is ``is_higher_better``.
  
          For multi-class task, the preds is group by class_id first, then group by row_id.
          If you want to get i-th row preds in j-th class, the access way is preds[j * num_data + i].
          To ignore the default metric corresponding to the used objective,
          set ``metrics`` to the string ``"None"``.
      init_model : str, pathlib.Path, Booster or None, optional (default=None)
          Filename of LightGBM model or Booster instance used for continue training.
      feature_name : list of str, or 'auto', optional (default="auto")
          Feature names.
          If 'auto' and data is pandas DataFrame, data columns names are used.
      categorical_feature : list of str or int, or 'auto', optional (default="auto")
          Categorical features.
          If list of int, interpreted as indices.
          If list of str, interpreted as feature names (need to specify ``feature_name`` as well).
          If 'auto' and data is pandas DataFrame, pandas unordered categorical columns are used.
          All values in categorical features should be less than int32 max value (2147483647).
          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.
      fpreproc : callable or None, optional (default=None)
          Preprocessing function that takes (dtrain, dtest, params)
          and returns transformed versions of those.
      seed : int, optional (default=0)
          Seed used to generate the folds (passed to numpy.random.seed).
      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)
          Whether to display the train metric in progress.
          The score of the metric is calculated again after each training step, so there is some impact on performance.
      return_cvbooster : bool, optional (default=False)
          Whether to return Booster models trained on each fold through ``CVBooster``.
  
      Returns
      -------
      eval_hist : dict
          Evaluation history.
          The dictionary has the following format:
          {'metric1-mean': [values], 'metric1-stdv': [values],
          'metric2-mean': [values], 'metric2-stdv': [values],
          ...}.
          If ``return_cvbooster=True``, also returns trained boosters via ``cvbooster`` key.
docstring_summary: Perform the cross-validation with given parameters.
docstring_tokens: Perform the cross - validation with given parameters .
function: def cv(params, train_set, num_boost_round=100,
         folds=None, nfold=5, stratified=True, shuffle=True,
         metrics=None, fobj=None, feval=None, init_model=None,
         feature_name='auto', categorical_feature='auto',
         fpreproc=None, seed=0, callbacks=None, eval_train_metric=False,
         return_cvbooster=False):
      """Perform the cross-validation with given parameters.
  
      Parameters
      ----------
      params : dict
          Parameters for Booster.
      train_set : Dataset
          Data to be trained on.
      num_boost_round : int, optional (default=100)
          Number of boosting iterations.
      folds : generator or iterator of (train_idx, test_idx) tuples, scikit-learn splitter object or None, optional (default=None)
          If generator or iterator, it should yield the train and test indices for each fold.
          If object, it should be one of the scikit-learn splitter classes
          (https://scikit-learn.org/stable/modules/classes.html#splitter-classes)
          and have ``split`` method.
          This argument has highest priority over other data split arguments.
      nfold : int, optional (default=5)
          Number of folds in CV.
      stratified : bool, optional (default=True)
          Whether to perform stratified sampling.
      shuffle : bool, optional (default=True)
          Whether to shuffle before splitting data.
      metrics : str, list of str, or None, optional (default=None)
          Evaluation metrics to be monitored while CV.
          If not None, the metric in ``params`` will be overridden.
      fobj : callable or None, optional (default=None)
          Customized objective function.
          Should accept two parameters: preds, train_data,
          and return (grad, hess).
  
              preds : numpy 1-D array
                  The predicted values.
                  Predicted values are returned before any transformation,
                  e.g. they are raw margin instead of probability of positive class for binary task.
              train_data : Dataset
                  The training dataset.
              grad : list, numpy 1-D array or pandas Series
                  The value of the first order derivative (gradient) of the loss
                  with respect to the elements of preds for each sample point.
              hess : list, numpy 1-D array or pandas Series
                  The value of the second order derivative (Hessian) of the loss
                  with respect to the elements of preds for each sample point.
  
          For multi-class task, the preds is group by class_id first, then group by row_id.
          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, 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.
  
              preds : numpy 1-D array
                  The predicted values.
                  If ``fobj`` is specified, predicted values are returned before any transformation,
                  e.g. they are raw margin instead of probability of positive class for binary task in this case.
              train_data : Dataset
                  The training dataset.
              eval_name : str
                  The name of evaluation function (without whitespace).
              eval_result : float
                  The eval result.
              is_higher_better : bool
                  Is eval result higher better, e.g. AUC is ``is_higher_better``.
  
          For multi-class task, the preds is group by class_id first, then group by row_id.
          If you want to get i-th row preds in j-th class, the access way is preds[j * num_data + i].
          To ignore the default metric corresponding to the used objective,
          set ``metrics`` to the string ``"None"``.
      init_model : str, pathlib.Path, Booster or None, optional (default=None)
          Filename of LightGBM model or Booster instance used for continue training.
      feature_name : list of str, or 'auto', optional (default="auto")
          Feature names.
          If 'auto' and data is pandas DataFrame, data columns names are used.
      categorical_feature : list of str or int, or 'auto', optional (default="auto")
          Categorical features.
          If list of int, interpreted as indices.
          If list of str, interpreted as feature names (need to specify ``feature_name`` as well).
          If 'auto' and data is pandas DataFrame, pandas unordered categorical columns are used.
          All values in categorical features should be less than int32 max value (2147483647).
          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.
      fpreproc : callable or None, optional (default=None)
          Preprocessing function that takes (dtrain, dtest, params)
          and returns transformed versions of those.
      seed : int, optional (default=0)
          Seed used to generate the folds (passed to numpy.random.seed).
      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)
          Whether to display the train metric in progress.
          The score of the metric is calculated again after each training step, so there is some impact on performance.
      return_cvbooster : bool, optional (default=False)
          Whether to return Booster models trained on each fold through ``CVBooster``.
  
      Returns
      -------
      eval_hist : dict
          Evaluation history.
          The dictionary has the following format:
          {'metric1-mean': [values], 'metric1-stdv': [values],
          'metric2-mean': [values], 'metric2-stdv': [values],
          ...}.
          If ``return_cvbooster=True``, also returns trained boosters via ``cvbooster`` key.
      """
      if not isinstance(train_set, Dataset):
          raise TypeError("Training only accepts Dataset object")
  
      params = copy.deepcopy(params)
      if fobj is not None:
          for obj_alias in _ConfigAliases.get("objective"):
              params.pop(obj_alias, None)
          params['objective'] = 'none'
      for alias in _ConfigAliases.get("num_iterations"):
          if alias in params:
              _log_warning(f"Found '{alias}' in params. Will use it instead of 'num_boost_round' argument")
              num_boost_round = params.pop(alias)
      params["num_iterations"] = num_boost_round
      # setting early stopping via global params should be possible
      params = _choose_param_value(
          main_param_name="early_stopping_round",
          params=params,
          default_value=None
      )
      if params["early_stopping_round"] is None:
          params.pop("early_stopping_round")
      first_metric_only = params.get('first_metric_only', False)
  
      if num_boost_round <= 0:
          raise ValueError("num_boost_round should be greater than zero.")
      if isinstance(init_model, (str, Path)):
          predictor = _InnerPredictor(model_file=init_model, pred_parameter=params)
      elif isinstance(init_model, Booster):
          predictor = init_model._to_predictor(dict(init_model.params, **params))
      else:
          predictor = None
  
      if metrics is not None:
          for metric_alias in _ConfigAliases.get("metric"):
              params.pop(metric_alias, None)
          params['metric'] = metrics
  
      train_set._update_params(params) \
               ._set_predictor(predictor) \
               .set_feature_name(feature_name) \
               .set_categorical_feature(categorical_feature)
  
      results = collections.defaultdict(list)
      cvfolds = _make_n_folds(train_set, folds=folds, nfold=nfold,
                              params=params, seed=seed, fpreproc=fpreproc,
                              stratified=stratified, shuffle=shuffle,
                              eval_train_metric=eval_train_metric)
  
      # setup callbacks
      if callbacks is None:
          callbacks = set()
      else:
          for i, cb in enumerate(callbacks):
              cb.__dict__.setdefault('order', i - len(callbacks))
          callbacks = set(callbacks)
  
      if "early_stopping_round" in params:
          callbacks.add(
              callback.early_stopping(
                  stopping_rounds=params["early_stopping_round"],
                  first_metric_only=first_metric_only,
                  verbose=_choose_param_value(
                      main_param_name="verbosity",
                      params=params,
                      default_value=1
                  ).pop("verbosity") > 0
              )
          )
  
      callbacks_before_iter = {cb for cb in callbacks if getattr(cb, 'before_iteration', False)}
      callbacks_after_iter = callbacks - callbacks_before_iter
      callbacks_before_iter = sorted(callbacks_before_iter, key=attrgetter('order'))
      callbacks_after_iter = sorted(callbacks_after_iter, key=attrgetter('order'))
  
      for i in range(num_boost_round):
          for cb in callbacks_before_iter:
              cb(callback.CallbackEnv(model=cvfolds,
                                      params=params,
                                      iteration=i,
                                      begin_iteration=0,
                                      end_iteration=num_boost_round,
                                      evaluation_result_list=None))
          cvfolds.update(fobj=fobj)
          res = _agg_cv_result(cvfolds.eval_valid(feval), eval_train_metric)
          for _, key, mean, _, std in res:
              results[f'{key}-mean'].append(mean)
              results[f'{key}-stdv'].append(std)
          try:
              for cb in callbacks_after_iter:
                  cb(callback.CallbackEnv(model=cvfolds,
                                          params=params,
                                          iteration=i,
                                          begin_iteration=0,
                                          end_iteration=num_boost_round,
                                          evaluation_result_list=res))
          except callback.EarlyStopException as earlyStopException:
              cvfolds.best_iteration = earlyStopException.best_iteration + 1
              for k in results:
                  results[k] = results[k][:cvfolds.best_iteration]
              break
  
      if return_cvbooster:
          results['cvbooster'] = cvfolds
  
      return dict(results)
function_tokens: def cv ( params , train_set , num_boost_round = 100 , folds = None , nfold = 5 , stratified = True , shuffle = True , metrics = None , fobj = None , feval = None , init_model = None , feature_name = 'auto' , categorical_feature = 'auto' , fpreproc = None , seed = 0 , callbacks = None , eval_train_metric = False , return_cvbooster = False ) : if not isinstance ( train_set , Dataset ) : raise TypeError ( "Training only accepts Dataset object" ) params = copy . deepcopy ( params ) if fobj is not None : for obj_alias in _ConfigAliases . get ( "objective" ) : params . pop ( obj_alias , None ) params [ 'objective' ] = 'none' for alias in _ConfigAliases . get ( "num_iterations" ) : if alias in params : _log_warning ( f"Found '{alias}' in params. Will use it instead of 'num_boost_round' argument" ) num_boost_round = params . pop ( alias ) params [ "num_iterations" ] = num_boost_round # setting early stopping via global params should be possible params = _choose_param_value ( main_param_name = "early_stopping_round" , params = params , default_value = None ) if params [ "early_stopping_round" ] is None : params . pop ( "early_stopping_round" ) first_metric_only = params . get ( 'first_metric_only' , False ) if num_boost_round <= 0 : raise ValueError ( "num_boost_round should be greater than zero." ) if isinstance ( init_model , ( str , Path ) ) : predictor = _InnerPredictor ( model_file = init_model , pred_parameter = params ) elif isinstance ( init_model , Booster ) : predictor = init_model . _to_predictor ( dict ( init_model . params , * * params ) ) else : predictor = None if metrics is not None : for metric_alias in _ConfigAliases . get ( "metric" ) : params . pop ( metric_alias , None ) params [ 'metric' ] = metrics train_set . _update_params ( params ) . _set_predictor ( predictor ) . set_feature_name ( feature_name ) . set_categorical_feature ( categorical_feature ) results = collections . defaultdict ( list ) cvfolds = _make_n_folds ( train_set , folds = folds , nfold = nfold , params = params , seed = seed , fpreproc = fpreproc , stratified = stratified , shuffle = shuffle , eval_train_metric = eval_train_metric ) # setup callbacks if callbacks is None : callbacks = set ( ) else : for i , cb in enumerate ( callbacks ) : cb . __dict__ . setdefault ( 'order' , i - len ( callbacks ) ) callbacks = set ( callbacks ) if "early_stopping_round" in params : callbacks . add ( callback . early_stopping ( stopping_rounds = params [ "early_stopping_round" ] , first_metric_only = first_metric_only , verbose = _choose_param_value ( main_param_name = "verbosity" , params = params , default_value = 1 ) . pop ( "verbosity" ) > 0 ) ) callbacks_before_iter = { cb for cb in callbacks if getattr ( cb , 'before_iteration' , False ) } callbacks_after_iter = callbacks - callbacks_before_iter callbacks_before_iter = sorted ( callbacks_before_iter , key = attrgetter ( 'order' ) ) callbacks_after_iter = sorted ( callbacks_after_iter , key = attrgetter ( 'order' ) ) for i in range ( num_boost_round ) : for cb in callbacks_before_iter : cb ( callback . CallbackEnv ( model = cvfolds , params = params , iteration = i , begin_iteration = 0 , end_iteration = num_boost_round , evaluation_result_list = None ) ) cvfolds . update ( fobj = fobj ) res = _agg_cv_result ( cvfolds . eval_valid ( feval ) , eval_train_metric ) for _ , key , mean , _ , std in res : results [ f'{key}-mean' ] . append ( mean ) results [ f'{key}-stdv' ] . append ( std ) try : for cb in callbacks_after_iter : cb ( callback . CallbackEnv ( model = cvfolds , params = params , iteration = i , begin_iteration = 0 , end_iteration = num_boost_round , evaluation_result_list = res ) ) except callback . EarlyStopException as earlyStopException : cvfolds . best_iteration = earlyStopException . best_iteration + 1 for k in results : results [ k ] = results [ k ] [ : cvfolds . best_iteration ] break if return_cvbooster : results [ 'cvbooster' ] = cvfolds return dict ( results )