Version: 2.1.0

Expr

class

class Expr

Categories: tableframe

A lazy column expression evaluated against a TableFrame.

Create expressions with col / lit from tabsdatak.tableframe.functions and pass them to a frame's select, filter, with_columns or group_by().agg. Operators are element-wise; reducers (sum, mean, min ...) collapse a group. Date/time and string helpers live under dt and str.

Examples

tf.with_columns((col("a") * 2).alias("doubled"))
tf.group_by("g").agg(col("a").sum().alias("total"))

Properties

property

dtExprDateTimeNameSpace

Namespace of date and time operations for temporal columns.

property

strExprStringNameSpace

Namespace of string operations for string columns.

Methods

method

sqrt

def sqrt() -> Expr

Square root of each element.

Example:

tf.select(col("v").sqrt().alias("root"))

method

cbrt

def cbrt() -> Expr

Cube root of each element.

Example:

tf.select(col("v").cbrt().alias("root"))

method

log10

def log10() -> Expr

Base-10 logarithm of each element.

Example:

tf.select(col("v").log10().alias("magnitude"))

method

exp

def exp() -> Expr

Exponential (e raised to each element).

Example:

tf.select(col("v").exp().alias("growth"))

method

alias

def alias(name: Any) -> Expr

Rename the output column of this expression.

Parameters:

parameter

nameAny

New column name. Must be a valid identifier (letters, digits, underscores; starting with a letter or underscore) up to 100 characters.

Example:

tf.select(col("a").alias("identifier"))

An expression keeps no name of its own, so alias every computed column:

tf.with_columns((col("a") * 2).alias("doubled"))

method

not_

def not_() -> Expr

Logical negation of a boolean expression.

Example:

tf.filter(col("flag").not_())

method

is_null

def is_null() -> Expr

Return whether each element is null.

Example:

tf.filter(col("v").is_null())

method

is_not_null

def is_not_null() -> Expr

Return whether each element is not null.

Example:

tf.filter(col("v").is_not_null())

method

is_finite

def is_finite() -> Expr

Return whether each floating-point element is finite.

Example:

tf.filter(col("v").is_finite())

method

is_infinite

def is_infinite() -> Expr

Return whether each floating-point element is infinite.

Example:

tf.filter(col("v").is_infinite())

method

is_nan

def is_nan() -> Expr

Return whether each floating-point element is NaN.

Example:

tf.filter(col("v").is_nan())

method

is_not_nan

def is_not_nan() -> Expr

Return whether each floating-point element is not NaN.

Example:

tf.filter(col("v").is_not_nan())

method

count

def count() -> Expr

Count the non-null elements in the group; see len.

Example:

tf.group_by("g").agg(col("v").count().alias("filled"))

method

len

def len() -> Expr

Count all rows in the group, including nulls; see count.

Example:

tf.group_by("g").agg(col("v").len().alias("rows"))

method

slice

def slice(offset: int | Expr, length: int | Expr | None = None) -> Expr

Take a contiguous slice of the column's values.

Parameters:

parameter

offsetint | Expr

Start index; a negative value counts from the end.

parameter

lengthint | Expr | None

Number of values to take; all remaining if omitted.

Example:

tf.select(col("a").slice(1, 2))

A negative offset counts from the end:

tf.select(col("a").slice(-2))  # the last two values

method

floor

def floor() -> Expr

Round each element down to the nearest integer.

Example:

tf.select(col("v").floor().alias("floor"))

method

ceil

def ceil() -> Expr

Round each element up to the nearest integer.

Example:

tf.select(col("v").ceil().alias("ceil"))

method

round

def round(decimals: int = 0, mode: RoundMode = 'half_to_even') -> Expr

Round floating-point elements to a number of decimals.

Parameters:

parameter

decimalsint

Number of decimal places to keep; non-negative.

parameter

modeRoundMode (Literal['half_to_even', 'half_away_from_zero', 'to_zero'])

Tie-breaking rule, one of half_to_even, half_away_from_zero or to_zero.

Example:

