Quantity classes#

class genno.core.attrseries.AttrSeries(data: Any | None = None, *args, name: Hashable | None = None, attrs: Mapping | None = None, **kwargs)[source]#

pandas.Series subclass imitating xarray.DataArray.

The AttrSeries class provides similar methods and behaviour to xarray.DataArray, so that genno.operator functions and user code can use xarray-like syntax. In particular, this allows such code to be agnostic about the order of dimensions.

Parameters:
  • units (str or pint.Unit, optional) – Set the units attribute. The value is converted to pint.Unit and added to attrs.

  • attrs (Mapping, optional) – Set the attrs of the AttrSeries. This attribute was added in pandas 1.0, but is not currently supported by the Series constructor.

name#

The name of this Quantity.

Like xarray.DataArray.name.

align_levels(other: AttrSeries) Tuple[Sequence[Hashable], AttrSeries][source]#

Return a copy of self with ≥1 dimension(s) in the same order as other.

Work-around for pandas-dev/pandas#25760 and other limitations of pandas.Series.

assign_coords(coords=None, **coord_kwargs)[source]#

Like xarray.DataArray.assign_coords().

bfill(dim: Hashable, limit: int | None = None)[source]#

Like xarray.DataArray.bfill().

clip(min=None, max=None, *, keep_attrs: bool | None = None)[source]#

Like xarray.DataArray.clip().

pandas.Series.clip() has arguments named lower and upper instead of min and max, respectively.

keep_attrs=False is not implemented.

property coords#

Like xarray.DataArray.coords. Read-only.

cumprod(dim=None, axis=None, skipna=None, **kwargs)[source]#

Like xarray.DataArray.cumprod().

property dims: Tuple[Hashable, ...]#

Like xarray.DataArray.dims.

drop(label)[source]#

Like xarray.DataArray.drop().

drop_vars(names: Hashable | Iterable[Hashable], *, errors: str = 'raise')[source]#

Like xarray.DataArray.drop_vars().

expand_dims(dim=None, axis=None, **dim_kwargs: Any) AttrSeries[source]#

Like xarray.DataArray.expand_dims().

ffill(dim: Hashable, limit: int | None = None)[source]#

Like xarray.DataArray.ffill().

classmethod from_series(series, sparse=None)[source]#

Like xarray.DataArray.from_series().

interp(coords: Mapping[Hashable, Any] | None = None, method: str = 'linear', assume_sorted: bool = True, kwargs: Mapping[str, Any] | None = None, **coords_kwargs: Any)[source]#

Like xarray.DataArray.interp().

This method works around two long-standing bugs in pandas:

item(*args)[source]#

Like xarray.DataArray.item().

rename(new_name_or_name_dict: Hashable | Mapping[Hashable, Hashable] | None = None, **names: Hashable)[source]#

Like xarray.DataArray.rename().

sel(indexers: Mapping[Any, Any] | None = None, method: str | None = None, tolerance=None, drop: bool = False, **indexers_kwargs: Any)[source]#

Like xarray.DataArray.sel().

property shape: Tuple[int, ...]#

Like xarray.DataArray.shape.

shift(shifts: Mapping[Hashable, int] | None = None, fill_value: Any | None = None, **shifts_kwargs: int)[source]#

Like xarray.DataArray.shift().

squeeze(dim=None, drop=False, axis=None)[source]#

Like xarray.DataArray.squeeze().

sum(dim: Dims = None, skipna: bool | None = None, min_count: int | None = None, keep_attrs: bool | None = None, **kwargs: Any) AttrSeries[source]#

Like xarray.DataArray.sum().

to_dataframe(name: Hashable | None = None, dim_order: Sequence[Hashable] | None = None) DataFrame[source]#

Like xarray.DataArray.to_dataframe().

to_series()[source]#

Like xarray.DataArray.to_series().

transpose(*dims)[source]#

Like xarray.DataArray.transpose().

where(cond: ~typing.Any, other: ~typing.Any = <NA>, drop: bool = False, *, axis=None, inplace: bool = False)[source]#

Like xarray.DataArray.where().

Passing True for drop is not implemented.

class genno.core.attrseries.AttrSeriesCoordinates(obj)[source]#
property variables#

Low level interface to Coordinates contents as dict of Variable objects.

This dictionary is frozen to prevent mutation.

class genno.core.sparsedataarray.SparseAccessor(obj)[source]#

xarray accessor to help SparseDataArray.

See the xarray accessor documentation, e.g. register_dataarray_accessor().

property COO_data#

True if the DataArray has sparse.COO data.

convert()[source]#

Return a SparseDataArray instance.

property dense#

Return a copy with dense (numpy.ndarray) data.

property dense_super#

Return a proxy to a numpy.ndarray-backed xarray.DataArray.

class genno.core.sparsedataarray.SparseDataArray(data: ~typing.Any = <NA>, coords: ~typing.Sequence[~typing.Tuple] | ~typing.Mapping[~typing.Hashable, ~typing.Any] | None = None, dims: str | ~typing.Sequence[~typing.Hashable] | None = None, name: ~typing.Hashable | None = None, attrs: ~typing.Mapping | None = None, indexes: ~typing.Dict[~typing.Hashable, ~pandas.core.indexes.base.Index] | None = None, fastpath: bool = False, **kwargs)[source]#

