======================================
BinaryExpandFD Component Specification
======================================

.. contents:: Contents
    :local:

Overview
========
**BinaryExpandFD component** is a feature descriptor.
This component executes binary expansion of NOMINAL data using attribute domain.

**Example**:

* SPD:

  .. code-block:: python

    dl1 -> bexp1

    ---

    components:
        dl1:
            component: DataLoader

        bexp1:
            component: BinaryExpandFDComponent
            features: scale == 'nominal'

* Input of the component:

 +--------+-----------+
 |   _sid |   weather |
 +========+===========+
 |   0    | cloudy    |
 +--------+-----------+
 |   1    | sunny     |
 +--------+-----------+
 |   2    | NaN       |
 +--------+-----------+
 |   3    | rainy     |
 +--------+-----------+
 |   4    | cloudy    |
 +--------+-----------+

* Output of the component:

 +--------+------------------------+-------------------------+------------------------+
 |   _sid |   bexp1(sunny)_weather |   bexp1(cloudy)_weather |   bexp1(rainy)_weather |
 +========+========================+=========================+========================+
 |    0   |            0           |          1              |      0                 |
 +--------+------------------------+-------------------------+------------------------+
 |    1   |            1           |          0              |      0                 |
 +--------+------------------------+-------------------------+------------------------+
 |    2   |          NaN           |        NaN              |    NaN                 |
 +--------+------------------------+-------------------------+------------------------+
 |    3   |            0           |          0              |      1                 |
 +--------+------------------------+-------------------------+------------------------+
 |    4   |            0           |          1              |      0                 |
 +--------+------------------------+-------------------------+------------------------+

This component has no component-specific external formats.

.. seealso::

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

|

Parameters
==========
There are no component-specific parameters.

|

Utilizable Sample Metadata
==========================
There are no component-specific sample metadata available.

|

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

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

  * - Attribute Name
    - Scale
    - Description
  * - *<component_id>*\ (*<original_attribute_value>*\ )_\ *<original_attribute_name>*
    - INTEGER
    - Binary-expanded value of the original attribute. The value is determined by the value of the original attribute.

      .. list-table::
         :header-rows: 1

         * - Value of Original Attribute
           - Value of This Attribute
         * - NaN
           - NaN
         * - *<original_attribute_value>*
           - 1
         * - Otherwise
           - 0

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>*\ (*<original_attribute_value>*\ )_\ *<original_attribute_name>*
    - original_value
    - Set the original attribute name.

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": "weather", ... },
            {"aid": "bexp1[0]", "name": "bexp1(sunny)_weather",
             "scale": "integer", "is_excluded": false, "cid": "bexp1", "cindex": 0,
             "values": null, "is_kept": false, "context": {"original_value": "sunny"}}, 
            {"aid": "bexp1[1]", "name": "bexp1(cloudy)_weather",
             "scale": "integer", "is_excluded": false, "cid": "bexp1", "cindex": 1,
             "values": null, "is_kept": false, "context": {"original_value": "cloudy"}}, 
            {"aid": "bexp1[2]", "name": "bexp1(rainy)_weather",
             "scale": "integer", "is_excluded": false, "cid": "bexp1", "cindex": 2,
             "values": null, "is_kept": false, "context": {"original_value": "rainy"}}
        ], 
        "links": [
            {"source": "dl1[0]", "target": "bexp1[0]"},
            {"source": "dl1[0]", "target": "bexp1[1]"}, 
            {"source": "dl1[0]", "target": "bexp1[2]"} 
        ]
    }

.. 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': ['weather'], 'params': {'original_value': 'sunny'}},
         {'source_attr_names': ['weather'], 'params': {'original_value': 'cloudy'}},
         {'source_attr_names': ['weather'], 'params': {'original_value': 'rainy'}}]}

Details
=======
* In the learning phase, this component only checks if the attributes are valid as shown below:

  * If the attribute includes a non-nominal value, this component raises an exception.
  * If the attribute value is empty or NaN, this component raises an exception.

* In the running phase, this component executes binary expansion and returns transformed data.
