UnaryOperation

class lsst.daf.relation.UnaryOperation

Bases: ABC

An abstract base class for operations that act on a single relation.

See also

Operations

Notes

A UnaryOperation represents the operation itself; the combination of an operation and the “target” relation it acts on to form a new relation is represented by the UnaryOperationRelation class. That combination should always be created via a call to the apply method (or something that calls it, like the convenience methods on the Relation class). In some cases, applying a UnaryOperation doesn’t return something involving the original operation, because of some combination of defaulted-parameter population and simplification, and there are even some UnaryOperation classes that should never actually appear in a UnaryOperationRelation.

UnaryOperation cannot be subclassed directly by external code, but it has two more restricted subclasses that can be:RowFilter and Reordering.

All concrete UnaryOperation types are frozen, equality-comparable dataclasses. They also provide a very concise str representation (in addition to the dataclass-provided repr) suitable for summarizing an entire relation tree.

Attributes Summary

columns_required	The columns the target relation must have in order for this operation to be applied to it (Set [ ColumnTag ] ).
is_count_dependent	Whether this operation depends on the number of rows in its target relation (bool).
is_count_invariant	Whether this operation can change the number of rows in its target relation (bool).
is_empty_invariant	Whether this operation can remove all rows from its target relation (bool).
is_order_dependent	Whether this operation depends on the order of the rows in its target relation (bool).

Methods Summary

applied_columns(target)	Return the columns of the relation that results from applying this operation to the given target.
applied_max_rows(target)	Return the maximum number of rows of the relation that results from applying this operation to the given target.
applied_min_rows(target)	Return the minimum number of rows of the relation that results from applying this operation to the given target.
apply(target, *[, preferred_engine, ...])	Create a new relation that represents the action of this operation on an existing relation.
commute(current)	Describe whether and how this operation can be moved upstream of an existing one without changing the content of the resulting relation.
is_supported_by(engine)	Whether this operation is supported by the given engine (bool).
simplify(upstream)	Return a simplified combination of this operation with another.

Attributes Documentation

columns_required

The columns the target relation must have in order for this operation to be applied to it (Set [ ColumnTag ] ).

is_count_dependent

Whether this operation depends on the number of rows in its target relation (bool).

is_count_invariant

Whether this operation can change the number of rows in its target relation (bool).

The number of rows here includes duplicates - removing duplicates is not considered a count-invariant operation.

is_empty_invariant

Whether this operation can remove all rows from its target relation (bool).

is_order_dependent

Whether this operation depends on the order of the rows in its target relation (bool).

Methods Documentation

applied_columns(target: Relation) → Set[ColumnTag]

Return the columns of the relation that results from applying this operation to the given target.

Parameters:

targetRelation

Relation the operation will act on.

Returns:

columnsSet [ ColumnTag ]

Columns the new relation would have.

applied_max_rows(target: Relation) → int | None

Return the maximum number of rows of the relation that results from applying this operation to the given target.

Parameters:

targetRelation

Relation the operation will act on.

Returns:

max_rowsint or None

Maximum number of rows the new relation would have.

abstract applied_min_rows(target: Relation) → int

Return the minimum number of rows of the relation that results from applying this operation to the given target.

Parameters:

targetRelation

Relation the operation will act on.

Returns:

min_rowsint

Minimum number of rows the new relation would have.

final apply(target: Relation, *, preferred_engine: Engine | None = None, backtrack: bool = True, transfer: bool = False, require_preferred_engine: bool = False) → Relation

Create a new relation that represents the action of this operation on an existing relation.

Parameters:

targetRelation

Relation the operation will act on.

preferred_engineEngine, optional

Engine that the operation would ideally be performed in. If this is not equal to target.engine, the backtrack, transfer, and require_preferred_engine arguments control the behavior. Some operations may supply their own preferred engine default, such as the “fixed” operand’s own engine in a PartialJoin.

backtrackbool, optional

If True (default) and the current engine is not the preferred engine, attempt to insert this operation before a transfer upstream of the current relation, as long as this can be done without breaking up any locked relations or changing the resulting relation content.

transferbool, optional

If True (False is default) and the current engine is not the preferred engine, insert a new Transfer to the preferred engine before this operation. If backtrack is also true, the transfer is added only if the backtrack attempt fails.

require_preferred_enginebool, optional

If True (False is default) and the current engine is not the preferred engine, raise EngineError. If backtrack is also true, the exception is only raised if the backtrack attempt fails. Ignored if transfer is true.

Returns:

new_relationRelation

Relation that includes this operation. This may be target if the operation is a no-op, and it may not be a UnaryOperationRelation holding this operation (or even a similar one) if the operation was inserted earlier in the tree via commutation relations or if simplification occurred.

Raises:

ColumnError

Raised if the operation could not be applied due to problems with the target relation’s columns.

EngineError

Raised if the operation could not be applied due to problems with the target relation’s engine.

Notes

Adding operations to relation trees is a potentially complex process in order to give both the operation type and the engine to customize the opportunity to enforce their own invariants. This final method provides the bulk of the high-level implementation, and is called by the Relation class’s convenience methods with essentially no additional logic. The overall sequence is as follows:

• apply starts by delegating to _begin_apply, which allows operation classes to replace the operation object itself, perform initial checks, and set the preferred engine.

• apply then performs the preferred_engine logic indicated by the backtrack transfer, and require_preferred_engine options, delegating backtracking to Engine.backtrack_unary.

• Engine.backtrack_unary will typically call back to commute to determine how and whether to move the new operation upstream of existing ones.

• If backtracking is not used or is not fully successful, apply then delegates to Engine.append_unary to add the operation to the root of the relation tree.

• The Engine methods are expected to delegate back to _finish_apply when they have identified the location in the tree where the new operation should be inserted.

• _finish_apply is responsible for actually constructing the UnaryOperationRelation when appropriate. The default implementation of _finish_apply also calls simplify to see if it is possible to merge the new operation with those immediately upstream of it or elide it entirely.

commute(current: UnaryOperationRelation) → UnaryCommutator

Describe whether and how this operation can be moved upstream of an existing one without changing the content of the resulting relation.

Parameters:

currentUnaryOperationRelation

A unary operation relation that is the current logical target of self.

Returns:

commutatorUnaryCommutator

A struct that either provides a version of current.operation that can be applied to current.target after a possibly-modified version of self, or an explanation of why this is impossible.

Notes

The commute implementations for the provided concrete UnaryOperation types assume that all unary operations preserve row order. If this is not the case in an engine, that engine should not implement Engine.backtrack_unary or take this into account itself when determining whether operations commute.

is_supported_by(engine: Engine) → bool

Whether this operation is supported by the given engine (bool).

simplify(upstream: UnaryOperation) → UnaryOperation | None

Return a simplified combination of this operation with another.

Parameters:

upstreamUnaryOperation

Operation that acts immediately prior to self.

Returns:

simplifiedUnaryOperation

Operation that combines the action of upstream followed by self, or None if no such combination is possible.