Grids

GridObject (GeoRefObject)

Base object representing a grid made of individual cells, supporting any dimension (2D, 3D, 4D, etc.).: - all indexed along the provided dimensions (e.g. UV in 2D, UVW in 3D, etc.) - with X, Y, Z coordinates at their center

There is no assumption on the grid actual representation and could be unstructured, irregular, regular, etc. You may use one of the provided children class or inherit this class to implement your own representation (e.g. hexahedrons).

Parameters:

Name	Type	Description	Default
name	str	object name.	required
geometry	~Data	geometry data, respectively X, Y and Z.	required
coords	~Data	grid coordinates.	required
coords_labels	List[geolime.base.enums.Coord]	labels corresponding to the given coordinates.	required
read_only	Union[bool, List[bool]]	whether XYZ coordinates are read-only. Use a single boolean for all, or a list a 3 booleans, respectively for each axis.	True

Exceptions:

Type	Description
ValueError	Object name is not provided.
ValueError	Shape is missing or incorrect.
ValueError	Number of coordinate labels doesn't match given coordinates shape.

Attributes:

Name	Type	Description
n_cells	int	total number of grid cells.
origin	Vector	grid origin.
shape	np.ndarray	shape of the grid.
dimension	int	number of dimensions.

dimension: int property readonly

Return the number of dimensions of the grid (2D, 3D, 4D, etc.).

Returns:

Type	Description
int	The number of dimensions.

n_cells: int property readonly

Return the total number of cells.

Returns:

Type	Description
int	The product of the number of cells in each dimension.

origin: ~Vector property readonly

Return the origin of the grid.

Returns:

Type	Description
~Vector	Grid origin 3D point (X, Y, Z).

shape: ndarray property readonly

Return the shape of the grid in each direction.

Returns:

Type	Description
ndarray	Grid shape as list.

aggregate(self, properties=None, agg_methods=[<AggregationMethod.SUM: 'sum'>, <AggregationMethod.MIN: 'min'>, <AggregationMethod.MAX: 'max'>, <AggregationMethod.MEAN: 'mean'>])

Return the object data grouped by location (X, Y) and grid index (U, V).

Parameters:

Name	Type	Description	Default
properties	List[str]	list of properties name to transfer to the GIS Object. Setting to None or empty list will select all existing properties.	None
agg_methods	List[str]	aggregation data methods. See pandas.DataFrame.group_byto find out supported methods.	[<AggregationMethod.SUM: 'sum'>, <AggregationMethod.MIN: 'min'>, <AggregationMethod.MAX: 'max'>, <AggregationMethod.MEAN: 'mean'>]

Returns:

Type	Description
DataFrame	DataFrame of XY coordinates with aggregated data.

Exceptions:

Type	Description
ValueError	if no aggregation method is provided. if 'X', 'Y', 'U' or 'V' are part of the properties.
Error	if one of the agg_methods is not supported.

axis(self, axis)

Return the cell unit vector for the given axis.

Returns:

Type	Description
~Vector	Grid directional vector (X, Y, Z).

Exceptions:

Type	Description
ValueError	if axis is out of dimensions

check_coords_bounds(self, coords)

Check whether grid coordinates are out of bounds or not. If true, the exception will be returned, otherwise None.

Parameters:

Name	Type	Description	Default
coords	ndarray	grid coordinates as (dimension,) or (N, dimension)	required

Returns:

Type	Description
ValueError	containing the error or None if coordinates are valid.

coords2idx(self, coords)

Get the global grid index of the cell corresponding to the given (U, V, W) coordinates. See idx2coords() for inverse function.

Parameters:

Name	Type	Description	Default
coords	Union[List[int], List[List[int]], numpy.ndarray]	Grid coordinates as (n_dim,) or (N, n_dim)	required

Returns:

Type	Description
Union[int, numpy.ndarray]	The global index or list of indices.

Exceptions:

Type	Description
ValueError	if grid coordinates are out of bounds.

coords2xyz(self, coords)

Get the (X, Y, Z) coordinates of the center of the cell corresponding to the given coordinate indices. Note that it returns the theoretical (X, Y, Z) position which may not exist (e.g. see BlockModel) or has been moved (e.g. actual positions have changed).

Parameters:

Name	Type	Description	Default
coords	~IntArray	Grid coordinates as (n_dim,) or (N, n_dim)	required

Returns:

Type	Description
ndarray	The (X, Y, Z) coordinates as an array of shape (n_dim,) if coords is a single coordinates set (n_dim,) or as an array of shape (N, n_dim) if coords is an array of N coordinates sets (N, n_dim).

Exceptions:

Type	Description
ValueError	If the grid coordinates doesn't have the expected dimension. If the grid coordinates are out of bounds

element_count(self)

Return the actual number of cells defined in the grid. This number may be different from n_cells depending on the grid type. Same as sample_count().

Returns:

Type	Description
int	Number of cells defined.

idx2coords(self, idx)

Get the grid coordinates of the cell corresponding to the given global grid index. See coords2idx() for inverse function.

Parameters:

Name	Type	Description	Default
idx	Union[int, List[int], numpy.ndarray]	global index or list of indices - index must be in range [0, n_cells[	required

Returns:

Type	Description
ndarray	The grid coordinates as an array of shape (n_dim,) if idx is an integer or as an array of shape (N, n_dim) if idx is an array of size N.

Exceptions:

Type	Description
ValueError	if idx is out of bounds.

indexed_coords(self, region=None)

Return the object geometry along with its indexed coordinates.

Returns:

Type	Description
ndarray	Object geometry and indices, respectively X, Y, Z, coords_labels data arrays.

sample_count(self)

Return the actual number of cells defined in the grid. This number may be different from n_cells depending on the grid type. Same as element_count().

Returns:

Type	Description
int	Number of cells defined.