tf.select(col("v").round(2).alias("rounded"))

method

round_sig_figs

def round_sig_figs(digits: int) -> Expr

Round elements to a number of significant figures.

Parameters:

parameter

digitsint

Number of significant figures to keep; positive.

Example:

tf.select(col("v").round_sig_figs(2).alias("approx"))

method

cast

def cast(
    dtype: PolarsDataType | type[Any],
    *,
    strict: bool = True,
    wrap_numerical: bool = False,
) -> Expr

Cast the expression to a different data type.

Parameters:

parameter

dtypePolarsDataType | type[Any] (DataType | type[Any])

Target data type (e.g. pl.Int64, pl.Float64, pl.String).

parameter

strictbool

If True, raise on values that do not fit the target; if False, set them to null instead.

parameter

wrap_numericalbool

If True, wrap on numeric overflow rather than raising.

Example:

tf.select(col("a").cast(Float64))

With strict=False an unconvertible value becomes null instead of raising:

tf.select(col("name").cast(Int64, strict=False))

method

fill_null

def fill_null(
    value: Any | Expr | None = None,
    strategy: FillNullStrategy | None = None,
    limit: int | None = None,
) -> Expr

Replace null values with a value or a fill strategy.

Pass either value or strategy, not both.

Parameters:

parameter

valueAny | Expr | None

Value or expression to substitute for nulls.

parameter

strategyFillNullStrategy | None (Literal['forward', 'backward', 'min', 'max', 'mean', 'zero', 'one'] | None)

Fill strategy instead of value: one of forward, backward, min, max, mean, zero or one.

parameter

limitint | None

Maximum consecutive nulls to fill with forward or backward.

Example:

tf.with_columns(col("v").fill_null(0.0))

A strategy fills from the neighbouring rows instead of a constant:

tf.sort("id").with_columns(col("v").fill_null(strategy="forward"))

method

fill_nan

def fill_nan(value: int | float | Expr | None) -> Expr

Replace NaN values with the given value.

Only affects NaN, not null. Use fill_null for nulls.

Parameters:

parameter

valueint | float | Expr | None

Value or expression to substitute for NaN.

Example:

tf.with_columns(col("v").fill_nan(0.0))

method

max

def max() -> Expr

Return the maximum element in the group.

Example:

tf.group_by("g").agg(col("a").max().alias("largest"))

method

min

def min() -> Expr

Return the minimum element in the group.

Example:

tf.group_by("g").agg(col("a").min().alias("smallest"))

method

sum

def sum() -> Expr

Return the sum of the elements in the group.

Example:

tf.group_by("g").agg(col("a").sum().alias("total"))

method

mean

def mean() -> Expr

Return the mean of the elements in the group.

Example:

tf.group_by("g").agg(col("a").mean().alias("average"))

method

median

def median() -> Expr

Return the median of the elements in the group.

Example:

tf.group_by("g").agg(col("a").median().alias("middle"))

method

n_unique

def n_unique() -> Expr

Count the distinct elements in the group.

Example:

tf.group_by("g").agg(col("a").n_unique().alias("distinct"))

method

first

def first(*, ignore_nulls: bool = False) -> Expr

Return the first element in the group.

Parameters:

parameter

ignore_nullsbool

If True, return the first non-null element.

Example:

tf.sort("id").group_by("g").agg(col("a").first().alias("earliest"))

method

last

def last(*, ignore_nulls: bool = False) -> Expr

Return the last element in the group.

Parameters:

parameter

ignore_nullsbool

If True, return the last non-null element.

Example:

tf.sort("id").group_by("g").agg(col("a").last().alias("latest"))

method

is_unique

def is_unique() -> Expr

Return whether each element occurs only once in the column.

Example:

tf.filter(col("g").is_unique())

method

filter

def filter(
    *predicates: IntoExprColumn | Iterable[IntoExprColumn] = (),
    **constraints: Any = {},
) -> Expr

Keep only the values that satisfy the given predicates.

Values whose predicate is not True (including null) are dropped. Typically used inside an aggregation.

