==============================================
FABHMEBernGateLinearCl Component Specification
==============================================

.. contents:: Contents
    :local:

Overview
========
FABHMEBernGateLinearCl component is a linear binary classification component with FAB/HME algorithm.
This component learns a tree-structured model in which each sample is assigned to a component according to Bernoulli gating functions.

.. note::

    FAB engine uses the word 'component' with a different meaning from that of SAMPO.
    Each component in FAB/HME is a prediction formula, and each sample data is assigned to a specific component for prediction.

**Example**:

* SPD:

  .. code-block:: yaml

    # fabhmecl.spd
    dl1 -> fab1

    ---
    components:
        dl1:
            component: DataLoader
        fab1:
            component: FABHMEBernGateLinearClComponent
            features: name != 'class'
            tree_depth: 3
            target: name == 'class'
            positive_label: 'Iris-setosa'

    global_settings:
        keep_attributes:
            - class
        feature_exclude:
            - class


* Input of the component:

 +--------+----------------+---------------+----------------+
 |   _sid | \sepal_length_ | \sepal_width_ |   class        |
 |        | in_cm          | in_cm         |                |
 +========+================+===============+================+
 | 0      | 4.9            | 2.5           | Iris-versicolor|
 +--------+----------------+---------------+----------------+
 | 1      | 6.2            | 2.8           | Iris-versicolor|
 +--------+----------------+---------------+----------------+
 | 2      | 7.2            | 3.6           | Iris-versicolor|
 +--------+----------------+---------------+----------------+
 | ...    | ...            | ...           | ...            |
 +--------+----------------+---------------+----------------+
 | 28     | 6.2            | 2.9           | Iris-setosa    |
 +--------+----------------+---------------+----------------+
 | 29     | 6.7            | 3.1           | Iris-setosa    |
 +--------+----------------+---------------+----------------+

 |

* Output of the component:

 +----------+-----------+------------+---------------+-----------------------+
 |   _sid   | \fab1_    | \fab1_     |\fab1_score    |   \fab1_              |
 |          | actual    | predict    |               |   assigned_comp_id    |
 +==========+===========+============+===============+=======================+
 | 0        | -1        | 1          | 2.657069e+00  | 2                     |
 +----------+-----------+------------+---------------+-----------------------+
 | 1        | -1        | 1          | 6.524541e-01  | 2                     |
 +----------+-----------+------------+---------------+-----------------------+
 | 2        | -1        | -1         | -1.600153e+00 | 0                     |
 +----------+-----------+------------+---------------+-----------------------+
 | ...      | ...       | ...        | ...           | ...                   |
 +----------+-----------+------------+---------------+-----------------------+
 | 28       |  1        | 1          | 6.524541e-01  | 2                     |
 +----------+-----------+------------+---------------+-----------------------+
 | 29       |  1        | -1         | -1.080094e+00 | 0                     |
 +----------+-----------+------------+---------------+-----------------------+

 |

 +----------+---------------+---------------+---------------+---------------+---------------+---------------+
 |   _sid   |   \fab1_      |   \fab1_      |   \fab1_      |   \fab1_      |   \fab1_      |   \fab1_      |
 |          |   predict_c0  |   score_c0    |   predict_c1  |   score_c1    |   predict_c2  |   score_c2    |
 +==========+===============+===============+===============+===============+===============+===============+
 | 0        |  1            |  7.921206e-01 | -1            | -1.028756e+00 | 1             | 2.657069e+00  |
 +----------+---------------+---------------+---------------+---------------+---------------+---------------+
 | 1        | -1            | -5.600341e-01 | -1            | -2.346818e+01 | 1             | 6.524541e-01  |
 +----------+---------------+---------------+---------------+---------------+---------------+---------------+
 | 2        | -1            | -1.600153e+00 | -1            | -1.082974e+01 | -1            | -8.895575e-01 |
 +----------+---------------+---------------+---------------+---------------+---------------+---------------+
 | ...      | ...           | ...           | ...           | ...           | ...           | ...           |
 +----------+---------------+---------------+---------------+---------------+---------------+---------------+
 | 28       | -1            | -5.600341e-01 | -1            | -1.821556e+01 | 1             | 6.524541e-01  |
 +----------+---------------+---------------+---------------+---------------+---------------+---------------+
 | 29       | -1            | -1.080094e+00 | -1            | -2.240158e+01 | -1            | -1.185517e-01 |
 +----------+---------------+---------------+---------------+---------------+---------------+---------------+

