> ## 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.

# melt

> Reshape a dataset by transforming columns into rows. 

This process involves transforming a dataset by first optionally organizing its rows based on certain criteria.
It then identifies unique values or combinations thereof within specified columns,
creating groups based on these unique identifiers. For each group,
specific functions are applied to the rows to summarize or condense their information.
The result is a new dataset where each row represents a unique group,
and each column corresponds to the outcome of a distinct summarization function applied across the grouped data.
For more information, refer to the [pandas melt documentation](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.melt.html).

## Usage

The following example shows how the step can be used in a recipe.

<Accordion title="Examples" icon="code" defaultOpen="true">
  <Tabs>
    <Tab title="Example 1">
      Given a dataset `sales` with columns for `date`, `product_id`, and `sales_amount`,
      we can use melt to transform this dataset into a long format.
      This transformation will create a new dataset `long_sales`
      where each row represents a single observation of sales amount for a product on a given date,
      facilitating further analysis or visualization.

      The resulting dataset `long_sales` will have the following columns:

      * `date`: the date of the observation
      * `variable`: indicating the product by its `product_id`
      * `value`: the sales amount for that product on the given date

      ```stan theme={null}
      melt(ds, {
        "id_vars": ["date"],
        "value_vars": ["product_id", "sales_amount"],
        "var_name": "variable",
        "value_name": "value"
      }) -> (ds_melted)
      ```
    </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}
      melt(ds_in: dataset, {
          "param": value,
          ...
      }) -> (melted: dataset)
      ```
    </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">
  <ParamField path="ds_in" type="dataset" required />
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="melted" type="dataset" required>
    Result of melting ds.
  </ParamField>
</Accordion>

## 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="id_vars" type="[string, array[string]]" required>
    Identifier columns.
    The column(s) to use as identifier variables.

    <Accordion title="Array items">
      <ParamField path="Item" type="string (ds_in.column)">
        Each item in array.
      </ParamField>
    </Accordion>

    <Accordion title="Examples">
      * order\_id
      * \['customer\_id', 'order\_id']
    </Accordion>
  </ParamField>

  <ParamField path="value_vars" type="[string, array[string]]" required>
    Value columns.
    The column(s) that are considered as value variables.

    <Accordion title="Array items">
      <ParamField path="Item" type="string (ds_in.column)">
        Each item in array.
      </ParamField>
    </Accordion>

    <Accordion title="Examples">
      * quantity
      * \['price', 'quantity', 'discount']
    </Accordion>
  </ParamField>

  <ParamField path="var_name" type="string" default="variable">
    Variable column name.
    Name of the variable column if not provided, we will use the name 'variable'.
  </ParamField>

  <ParamField path="value_name" type="string" default="value">
    Value column name.
    Name of the value column if not provided, we will use the name 'value'.
  </ParamField>
</Accordion>