GeoEco.Datasets.Virtual.BlockStatisticGrid

class GeoEco.Datasets.Virtual.BlockStatisticGrid(grid, statistic, xySize=None, zSize=None, tSize=None, tUnit=None, tStart=None, tSemiRegularity=None)

Bases: Grid

A Grid representing a block statistic computed over another Grid.

This class partitions the input Grid into non-overlapping blocks of cells and computes a summary statistic for each block, yielding a reduced resolution representation of it. This operation is sometimes known as downsampling.

Parameters:

• grid (Grid) – Grid for which a block statistic should be computed. This input grid must have a constant increment in each dimension for which summarization is requested. For example, if the zSize parameter is given, indicating that summarization should be performed in the depth dimension, then the input grid must have z coordinates that increment by a constant value. If it does not, then BlockStatisticGrid cannot summarize in the z dimension, and zSize should be left as None. In that situation, the BlockStatisticGrid will have the same number of cells in the z direction as the input grid.

• statistic (str) –

  Summary statistic to calculate for each block, one of:

  • count - number of cells in the block that have data.

  • maximum - miniumum value of call cells in the block with data.

  • mean - mean value of all cells in the block with data.

  • median - median value of all cells in the block with data.

  • minimum - miniumum value of all cells in the block with data.

  • range - maximum value minus the minimum value, considering all cells in the block with data.

  • standard_deviation - sample standard deviation (i.e. the standard deviation estimated using Bessel’s correction) of all cells in the block with data. In order to calculate this, there must be at least two cells in the block with data.

  • sum - sum of all cells in the block with data.

  In all statistics, NoData values are ignored. For example, if a 5 x 5 block has 2 cells with the NoData value, all statistics will be based on the 23 cells that have data. If no cells in a block have data, i.e., they all have the NoData value, the result is the NoData value.

  Allowed values꞉ 'count', 'maximum', 'mean', 'median', 'minimum', 'range', 'standard_deviation', 'sum'.

• xySize (int, optional) – Size of the block in the x and y directions. If not given, 1 will be used, and summarization will not be performed for the x or y dimensions. In this situation, the block statistic grid will have the same number of cells in the x and y directions as the input grid. Minimum value꞉ 1.

• zSize (int, optional) – Size of the block in the z (depth) direction. If not given, 1 will be used, and summarization will not be performed for the z dimension. In this situation, the block statistic grid will have the same number of cells in the z direction as the input grid. This parameter should be omitted if the input grid does not have a z dimension. Minimum value꞉ 1.

• tSize (int, optional) –

  Size of the block in the t (time) direction, in the units given by the tUnit parameter. If not given, 1 will be used, and summarization will not be performed for the t dimension. In this situation, the block statistic grid will have the same number of cells in the t direction as the input grid. This parameter should be omitted if the input grid does not have a t dimension.

  The length of time specified by tSize and tUnit must be longer than the time increment of the input grid. If tUnit is month or year and the tIncrementUnit of the input grid is day, hour, minute, or second, then the resulting blocks will be based on however many days, hours, minutes, or seconds actually fall within each block of months or years.

  A time slice of the input grid will be included in a block if its start time is greater than or equal to the start time of the block, and less than or equal to the end time of the block. By default, the start times of the blocks are aligned with midnight of January 1 of the year the input grid starts. The tStart parameter can override this behavior.

  For example, if the input grid contains hourly time slices and starts on 2012-02-19 13:00:00, and the block statistic grid is defined with a tSize of 1, a tUnit of month, and tStart is not given, then the first block will summarize slices that start 2012-02-01 00:00:00 through 2012-02-29 23:00:00, inclusive. The second time slice will summarize slices that start 2012-03-01 00:00:00 through 2012-03-31 23:00:00, inclusive.

  If tUnit is day, hour, minute, or second and the tSize would yield a series of blocks with a block that overlapped the transition from December to January, the tSemiRegularity parameter controls what happens.

  Minimum value꞉ 1.

• tUnit (str, optional) – Unit of the tSize parameter. This parameter should be omitted if the input grid does not have a t dimension. Allowed values꞉ 'year', 'month', 'day', 'hour', 'minute', 'second'.

• tStart (datetime, optional) –

  Date and time to which the summary blocks’ minimum t coordinates should be aligned (or “snapped”). Ignored if no summarization is performed in the t direction (i.e., tSize is not given).

  If a start date and time is given, it must be less than or equal to the minimum t coordinate of the first time slice of the input grid. If it is not given, it will be set to midnight on January 1 of the year the input grid starts.

  Blocks will be laid out in the t direction starting at this date and time until a block is found that starts on or before the minimum t coordinate of the input grid and ends after that coordinate. That block will become the first in the block statistic grid (the ones before it will be dropped).

  If tUnit is month, then the start date and time must be midnight on the first day of a month. The resulting summary blocks will thus encompass whole months. Starting the blocks at any time other than the very beginning of the month is not currently supported.

  If tSemiRegularity is annual, then the start date and time must be midnight on January 1 of a year.

• tSemiRegularity (str, optional) –

  Type of semi-regularity to use for the t coordinate. Ignored if no summarization is performed in the t direction (i.e., tSize is not given), or if tUnit is month or year.

  If tUnit is day, hour, minute, or second and tSemiRegularity is not given, then the resulting series of summary blocks will be allowed to contain blocks that overlap the December/January transition. For example, this would happen if tUnit is day and tSize is anything other than 1. This may be fine for many applications, but sometimes it is desirable for the first block of every year to start at midnight on January 1. To enable that, set tSemiRegularity to annual.

  When tSemiRegularity is annual, the final block of each year will be prevented from extending into January 1. Once the maximum number of whole blocks are fitted into the year, the remaining fraction of time until midnight January 1 of the next year is calculated. If it is less than half a block long, then the final whole block is expanded to include the remaining fraction. But if it is half or more of a block long, the remaining fraction is added to the year as an additional, shorter-than-usual block.

  For example, if tSize is 8, tUnit is day, and tSemiRegularity is annual, then the first block of every year will always start on midnight January 1. There will always be 46 blocks per year. The 46th block of every year will always start midnight December 27 on non leap years, and midnight December 26 on leap years. In either case, the 46th block will stop at midnight January 1 of the following year, spanning 5 days on non leap years and 6 days on leap years.

  Allowed values꞉ 'annual'. Case sensitive.

Returns:

BlockStatisticGrid instance.

Return type:

BlockStatisticGrid

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, float, or single-element numpy array giving the 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 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