@calc¶
Calculate new columns from expressions — arithmetic, string operations, or built-in formulas from the expression library.
Simple Example¶
import additory as add
import polars as pl
df = pl.DataFrame({
'price': [100, 200, 300],
'quantity': [2, 3, 1],
})
result = add.transform('@calc', df, expression='price * quantity', name='total')
print(result)
Parameters¶
The @calc mode uses these parameters from add.transform():
| Parameter | Type | Default | Description |
|---|---|---|---|
expression | str or list[str] | None | Expression(s) to evaluate |
name | str or list[str] | None | Output column name(s) for the result |
strategy | dict | None | Map of {name: expression} for multiple columns |
position | str or int | 'end' | Where to place new columns |
Single Expression¶
Use expression and name to calculate one column at a time:
Supported operators: +, -, *, /, ** (power), % (modulo).
# Arithmetic
result = add.transform('@calc', df, expression='salary * 1.1', name='new_salary')
# String concatenation (when columns are text)
result = add.transform('@calc', df, expression='first_name + " " + last_name', name='full_name')
Multiple Expressions¶
Using the strategy parameter¶
The strategy dict maps output column names to expressions. Columns are calculated in order, so later expressions can reference earlier ones:
result = add.transform('@calc', df, strategy={
'total': 'price * quantity',
'tax': 'total * 0.1',
'grand_total': 'total + tax',
})
Using lists¶
Pass parallel lists of expressions and names:
result = add.transform('@calc', df,
expression=['price * quantity', 'price * 0.1'],
name=['total', 'discount'],
)
Strategy is cleaner for chained calculations
When later columns depend on earlier ones (like tax depending on total), use the strategy dict. The list form evaluates each expression independently against the original columns.
Positioning¶
Control where new columns appear in the result:
# At the start
result = add.transform('@calc', df, expression='price * quantity',
name='total', position='start')
# After a specific column
result = add.transform('@calc', df, expression='price * quantity',
name='total', position='after:price')
# Before a specific column
result = add.transform('@calc', df, expression='price * quantity',
name='total', position='before:quantity')
# At a specific index
result = add.transform('@calc', df, expression='price * quantity',
name='total', position=2)
Built-in Expressions¶
Use the inbuilt: prefix to reference expressions from the built-in library:
# BMI from weight and height columns
result = add.transform('@calc', df, expression='inbuilt:bmi')
# ROI from revenue and cost columns
result = add.transform('@calc', df, expression='inbuilt:roi')
Built-in expressions auto-match column names from your DataFrame to the expression's required inputs. For example, inbuilt:bmi expects columns named weight and height.
Expression catalog
See the Expression Catalog for the full list of built-in expressions across core, finance, medical, physics, chemistry, engineering, and statistics categories.
Practical Scenarios¶
Financial calculations¶
import additory as add
import polars as pl
orders = pl.DataFrame({
'product': ['Widget', 'Gadget', 'Gizmo'],
'price': [25.00, 49.99, 12.50],
'quantity': [100, 50, 200],
'discount_rate': [0.1, 0.05, 0.15],
})
result = add.transform('@calc', orders, strategy={
'subtotal': 'price * quantity',
'discount': 'subtotal * discount_rate',
'total': 'subtotal - discount',
})
Using built-in medical expressions¶
patients = pl.DataFrame({
'name': ['Alice', 'Bob', 'Carol'],
'weight': [70, 85, 60],
'height': [1.70, 1.80, 1.65],
})
result = add.transform('@calc', patients, expression='inbuilt:bmi', name='bmi')
Next Steps¶
- Expression Catalog — all built-in expressions
- Expression Files — write your own
.addfiles - add.transform() — all 12 transform modes