ColumnExpression

class lsst.daf.relation.ColumnExpression

Bases: abc.ABC

An abstract base class and factory for scalar, non-boolean column expressions.

ColumnExpression inheritance is closed to the types already provided by this package, but considerable custom behavior can still be provided via the ColumnFunction class and an Engine that knows how to interpret its name value. These concrete types can all be constructed via factory methods on ColumnExpression itself, so the derived types themselves only need to be referenced when writing match expressions that process an expression tree. See Extensibility for rationale and details.

Attributes Summary

columns_required Columns required by this expression (Set [ ColumnTag ]).

Methods Summary

eq(other) Construct a boolean equality-comparison expression.
function(name, *args, dtype, …) Construct an expression that represents a function call with expression arguments.
ge(other) Construct a boolean greater-or-equal-comparison expression.
gt(other) Construct a boolean greater-than-comparison expression.
is_supported_by(engine) Test whether the given engine is capable of evaluating this expression.
le(other) Construct a boolean less-or-equal-comparison expression.
literal(value, dtype, None] = None) Construct an expression backed by a regular Python object.
lt(other) Construct a boolean less-than-comparison expression.
method(name, *args, dtype, …) Construct an expression that represents a method call with expression arguments.
ne(other) Construct a boolean inequality-comparison expression.
predicate_function(name, *args, …) Construct an expression that represents a function call with expression arguments and a boolean result.
predicate_method(name, *args, …) Construct an expression that represents a method call with expression arguments and a boolean result.
reference(tag, dtype, None] = None) Construct an expression that refers to a column in a relation.

Attributes Documentation

columns_required

Columns required by this expression (Set [ ColumnTag ]).

This includes columns required by expressions nested within this one.

Methods Documentation

eq(other: lsst.daf.relation._columns._expression.ColumnExpression) → lsst.daf.relation._columns._expression.PredicateFunction

Construct a boolean equality-comparison expression.

Parameters:
other : ColumnExpression

Expression whose value will be compared to that of self.

Returns:
comparison : Predicate

Boolean column expression.

classmethod function(name: str, *args, dtype: type | None = None, supporting_engine_types: Iterable[type[Engine]] | None = None) → ColumnFunction

Construct an expression that represents a function call with expression arguments.

Parameters:
name : str

Name of the method, to be interpreted by the Engine or other algorithm.

*args : ColumnExpression

Expressions to pass as arguments to the method (not including self; this is a classmethod, so it never has access to self).

dtype : type or None, optional

The Python type this expression evaluates to (type or None).

supporting_engine_types : Iterable [ type ], optional

If provided, the set of Engine types that are expected to support this expression. If None (default), all engines are assumed to support it.

Returns:
function : ColumnFunction

Column expression that represents this function call.

ge(other: lsst.daf.relation._columns._expression.ColumnExpression) → lsst.daf.relation._columns._expression.PredicateFunction

Construct a boolean greater-or-equal-comparison expression.

Parameters:
other : ColumnExpression

Expression whose value will be compared to that of self.

Returns:
comparison : Predicate

Boolean column expression.

gt(other: lsst.daf.relation._columns._expression.ColumnExpression) → lsst.daf.relation._columns._expression.PredicateFunction

Construct a boolean greater-than-comparison expression.

Parameters:
other : ColumnExpression

Expression whose value will be compared to that of self.

Returns:
comparison : Predicate

Boolean column expression.

is_supported_by(engine: Engine) → bool

Test whether the given engine is capable of evaluating this expression.

Parameters:
engine : Engine

Engine to test.

Returns:
supported : bool

Whether the engine supports this expression and all expressions nested within it.

le(other: lsst.daf.relation._columns._expression.ColumnExpression) → lsst.daf.relation._columns._expression.PredicateFunction

Construct a boolean less-or-equal-comparison expression.

Parameters:
other : ColumnExpression

Expression whose value will be compared to that of self.

Returns:
comparison : Predicate

Boolean column expression.

