xarray_units.accessor module#

class Units(accessed: TDataArray, chain: int = 1, of: Sequence[Hashable] | Hashable = None)[source]#

Bases: Generic[TDataArray]

DataArray accessor for handling units.

Parameters:

  • accessed (TDataArray) – DataArray to be accessed.

  • chain (int) – Length of method chain. If it is greater than 1, each accessor method (or operation) will return not the resulting DataArray but an accessor of it with the length of chain - 1. Note that, while this simplifies the method chain notation, static type checking may not work correctly in the middle of it.

  • of (Sequence[Hashable] | Hashable) – Coordinate(s) of the DataArray to be accessed. If specified, each accessor method will be applied not to the DataArray itself but to the selected coordinates, and return the DataArray with the updated coordinates.

  • Raises – TypeError: Raised if options of the accessor are not valid.

accessed: TDataArray#

DataArray to be accessed.

add(right: Any) → TDataArray#

Perform left + right considering units.

When called from an accessor, it runs accessed + right.

Parameters:

  • left (TDataArray) – DataArray with units on the left side of the operator.

  • right (Any) – Any data on the right side of the operator.

Returns:

DataArray of the result of the operation.

Raises:
Return type:

TDataArray

apply(method: str, /, *args: Any, **kwargs: Any) → TDataArray#

Apply a method of Astropy Quantity to a DataArray.

When called from an accessor, it runs apply(accessed, method, ...).

Parameters:

  • da (TDataArray) – Input DataArray with units.

  • method (str) – Method (or property) name of Astropy Quantity.

  • *args (Any) – Positional arguments of the method.

  • *kwargs (Any) – Keyword arguments of the method.

Returns:

DataArray with the method (or property) applied.

Raises:
Return type:

TDataArray

See also

https://docs.astropy.org/en/stable/units/quantity.html

chain: int = 1#

Length of method chain.

decompose() → TDataArray#

Convert a DataArray with units to decomposed ones.

When called from an accessor, it runs decompose(accessed).

Parameters:

da (TDataArray) – Input DataArray with units.

Returns:

DataArray with the decomposed units.

Raises:
Return type:

TDataArray

See also

https://docs.astropy.org/en/stable/units/decomposing_and_composing.html

eq(right: Any) → TDataArray#

Perform left == right considering units.

When called from an accessor, it runs accessed == right.

Parameters:

  • left (TDataArray) – DataArray with units on the left side of the operator.

  • right (Any) – Any data on the right side of the operator.

Returns:

DataArray of the result of the operation.

Raises:
Return type:

TDataArray

floordiv(right: Any) → TDataArray#

Perform left // right considering units.

When called from an accessor, it runs accessed // right.

Parameters:

  • left (TDataArray) – DataArray with units on the left side of the operator.

  • right (Any) – Any data on the right side of the operator.

Returns:

DataArray of the result of the operation.

Raises:
Return type:

TDataArray

format(format: str, /, coords: bool = True, **kwargs: Any) → TDataArray#

Format units of a DataArray.

When called from an accessor, it runs format(accessed, format, ...).

Parameters:

  • da (TDataArray) – Input DataArray with units.

  • format (str) – Format of units (e.g. "console", "latex").

  • coords (bool) – Whether to also format the units of the coordinates.

  • **kwargs (Any) – Keyword arguments of the formatting.

Returns:

DataArray with formatted units.

Raises:
Return type:

TDataArray

See also

https://docs.astropy.org/en/stable/units/format.html

ge(right: Any) → TDataArray#

Perform left >= right considering units.

When called from an accessor, it runs accessed >= right.

Parameters:

  • left (TDataArray) – DataArray with units on the left side of the operator.

  • right (Any) – Any data on the right side of the operator.

Returns:

DataArray of the result of the operation.

Raises:
Return type:

TDataArray

gt(right: Any) → TDataArray#

Perform left > right considering units.

When called from an accessor, it runs accessed > right.

Parameters:

  • left (TDataArray) – DataArray with units on the left side of the operator.

  • right (Any) – Any data on the right side of the operator.

Returns:

DataArray of the result of the operation.

Raises:
Return type:

TDataArray

le(right: Any) → TDataArray#

Perform left <= right considering units.

When called from an accessor, it runs accessed <= right.

Parameters:

  • left (TDataArray) – DataArray with units on the left side of the operator.

  • right (Any) – Any data on the right side of the operator.

Returns:

DataArray of the result of the operation.

Raises:
Return type:

TDataArray

like(other: DataArray, /, equivalencies: Equivalency | None = None) → TDataArray#

Convert a DataArray with units to those of the other.

When called from an accessor, it runs like(accessed, other, ...).

Parameters:

  • da (TDataArray) – Input DataArray with units.

  • other (DataArray) – DataArray with units to which the input is converted.

  • equivalencies (Equivalency | None) – Optional Astropy equivalencies.

Returns:

DataArray with the converted units.

Raises:
Return type:

TDataArray

See also

https://docs.astropy.org/en/stable/units/quantity.html

lt(right: Any) → TDataArray#

Perform left < right considering units.

When called from an accessor, it runs accessed < right.

Parameters:

  • left (TDataArray) – DataArray with units on the left side of the operator.

  • right (Any) – Any data on the right side of the operator.

Returns:

DataArray of the result of the operation.

Raises:
Return type:

TDataArray

matmul(right: Any) → TDataArray#

