GeoEco.Datasets.Virtual.TimeSeriesGridStack

class GeoEco.Datasets.Virtual.TimeSeriesGridStack(collection, expression=None, reportProgress=True, **options)

Bases: Grid

A Grid built by stacking a set of 2D (yx) or 3D (zyx) Grids queried from a DatasetCollection.

Parameters:

collection (DatasetCollection) –
DatasetCollection containing the Grids to stack. The Grids must all have the same dimensions. Typically, they are either 2-dimensional with dimensions yx or 3-dimensional with dimensions zyx. However, they may also include a t dimension (i.e. tyx or tzyx) so long as the length of each Grid in the t direction is 1. In any case, they must all have the same length as each other for the other dimensions. They must also each have a QueryableAttribute defined with a DataType of DateTimeTypeMetadata. The value of this QueryableAttribute must give the time coordinate of the Grid.

The oldest Grid in collection selected by expression must also have three lazy properties defined: TIncrement, TIncrementUnit, and TCornerCoordType. It should also have TSemiRegularity defined if necessary. Please see the Grid documentation for descriptions of these properties.

Alternatively, if collection is the parent collection of the Grids, those lazy properties can be defined by collection itself, rather than being defined by the oldest Grid it contains. This is the common use pattern when the Grids do not have a t dimension.

The Grids that are selected by expression must form a time series with time coordinates that are consistent with the TIncrement and TIncrementUnit. For example, if TIncrement is 1 and TIncrementUnit is 'month', the Grids must occur as a monthly series. Missing time slices are OK and will be automatically represented as slices of NoData. For example, if the DatasetCollection contains 118 monthly Grids spanning 10 years but is missing 2 Grids due to a satellite failure in one of those years, then those two months will automatically be represented as NoData across the entire spatial extent.

There must not be any duplicate time slices used to define the TimeSeriesGridStack. If collection contains duplicates, expression should be used to select a unique set of slices. For example, if collection includes Grids for several oceanographic variables but they can be distinguished from each other by the VariableName QueryableAttribute, then expression could be set to "VariableName = 'SST'", so that only the SST Grids are stacked.
expression (str, optional) –
A SQL-like query expression that selects the datasets of interest based on the values of their queryable attributes. If not provided, all of the datasets in the collection will be selected.

