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

# calculate

> Evaluates a formula containing basic arithmetic over a dataset's columns. 

For example, to multiply column `A` by two and add column `Col B`, you would simply write

```java theme={null}
calculate(ds[["A", "Col B"]], {
    "formula": "2 * A - `Col B`"
}) -> (ds.result)
```

For more details regarding valids operators etc. see the [Pandas eval() documentation](https://pandas.pydata.org/pandas-docs/stable/user_guide/enhancingperf.html#expression-evaluation-via-eval),
more specifically the [supported syntax](https://pandas.pydata.org/pandas-docs/stable/user_guide/enhancingperf.html#supported-syntax),
and [eval() applied to DataFrames](https://pandas.pydata.org/pandas-docs/stable/user_guide/enhancingperf.html#the-dataframe-eval-method).

Note that assignments in the formula are not supported, since the result must always be a new column,
i.e. the following kind of formula should be avoided: `"c = a + b"`. The correct way to return the result
as a column would simply be `"a + b"`.

If the name of an input column contains spaces, such as in the example above, it should be quoted in
single backticks.

## 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">
      Assuming a dataset `ds` containing the numeric columns `num_a`, `num_b` and `num_c`, and a constant `a` with value 1.3, the following formula transforms each column numerically before adding and multiplying them together, all in one step:

      ```stan theme={null}
      calculate(ds, {
          "formula": "log(num_a) + num_b**3 * (num_c + @a)",
          "constants": {"a": 1.3}
      }) -> (ds.result)
      ```
    </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}
      calculate(ds: dataset, {
          "param": value,
          ...
      }) -> (result: number)
      ```
    </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" type="dataset" required>
    A dataset with columns to be used in the evaluation of the formula. Note, all columns mentioned in the formula must be numeric!
  </ParamField>
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="result" type="column[number]" required>
    A numeric column containing the result of evaluating the formula.
  </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="formula" type="string" required>
    The formula to execute.
    A formula containing basic arithmetic operations and references to column names.
  </ParamField>

  <ParamField path="constants" type="object">
    Constants to be used in the formula.
    An object of key-value pairs, where keys refer to names of constants whose values will be available
    in the formula with a `@` prefix. E.g. `"constants": {"factor": 1.23}` makes it possible to refer to
    `@factor` in the formula with given value; also see example(s).

    <Accordion title="Item properties">
      <ParamField path="Items" type="[number, string]">
        One or more constants.
        Note that all constant must be of allowed types (number or string).
      </ParamField>
    </Accordion>
  </ParamField>
</Accordion>