> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# create_filter_insight

> Create a new insight from a selection of nodes. 

## Usage

The following examples show how the step can be used in a recipe.

<Accordion title="Examples" icon="code" defaultOpen="true">
  <Tabs>
    <Tab title="Example 1">
      The following example is the most simple way to create a new insight. It just create an insight of the "age" variable by adding its chart and a title.

      ```stan theme={null}
      create_filter_insight({
        "column": "age",
        "title": "Age distribution"
      })
      ```
    </Tab>

    <Tab title="Example 2">
      The following example creates an insight of the "age" variable by adding its chart, a title and making a filter selection from its 75 percentil to its maximum value.

      ```stan theme={null}
      create_filter_insight({
        "column": "age",
        "title": "Most aged people",
        "selection": "age: >= P75 AND <= MAX"
      })
      ```
    </Tab>

    <Tab title="Example 3">
      The following example creates an insight of the "cluster" variable by representing it as list.

      ```stan theme={null}
      create_filter_insight({
        "column": "cluster",
        "title": "Cluster segments",
        "columnViewModes": {
          "cluster": "list"
        }
      })
      ```
    </Tab>

    <Tab title="Signature">
      General syntax for using the step in a recipe. Shows the inputs and outputs the step is expected to receive and will produce respectively. For futher details see sections below.

      ```stan theme={null}
      create_filter_insight(, {
          "param": value,
          ...
      })
      ```
    </Tab>
  </Tabs>
</Accordion>

## Inputs & Outputs

The following are the inputs expected by the step and the outputs it produces. These are generally
columns (`ds.first_name`), datasets (`ds` or `ds[["first_name", "last_name"]]`) or models (referenced
by name e.g. `"churn-clf"`).

<Accordion title="Inputs" icon="right-to-bracket" />

<Accordion title="Outputs" icon="right-from-bracket" />

## Configuration

The following parameters can be used to configure the behaviour of the step by including them in
a json object as the last "input" to the step, i.e. `step(..., {"param": "value", ...}) -> (output)`.