The expression is similar to a SQL “where” clause and may contain the following elements:
- The names of any queryable attributes, with no delimiters, that are defined for objects in the collection, including those they inherit from their parents.
- The binary comparison operators =, <, >, <=, >=, and <>.
- Literals for integers, floating point numbers (with . as the decimal point), Booleans (written true and false), strings (delimited with single or double quotation marks), or dates (written #YYYY-mm-dd HH:MM:SS# or #YYYY-mm-dd# with YYYY as the four-digit year, mm as the two-digit month, dd as the two-digit day, HH as the two-digit hour 00 to 23, MM as the two-digit second, and SS as the two-digit second, with the hour, minute, and second assumed to be 00:00:00 if not provided).
- The binary comparison operator in or not in followed by a comma-delimited list of literals, enclosed in ( and ).
- The binary comparison operator matches followed by a string literal that specifies a regular expression in Python syntax.
- The binary arithmetic operators +, -, *, and /, which may be applied to queryable attributes and numeric literals.
- The unary arithmetic operator -, which may be used to negate a queryable attribute or numeric literal.
- The binary logical operators or and and and unary logical operator not. not has highest precedence; or has lowest. Logical expressions may be chained together but not nested (in parentheses or by any other means).
Operators and queryable attribute names are case-insensitive. Minimum length꞉ 1.
reportProgress (bool, optional) – If True, progress messages will be logged periodically as the query proceeds.
options (dict mapping str to object) – Additional options specific to the collection type.

Returns:

TimeSeriesGridStack instance.

Return type:

TimeSeriesGridStack

Properties

property CenterCoords: (object) Coordinates of the grid cell centers, indexed using the 1-character dimension of interest and optionally a range to retrieve a numpy.ndarray of coordinates (e.g. CenterCoords['x', 0:4]) or an integer to retrieve a float for a single coordinate (e.g. CenterCoords['x', 10]). Coordinates for the t dimension are returned as datetime instances. Read only.

property CoordDependencies: (tuple of str) Same length as Dimensions. Dimensions that each dimension depends on for determining its coordinates. None for dimensions that have a constant coordinate increment. Read only.

property CoordIncrements: (tuple of float) Same length as Dimensions. Coordinate increment for each dimension. None for dimensions that do not have a constant coordinate increment. Read only.

property Data: (object) This grid’s data, indexable using slices (e.g. grid.Data[:, 5:10, -10:]) or integers (e.g. grid.Data[0,1,-2]) or both in combination. Strides and negative indexes are supported in the traditional manner. If the grid is writable, Data can be assigned to write values to the grid, e.g. grid.Data[0,1] = 5 or grid.Data[:,:] = numpy.zeros(grid.Shape). Returns and accepts numpy.ndarray, float, and int. Read only.

property DataIsScaled: (bool) If True, the underlying raw data are stored as the UnscaledDataType to save storage space and then transformed by a scaling equation on the fly when they are returned by Data. The raw data can be accessed with UnscaledData. If False, the raw data are returned as is, with no transformation needed, and UnscaledDataType and DataType are the same, and UnscaledData returns the same values as Data. Read only.

property DataType: (str) Numeric data type of the grid, after the scaling function (if any) has been applied to the raw data. numpy.ndarrays returned by Data have this type. Read only. Allowed values꞉ 'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'float32', 'float64'. Case sensitive.

property Dimensions: (str) Dimensions of this grid. Read only. Allowed values꞉ 'yx', 'zyx', 'tyx', 'tzyx'. Case sensitive.

property DisplayName: (str) Informal name of this object, suitable to be displayed to the user. Read only. Minimum length꞉ 1.

property MaxCoords: (object) Maximum coordinate value for each cell (i.e., the coordinates of the cells’ right edges), indexed using the 1-character dimension of interest and optionally a range to retrieve a numpy.ndarray of coordinates (e.g. MaxCoords['x', 0:4]) or an integer to retrieve a float for a single coordinate (e.g. MaxCoords['x', 10]). Coordinates for the t dimension are returned as datetime instances. Read only.

property MinCoords: (object) Minimum coordinate value for each cell (i.e., the coordinates of the cells’ left edges), indexed using the 1-character dimension of interest and optionally a range to retrieve a numpy.ndarray of coordinates (e.g. MinCoords['x', 0:4]) or an integer to retrieve a float for a single coordinate (e.g. MinCoords['x', 10]). Coordinates for the t dimension are returned as datetime instances. Read only.

property NoDataValue: (object or None) int or float value that indicates that cells of Data should be interpreted as having no data (these are also known as missing, NA, or NULL cells), or None if all cells must have data. Read only.

property ParentCollection: (DatasetCollection or None) Parent DatasetCollection that this object is part of (if any). Read only.

property ReportProgress: None

property Shape: (tuple of int) Same length as Dimensions. Length (number of grid cells) of each dimension. Read only.

property TCountPerSemiRegularPeriod: (int or None) Number of time slices per semi-regular period (i.e. per year). None if the grid’s dimensions do not contain a t coordinate or the t coordinate is not semi-regular. Read only.

property TIncrementUnit: (str or None) Unit of the t coordinate. None if the grid’s dimensions do not contain a t coordinate. Read only. Allowed values꞉ 'year', 'month', 'day', 'hour', 'minute', 'second'. Case sensitive.

property TSemiRegularity: (str or None) Type of semi-regularity used for the t coordinate. None if the grid’s dimensions do not contain a t coordinate or the t coordinate is not semi-regular. Read only. Allowed values꞉ 'annual'. Case sensitive.

property UnscaledData: (object) This grid’s data underlying raw data, before it has been transformed by a scaling equation. UnscaledData is indexable using slices (e.g. grid.UnscaledData[:, 5:10, -10:]) or integers (e.g. grid.UnscaledData[0,1,-2]) or both in combination. Strides and negative indexes are supported in the traditional manner. If the grid is writable, UnscaledData can be assigned to write values to the grid, e.g. grid.UnscaledData[0,1] = 5 or grid.UnscaledData[:,:] = numpy.zeros(grid.Shape). Returns and accepts numpy.ndarray, float, and int. Read only.

property UnscaledDataType: (str) Numeric data type of the grid’s raw data, before it has been transformed by a scaling equation. numpy.ndarrays returned by UnscaledData have this type. If no transformation is needed (DataIsScaled is False), then UnscaledDataType and ScaledDataType are the same, and UnscaledData returns the same values as Data. Read only. Allowed values꞉ 'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'float32', 'float64'. Case sensitive.

property UnscaledNoDataValue: (object or None) int or float value that indicates that cells of UnscaledData should be interpreted as having no data (these are also known as missing, NA, or NULL cells), or None if all cells must have data. Read only.

Methods

`Close`	Closes any open files or connections associated with this object and releases any other resources allocated to access it.
`ConvertSpatialReference`	Converts a spatial reference from one format to another, such as an OGC WKT string to a Proj4 string.
`DeleteLazyPropertyValue`	Deletes the lazy property with the specified name.
`GetAllQueryableAttributes`	Returns a list of all queryable attributes.
`GetIndicesForCoords`	Given a `tuple` or `list` of coordinates, returns a `list` of `int` indices into `Data` for the cell that contains the coordinates.
`GetLazyPropertyValue`	Returns the value of the lazy property with the specified name.
`GetQueryableAttribute`	Returns the queryable attribute with the specified name.
`GetQueryableAttributeValue`	Returns the value of the queryable attribute with the specified name.
`GetQueryableAttributesWithDataType`	Returns a list queryable attributes having the specified data type.
`GetSpatialReference`	Returns the spatial reference of this dataset.
`HasLazyPropertyValue`	Returns True if the specified lazy property has a value.
`SetLazyPropertyValue`	Sets the lazy property with the specified name to the specified value.
`SetSpatialReference`	Sets the spatial reference of this dataset.
`TestCapability`	Tests whether a capability is supported by this class or an instance of it.
`numpy_equal_nan`