DataArray with sparse data.

SparseDataArray uses sparse.COO for storage with numpy.nan as its sparse.SparseArray.fill_value. Some methods of DataArray are overridden to ensure data is in sparse, or dense, format as necessary, to provide expected functionality not currently supported by sparse, and to avoid exhausting memory for some operations that require dense data.

clip(min=None, max=None, *, keep_attrs=None)[source]#

Override clip() to return SparseDataArray.

ffill(dim: Hashable, limit: int | None = None)[source]#

Override ffill() to auto-densify.

classmethod from_series(obj, sparse=True)[source]#

Convert a pandas.Series into a SparseDataArray.

interp(coords=None, method='linear', assume_sorted=False, kwargs=None, **coords_kwargs: Any)[source]#

Override interp() to auto-densify.

item(*args)#

Like item().

sel(indexers: Mapping[Any, Any] | None = None, method: str | None = None, tolerance=None, drop: bool = False, **indexers_kwargs: Any) SparseDataArray[source]#

Return a new array by selecting labels along the specified dim(s).

Overrides sel() to handle >1-D indexers with sparse data.

property size: int#

Number of elements in the array.

Equal to np.prod(a.shape), i.e., the product of the array’s dimensions.

squeeze(dim=None, drop=False, axis=None)[source]#

Return a new object with squeezed data.

Parameters:
  • dim (None or Hashable or collections.abc.Iterable of Hashable, optional) – Selects a subset of the length one dimensions. If a dimension is selected with length greater than one, an error is raised. If None, all length one dimensions are squeezed.

  • drop (bool, default: False) – If drop=True, drop squeezed coordinates instead of making them scalar.

  • axis (None or int or collections.abc.Iterable of int, optional) – Like dim, but positional.

Returns:

squeezed – This object, but with with all or a subset of the dimensions of length 1 removed.

Return type:

same type as caller

See also

numpy.squeeze

to_dataframe(name: Hashable | None = None, dim_order: Sequence[Hashable] | None = None) DataFrame[source]#

Convert this array and its coords into a pandas.DataFrame.

Overrides to_dataframe().

to_series() Series[source]#

Convert this array into a Series.

Overrides to_series() to create the series without first converting to a potentially very large numpy.ndarray.

where(cond: ~typing.Any, other: ~typing.Any = <NA>, drop: bool = False)[source]#

Override where() to auto-densify.

class genno.core.base.BaseQuantity(data: Any | None = None, coords: Sequence[Tuple] | Mapping[Hashable, Any] | None = None, dims: str | Sequence[Hashable] | None = None, name: Hashable | None = None, attrs: Mapping | None = None, indexes: Dict[Hashable, Index] | None = None, fastpath: bool = False, **kwargs)[source]#

Common base for a class that behaves like xarray.DataArray.

The class has units and unit-aware binary operations.

class genno.core.base.BinaryOpsMixIn[source]#

Binary operations for Quantity.

Subclasses must implement _perform_binary_op().

Several binary operations are provided with methods that:

  • Convert scalar operands to Quantity.

  • Determine result units.

  • Preserve name and non-unit attrs.

class genno.core.base.UnitsMixIn[source]#

Object with units and _binary_op_units().

property units#

Retrieve or set the units of the Quantity.

Examples

Create a quantity without units:

>>> qty = Quantity(...)

Set using a string; automatically converted to pint.Unit:

>>> qty.units = "kg"
>>> qty.units
<Unit('kilogram')>
genno.core.base.collect_attrs(data, attrs_arg: Mapping | None, kwargs: MutableMapping) MutableMapping[source]#

Handle attrs and ‘units’ kwargs to Quantity constructors.

genno.core.base.make_binary_op(op, *, swap: bool)[source]#

Create a method for binary operator name.

genno.core.base.prepare_binary_op(obj: BaseQuantity, other, op, swap: bool) Tuple[BaseQuantity, BaseQuantity, Unit, float][source]#

Prepare inputs for a binary operation.

Returns:

  1. The left operand (obj if swap is False else other).

  2. The right operand. If units of other are different than obj, other is scaled.

  3. Units for the result. In additive operations, the units of obj take precedence.

  4. Any scaling factor needed to make units of other compatible with obj.

genno.core.base.rank(op) int[source]#

Rank of the binary operation op.

See ‘Hyperoperation’ on Wikipedia for the sense of this meaning of ‘rank’.

genno.core.base.single_column_df(data, name: Hashable) Tuple[Any, Hashable][source]#

Handle data and name arguments to Quantity constructors.

genno.core.quantity.AnyQuantity#

Either AttrSeries or SparseDataArray. Code in genno or user code that receives or returns any Quantity implementation should be typed with this type.

alias of AttrSeries | SparseDataArray

genno.core.quantity.CLASS = 'AttrSeries'#

Name of Quantity.

genno.core.quantity.Quantity#

Class used to implement Quantity.

class genno.compat.xarray.DataArrayLike(*args, **kwargs)[source]#

Protocol for a xarray.DataArray -like API.

This class is used to set signatures and types for methods and attributes on AttrSeries class, which then supplies implementations of each method. Objects typed AnyQuantity see either the signatures of this protocol, or identical signatures for the same methods on DataArray via SparseDataArray.