Parameters:

parameter

*predicatesIntoExprColumn | Iterable[IntoExprColumn] (Expr | str | Iterable[Expr | str])

Boolean expressions to apply.

parameter

**constraintsAny

column=value keyword filters, combined with predicates using logical and.

Example:

tf.group_by("g").agg(
    col("a").filter(col("a") > 1).sum().alias("big_total"),
)

method

and_

def and_(*others: Any = ()) -> Expr

Bitwise and with the given expressions (integer or boolean).

Parameters:

parameter

*othersAny

Expressions to combine with logical/bitwise and.

Example:

tf.filter(col("flag").and_(col("a") > 2))

method

or_

def or_(*others: Any = ()) -> Expr

Bitwise or with the given expressions (integer or boolean).

Parameters:

parameter

*othersAny

Expressions to combine with logical/bitwise or.

Example:

tf.filter(col("flag").or_(col("a") > 3))

method

eq

def eq(other: Any) -> Expr

Element-wise equality, equivalent to expr == other.

Parameters:

parameter

otherAny

Value or expression to compare against. A null on either side yields null; use eq_missing to treat two nulls as equal.

Example:

tf.filter(col("g").eq("x"))

method

eq_missing

def eq_missing(other: Any) -> Expr

Element-wise equality where two nulls compare as equal.

Parameters:

parameter

otherAny

Value or expression to compare against.

Example:

tf.select(col("v").eq(None).alias("eq"))  # null everywhere
tf.select(col("v").eq_missing(None).alias("eq_missing"))  # True on nulls

method

ge

def ge(other: Any) -> Expr

Element-wise greater-than-or-equal, like expr >= other.

Parameters:

parameter

otherAny

Value or expression to compare against.

Example:

tf.filter(col("a").ge(2))

method

gt

def gt(other: Any) -> Expr

Element-wise greater-than, like expr > other.

Parameters:

parameter

otherAny

Value or expression to compare against.

Example:

tf.filter(col("a").gt(2))

method

le

def le(other: Any) -> Expr

Element-wise less-than-or-equal, like expr <= other.

Parameters:

parameter

otherAny

Value or expression to compare against.

Example:

tf.filter(col("a").le(2))

method

lt

def lt(other: Any) -> Expr

Element-wise less-than, like expr < other.

Parameters:

parameter

otherAny

Value or expression to compare against.

Example:

tf.filter(col("a").lt(2))

method

ne

def ne(other: Any) -> Expr

Element-wise inequality, equivalent to expr != other.

Parameters:

parameter

otherAny

Value or expression to compare against. A null on either side yields null; use ne_missing to treat two nulls as equal.

Example:

tf.filter(col("g").ne("x"))

method

ne_missing

def ne_missing(other: Any) -> Expr

Element-wise inequality where two nulls compare as equal.

Parameters:

parameter

otherAny

Value or expression to compare against.

Example:

tf.select(col("v").ne_missing(None).alias("filled"))

method

add

def add(other: Any) -> Expr

Add other; for strings, concatenate. Same as +.

Parameters:

parameter

otherAny

Value or expression to add or concatenate.

Example:

tf.with_columns(col("a").add(1).alias("next"))

method

floordiv

def floordiv(other: Any) -> Expr

Floor division by other. Same as //.

Parameters:

parameter

otherAny

Value or expression to divide by.

Example:

tf.select(col("a").floordiv(2).alias("halved"))

method

mod

def mod(other: Any) -> Expr

Modulo (remainder) by other. Same as %.

Parameters:

parameter

otherAny

Value or expression to divide by.

Example:

tf.select(col("a").mod(2).alias("parity"))

method

mul

def mul(other: Any) -> Expr

Multiply by other. Same as *.

Parameters:

parameter

otherAny

Value or expression to multiply by.

Example:

tf.with_columns(col("a").mul(10).alias("scaled"))

method

sub

def sub(other: Any) -> Expr

Subtract other. Same as -.

Parameters:

parameter

otherAny

Value or expression to subtract.