classmethod literal(value: Any, dtype: Optional[type, None] = None) → lsst.daf.relation._columns._expression.ColumnLiteral

Construct an expression backed by a regular Python object.

Parameters:
value

Value for the expression.

dtype : type or None, optional

The Python type this expression evaluates to (type or None).

Returns:
literal : ColumnLiteral

A column expression backed by the given value.

lt(other: lsst.daf.relation._columns._expression.ColumnExpression) → lsst.daf.relation._columns._expression.PredicateFunction

Construct a boolean less-than-comparison expression.

Parameters:
other : ColumnExpression

Expression whose value will be compared to that of self.

Returns:
comparison : Predicate

Boolean column expression.

method(name: str, *args, dtype: type | None = None, supporting_engine_types: Iterable[type[Engine]] | None = None) → ColumnFunction

Construct an expression that represents a method call with expression arguments.

Parameters:
name : str

Name of the method, to be interpreted by the Engine or other algorithm.

*args : ColumnExpression

Expressions to pass as arguments to the method (after self).

dtype : type or None, optional

The Python type this expression evaluates to (type or None).

supporting_engine_types : Iterable [ type ], optional

If provided, the set of Engine types that are expected to support this expression. If None (default), all engines are assumed to support it.

Returns:
function : ColumnFunction

Column expression that represents this function call.

Notes

ColumnExpression cannot actually force an engine to interpret the given name as the name of a method rather than something else; calling this method like this:

a.method("name", b)

is exactly equivalent to:

ColumnExpression.function("name", a, b)

The provided iteration and sql engines both interpret these names as method names if and only if they are not first found in the built-in operator module.

ne(other: lsst.daf.relation._columns._expression.ColumnExpression) → lsst.daf.relation._columns._expression.PredicateFunction

Construct a boolean inequality-comparison expression.

Parameters:
other : ColumnExpression

Expression whose value will be compared to that of self.

Returns:
comparison : Predicate

Boolean column expression.

classmethod predicate_function(name: str, *args, supporting_engine_types: Iterable[type[Engine]] | None = None) → PredicateFunction

Construct an expression that represents a function call with expression arguments and a boolean result.

Parameters:
name : str

Name of the method, to be interpreted by the Engine or other algorithm.

*args : ColumnExpression

Expressions to pass as arguments to the method (not including self; this is a classmethod, so it never has access to self).

dtype : type or None, optional

The Python type this expression evaluates to (type or None).

supporting_engine_types : Iterable [ type ], optional

If provided, the set of Engine types that are expected to support this expression. If None (default), all engines are assumed to support it.

Returns:
function : PredicateFunction

Boolean column expression that represents this function call.

predicate_method(name: str, *args, supporting_engine_types: Set[type[Engine]] | None = None) → PredicateFunction

Construct an expression that represents a method call with expression arguments and a boolean result.

Parameters:
name : str

Name of the method, to be interpreted by the Engine or other algorithm.

*args : ColumnExpression

Expressions to pass as arguments to the method (after self).

dtype : type or None, optional

The Python type this expression evaluates to (type or None).

supporting_engine_types : Iterable [ type ] optional

If provided, the set of Engine types that are expected to support this expression. If None (default), all engines are assumed to support it.

Returns:
function : PredicateFunction

Boolean column expression that represents this function call.

Notes

ColumnExpression cannot actually force an engine to interpret the given name as the name of a method rather than something else; calling this method like this:

a.predicate_method("name", b)

is exactly equivalent to:

ColumnExpression.predicate_function("name", a, b)

The provided iteration and sql engines both interpret these names as method names if and only if they are not first found in the built-in operator module.

classmethod reference(tag: lsst.daf.relation._columns._tag.ColumnTag, dtype: Optional[type, None] = None) → lsst.daf.relation._columns._expression.ColumnReference

Construct an expression that refers to a column in a relation.

Parameters:
tag : ColumnTag

Identifier for the column to reference.

dtype : type or None, optional

The Python type this expression evaluates to (type or None).

Returns:
reference : ColumnReference

A column expression that refers the given relation column.