===================================
HingeRampFL Component Specification
===================================

.. contents:: Contents
    :local:

Overview
========
**HingeRampFL component** is a feature learner.
This component generates 'slope', 'intercept', 'upper_limit' and 'lower_limit' by learning sample data, and outputs features using them.
The scale of the input must be INTEGER or REAL.

**Example**:

* SPD:

  .. code-block:: python

    dl1 -> hrfl1

    ---

    components:
        dl1:
            component: DataLoader

        hrfl1:
            component: HingeRampFLComponent
            features: scale == 'real' or scale == 'integer'
            max_num_output_features: 100

* 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 | hrfl1(2.0:-9.2:1.0:0.0)_Sepal.Length |
 +========+======================================+
 |   0    | 1                                    |
 +--------+--------------------------------------+
 |   1    | 1                                    |
 +--------+--------------------------------------+
 |   2    | 0.20000000000000107                  |
 +--------+--------------------------------------+
 |   3    | 0.0                                  |
 +--------+--------------------------------------+
 |   4    | 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 **HingeRampFL 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
=================
**HingeRampFL component** generates the following attribute:

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

  * - Attribute Name
    - Scale
    - Description
  * - *<component_id>*\ (<slope>:<intercept>:<upper_limit>:<lower_limit>)\ _\ *<original_attribute_name>*
    - REAL
    - Linearly-transformed value with upper/lower limit 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>*\ (<slope>:<intercept>:<upper_limit>:<lower_limit>)\ _\ *<original_attribute_name>*
    - slope
    - Set the value of ``slope``.
  * - *<component_id>*\ (<slope>:<intercept>:<upper_limit>:<lower_limit>)\ _\ *<original_attribute_name>*
    - intercept
    - Set the value of ``intercept``.
  * - *<component_id>*\ (<slope>:<intercept>:<upper_limit>:<lower_limit>)\ _\ *<original_attribute_name>*
    - upper_limit
    - Set the value of ``upper_limit``.
  * - *<component_id>*\ (<slope>:<intercept>:<upper_limit>:<lower_limit>)\ _\ *<original_attribute_name>*
    - lower_limit
    - Set the value of ``lower_limit``.

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": "hrfl1[0]", "name": "hrfl1(2.0:1.0:1.0:0.0)_Sepal.Length", "scale": "real",
             "is_excluded": false, "cid": "hrfl1", "cindex": 0, "values": null, "is_kept": false,
             "context": {"slope": 2.0000000000000000e+00, "intercept": 1.0000000000000000e+00,
                         "lower_limit": 0.0000000000000000e+00, "upper_limit": 1.0000000000000000e+01}}
        ],
        "links": [
            {"source": "dl1[0]", "target": "hrfl1[0]"}
        ]
    }

.. 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': {'slope': 2.0000000000000000e+00,
                     'intercept': 1.0000000000000000e+00,
                     'lower_limit': 0.0000000000000000e+00,
                     'upper_limit': 1.0000000000000000e+01}}]}



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

  * Linear Function

    :math:`y =` ``slope`` :math:`\times` **input value** :math:`+` ``intercept``

  * Conditional Branching

    :math:`y <` ``lower_limit``:
      **output value** = ``lower_limit``

    ``lower_limit`` :math:`\leq y \leq` ``upper_limit``:
      **output value** = :math:`y`

    ``upper_limit`` :math:`< y`:
      **output value** = ``upper_limit``

  where ``slope``, ``intercept``, ``lower_limit``, and ``upper_limit`` are the component parameters.