Example:

tf.with_columns(col("b").sub(col("a")).alias("gap"))

method

neg

def neg() -> Expr

Unary negation of each element. Same as unary -.

Example:

tf.select(col("a").neg().alias("negated"))

method

truediv

def truediv(other: Any) -> Expr

True (floating-point) division by other. Same as /.

Parameters:

parameter

otherAny

Value or expression to divide by.

Example:

tf.select(col("b").truediv(col("a")).alias("ratio"))

method

pow

def pow(exponent: IntoExprColumn | int | float) -> Expr

Raise each element to the power of exponent. Same as **.

Parameters:

parameter

exponentIntoExprColumn | int | float (Expr | str | int | float)

Value or expression to use as the exponent.

Example:

tf.select(col("a").pow(2).alias("squared"))

method

xor

def xor(other: Any) -> Expr

Bitwise xor with other (integer or boolean). Same as ^.

Parameters:

parameter

otherAny

Value or expression to combine with xor.

Example:

tf.select(col("flag").xor(True).alias("toggled"))

method

is_in

def is_in(other: Expr | Collection[Any], *, nulls_equal: bool = False) -> Expr

Return whether each element is contained in other.

Parameters:

parameter

otherExpr | Collection[Any]

Collection or expression of allowed values.

parameter

nulls_equalbool

If True, a null element matches a null in other.

Example:

tf.filter(col("g").is_in(["x", "y"]))

method

is_between

def is_between(
    lower_bound: IntoExpr,
    upper_bound: IntoExpr,
    closed: ClosedInterval = 'both',
) -> Expr

Return whether each element lies between two bounds.

Parameters:

parameter

Lower bound value or expression.

parameter

Upper bound value or expression.

parameter

closedClosedInterval (Literal['left', 'right', 'both', 'none'])

Which ends are inclusive: both (default), left, right or none.

Example:

tf.filter(col("a").is_between(2, 4))

Both bounds are inclusive by default; closed narrows them:

tf.filter(col("a").is_between(2, 4, closed="left"))

method

hash

def hash(
    seed: int = 0,
    seed_1: int | None = None,
    seed_2: int | None = None,
    seed_3: int | None = None,
) -> Expr

Hash each element to a 64-bit unsigned integer.

Parameters:

parameter

seedint

Base seed for the hash.

parameter

seed_1int | None

Optional additional seed.

parameter

seed_2int | None

Optional additional seed.

parameter

seed_3int | None

Optional additional seed.

Example:

tf.select(col("email").hash().alias("fingerprint"))

method

reinterpret

def reinterpret(
    *,
    signed: bool | None = None,
    dtype: PolarsDataType | None = None,
) -> Expr

Reinterpret a 64-bit integer's bits as another integer type.

Reinterprets the raw bits (no value conversion); for a real conversion use cast. Only valid on 64-bit integer columns.

Parameters:

parameter

signedbool | None

If True reinterpret as signed, if False as unsigned.

parameter

dtypePolarsDataType | None (DataType | None)

Explicit target integer type; overrides signed.

Example:

tf.select(col("a").reinterpret(signed=False).alias("bits"))

method

abs

def abs() -> Expr

Absolute value of each element.

Example:

tf.select(col("v").abs().alias("size"))

method

rank

def rank(
    method: RankMethod = 'average',
    *,
    descending: bool = False,
    seed: int | None = None,
) -> Expr

Assign a rank to each element within the column.

Parameters:

parameter

methodRankMethod (Literal['average', 'min', 'max', 'dense', 'ordinal', 'random'])

Tie-handling method: average (default), min, max, dense, ordinal or random.

parameter

descendingbool

If True, rank from largest to smallest.

parameter

seedint | None

Random seed, used only when method is random.

Example:

tf.with_columns(col("a").rank().alias("position"))

method decides how ties are resolved, and descending ranks the largest value first:

tf.with_columns(col("a").rank("dense", descending=True).alias("place"))

method

diff

def diff(n: int | IntoExpr = 1, null_behavior: NullBehavior = 'ignore') -> Expr

