Skip to content

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 np.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
3

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
24

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
np.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[AggregationMethod]

aggregation data methods. See Pandas - Group By to find out supported methods.

 [AggregationMethod.SUM, AggregationMethod.MIN, AggregationMethod.MAX, AggregationMethod.MEAN]

Returns:

Type Description
pd.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

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]], np.ndarray]

Grid coordinates as (n_dim,) or (N, n_dim)

 required

Returns:

Type Description
Union[int, np.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
1

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]], np.ndarray]

Grid coordinates as (n_dim,) or (N, n_dim)

 required

Returns:

Type Description
np.ndarray

The (X, Y, Z) coordinates as an array of shape (n_dim,) if coords is a single
np.ndarray

coordinates set (n_dim,) or as an array of shape (N, n_dim) if coords is an array
np.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]])

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
24

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], np.ndarray]

global index or list of indices - index must be in range [0, n_cells[

 required

Returns:

Type Description
np.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
np.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
24

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.