Perform left @ right considering units.

When called from an accessor, it runs accessed @ right.

Parameters:

  • left (TDataArray) – DataArray with units on the left side of the operator.

  • right (Any) – Any data on the right side of the operator.

Returns:

DataArray of the result of the operation.

Raises:
Return type:

TDataArray

mod(right: Any) → TDataArray#

Perform left % right considering units.

When called from an accessor, it runs accessed % right.

Parameters:

  • left (TDataArray) – DataArray with units on the left side of the operator.

  • right (Any) – Any data on the right side of the operator.

Returns:

DataArray of the result of the operation.

Raises:
Return type:

TDataArray

mul(right: Any) → TDataArray#

Perform left * right considering units.

When called from an accessor, it runs accessed * right.

Parameters:

  • left (TDataArray) – DataArray with units on the left side of the operator.

  • right (Any) – Any data on the right side of the operator.

Returns:

DataArray of the result of the operation.

Raises:
Return type:

TDataArray

ne(right: Any) → TDataArray#

Perform left != right considering units.

When called from an accessor, it runs accessed != right.

Parameters:

  • left (TDataArray) – DataArray with units on the left side of the operator.

  • right (Any) – Any data on the right side of the operator.

Returns:

DataArray of the result of the operation.

Raises:
Return type:

TDataArray

of: Sequence[Hashable] | Hashable = None#

Coordinate(s) of the DataArray to be accessed.

pow(right: Any) → TDataArray#

Perform left ** right considering units.

When called from an accessor, it runs accessed ** right.

Parameters:

  • left (TDataArray) – DataArray with units on the left side of the operator.

  • right (Any) – Any data on the right side of the operator.

Returns:

DataArray of the result of the operation.

Raises:
Return type:

TDataArray

set(units: UnitBase | str, /, *, overwrite: bool = False) → TDataArray#

Set units to a DataArray.

When called from an accessor, it runs set(accessed, units, ...).

Parameters:

  • da (TDataArray) – Input DataArray.

  • units (UnitBase | str) – Units to be set to the input.

  • overwrite (bool) – Whether to overwrite existing units.

Returns:

DataArray with given units in attrs["units"].

Raises:
Return type:

TDataArray

sub(right: Any) → TDataArray#

Perform left - right considering units.

When called from an accessor, it runs accessed - right.

Parameters:

  • left (TDataArray) – DataArray with units on the left side of the operator.

  • right (Any) – Any data on the right side of the operator.

Returns:

DataArray of the result of the operation.

Raises:
Return type:

TDataArray

take(operator: Literal['mul', 'pow', 'matmul', 'truediv'] | Literal['add', 'sub', 'floordiv', 'mod', 'lt', 'le', 'eq', 'ne', 'ge', 'gt'], right: Any, /) → TDataArray#

Perform an operation between left and right data considering units.

Parameters:

  • left (TDataArray) – DataArray with units on the left side of the operator.

  • operator (Literal['mul', 'pow', 'matmul', 'truediv'] | ~typing.Literal['add', 'sub', 'floordiv', 'mod', 'lt', 'le', 'eq', 'ne', 'ge', 'gt']) – Name of the operator (e.g. "add", "gt").

  • right (Any) – Any data on the right side of the operator.

Returns:

DataArray of the result of the operation. Units are the same as left in a numerical operation (e.g. "add") or nothing in a relational operation (e.g. "gt").

Raises:
Return type:

TDataArray

to(units: UnitBase | str, /, equivalencies: Equivalency | None = None) → TDataArray#

Convert a DataArray with units to other units.

When called from an accessor, it runs to(accessed, units, ...).

Parameters:

  • da (TDataArray) – Input DataArray with units.

  • units (UnitBase | str) – Units to which the input is converted.

  • equivalencies (Equivalency | None) – Optional Astropy equivalencies.

Returns:

DataArray with the converted units.

Raises:
Return type:

TDataArray

See also

https://docs.astropy.org/en/stable/units/quantity.html

truediv(right: Any) → TDataArray#

Perform left / right considering units.

When called from an accessor, it runs accessed / right.

Parameters:

  • left (TDataArray) – DataArray with units on the left side of the operator.

  • right (Any) – Any data on the right side of the operator.

Returns:

DataArray of the result of the operation.

Raises:
Return type:

TDataArray

unset() → TDataArray#

Remove units from a DataArray.

When called from an accessor, it runs unset(accessed).

Parameters:

da (TDataArray) – Input DataArray.

Returns:

DataArray with units removed.

Return type:

TDataArray

units(accessed: TDataArray, /, *, chain: int = 1, of: Sequence[Hashable] | Hashable = None) → Units[TDataArray][source]#

Return a units accessor of a DataArray.

Parameters:

  • accessed (TDataArray) – DataArray to be accessed.

  • chain (int) – Length of method chain. If it is greater than 1, each accessor method (or operation) will return not the resulting DataArray but an accessor of it with the length of chain - 1. Note that, while this simplifies the method chain notation, static type checking may not work correctly in the middle of it.

  • of (Sequence[Hashable] | Hashable) – Coordinate(s) of the DataArray to be accessed. If specified, each accessor method will be applied not to the DataArray itself but to the selected coordinates, and return the DataArray with the updated coordinates.

Returns:

Units accessor of the DataArray.

Raises:

TypeError – Raised if options of the accessor are not valid.

Return type:

Units[TDataArray]