# dask.dataframe.DataFrame.eval

#### DataFrame.eval(expr, \*\*kwargs)

Evaluate a string describing operations on DataFrame columns.

This docstring was copied from pandas.DataFrame.eval.

Some inconsistencies with the Dask version may exist.

#### WARNING
This method can run arbitrary code which can make you vulnerable to code
injection if you pass user input to this function.

Operates on columns only, not specific rows or elements.  This allows
eval to run arbitrary code, which can make you vulnerable to code
injection if you pass user input to this function.

* **Parameters:**
  **expr**
  : The expression string to evaluate.
    <br/>
    You can refer to variables
    in the environment by prefixing them with an ‘@’ character like
    `@a + b`.
    <br/>
    You can refer to column names that are not valid Python variable names
    by surrounding them in backticks. Thus, column names containing spaces
    or punctuation (besides underscores) or starting with digits must be
    surrounded by backticks. (For example, a column named “Area (cm^2)” would
    be referenced as ``Area (cm^2)``). Column names which are Python keywords
    (like “if”, “for”, “import”, etc) cannot be used.
    <br/>
    For example, if one of your columns is called `a a` and you want
    to sum it with `b`, your query should be ``a a` + b`.
    <br/>
    See the documentation for [`eval()`](#dask.dataframe.DataFrame.eval) for full details of
    supported operations and functions in the expression string.

  **inplace**
  : If the expression contains an assignment, whether to perform the
    operation inplace and mutate the existing DataFrame. Otherwise,
    a new DataFrame is returned.
    <br/>
    #### Deprecated
    Deprecated since version 3.1.0: This keyword is deprecated and will be removed in pandas 4.0.
    See the [whatsnew note on PDEP-8](https://pandas.pydata.org/docs/dev/whatsnew/v3.1.0.html#deprecation-inplace)
    for more details.

  **\*\*kwargs**
  : See the documentation for [`eval()`](#dask.dataframe.DataFrame.eval) for complete details
    on the keyword arguments accepted by
    [`eval()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.eval.html#pandas.DataFrame.eval).
* **Returns:**
  ndarray, scalar, pandas object, or None
  : The result of the evaluation or None if `inplace=True`.

#### SEE ALSO
[`DataFrame.query`](dask.dataframe.DataFrame.query.html.md#dask.dataframe.DataFrame.query)
: Evaluates a boolean expression to query the columns of a frame.

[`DataFrame.assign`](dask.dataframe.DataFrame.assign.html.md#dask.dataframe.DataFrame.assign)
: Can evaluate an expression or function to create new values for a column.

[`eval`](#dask.dataframe.DataFrame.eval)
: Evaluate a Python expression as a string using various backends.

### Notes

For more details see the API documentation for [`eval()`](#dask.dataframe.DataFrame.eval).
For detailed examples see [enhancing performance with eval](https://pandas.pydata.org/pandas-docs/stable/user_guide/enhancingperf.html#enhancingperf-eval).

### Examples

```pycon
>>> df = pd.DataFrame(
...     {"A": range(1, 6), "B": range(10, 0, -2), "C&C": range(10, 5, -1)}
... )
>>> df
   A   B  C&C
0  1  10   10
1  2   8    9
2  3   6    8
3  4   4    7
4  5   2    6
>>> df.eval("A + B")
0    11
1    10
2     9
3     8
4     7
dtype: int64
```

Assignment is allowed though by default the original DataFrame is not
modified.

```pycon
>>> df.eval("D = A + B")
   A   B  C&C   D
0  1  10   10  11
1  2   8    9  10
2  3   6    8   9
3  4   4    7   8
4  5   2    6   7
>>> df
   A   B  C&C
0  1  10   10
1  2   8    9
2  3   6    8
3  4   4    7
4  5   2    6
```

Multiple columns can be assigned to using multi-line expressions:

```pycon
>>> df.eval(
...     '''
... D = A + B
... E = A - B
... '''
... )
   A   B  C&C   D  E
0  1  10   10  11 -9
1  2   8    9  10 -6
2  3   6    8   9 -3
3  4   4    7   8  0
4  5   2    6   7  3
```

For columns with spaces or other disallowed characters in their name, you can
use backtick quoting.

```pycon
>>> df.eval("B * `C&C`")
0    100
1     72
2     48
3     28
4     12
dtype: int64
```

Local variables shall be explicitly referenced using `@`
character in front of the name:

```pycon
>>> local_var = 2
>>> df.eval("@local_var * A")
0     2
1     4
2     6
3     8
4    10
Name: A, dtype: int64
```

<!-- !! processed by numpydoc !! -->