<Accordion title="Parameters" defaultOpen="true" icon="sliders">
  <ParamField path="title" type="string" required>
    Title of the insight.
  </ParamField>

  <ParamField path="replayDisabled" type="[string, boolean]" default="false">
    Indicates if the insight can replay its original state or not.

    Values must be one of the following:

    * `drillDown`
    * `directSelectionInGraph`
    * `nonPersistedColumn`
    * `True`
    * `False`
  </ParamField>

  <ParamField path="colorColumn" type="[string, null]">
    Column used to color the UI.
  </ParamField>

  <ParamField path="insightThemeMode" type="string">
    Theme mode applied to the whole insight.

    Values must be one of the following:

    * `dark`
    * `light`
  </ParamField>

  <ParamField path="isAutoMode" type="boolean">
    Defines if the cross-filters mode is set to auto.
  </ParamField>

  <ParamField path="ignoreNulls" type="boolean">
    Defines if the cross-filters and significant variables should ignore null values.
  </ParamField>

  <ParamField path="relative" type="boolean">
    Sets the visualization type to absolute or relative.
  </ParamField>

  <ParamField path="statsVisibility" type="boolean">
    Useful to shown or not the statistics of the main variable/column.
  </ParamField>

  <ParamField path="selection" type="string">
    A filter query.
    See [Advanced query filters](https://docs.graphext.com/concepts/ds-concepts/filter-queries#advanced-filter-queries) for more information.
  </ParamField>

  <ParamField path="categoricalColumnsOrdering" type="object">
    The order in which a variable's categories are displayed.
    An object configuring for each column a method determining the order of its categories.

    <Accordion title="Item properties">
      <ParamField path="Items" type="string">
        Order of the categories in a specific column.

        Values must be one of the following:

        * `BACKGROUND`
        * `FOREGROUND`
        * `UPLIFT`
        * `TFIDF`
        * `ORDINAL`
      </ParamField>
    </Accordion>
  </ParamField>

  <ParamField path="categoricalColumnsThreshold" type="object">
    Configure categories to hide in the filter view of categorical variables.
    Categories less frequent than the configured threshold will not appear in the UI.

    <Accordion title="Properties">
      <ParamField path="thresholds" type="[array, array, array, array]">
        A list of threshold configurations.
        A categorical column can have two kinds of thresholds determining whether specific categories will be
        hidden from its view in the UI: a minimum number of rows in the current *selection* below which a category
        will be hidden, or a minimum number of rows in the *whole dataset* (*everything*).

        The `thresholds` parameter should be a list containing 1 or 2 objects: the configuration of a *selection*
        threshold, and/or the configuration of a threshold for *everything*.

        <Accordion title="Options">
          <Tabs>
            <Tab title="array">
              <ParamField path="{_}" type="array">
                array.

                <Accordion title="Array items">
                  <ParamField path="Item 0" type="object">
                    Configure categories to be discarded (hidden) in terms of their occurrence in the *whole dataset*.
                    Categories with a number (or percentage) of rows in the *whole dataset* less than `value` will be discarded (hidden from the variable's filter view).

                    <Accordion title="Properties">
                      <ParamField path="target" type="string" default="EVERYTHING">
                        Whether to apply the threshold to the current selection of rows or all rows in the dataset.
                      </ParamField>

                      <ParamField path="reference" type="string">
                        Whether to interpret the threshold value as an absolute (count) or percentage of rows.

                        Values must be one of the following:

                        * `ABSOLUTE`
                        * `PERCENTAGE`
                      </ParamField>

                      <ParamField path="value" type="number">
                        Categories less frequent than this value will be discarded (hidden).
                      </ParamField>
                    </Accordion>
                  </ParamField>
                </Accordion>
              </ParamField>
            </Tab>

            <Tab title="array">
              <ParamField path="{_}" type="array">
                array.

                <Accordion title="Array items">
                  <ParamField path="Item 0" type="object">
                    Configure categories to be discarded (hidden) in terms of their occurrence in the *current selection*.
                    Categories with a number (or percentage) of rows in the current selection less than `value` will be discarded (hidden from the variable's filter view).

                    <Accordion title="Properties">
                      <ParamField path="target" type="string" default="SELECTION">
                        Whether to apply the threshold to the current selection of rows or all rows in the dataset.
                      </ParamField>

                      <ParamField path="reference" type="string">
                        Whether to interpret the threshold value as an absolute (count) or percentage of rows.

                        Values must be one of the following:

                        * `ABSOLUTE`
                        * `PERCENTAGE`
                      </ParamField>

                      <ParamField path="value" type="number">
                        Categories less frequent than this value will be discarded (hidden).
                      </ParamField>
                    </Accordion>
                  </ParamField>
                </Accordion>
              </ParamField>
            </Tab>

            <Tab title="array">
              <ParamField path="{_}" type="array">
                array.

                <Accordion title="Array items">
                  <ParamField path="Item 0" type="object">
                    Configure categories to be discarded (hidden) in terms of their occurrence in the *whole dataset*.
                    Categories with a number (or percentage) of rows in the *whole dataset* less than `value` will be discarded (hidden from the variable's filter view).

                    <Accordion title="Properties">
                      <ParamField path="target" type="string" default="EVERYTHING">
                        Whether to apply the threshold to the current selection of rows or all rows in the dataset.
                      </ParamField>

                      <ParamField path="reference" type="string">
                        Whether to interpret the threshold value as an absolute (count) or percentage of rows.

                        Values must be one of the following:

                        * `ABSOLUTE`
                        * `PERCENTAGE`
                      </ParamField>

                      <ParamField path="value" type="number">
                        Categories less frequent than this value will be discarded (hidden).
                      </ParamField>
                    </Accordion>
                  </ParamField>

                  <ParamField path="Item 1" type="object">
                    Configure categories to be discarded (hidden) in terms of their occurrence in the *current selection*.
                    Categories with a number (or percentage) of rows in the current selection less than `value` will be discarded (hidden from the variable's filter view).

                    <Accordion title="Properties">
                      <ParamField path="target" type="string" default="SELECTION">
                        Whether to apply the threshold to the current selection of rows or all rows in the dataset.
                      </ParamField>

                      <ParamField path="reference" type="string">
                        Whether to interpret the threshold value as an absolute (count) or percentage of rows.

                        Values must be one of the following:

                        * `ABSOLUTE`
                        * `PERCENTAGE`
                      </ParamField>

                      <ParamField path="value" type="number">
                        Categories less frequent than this value will be discarded (hidden).
                      </ParamField>
                    </Accordion>
                  </ParamField>
                </Accordion>
              </ParamField>
            </Tab>

            <Tab title="array">
              <ParamField path="{_}" type="array">
                array.

                <Accordion title="Array items">
                  <ParamField path="Item 0" type="object">
                    Configure categories to be discarded (hidden) in terms of their occurrence in the *current selection*.
                    Categories with a number (or percentage) of rows in the current selection less than `value` will be discarded (hidden from the variable's filter view).

                    <Accordion title="Properties">
                      <ParamField path="target" type="string" default="SELECTION">
                        Whether to apply the threshold to the current selection of rows or all rows in the dataset.
                      </ParamField>

                      <ParamField path="reference" type="string">
                        Whether to interpret the threshold value as an absolute (count) or percentage of rows.

                        Values must be one of the following:

                        * `ABSOLUTE`
                        * `PERCENTAGE`
                      </ParamField>

                      <ParamField path="value" type="number">
                        Categories less frequent than this value will be discarded (hidden).
                      </ParamField>
                    </Accordion>
                  </ParamField>

                  <ParamField path="Item 1" type="object">
                    Configure categories to be discarded (hidden) in terms of their occurrence in the *whole dataset*.
                    Categories with a number (or percentage) of rows in the *whole dataset* less than `value` will be discarded (hidden from the variable's filter view).

                    <Accordion title="Properties">
                      <ParamField path="target" type="string" default="EVERYTHING">
                        Whether to apply the threshold to the current selection of rows or all rows in the dataset.
                      </ParamField>

                      <ParamField path="reference" type="string">
                        Whether to interpret the threshold value as an absolute (count) or percentage of rows.

                        Values must be one of the following:

                        * `ABSOLUTE`
                        * `PERCENTAGE`
                      </ParamField>

                      <ParamField path="value" type="number">
                        Categories less frequent than this value will be discarded (hidden).
                      </ParamField>
                    </Accordion>
                  </ParamField>
                </Accordion>
              </ParamField>
            </Tab>
          </Tabs>
        </Accordion>
      </ParamField>

      <ParamField path="isDefault" type="boolean" default="false">
        Flag for internal usage identifying non-user configurations.
      </ParamField>
    </Accordion>
  </ParamField>

  <ParamField path="column" type="[string, null]" required>
    Main column from which the insight is created.
  </ParamField>

  <ParamField path="columnViewModes" type="object">
    Visual representation mode of the insight's columns.
    For each column select whether to show it as a list or bar chart.
    By default, all column representations are "barChart".

    <Accordion title="Item properties">
      <ParamField path="Items" type="string">
        One or more additional parameters.

        Values must be one of the following:

        * `barChart`
        * `list`
      </ParamField>
    </Accordion>

    <Accordion title="Examples">
      * `{"country": "list", "vote intention": "list", "cluster": "barChart"}`
    </Accordion>
  </ParamField>

  <ParamField path="elements" type="array[object]">
    Type and appearance of an insight's elements.
    A list in which each item is an object configuring the appearance of a particular insight element.

    <Accordion title="Array items">
      <ParamField path="kind" type="string">
        Specify the type of element.

        Values must be one of the following:

        `TITLE` `DESCRIPTION` `CHART` `GRAPH` `STATS` `LEGEND` `LEGEND_COLOR_SCALE` `TABLE_CHART`
      </ParamField>

      <ParamField path="text" type="string">
        The text shown for this insight element.
      </ParamField>

      <ParamField path="hidden" type="boolean">
        Element visibility.
      </ParamField>

      <ParamField path="layout" type="object">
        The element's position and size.
        The position refers to the top-left corner of the rectangle representing the insight element,
        while the size is given by its width and height. For reference, the entire insight is 12 units
        wide and 9 units high, and the origin (0, 0) of the x/y coordinates is in its top-left corner.

        <Accordion title="Properties">
          <ParamField path="x" type="integer">
            Horizontal position of the element's top-left corner.
            In increments of 1; 0 being the left-most and 8 the right-most position.

            Values must be in the following range:

            ```javascript theme={null}
            -1 ≤ x ≤ 11
            ```
          </ParamField>

          <ParamField path="y" type="integer">
            Vertical position of the element's top-left corner.
            In increments of 1; 0 being the top-most and 11 the bottom-most position.

            Values must be in the following range:

            ```javascript theme={null}
            0 ≤ y ≤ 11
            ```
          </ParamField>

          <ParamField path="w" type="integer">
            The width of the element (in increments of 1).

            Values must be in the following range:

            ```javascript theme={null}
            0 ≤ w ≤ 12
            ```
          </ParamField>

          <ParamField path="h" type="integer">
            The height of the element (in increments of 1).

            Values must be in the following range:

            ```javascript theme={null}
            0 ≤ h ≤ 9
            ```
          </ParamField>
        </Accordion>
      </ParamField>

      <ParamField path="column" type="string">
        Name of the column containing the data to be used in this insight element.
        *Required* if the element is of type CHART or STATS.
      </ParamField>
    </Accordion>
  </ParamField>
</Accordion>