Grids🍋

`GridObject` 🍋

Bases: 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`	`Optional[Data]`	geometry data, respectively X, Y and Z.	`None`
`coords`	`Optional[Data]`	grid coordinates, typically U, V, W.	`None`
`extra_coord_labels`	`List[str]`	labels corresponding to extra coordinates beyond the grid axes. For example, 4D cube would have an extra-dimension T beyond (U, V, W), therefore: `extra_coord_labels=["T"]`	`[]`
`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`

Raises:

Type	Description
`ValueError`	Object name is not provided. Shape is missing or incorrect. 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`	`ndarray`	shape of the grid.
`dimension`	`int`	number of dimensions.

`dimension: int` `property` 🍋

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

Returns:

Type	Description
`int`	The number of dimensions.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.dimension

Output

`n_cells: int` `property` 🍋

Return the total number of cells.

Returns:

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

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.n_cells

Output

`origin: Vector` `property` 🍋

Return the origin of the grid.

Returns:

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

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.origin

Output

array([0., 0., 0.])

`shape: np.ndarray` `property` 🍋

Return the shape of the grid in each direction.

Returns:

Type	Description
`ndarray`	Grid shape as list.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.shape

Output

array([4, 3, 2])

`aggregate(properties=None, agg_methods=[AggregationMethod.SUM, AggregationMethod.MIN, AggregationMethod.MAX, AggregationMethod.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[Union[AggregationMethod, Callable]]`	aggregation data methods. See Pandas - Group By to find out supported methods.	`[SUM, MIN, MAX, MEAN]`

Returns:

Type	Description
`DataFrame`	DataFrame of XY coordinates with aggregated data.

Raises:

Type	Description
`ValueError`	No aggregation method is provided. 'X', 'Y', 'U' or 'V' are part of the properties.
`AttributeError`	One of the aggregation methods is not supported.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.aggregate()

Output

    X    Y  U  V  Z_sum  Z_min  Z_max  Z_mean  W_sum  W_min  W_max  W_mean
0   0.5  0.5  0  0    2.0    0.5    1.5     1.0      1      0      1     0.5
1   0.5  1.5  0  1    2.0    0.5    1.5     1.0      1      0      1     0.5
2   0.5  2.5  0  2    2.0    0.5    1.5     1.0      1      0      1     0.5
3   1.5  0.5  1  0    2.0    0.5    1.5     1.0      1      0      1     0.5
4   1.5  1.5  1  1    2.0    0.5    1.5     1.0      1      0      1     0.5
5   1.5  2.5  1  2    2.0    0.5    1.5     1.0      1      0      1     0.5
6   2.5  0.5  2  0    2.0    0.5    1.5     1.0      1      0      1     0.5
7   2.5  1.5  2  1    2.0    0.5    1.5     1.0      1      0      1     0.5
8   2.5  2.5  2  2    2.0    0.5    1.5     1.0      1      0      1     0.5
9   3.5  0.5  3  0    2.0    0.5    1.5     1.0      1      0      1     0.5
10  3.5  1.5  3  1    2.0    0.5    1.5     1.0      1      0      1     0.5
11  3.5  2.5  3  2    2.0    0.5    1.5     1.0      1      0      1     0.5

`axis(axis=None)` 🍋

Return the cell unit vector for the given axis. If axis is not provided, the sum of all vectors is returned.

Parameters:

Name	Type	Description	Default
`axis`	`Optional[Axis]`	given axis to get the vector from. If None, the sum of all axes is computed.	`None`

Returns:

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

Raises:

Type	Description
`ValueError`	Axis is out of dimensions when provided.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.axis(1)
vx.axis()

Output

array([0., 1., 0.])
array([1., 1., 1.])

`check_coords_bounds(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`	`Vector`	grid coordinates as (dimension,) or (N, dimension)	required

Returns:

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

Example

Example 1Example 2

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.check_coords_bounds([0,0,0])

Output

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.check_coords_bounds([3,5,0])

Output

ValueError('idx 5.0 is out of bounds [0, 2] for axis 1')

`coords2idx(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]], ndarray]`	Grid coordinates as (n_dim,) or (N, n_dim)	required

Returns:

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

Raises:

Type	Description
`ValueError`	Grid coords are out of bounds.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.coords2idx([1, 0, 0])

Output

`coords2xyz(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`	`Union[List[int], List[List[int]], ndarray]`	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
`ndarray`	coordinates set (n_dim,) or as an array of shape (N, n_dim) if coords is an array
`ndarray`	of N coordinates sets (N, n_dim).

Raises:

Type	Description
`ValueError`	Grid coords doesn't have the expected dimension. Grid coords are out of bounds.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.coords2xyz([[1, 0, 0], [3, 0, 1]])

Output

array([[1.5, 0.5, 0.5],
       [3.5, 0.5, 1.5]])

`downscale(name, discr)` 🍋

Downscale the GridObject by a given discretisation.

Parameters:

Name	Type	Description	Default
`name`	`str`	name of the newly created GridObject.	required
`discr`	`Vector`	Discretisation of the new GridObject.	required

