Reordering¶

class lsst.daf.relation.Reordering¶

Bases: lsst.daf.relation.UnaryOperation

An extensible UnaryOperation subclass for operations that only reorder rows.

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: lsst.daf.relation._relation.Relation) → collections.abc.Set[lsst.daf.relation._columns._tag.ColumnTag]¶

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

Parameters:	target : `Relation` Relation the operation will act on.
Returns:	columns : `Set` [ `ColumnTag` ] Columns the new relation would have.

applied_max_rows(target: lsst.daf.relation._relation.Relation) → int | None[int, None]¶

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

Parameters:	target : `Relation` Relation the operation will act on.
Returns:	max_rows : `int` or `None` Maximum number of rows the new relation would have.

applied_min_rows(target: lsst.daf.relation._relation.Relation) → int¶

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

Parameters:	target : `Relation` Relation the operation will act on.
Returns:	min_rows : `int` Minimum number of rows the new relation would have.

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:	target : `Relation` Relation the operation will act on. preferred_engine : `Engine`, 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`. backtrack : `bool`, 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. transfer : `bool`, 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_engine : `bool`, 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_relation : `Relation` 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:	current : `UnaryOperationRelation` A unary operation relation that is the current logical target of `self`.
Returns:	commutator : `UnaryCommutator` 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: lsst.daf.relation._unary_operation.UnaryOperation) → lsst.daf.relation._unary_operation.UnaryOperation | None[lsst.daf.relation._unary_operation.UnaryOperation, None]¶

Return a simplified combination of this operation with another.

Parameters:	upstream : `UnaryOperation` Operation that acts immediately prior to `self`.
Returns:	simplified : `UnaryOperation` Operation that combines the action of `upstream` followed by `self`, or `None` if no such combination is possible.

Navigation

Reordering¶