This component has component-specific external formats for model and prediction result evaluation.

.. seealso::

    Component-common external format files in :ref:`convert_process`

|

Parameters
==========
This component has the following component-specific parameters.

SPD
---

The following parameters are for "components" section of SPD.

.. list-table::
  :header-rows: 1
  :widths: 10, 5, 15, 10, 50

  * - Parameter Name
    - Type
    - Domain
    - Default Value
    - Description
  * - positive_label [1]_
    - str
    - See Description
    - --
    - A value chosen from the target attributes to be set as positive label.
      The domain of this parameter corresponds to that of the target attribute.
  * - max_fab_iterations
    - int
    - [1, inf)
    - 100
    - Maximum number of FAB-iterations.
  * - start_from_mstep [2]_ [3]_
    - bool
    - True / False
    - False
    - If True, the first iteration starts with M-step; otherwise, E-step.
  * - num_acceleration_steps
    - int
    - [0, inf)
    - 0
    - The number of steps of acceleration algorithm for each FAB-iteration.
      If 0, the acceleration algorithm is disabled.
  * - repeat_until_convergence
    - bool
    - True / False
    - False
    - If False, FAB-iterations and the post-processing are executed only once
      even if the FAB-iterations are stopped not by convergence condition but
      by ``max_fab_iterations`` condition.
  * - projection_estep
    - bool
    - True / False
    - False
    - Whether the projection E-step algorithm is enabled.
  * - shrink_threshold
    - float or str
    - [1, inf) or (0%, 100%)
    - 1.0
    - Threshold value for shrinkage. If a percentage value (e.g. ``'1.0%'``)
      is specified, shrinkage is executed according to relative value,
      :math:`N_{\rm scaled\_sample} \times t_{\rm shrink}` where
      :math:`t_{\rm shrink}` is the threshold value and :math:`N_{\rm scaled\_sample}`
      is the number of scaled expected samples.
  * - fab_stop_threshold
    - float or str
    - (0, inf) or (0%, inf%)
    - 0.001
    - Threshold value for FAB-iterations: if the increase of FIC value
      is less than the threshold, the FAB-iterations is considered to
      be converged. If a percentage value (e.g. ``'1.0%'``) is specified,
      convergence check is executed according to relative value,
      :math:`(FIC^{(t)} - FIC^{(t-1)}) / | FIC^{(t-1)} |`.
  * - gate_features
    - str
    - Query format
    - all()
    - Features which are applied to gate parameter optimizations.
      If not specified, all features are used.
  * - comp_features
    - str
    - Query format
    - all()
    - Features which are applied to component parameter optimizations.
      If not specified, all features are used.
      If empty, the model is learned as a decision tree.
  * - comp_mandatory_features
    - str
    - Query format
    - See Description
    - Features which non-L0-regularize constraints are applied to.
      It means the specified features will always be relevant for all components.
      If not specified, no features are specified for non-L0-regularization,
      which implies all relevant features are selected by FoBa algorithm.
  * - comp_positive_features
    - str
    - Query format
    - See Description
    - Features whose weight values for all components are constrained to positive values.
      If not specified, all features are optimized with no constraints.
  * - comp_negative_features
    - str
    - Query format
    - See Description
    - Features whose weight values for all components are constrained to negative values.
      If not specified, all features are optimized with no constraints.
  * - tree_depth [2]_ [3]_
    - int
    - [0, inf)
    - 5
    - Initial depth of the gate-tree structure of latent variable prior.
      The initial number of components is :math:`2^d` where :math:`d` is
      tree depth. If 0, the optimization with only one component will be
      executed.
  * - comp_weights_min_scale [2]_ [3]_
    - float
    - (-inf, inf)
    - -0.5
    - Scale value for the initialization of weight values of components.
  * - comp_weights_max_scale [2]_ [3]_
    - float
    - (-inf, inf)
    - 0.5
    - Scale value for the initialization of weight values of components.
  * - comp_bias_min_scale [2]_ [3]_
    - float
    - (-inf, inf)
    - 0.25
    - Scale value for the initialization of bias values of components.
  * - comp_bias_max_scale [2]_ [3]_
    - float
    - (-inf, inf)
    - 0.75
    - Scale value for the initialization of bias values of components.
  * - gate_max_bins
    - int
    - [1, inf)
    - See Description
    - Maximum number of binning for each feature, which is used for gate
      parameter optimization. If not specified, all unique samples for each feature
      are used; otherwise, the equal-width binning algorithm is adopted.
  * - comp_foba_skip
    - str
    - {'power_of_two', 'quarter_square', 'none'}
    - 'power_of_two'
    - The judging function type for the FoBa algorithm skipping. If 'none',
      FoBa is executed for all FAB-iteration steps. FoBa is skipped at
      :math:`{\rm log}_{2}t \ne {\rm ceil}({\rm log}_{2}t)` if 'power_of_two', or
      :math:`t \bmod {\rm ceil}(\sqrt{t}) \ne 0` if 'quarter_square'.
      :math:`t` is FAB-iteration step index (:math:`t` starts from 1).
  * - comp_foba_skip_max_interval
    - int
    - [2, inf)
    - 25
    - The maximum interval for the FoBa algorithm skipping. If comp_foba_skip is 'none',
      this value is ignored.
  * - comp_backward_step
    - bool
    - True / False
    - False
    - Whether the backward-steps of FoBa algorithm are enabled. In the
      post-process, backward-steps are carried out regardless of this argument
      value.
  * - comp_l2_regularize
    - float
    - [0, inf)
    - 0.0
    - L2-regularization hyper-parameter for component parameter optimization.
      The larger the specified value, the stronger the regularization effect
      is. If 0.0, L2-regularization is disabled.
  * - with_comp_scaled_l0_regularize
    - bool
    - True / False
    - True
    - Whether with scaled L0-regularization using a tighter lower bound of
      FIC for component parameter optimization; approximation of det(F) is
      refined, where F is a Fisher matrix.
  * - max_comp_relevant_features
    - int
    - [1, inf)
    - 100
    - Maximum number of the relevant features for each component.
  * - max_comp_foba_iterations
    - int
    - [1, inf)
    - 100
    - Maximum number of the FoBa-iterations for each component.
  * - num_threads_gates
    - int
    - [1, inf)
    - 1
    - Maximum number of OpenMP threads of gate parameter optimization where
      tasks for all gates are divided into.
  * - num_threads_gate_features
    - int
    - [1, inf)
    - 1
    - Maximum number of OpenMP threads of gate parameter optimization where
      tasks for all features are divided into.
  * - num_threads_comps
    - int
    - [1, inf)
    - 1
    - Maximum number of OpenMP threads of component parameter optimization.

