====================================
LogarithmFD Component Specification
====================================

.. contents:: Contents
    :local:

Overview
========
**LogarithmFD component** is a feature descriptor.
This component produces the logarithm of an input.
The scale of the input must be INTEGER or REAL.

**Example**:

* SPD:

  .. code-block:: python

    dl1 -> log1

    ---

    components:
        dl1:
            component: DataLoader

        log1:
            component: LogarithmFDComponent
            features: scale == 'real' or scale == 'integer'
            base: 10

* Input of the component:

 +--------+---------------+------------+
 |   _sid |   temperature |   pressure |
 +========+===============+============+
 | 0      | 22.3          | 1001       |
 +--------+---------------+------------+
 | 1      | 21.8          | 1002       |
 +--------+---------------+------------+
 | 2      | inf           | NaN        |
 +--------+---------------+------------+
 | 3      | 23.4          | 1002       |
 +--------+---------------+------------+
 | 4      | -inf          | 1002       |
 +--------+---------------+------------+

* Output of the component:

 +--------+--------------------+-----------------+
 |   _sid |   log1_temperature |   log1_pressure |
 +========+====================+=================+
 | 0      | 1.348305           | 3.000434        |
 +--------+--------------------+-----------------+
 | 1      | 1.338456           | 3.000868        |
 +--------+--------------------+-----------------+
 | 2      | inf                | NaN             |
 +--------+--------------------+-----------------+
 | 3      | 1.369216           | 3.000868        |
 +--------+--------------------+-----------------+
 | 4      | -inf               | 3.000868        |
 +--------+--------------------+-----------------+

This component has no component-specific external formats.

.. seealso::

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

|

Parameters
==========
Here is the component-specific parameter for the **LogarithmFD component**.
Symbol :math:`\mathrm{e}` is the Napier's constant.

SPD
---

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

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

   * - Parameter Name
     - Type
     - Domain
     - Default Value
     - Description
   * - base
     - float
     - 2, 10, :math:`\mathrm{e}`
     - :math:`\mathrm{e}`
     -   The base of a logarithm. This component produces logarithm values with respect to the base.
         If you like to designate :math:`\mathrm{e}` (Napier's constant) as base,
         please describe it as a character **'e'** in SPD files as shown below::
        
             base: 'e'

|

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

|

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

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

  * - Attribute Name
    - Scale
    - Description
  * - *<component_id>*\ _\ *<original_attribute_name>*
    - REAL
    - Logarithm of the original attribute.

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_name>*
    - base
    - Set the value of ``base``.

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": "temperature", ... },
            {"aid": "dl1[1]", "name": "pressure", ... },
            {"aid": "log1[0]", "name": "log1_temperature", "scale": "real",
             "is_excluded": false, "cid": "log1", "cindex": 0, "values": null,
             "is_kept": false, "context": {"base": 10}}, 
            {"aid": "log1[1]", "name": "log1_pressure", "scale": "real",
             "is_excluded": false, "cid": "log1", "cindex": 1, "values": null,
             "is_kept": false, "context": {"base": 10}}
        ], 
        "links": [
            {"source": "dl1[0]", "target": "log1[0]"},
            {"source": "dl1[1]", "target": "log1[1]"}
        ]
    }

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

|

Details
=======
* In the learning phase, this component only checks if the **base** parameter is valid.
* In the running phase, this component produces an output **output value** from an input **input value** as shown below:

  * **input value** is NaN:
      **output value** = NaN
  * **input value** :math:`\leq -\mathrm{e}`:
      **output value** = -log(- **input value**, base)
  * :math:`-\mathrm{e} \leq` **input value** :math:`\leq \mathrm{e}`:
      **output value** = **input value** / (:math:`\mathrm{e} \times` log(base, :math:`\mathrm{e}`))
  * :math:`\mathrm{e} \leq` **input value**:
      **output value** = log(**input value**, base)

  where log(x, base) is a function returns the logarithm of x to base.