Returns:

Type	Description
`None`	GridObject object downscaled.

`element_count()` 🍋

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.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.element_count()

Output

`idx2coords(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], 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.

Raises:

Type	Description
`ValueError`	idx is out of bounds.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.idx2coords(3)

Output

array([3, 0, 0])

`indexed_coords(region=None)` 🍋

Return the object geometry along with its indexed coordinates.

Parameters:

Name	Type	Description	Default
`region`	`str`	Region or condition to filter the data.	`None`

Returns:

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

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.indexed_coords()

Output

array([[0.5, 0.5, 0.5, 0. , 0. , 0. ],
    [1.5, 0.5, 0.5, 1. , 0. , 0. ],
    [2.5, 0.5, 0.5, 2. , 0. , 0. ],
    [3.5, 0.5, 0.5, 3. , 0. , 0. ],
    [0.5, 1.5, 0.5, 0. , 1. , 0. ],
    [1.5, 1.5, 0.5, 1. , 1. , 0. ],
    [2.5, 1.5, 0.5, 2. , 1. , 0. ],
    [3.5, 1.5, 0.5, 3. , 1. , 0. ],
    [0.5, 2.5, 0.5, 0. , 2. , 0. ],
    [1.5, 2.5, 0.5, 1. , 2. , 0. ],
    [2.5, 2.5, 0.5, 2. , 2. , 0. ],
    [3.5, 2.5, 0.5, 3. , 2. , 0. ],
    [0.5, 0.5, 1.5, 0. , 0. , 1. ],
    [1.5, 0.5, 1.5, 1. , 0. , 1. ],
    [2.5, 0.5, 1.5, 2. , 0. , 1. ],
    [3.5, 0.5, 1.5, 3. , 0. , 1. ],
    [0.5, 1.5, 1.5, 0. , 1. , 1. ],
    [1.5, 1.5, 1.5, 1. , 1. , 1. ],
    [2.5, 1.5, 1.5, 2. , 1. , 1. ],
    [3.5, 1.5, 1.5, 3. , 1. , 1. ],
    [0.5, 2.5, 1.5, 0. , 2. , 1. ],
    [1.5, 2.5, 1.5, 1. , 2. , 1. ],
    [2.5, 2.5, 1.5, 2. , 2. , 1. ],
    [3.5, 2.5, 1.5, 3. , 2. , 1. ]])

`sample_count()` 🍋

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.

Example

import geolime as geo
vx = geo.Voxel("MyGridObj", [4, 3, 2])
vx.sample_count()

Output

`to_pyvista(properties=None)` 🍋

Export GridObject and selected properties to Pyvista ImageData.

Parameters:

Name	Type	Description	Default
`properties`	`Optional[Union[str, List[str]]]`	Property or list of properties to export to Pyvista.	`None`

Returns:

Type	Description
`ImageData`	ImageData object.

`translate_by(coord, expr, region=None)` 🍋

Shift the given existing X, Y or Z coordinate by the given expression or value.

Parameters:

Name	Type	Description	Default
`coord`	`Union[Attribute, Coord]`	coordinate property.	required
`expr`	`str`	expression use to compute the property values. Use backquotes when attribute names contains whitespace.	required
`region`	`Optional[str]`	region or condition in which to set the property data.	`None`

Raises:

Type	Description
`ValueError`	Coordinate doesn't exist.

Last update: 2022-01-06

Grids🍋

GridObject 🍋

dimension: int property 🍋

n_cells: int property 🍋

origin: Vector property 🍋

shape: np.ndarray property 🍋

aggregate(properties=None, agg_methods=[AggregationMethod.SUM, AggregationMethod.MIN, AggregationMethod.MAX, AggregationMethod.MEAN]) 🍋

axis(axis=None) 🍋

check_coords_bounds(coords) 🍋

coords2idx(coords) 🍋

coords2xyz(coords) 🍋

downscale(name, discr) 🍋

element_count() 🍋

idx2coords(idx) 🍋

indexed_coords(region=None) 🍋

sample_count() 🍋

to_pyvista(properties=None) 🍋

translate_by(coord, expr, region=None) 🍋

`GridObject` 🍋

`dimension: int` `property` 🍋

`n_cells: int` `property` 🍋

`origin: Vector` `property` 🍋

`shape: np.ndarray` `property` 🍋

`aggregate(properties=None, agg_methods=[AggregationMethod.SUM, AggregationMethod.MIN, AggregationMethod.MAX, AggregationMethod.MEAN])` 🍋

`axis(axis=None)` 🍋

`check_coords_bounds(coords)` 🍋

`coords2idx(coords)` 🍋

`coords2xyz(coords)` 🍋

`downscale(name, discr)` 🍋

`element_count()` 🍋

`idx2coords(idx)` 🍋

`indexed_coords(region=None)` 🍋

`sample_count()` 🍋

`to_pyvista(properties=None)` 🍋

`translate_by(coord, expr, region=None)` 🍋