==================================
BinarizeFL Component Specification
==================================

.. contents:: Contents
    :local:

Overview
========
**BinarizeFL component** is a feature learner.
This component generates 'threshold' by learning sample data, and outputs features using it.
The scale of the input must be INTEGER or REAL.

**Example**:

* SPD: 

  .. code-block:: python

    dl1 -> binfl

    ---

    components:
        dl1:
            component: DataLoader
  
        binfl:
            component: BinarizeFLComponent
            features: scale == 'integer' or scale == 'real'
            max_num_output_features: 5

* Input of the component:

 +-------+--------------+--------------+
 |  _sid | Sepal.Length | Petal.Length |
 +=======+==============+==============+
 |   0   | 5.1          | 1.4          |
 +-------+--------------+--------------+
 |   1   | inf          | 1.4          |
 +-------+--------------+--------------+
 |   2   | 4.7          | 1.3          |
 +-------+--------------+--------------+
 |   3   | 4.6          | -inf         |
 +-------+--------------+--------------+
 |   4   | NaN          | NaN          |
 +-------+--------------+--------------+

* Output of the component:

 +-------+-------------------------+-------------------------+-------------------------+
 |  _sid | binfl(5.1)_Sepal.Length | binfl(4.7)_Sepal.Length | binfl(4.6)_Sepal.Length |
 +=======+=========================+=========================+=========================+
 |   0   | 1                       | 1                       | 1                       |
 +-------+-------------------------+-------------------------+-------------------------+
 |   1   | 1                       | 1                       | 1                       |
 +-------+-------------------------+-------------------------+-------------------------+
 |   2   | 0                       | 1                       | 1                       |
 +-------+-------------------------+-------------------------+-------------------------+
 |   3   | 0                       | 0                       | 1                       |
 +-------+-------------------------+-------------------------+-------------------------+
 |   4   | NaN                     | NaN                     | NaN                     |
 +-------+-------------------------+-------------------------+-------------------------+

|

 +-------+-------------------------+-------------------------+
 |  _sid | binfl(1.4)_Petal.Length | binfl(1.3)_Petal.Length |
 +=======+=========================+=========================+
 |   0   | 1                       | 1                       |
 +-------+-------------------------+-------------------------+
 |   1   | 1                       | 1                       |
 +-------+-------------------------+-------------------------+
 |   2   | 0                       | 1                       |
 +-------+-------------------------+-------------------------+
 |   3   | 0                       | 0                       |
 +-------+-------------------------+-------------------------+
 |   4   | NaN                     | NaN                     |
 +-------+-------------------------+-------------------------+

This component has no component-specific external formats.

.. seealso::

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

|

Parameters
==========
Here are the component-specific parameters for the **BinarizeFL component**.

SPD
---

The following parameter is for "components" section of SPD.

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

   * - Parameter Name
     - Type
     - Domain
     - Default Value
     - Description
   * - max_num_output_features: [1]_
     - int
     - [1, inf)
     - --
     - The upper limit value of the number of output attributes.

.. [1] Required parameter

|

Output Attributes
=================
**BinarizeFL component** generates the following attribute:

.. list-table::
  :header-rows: 1
  :widths: 3,1,3

  * - Attribute Name
    - Scale
    - Description
  * - *<component_id>*\ (<threshold>)\ _\ *<original_attribute_name>*
    - INTEGER
    - Binarized value by threshold of the original value.

These attributes are in the component output data. These can be loaded
in SAMPO API or saved as data.csv after executing :ref:`convert_process`.

.. seealso::

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

|

Attribute Metadata
==================
The metadata of the output attributes is created with the following rules.
    
Context Rule
------------
.. list-table::
  :header-rows: 1
  :widths: 3,1,3

  * - Attribute Name 
    - Context Name
    - Description
  * - *<component_id>*\ (<threshold>)\ _\ *<original_attribute_name>*
    - threshold
    - Set the value of ``threshold``.

Derivation Rule
---------------
Each new attribute is derived from the corresponding attribute selected by the ``features`` parameter of the component.

Example
-------
.. code-block:: javascript

    {
        "nodes": [
            {"aid": "_sid", "name": "_sid", ... },
            {"aid": "dl1[0]", "name": "Sepal.Length", ... },
            {"aid": "dl1[1]", "name": "Petal.Length", ... },
            {"aid": "binfl[0]", "name": "binfl(5.1)_Sepal.Length", "scale": "integer",
             "is_excluded": false, "cid": "binfl", "cindex": 0, "values": null, "is_kept": false,
             "context": {"threshold": 5.1000000000000000e+00}},
            {"aid": "binfl[1]", "name": "binfl(4.7)_Sepal.Length", "scale": "integer",
             "is_excluded": false, "cid": "binfl", "cindex": 1, "values": null, "is_kept": false,
             "context": {"threshold": 4.7000000000000000e+00}},
            {"aid": "binfl[2]", "name": "binfl(4.6)_Sepal.Length", "scale": "integer",
             "is_excluded": false, "cid": "binfl", "cindex": 2, "values": null, "is_kept": false,
             "context": {"threshold": 4.6000000000000000e+00}},
            {"aid": "binfl[3]", "name": "binfl(1.4)_Petal.Length", "scale": "integer",
             "is_excluded": false, "cid": "binfl", "cindex": 3, "values": null, "is_kept": false,
             "context": {"threshold": 1.4000000000000000e+00}},
            {"aid": "binfl[4]", "name": "binfl(1.3)_Petal.Length", "scale": "integer",
             "is_excluded": false, "cid": "binfl", "cindex": 4, "values": null, "is_kept": false,
             "context": {"threshold": 1.30000000000000000e+00}},
        ], 
        "links": [
            {"source": "dl1[0]", "target": "binfl[0]"}, 
            {"source": "dl1[0]", "target": "binfl[1]"},
            {"source": "dl1[0]", "target": "binfl[2]"}, 
            {"source": "dl1[1]", "target": "binfl[3]"} 
            {"source": "dl1[1]", "target": "binfl[4]"} 
        ]
    }

.. seealso::
    
    Attribute metadata file format in :ref:`Attribute Metadata File Specification <attribute-metadata>`

|

Model
=====
The model of this component can be described by its fd_params.

.. list-table::
  :header-rows: 1
  :widths: 3,1,3

  * - fd_params
    - Type
    - Description
  * - source_attr_names
    - list of string
    - A list of attribute names where the output attribute is derived from.
  * - params
    - dict
    - The keys of this dictionary are the same as the context of this component's Attribute Metadata.

When loaded in the SAMPO API, the model is represented as a dict of its fd_params.

.. seealso::

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

::

    {'fd_params':
        [{'source_attr_names': ['Sepal.Length'], 'params': {'threshold': 5.1000000000000000e+00}},
         {'source_attr_names': ['Sepal.Length'], 'params': {'threshold': 4.7000000000000000e+00}},
         {'source_attr_names': ['Sepal.Length'], 'params': {'threshold': 4.6000000000000000e+00}},
         {'source_attr_names': ['Petal.Length'], 'params': {'threshold': 1.4000000000000000e+00}},
         {'source_attr_names': ['Petal.Length'], 'params': {'threshold': 1.30000000000000000e+00}}]}

Details
=======
* In the running phase, the output values calculated by the input values and parameter as follows.

    * :math:`original value >=` ``threshold``:
        **output value** = ``1``

    * :math:`original value <` ``threshold``:
        **output value** = ``0``

