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

# filter_with_formula

> Filter rows using a (pandas-compatible) formula. 

Allowed elements in the fomula are column names as well as common operators and values for comparison
(strings need to be specified using single quotes, see example below).

For more details about valid formulas see [here](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.query.html).

## 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 first example *keeps* those rows where the "salary" column is either "low" or "high":

      ```stan theme={null}
      filter_with_formula(ds, {
        "formula": "salary == 'low' or salary == 'high'"
        }) -> (ds_filtered)
      ```
    </Tab>

    <Tab title="Example 2">
      The next example *drops* those rows where the column "number\_project" is less than 3 or greater than 4, i.e. it keeps values in the range \[3, 4] only.

      ```stan theme={null}
      filter_with_formula(ds, {
        "formula": "number_project >= 3 and number_project <= 4"
      }) -> (ds_filtered)
      ```
    </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}
      filter_with_formula(ds_in: dataset, {
          "param": value,
          ...
      }) -> (ds_out: 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>
    An input dataset to filter.
  </ParamField>
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="ds_out" type="dataset" required>
    A new dataset containing the same columns as the input dataset but only those rows passing the filter query.
  </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>
    A formula describing the matching operation to perform on each row.

    <Accordion title="Examples">
      * `salary == 'low' or salary == 'high'`
      * `number_project >= 3 and number_project <= 4`
    </Accordion>
  </ParamField>
</Accordion>