class_docstr: Optimises hyper-parameters of the whole Pipeline.
  
  - NA encoder (missing values encoder)
  - CA encoder (categorical features encoder)
  - Feature selector (OPTIONAL)
  - Stacking estimator - feature engineer (OPTIONAL)
  - Estimator (classifier or regressor)
  
  Works for both regression and classification (multiclass or binary) tasks.
  
  Parameters
  ----------
  scoring : str, callable or None. default: None
      A string or a scorer callable object.
  
      If None, "neg_log_loss" is used for classification and
      "neg_mean_squared_error" for regression
  
      Available scorings can be found in the module sklearn.metrics:
      https://scikit-learn.org/stable/modules/model_evaluation.html#the-scoring-parameter-defining-model-evaluation-rules
  
  n_folds : int, default = 2
      The number of folds for cross validation (stratified for classification)
  
  random_state : int, default = 1
      Pseudo-random number generator state used for shuffling
  
  to_path : str, default = "save"
      Name of the folder where models are saved
  
  verbose : bool, default = True
      Verbose mode
class_docstr_tok: ["Optimises","hyper-parameters","of","the","whole","Pipeline",".","-","NA","encoder","(","missing","values","encoder",")","-","CA","encoder","(","categorical","features","encoder",")","-","Feature","selector","(","OPTIONAL",")","-","Stacking","estimator","-","feature","engineer","(","OPTIONAL",")","-","Estimator","(","classifier","or","regressor",")","Works","for","both","regression","and","classification","(","multiclass","or","binary",")","tasks",".","Parameters","--","--","--","--","--","scoring",":","str",",","callable","or","None",".","default",":","None","A","string","or","a","scorer","callable","object",".","If","None",",","``","neg_log_loss","''","is","used","for","classification","and","``","neg_mean_squared_error","''","for","regression","Available","scorings","can","be","found","in","the","module","sklearn.metrics",":","https",":","\/\/scikit-learn.org\/stable\/modules\/model_evaluation.html","#","the-scoring-parameter-defining-model-evaluation-rules","n_folds",":","int",",","default","=","2","The","number","of","folds","for","cross","validation","(","stratified","for","classification",")","random_state",":","int",",","default","=","1","Pseudo-random","number","generator","state","used","for","shuffling","to_path",":","str",",","default","=","``","save","''","Name","of","the","folder","where","models","are","saved","verbose",":","bool",",","default","=","True","Verbose","mode"]
docstr: Optimises the Pipeline.
  
  Optimises hyper-parameters of the whole Pipeline with a given scoring
  function. Algorithm used to optimize : Tree Parzen Estimator.
  
  IMPORTANT : Try to avoid dependent parameters and to set one feature
  selection strategy and one estimator strategy at a time.
  
  Parameters
  ----------
  space : dict, default = None.
      Hyper-parameters space:
  
      - The keys must respect the following syntax : "enc__param".
  
          - "enc" = "ne" for na encoder
          - "enc" = "ce" for categorical encoder
          - "enc" = "fs" for feature selector [OPTIONAL]
          - "enc" = "stck"+str(i) to add layer n°i of meta-features [OPTIONAL]
          - "enc" = "est" for the final estimator
  
          - "param" : a correct associated parameter for each step. Ex: "max_depth" for "enc"="est", ...
  
      - The values must respect the syntax: {"search":strategy,"space":list}
  
          - "strategy" = "choice" or "uniform". Default = "choice"
          - list : a list of values to be tested if strategy="choice". Else, list = [value_min, value_max].
  
  df : dict, default = None
      Dataset dictionary. Must contain keys and values:
  
      - "train": pandas DataFrame for the train set.
      - "target" : encoded pandas Serie for the target on train set (with dtype='float' for a regression or dtype='int' for a classification). Indexes should match the train set.
  
  max_evals : int, default = 40.
      Number of iterations.
      For an accurate optimal hyper-parameter, max_evals = 40.
  
  Returns
  -------
  dict.
      The optimal hyper-parameter dictionary.
  
  Examples
  --------
  >>> from mlbox.optimisation import *
  >>> from sklearn.datasets import load_boston
  >>> #loading data
  >>> dataset = load_boston()
  >>> #optimising the pipeline
  >>> opt = Optimiser()
  >>> space = {
  ...     'fs__strategy':{"search":"choice","space":["variance","rf_feature_importance"]},
  ...     'est__colsample_bytree':{"search":"uniform", "space":[0.3,0.7]}
  ... }
  >>> df = {"train" : pd.DataFrame(dataset.data), "target" : pd.Series(dataset.target)}
  >>> best = opt.optimise(space, df, 3)
