pandas.DataFrame.eval

DataFrame.eval(expr, *, inplace=False, **kwargs)

Evaluate a string describing operations on DataFrame columns.

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:

exprstr

The expression string to evaluate.

You can refer to variables in the environment by prefixing them with an ‘@’ character like @a + b.

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.

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.

See the documentation for eval() for full details of supported operations and functions in the expression string.

inplacebool, default False

If the expression contains an assignment, whether to perform the operation inplace and mutate the existing DataFrame. Otherwise, a new DataFrame is returned.

**kwargs

See the documentation for eval() for complete details on the keyword arguments accepted by eval().

Returns:

ndarray, scalar, pandas object, or None

The result of the evaluation or None if inplace=True.

See also

DataFrame.query

Evaluates a boolean expression to query the columns of a frame.

DataFrame.assign

Can evaluate an expression or function to create new values for a column.

eval

Evaluate a Python expression as a string using various backends.

Notes

For more details see the API documentation for eval(). For detailed examples see enhancing performance with eval.

Examples

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

>>> 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:

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

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

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

>>> local_var = 2
>>> df.eval("@local_var * A")
0     2
1     4
2     6
3     8
4    10