Derived columns
Compute a derived metric from several existing columns.
Pandas · Module
df.eval
DataFrame.eval evaluates a string expression against DataFrame columns. It can compute results or assign derived columns, optionally mutating the original DataFrame.
How it works
DataFrame.eval interprets a string expression in the context of a DataFrame’s columns. Assignments can create or update columns; by default the operation returns a new DataFrame, while inplace=True mutates the original. The expression can also produce a scalar, array-like result, or pandas object.
Syntax
DataFrame.eval(expr, *, inplace=False, **kwargs)Parameters
| Name | Type | Description |
|---|---|---|
expr | str | The expression string to evaluate. |
inplace | bool, default False | If an assignment is present, whether to mutate the existing DataFrame; otherwise a new DataFrame is returned. |
kwargs | **kwargs | Additional keyword arguments forwarded for expression evaluation. |
Returns
ndarray, scalar, pandas object, or None; the evaluated result, or None when inplace=True.
Key points
- The method evaluates column-oriented expressions supplied as strings.
- External variables are explicitly marked with @ when used in an expression.
- Backticks allow expressions to refer to columns with spaces, punctuation, or leading digits.
- The inplace flag controls whether assignment changes the original DataFrame.
- The return value depends on the expression and whether inplace mutation is requested.
Common mistakes
- Do not pass untrusted user input directly as the expression.
- Use another operation when the calculation must target individual rows or elements.
- Python keyword column names cannot be referenced normally in the expression.
Example: Create a derived column
import pandas as pd
scores = pd.DataFrame({"math": [80, 90], "bonus": [5, 3]})
scores.eval("total = math + bonus", inplace=True)
print(scores)
Creates a new column from existing DataFrame columns and mutates the DataFrame explicitly.
When to use it
Readable column calculations
Apply a compact column expression without manually repeating DataFrame indexing.
Expressions with external variables
Use a caller-provided threshold or other local value in a column expression.
Interview questions
QWhat does DataFrame.eval do?
It evaluates a string in the context of the DataFrame’s columns, so column names can be used directly without prefixing them with the DataFrame variable. An assignment expression can derive or replace a column.
Follow-up: How would you reference an external Python variable? Prefix that variable with @ in the expression, such as @threshold.
QHow does inplace affect the result?
With inplace=False, the default, an assignment produces a new DataFrame and leaves the original unchanged. With inplace=True, an assignment mutates the existing DataFrame and the method returns None.
Follow-up: What should code inspect when inplace=True? It should use the mutated DataFrame rather than expecting a returned result.
QHow are unusual column names handled?
The expression may refer to columns whose names are not valid Python identifiers by surrounding those names with backticks. This covers names containing spaces, punctuation other than underscores, or leading digits.
Follow-up: Can a column named like a Python keyword be referenced with backticks? No; the documentation says Python-keyword column names cannot be used.
Related
pandas.evalDataFrame.query