.. [1] Required parameter
.. [2] Ignore parameter in posterior hot-start
.. [3] Ignore parameter in model hot-start


SRC
---

The following parameter is for "hotstart" section of SRC.

.. list-table::
  :header-rows: 1
  :widths: 10, 5, 15, 10, 50

  * - Parameter Name
    - Type
    - Domain
    - Default Value
    - Description
  * - type
    - str
    - {'posterior', 'mh_refit_comp', 'mh_opt_comp', 'mh_refit_gate_and_refit_comp', 'mh_refit_gate_and_opt_comp', 'mh_opt_gate_and_opt_comp'}
    - 
    - The hot-start type. If 'posterior', FAB learns with posterior hot-start which use the
      initial model whose tree structure is generated by base model and data. Each gate and
      component parameters are initialized randomly. 'mh_XXX' means FAB learns with model
      hot-start which uses base model as initial model. 'refit_{gate, comp}' means refitting the
      gate functions or prediction formulas with current data. 'opt_{gate, comp}' means optimizing
      (feature selection and fitting) the gate functions or prediction formulas with current data.

|

Utilizable Sample Metadata
==========================
.. warning::

   _fabhme_assigned_comp_id is deprecated. Use hotstart section of SRC instead of _fabhme_assigned_comp_id data column.