docstr_tok: ["Optimises","the","Pipeline",".","Optimises","hyper-parameters","of","the","whole","Pipeline","with","a","given","scoring","function",".","Algorithm","used","to","optimize",":","Tree","Parzen","Estimator",".","IMPORTANT",":","Try","to","avoid","dependent","parameters","and","to","set","one","feature","selection","strategy","and","one","estimator","strategy","at","a","time",".","Parameters","--","--","--","--","--","space",":","dict",",","default","=","None",".","Hyper-parameters","space",":","-","The","keys","must","respect","the","following","syntax",":","``","enc__param","''",".","-","``","enc","''","=","``","ne","''","for","na","encoder","-","``","enc","''","=","``","ce","''","for","categorical","encoder","-","``","enc","''","=","``","fs","''","for","feature","selector","[","OPTIONAL","]","-","``","enc","''","=","``","stck","''","+str","(","i",")","to","add","layer","n\u00b0i","of","meta-features","[","OPTIONAL","]","-","``","enc","''","=","``","est","''","for","the","final","estimator","-","``","param","''",":","a","correct","associated","parameter","for","each","step",".","Ex",":","``","max_depth","''","for","``","enc","''","=","''","est","''",",","...","-","The","values","must","respect","the","syntax",":","{","``","search","''",":","strategy",",","''","space","''",":","list","}","-","``","strategy","''","=","``","choice","''","or","``","uniform","''",".","Default","=","``","choice","''","-","list",":","a","list","of","values","to","be","tested","if","strategy=","''","choice","''",".","Else",",","list","=","[","value_min",",","value_max","]",".","df",":","dict",",","default","=","None","Dataset","dictionary",".","Must","contain","keys","and","values",":","-","``","train","''",":","pandas","DataFrame","for","the","train","set",".","-","``","target","''",":","encoded","pandas","Serie","for","the","target","on","train","set","(","with","dtype='float","'","for","a","regression","or","dtype='int","'","for","a","classification",")",".","Indexes","should","match","the","train","set",".","max_evals",":","int",",","default","=","40",".","Number","of","iterations",".","For","an","accurate","optimal","hyper-parameter",",","max_evals","=","40",".","Returns","--","--","--","-","dict",".","The","optimal","hyper-parameter","dictionary",".","Examples","--","--","--","--",">",">",">","from","mlbox.optimisation","import","*",">",">",">","from","sklearn.datasets","import","load_boston",">",">",">","#","loading","data",">",">",">","dataset","=","load_boston","(",")",">",">",">","#","optimising","the","pipeline",">",">",">","opt","=","Optimiser","(",")",">",">",">","space","=","{","...","'fs__strategy","'",":","{","``","search","''",":","''","choice","''",",","''","space","''",":","[","``","variance","''",",","''","rf_feature_importance","''","]","}",",","...","'est__colsample_bytree","'",":","{","``","search","''",":","''","uniform","''",",","``","space","''",":","[","0.3,0.7","]","}","...","}",">",">",">","df","=","{","``","train","''",":","pd.DataFrame","(","dataset.data",")",",","``","target","''",":","pd.Series","(","dataset.target",")","}",">",">",">","best","=","opt.optimise","(","space",",","df",",","3",")"]
code: def optimise(self, space, df, max_evals=40):
      """Optimises the Pipeline.
  
      Optimises hyper-parameters of the whole Pipeline with a given scoring
      function. Algorithm used to optimize : Tree Parzen Estimator.
  
      IMPORTANT : Try to avoid dependent parameters and to set one feature
      selection strategy and one estimator strategy at a time.
  
      Parameters
      ----------
      space : dict, default = None.
          Hyper-parameters space:
  
          - The keys must respect the following syntax : "enc__param".
  
              - "enc" = "ne" for na encoder
              - "enc" = "ce" for categorical encoder
              - "enc" = "fs" for feature selector [OPTIONAL]
              - "enc" = "stck"+str(i) to add layer n°i of meta-features [OPTIONAL]
              - "enc" = "est" for the final estimator
  
              - "param" : a correct associated parameter for each step. Ex: "max_depth" for "enc"="est", ...
  
          - The values must respect the syntax: {"search":strategy,"space":list}
  
              - "strategy" = "choice" or "uniform". Default = "choice"
              - list : a list of values to be tested if strategy="choice". Else, list = [value_min, value_max].
  
      df : dict, default = None
          Dataset dictionary. Must contain keys and values:
  
          - "train": pandas DataFrame for the train set.
          - "target" : encoded pandas Serie for the target on train set (with dtype='float' for a regression or dtype='int' for a classification). Indexes should match the train set.
  
      max_evals : int, default = 40.
          Number of iterations.
          For an accurate optimal hyper-parameter, max_evals = 40.
  
      Returns
      -------
      dict.
          The optimal hyper-parameter dictionary.
  
      Examples
      --------
      >>> from mlbox.optimisation import *
      >>> from sklearn.datasets import load_boston
      >>> #loading data
      >>> dataset = load_boston()
      >>> #optimising the pipeline
      >>> opt = Optimiser()
      >>> space = {
      ...     'fs__strategy':{"search":"choice","space":["variance","rf_feature_importance"]},
      ...     'est__colsample_bytree':{"search":"uniform", "space":[0.3,0.7]}
      ... }
      >>> df = {"train" : pd.DataFrame(dataset.data), "target" : pd.Series(dataset.target)}
      >>> best = opt.optimise(space, df, 3)
      """
  
      hyperopt_objective = lambda params: -self.evaluate(params, df)
  
      # Creating a correct space for hyperopt
  
      if space is None:
          warnings.warn(
              "Space is empty. Please define a search space. "
              "Otherwise, call the method 'evaluate' for custom settings"
          )
          return dict()
  
      else:
          if len(space) == 0:
              warnings.warn(
                  "Space is empty. Please define a search space. "
                  "Otherwise, call the method 'evaluate' for custom settings"
              )
              return dict()
  
          else:
              hyper_space = {}
  
              for p in space.keys():
                  if "space" not in space[p]:
                      raise ValueError(
                          "You must give a space list ie values"
                          " for hyper parameter " + p + "."
                      )
  
                  else:
                      if "search" in space[p]:
                          if space[p]["search"] == "uniform":
                              hyper_space[p] = hp.uniform(
                                  p,
                                  np.sort(space[p]["space"])[0],  # noqa
                                  np.sort(space[p]["space"])[-1],
                              )  # noqa
  
                          elif space[p]["search"] == "choice":
                              hyper_space[p] = hp.choice(
                                  p, space[p]["space"]
                              )
                          else:
                              raise ValueError(
                                  "Invalid search strategy "
                                  "for hyper parameter "
                                  + p
                                  + ". Please"
                                  " choose between 'choice' and 'uniform'."
                              )
  
                      else:
                          hyper_space[p] = hp.choice(
                              p, space[p]["space"]
                          )
  
              best_params = fmin(
                  hyperopt_objective,
                  space=hyper_space,
                  algo=tpe.suggest,
                  max_evals=max_evals,
              )
  
              # Displaying best_params
  
              for p, v in best_params.items():
                  if "search" in space[p]:
                      if space[p]["search"] == "choice":
                          best_params[p] = space[p]["space"][v]
                      else:
                          pass
                  else:
                      best_params[p] = space[p]["space"][v]
  
              if self.verbose:
                  print("")
                  print("")
                  print("~" * 137)
                  print("~" * 57 + " BEST HYPER-PARAMETERS " + "~" * 57)
                  print("~" * 137)
                  print("")
                  print(best_params)
  
              return best_params
  
imports: import numpy
  import pandas
  import warnings
  import time
  from hyperopt import fmin, hp, tpe
  from sklearn.model_selection import cross_val_score, KFold, StratifiedKFold
  from sklearn.pipeline import Pipeline
  from sklearn.metrics import SCORERS, make_scorer, roc_auc_score
  from ..encoding.na_encoder import NA_encoder
  from ..encoding.categorical_encoder import Categorical_encoder
  from ..model.classification.feature_selector import Clf_feature_selector
  from ..model.regression.feature_selector import Reg_feature_selector
  from ..model.classification.stacking_classifier import StackingClassifier
  from ..model.regression.stacking_regressor import StackingRegressor
  from ..model.classification.classifier import Classifier
  from ..model.regression.regressor import Regressor
label_desc: Use image node_id 5 for calling the Optimiser obj's underlying member method code with example usage: obj.optimise(space, df, max_evals) and returns: dict, dict, best_params