Predicates

Bindings should build portable expressions through altar.predicates.

predicates

Stable predicate DSL shared by model and evidence-source bindings.

A predicate built here has matching Python and SQL interpretations. Binding authors should use this façade instead of the implementation module under :mod:altar.plugins.

And dataclass

And(*operands: Predicate)

Bases: Predicate

Logical AND over a tuple of operands.

Defined as a frozen dataclass like the other nodes, so it is hashable and comparable. The custom __init__ accepts the variadic form And(a, b, c).

Greatest dataclass

Greatest()

Bases: _NullIgnoringExtremum

The largest non-null operand, or null when every operand is null. Variadic: Greatest(a, b, c).

Use it for "the maximum over several nullable columns", such as an allele frequency over ancestry groups, where one missing group must not hide the others. The SQL rendering is GREATEST(COALESCE(a, b, c), COALESCE(b, c, a), COALESCE(c, a, b)), which gives the same answer on BigQuery, whose GREATEST is NULL when any argument is NULL, and on DuckDB, whose GREATEST skips NULLs.

In dataclass

In(operand: Term, values: Iterable[Any])

Bases: Predicate

Whether a term equals one of a tuple of literal values: SQL term IN (v1, v2, ...).

Semantics follow SQL: a null term is unknown, a match is true, and otherwise the result is false. An empty tuple is false for every row, null term included, and renders to FALSE because IN () is not valid SQL. The values must be non-null literals of one type family (booleans, numbers, or strings); a None value is rejected because SQL makes x IN (..., NULL) unknown rather than true for a null x. Write "one of these values, or missing" as Or(In(term, values), IsNull(term)).

Values are stored as a tuple of built-in scalars (NumPy scalars are converted) with duplicates removed in first-occurrence order. A set is rejected because its iteration order, and so the SQL text, is not stable between processes.

IsNull dataclass

IsNull(operand: Term)

Bases: Predicate

Whether a term is null (a missing column or a None value counts as null in Python).

Unlike every other test it is always definite, True or False, never unknown. Write the negation as Not(IsNull(term)), which renders to NOT (term IS NULL).

Least dataclass

Least()

Bases: _NullIgnoringExtremum

The smallest non-null operand, or null when every operand is null. Variadic: Least(a, b, c).

Or dataclass

Or(*operands: Predicate)

Bases: Predicate

Logical OR over a tuple of operands.

A frozen dataclass like the other nodes. The custom __init__ accepts the variadic form Or(a, b, c).

Predicate

Bases: ABC

A boolean expression over columns, renderable to a Python callable and to SQL.

evaluate abstractmethod

evaluate(row: Mapping[str, Any]) -> bool | None

Evaluate against row with three-valued logic, returning True, False, or None (unknown).

to_python

to_python() -> Callable[[Mapping[str, Any]], bool]

Return a callable that tests a row and returns True only when the predicate is definitely true.

An unknown (None) result counts as not matching, the same as a SQL boolean filter.

Term

Bases: ABC

A value-producing expression: a column, a literal, or a function of terms.

evaluate abstractmethod

evaluate(row: Mapping[str, Any]) -> Any

Return the term's value for row, or None if a referenced column is missing or None.