This component can utilize the _fabhme_assigned_comp_id attribute of the sample metadata to hot-start with posterior.
When the attribute _fabhme_assigned_comp_id attribute is specified in the input data,
this component will start the FAB/HME algorithm with the _fabhme_assigned_comp_id attribute values as its initial posterior.

To create the attribute _fabhme_assigned_comp_id, see the specification of the command sampo_ps_fabhme export_assigned_comp_id.

|

Output Attributes
=================

.. include:: ./fabhme/linear_cl_output_attributes.rst

These attributes are in the component output data. These can be loaded in SAMPO API.

.. seealso::

    Obtaining process results via `ProcessResultLoader <../../api/process_result_loader.html>`_.

When :ref:`convert_process` is executed,
the component output data will be saved in *<component_id>*\_predict_result.csv.

.. include:: ./fabhme/cl_predict_result.rst

|

Attribute Metadata
==================

.. include:: ./fabhme/linear_cl_attr_metadata.rst

|

Model
=====

.. include:: ./fabhme/linear_cl_model_params.rst
.. include:: ./fabhme/bern_gate_tree_keys.rst

When the model is loaded in the SAMPO API, the model parameters will be output as a single dictionary.

.. seealso::

    Obtaining process results via `ProcessResultLoader <../../api/process_result_loader.html>`_

::

    {'fic': -10.530893900263704,
     'num_initial_comps': 32,
     'num_active_comps': 2,
     'gate_tree':
         {'gate_type': 'bern',
          'hard_gate': True,
          'nodes': [
              {'node_type': 'gate',
               'node_id': 0,
               'gate_func':
                   {'threshold': 5.45,
                    'aid': 'dl[0]',
                    'attr_name': 'sepal_length_in_cm',
                    'prob_left_smaller_than_threshold': 0.0}},
              {'comp_id': 0, 'node_type': 'component', 'node_id': 1},
              {'comp_id': 7, 'node_type': 'component', 'node_id': 2}],
          'edges': [
              {'source': 0,
               'target': 1,
               'is_left': True},
              {'source': 0,
               'target': 2,
               'is_left': False}]}},
     'prediction_formulas':
                             prediction_formula_0  prediction_formula_7
         attr_name
         sepal_length_in_cm              0.000000              0.000000
         petal_length_in_cm             15.125137             20.946018
         bias                          -53.462099            -58.358208}


External Format
---------------
When :ref:`convert_process` is executed,
the model parameters are saved into different files and are grouped as:
general information, gating function, and prediction formula.

General Information
```````````````````
This file describes which consist of the following model parameters: :math:`FIC` after learning the model,
initial number of components, and the terminal number of components.

::

    fic,num_initial_comps,num_active_comps
    -1.294308e+02,8,3

Gate Tree
`````````

.. include:: ./fabhme/model_bern_gate_tree.rst

Prediction Formulas
```````````````````

.. include:: ./fabhme/model_linear_cl_prediction_formulas.rst


Prediction Result Evaluation
============================

.. include:: ./fabhme/cl_predict_result_evaluation_indices.rst

When obtaining these evaluation results in SAMPO API, a pandas.DataFrame is loaded
with the evaluation indices as the columns of the DataFrame.

.. seealso::

    Obtaining process results via `ProcessResultLoader <../../api/process_result_loader.html>`_

External Format
---------------
When :ref:`convert_process` is executed, the evaluation results
are saved as a CSV file with the evaluation indices as the header of the CSV.

.. include:: ./fabhme/cl_predict_result_evaluation.rst

|

Details
=======
If a data set has samples with missing or +/-Inf values, this component ignores those samples.