Difference between each element and one n rows away.

Works on numeric and temporal columns. Order-dependent, so sort first for a deterministic result.

Parameters:

parameter

Rows to look back; negative looks forward.

parameter

null_behaviorNullBehavior (Literal['ignore', 'drop'])

How to handle nulls: ignore or drop.

Example:

tf.sort("id").with_columns(col("a").diff().alias("change"))

method

clip

def clip(
    lower_bound: NumericLiteral | TemporalLiteral | IntoExprColumn | None = None,
    upper_bound: NumericLiteral | TemporalLiteral | IntoExprColumn | None = None,
) -> Expr

Clamp each element to the given bounds.

Values below lower_bound become it, values above upper_bound become it, values in range are unchanged. Provide at least one bound.

Parameters:

parameter

Minimum allowed value; None for no lower bound.

parameter

Maximum allowed value; None for no upper bound.

Example:

tf.with_columns(col("a").clip(2, 3).alias("clipped"))

One bound may be omitted to clamp on a single side:

tf.with_columns(col("a").clip(lower_bound=2).alias("at_least_two"))

method

sign

def sign() -> Expr

Return the sign of each element (-1, 0 or 1).

Example:

tf.select(col("v").sign().alias("sign"))

method

sin

def sin() -> Expr

Sine of each element, in radians.

Example:

tf.select(col("v").sin().alias("sin"))

method

cos

def cos() -> Expr

Cosine of each element, in radians.

Example:

tf.select(col("v").cos().alias("cos"))

method

tan

def tan() -> Expr

Tangent of each element, in radians.

Example:

tf.select(col("v").tan().alias("tan"))

method

cot

def cot() -> Expr

Cotangent of each element, in radians.

Example:

tf.select(col("v").cot().alias("cot"))

method

arcsin

def arcsin() -> Expr

Inverse sine of each element.

Example:

tf.select(col("v").arcsin().alias("arcsin"))

method

arccos

def arccos() -> Expr

Inverse cosine of each element.

Example:

tf.select(col("v").arccos().alias("arccos"))

method

arctan

def arctan() -> Expr

Inverse tangent of each element.

Example:

tf.select(col("v").arctan().alias("arctan"))

method

sinh

def sinh() -> Expr

Hyperbolic sine of each element.

Example:

tf.select(col("v").sinh().alias("sinh"))

method

cosh

def cosh() -> Expr

Hyperbolic cosine of each element.

Example:

tf.select(col("v").cosh().alias("cosh"))

method

tanh

def tanh() -> Expr

Hyperbolic tangent of each element.

Example:

tf.select(col("v").tanh().alias("tanh"))

method

arcsinh

def arcsinh() -> Expr

Inverse hyperbolic sine of each element.

Example:

tf.select(col("v").arcsinh().alias("arcsinh"))

method

arccosh

def arccosh() -> Expr

Inverse hyperbolic cosine of each element.

Example:

tf.select(col("v").arccosh().alias("arccosh"))

method

arctanh

def arctanh() -> Expr

Inverse hyperbolic tangent of each element.

Example:

tf.select(col("v").arctanh().alias("arctanh"))

method

degrees

def degrees() -> Expr

Convert each element from radians to degrees.

Example:

tf.select(col("v").degrees().alias("degrees"))

method

radians

def radians() -> Expr

Convert each element from degrees to radians.

Example:

tf.select(col("v").radians().alias("radians"))

method

log

def log(base: float | IntoExpr = 2.718281828459045) -> Expr

Logarithm of each element to the given base.

Parameters:

parameter

Logarithm base; defaults to e (natural logarithm).

Example:

tf.select(col("v").log().alias("ln"))

Pass a base for a logarithm other than the natural one:

tf.select(col("v").log(2).alias("log2"))

method

log1p

def log1p() -> Expr

Natural logarithm of 1 + element.

Example:

tf.select(col("v").log1p().alias("log1p"))

Examples​

Properties​

Methods​

Examples

Properties

Methods