:py:mod:`ForeTiS.model._base_model`
===================================

.. py:module:: ForeTiS.model._base_model


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   ForeTiS.model._base_model.BaseModel




.. py:class:: BaseModel(optuna_trial, datasets, featureset_name, pca_transform, target_column, optimize_featureset)

   Bases: :py:obj:`abc.ABC`

   BaseModel parent class for all models that can be used within the framework.

   Every model must be based on :obj:`~ForeTiS.model._base_model.BaseModel` directly or
   BaseModel's child classes, e.g. :obj:`~ForeTiS.model._sklearn_model.SklearnModel` or
   :obj:`~ForeTiS.model._torch_model.TorchModel`

   ** Attributes **

       * Instance attributes *

       - optuna_trial (*optuna.trial.Trial*): trial of optuna for optimization
       - datasets (*list<pd.DataFrame>*): all datasets that are available
       - n_outputs (*int*): number of outputs of the prediction model
       - all_hyperparams (*dict*): dictionary with all hyperparameters with related info that can be tuned (structure see :obj:`~ForeTiS.model._base_model.BaseModel.define_hyperparams_to_tune`)
       - dataset (*pd.DataFrame*): the dataset for this optimization trial
       - model: model object
       - target_column: the target column for the prediction
       - pca_transform: whether conducting pca transformation should be a hyperparameter to optimize or not
       - featureset: the recent featureset

   :param optuna_trial: Trial of optuna for optimization
   :param datasets: all datasets that are available
   :param featureset_name: the name of the recent feature set
   :param target_column: the target column for the prediction
   :param pca_transform: whether conducting pca transformation should be a hyperparameter to optimize or not
   :param optimize_featureset: whether the feature set should be optimized or not


   .. py:method:: define_model()
      :abstractmethod:

      Method that defines the model that needs to be optimized.
      Hyperparams to tune have to be specified in all_hyperparams and suggested via suggest_hyperparam_to_optuna().
      The hyperparameters have to be included directly in the model definiton to be optimized.
      e.g. if you want to optimize the number of layers, do something like

          .. code-block:: python

              n_layers = self.suggest_hyperparam_to_optuna('n_layers') # same name in define_hyperparams_to_tune()
              for layer in n_layers:
                  do something

      Then the number of layers will be optimized by optuna.


   .. py:method:: define_hyperparams_to_tune()
      :abstractmethod:

      Method that defines the hyperparameters that should be tuned during optimization and their ranges.
      Required format is a dictionary with:

      .. code-block:: python

          {
              'name_hyperparam_1':
                  {
                  # MANDATORY ITEMS
                  'datatype': 'float' | 'int' | 'categorical',
                  FOR DATATYPE 'categorical':
                      'list_of_values': []  # List of all possible values
                  FOR DATATYPE ['float', 'int']:
                      'lower_bound': value_lower_bound,
                      'upper_bound': value_upper_bound,
                      # OPTIONAL ITEMS (only for ['float', 'int']):
                      'log': True | False  # sample value from log domain or not
                      'step': step_size # step of discretization.
                                          # Caution: cannot be combined with log=True
                                                          # - in case of 'float' in general and
                                                          # - for step!=1 in case of 'int'
                  },
              'name_hyperparam_2':
                  {
                  ...
                  },
              ...
              'name_hyperparam_k':
                  {
                  ...
                  }
          }

      If you want to use a similar hyperparameter multiple times (e.g. Dropout after several layers),
      you only need to specify the hyperparameter once. Individual parameters for every suggestion will be created.


   .. py:method:: retrain(retrain)
      :abstractmethod:

      Method that runs the retraining of the model

      :param retrain: data for retraining


   .. py:method:: update(update, period)
      :abstractmethod:

      Method that runs the updating of the model

      :param update: data for updating


   .. py:method:: predict(X_in)
      :abstractmethod:

      Method that predicts target values based on the input X_in

      :param X_in: feature matrix as input

      :return: numpy array with the predicted values


   .. py:method:: train_val_loop(train, val)
      :abstractmethod:

      Method that runs the whole training and validation loop

      :param train: data for the training
      :param val: data for validation

      :return: predictions on validation set


   .. py:method:: suggest_hyperparam_to_optuna(hyperparam_name)

      Suggest a hyperparameter of hyperparam_dict to the optuna trial to optimize it.

      If you want to add a parameter to your model / in your pipeline to be optimized, you need to call this method

      :param hyperparam_name: name of the hyperparameter to be tuned (see :obj:`~ForeTiS.model._base_model.BaseModel.define_hyperparams_to_tune`)

      :return: suggested value


   .. py:method:: suggest_all_hyperparams_to_optuna()

      Some models accept a dictionary with the model parameters.
      This method suggests all hyperparameters in all_hyperparams and gives back a dictionary containing them.

      :return: dictionary with suggested hyperparameters


   .. py:method:: featureset_hyperparam()

      Method that defines the feature set hyperparameter that should be tuned during optimization and its ranges.


   .. py:method:: pca_transform()

      Method that defines the pca transform hyperparameter that should be tuned during optimization and its ranges.


   .. py:method:: save_model(path, filename)

      Persist the whole model object on a hard drive
      (can be loaded with :obj:`~ForeTiS.model._model_functions.load_model`)

      :param path: path where the model will be saved
      :param filename: filename of the model