easy_vic_build.tools.dpc_func.basin_grid_func

Grid utility functions for basin-grid conversion and array mapping.

This module provides helper functions to:

• build basin-based grids at one or multiple resolutions,

• map GeoDataFrame rows to array indices and back,

• create and fill gridded arrays from vector attributes,

• derive mask arrays and coordinate-index mappings.

Functions

assignValue_for_grid_array(empty_grid_array, ...)	Assign values to the empty grid array at the specified indices.
build_grid_shp(basin_shp, grid_res_level0, ...)	Build multi-resolution grid layers for one basin geometry.
createArray_from_gridshp(grid_shp[, ...])	Create a grid array from the grid shape, with values assigned from a specific column.
createEmptyArray_and_assignValue_from_gridshp(...)	Create an empty grid array and assign values from grid shape data.
createEmptyArray_from_gridshp(...[, ...])	Create an empty grid array with the given latitude and longitude grid points.
createGridForBasin(basin_shp, grid_res, ...)	Create grid points for the given basin shape.
createStand_grids_lat_lon_from_gridshp(grid_shp)	Generate sorted latitude and longitude arrays from grid shape.
createmaskArray_for_gridshp_intersect_basinshp(...)	Build a boolean mask for grid cells outside a basin polygon.
createmaskArray_for_gridshp_intersect_gridshpRef(...)	Build a boolean mask for grid cells outside a reference grid extent.
grids_array_coord_map(grid_shp[, reverse_lat])	Generate coordinate-to-index mappings for grid arrays.
gridshp_index_to_grid_array_index(grid_shp, ...)	Convert grid shape indices to the corresponding grid array indices.
intersectGridsWithBasins(grids, basins)	Identify and collect grid cells intersecting each basin.
retriveArray_to_gridshp_values_list(...)	Retrieve values from a gridded array using row/column index lists.
shift_grids(grid_shp, dx, dy)	Translate all grid geometries by fixed offsets.

easy_vic_build.tools.dpc_func.basin_grid_func.createGridForBasin(basin_shp, grid_res, **create_grid_kwargs)

Create grid points for the given basin shape.

Parameters:

• basin_shp (geopandas.GeoDataFrame) – Basin polygon dataset used to generate the grid.

• grid_res (float) – Grid resolution. If None, only one boundary grid is created.

• **create_grid_kwargs (dict) – Extra keyword arguments passed to Grids_for_shp construction.

Returns:

(grid_shp_lon, grid_shp_lat, grid_shp) where longitude and latitude are center-point coordinate lists and grid_shp is the generated Grids_for_shp object.

Return type:

tuple

easy_vic_build.tools.dpc_func.basin_grid_func.shift_grids(grid_shp, dx, dy)

Translate all grid geometries by fixed offsets.

Parameters:

• grid_shp (geopandas.GeoDataFrame) – Grid dataset containing geometry and point_geometry columns.

• dx (float) – Horizontal shift in coordinate units.

• dy (float) – Vertical shift in coordinate units.

Returns:

Shifted grid dataset.

Return type:

geopandas.GeoDataFrame

easy_vic_build.tools.dpc_func.basin_grid_func.createStand_grids_lat_lon_from_gridshp(grid_shp, grid_res=None, reverse_lat=True)

Generate sorted latitude and longitude arrays from grid shape.

Parameters:

• grid_shp (geopandas.GeoDataFrame) – Grid dataset containing point_geometry.

• grid_res (float, optional) – The resolution of the grid. If None, the grid will be a complete rectangular grid.

• reverse_lat (bool, optional) – If True, latitude will be sorted from large to small, top to bottom.

Returns:

• stand_grids_lat (numpy.ndarray) – Sorted latitude values of the grid.

• stand_grids_lon (numpy.ndarray) – Sorted longitude values of the grid.

easy_vic_build.tools.dpc_func.basin_grid_func.createEmptyArray_from_gridshp(stand_grids_lat, stand_grids_lon, third_dim_len=None, dtype=<class 'float'>, missing_value=nan)

Create an empty grid array with the given latitude and longitude grid points.

Parameters:

• stand_grids_lat (numpy.ndarray) – Latitude values of the grid.

• stand_grids_lon (numpy.ndarray) – Longitude values of the grid.

• third_dim_len (int, optional) – Length of the third dimension. If None, a 2D array is returned.

• dtype (data-type, optional) – The desired data type for the array. Default is float.

• missing_value (scalar, optional) – The value to use for missing data. Default is NaN.

Returns:

grid_array – The empty grid array with the specified shape and missing values.

Return type:

numpy.ndarray

easy_vic_build.tools.dpc_func.basin_grid_func.gridshp_index_to_grid_array_index(grid_shp, stand_grids_lat, stand_grids_lon)

Convert grid shape indices to the corresponding grid array indices.

Parameters:

• grid_shp (geopandas.GeoDataFrame) – Grid dataset containing point_geometry.

• stand_grids_lat (numpy.ndarray) – The latitude values of the stand grids.

• stand_grids_lon (numpy.ndarray) – The longitude values of the stand grids.

Returns:

• rows_index (list) – The row indices of the grid array.

• cols_index (list) – The column indices of the grid array.

easy_vic_build.tools.dpc_func.basin_grid_func.assignValue_for_grid_array(empty_grid_array, values_list, rows_index, cols_index)

Assign values to the empty grid array at the specified indices.

Parameters:

• empty_grid_array (numpy.ndarray) – The empty grid array to which values will be assigned.

• values_list (list) – The list of values to assign.

• rows_index (list) – The row indices where values will be assigned.

• cols_index (list) – The column indices where values will be assigned.

Returns:

grid_array – The grid array with assigned values.

Return type:

numpy.ndarray

easy_vic_build.tools.dpc_func.basin_grid_func.retriveArray_to_gridshp_values_list(grid_array, rows_index, cols_index)

Retrieve values from a gridded array using row/column index lists.

Parameters:

• grid_array (numpy.ndarray) – Source array containing gridded values.

• rows_index (array-like of int) – Row indices corresponding to target records.

• cols_index (array-like of int) – Column indices corresponding to target records.

Returns:

Values sampled from grid_array at (rows_index, cols_index).

Return type:

numpy.ndarray

easy_vic_build.tools.dpc_func.basin_grid_func.createEmptyArray_and_assignValue_from_gridshp(stand_grids_lat, stand_grids_lon, values_list, rows_index, cols_index, dtype=<class 'float'>, missing_value=nan)

Create an empty grid array and assign values from grid shape data.

Parameters:

• stand_grids_lat (numpy.ndarray) – Latitude values of the stand grids.

• stand_grids_lon (numpy.ndarray) – Longitude values of the stand grids.

• values_list (list) – List of values to assign.

• rows_index (list) – Row indices for assigning values.

• cols_index (list) – Column indices for assigning values.

• dtype (data-type, optional) – The desired data type for the array. Default is float.

• missing_value (scalar, optional) – The value to use for missing data. Default is NaN.

Returns:

grid_array – The grid array with assigned values.

Return type:

numpy.ndarray

easy_vic_build.tools.dpc_func.basin_grid_func.createArray_from_gridshp(grid_shp, value_column=None, values_list=None, grid_res=None, dtype=<class 'float'>, missing_value=nan, plot=False, reverse_lat=True)

Create a grid array from the grid shape, with values assigned from a specific column.

Parameters:

• grid_shp (geopandas.GeoDataFrame) – Grid dataset containing point_geometry and optional value columns.

• value_column (str, optional) – Column name in grid_shp used as the source values.

• values_list (array-like, optional) – Explicit values to assign. Used when value_column is None.

• grid_res (float, optional) – The resolution of the grid. Default is None.

• dtype (data-type, optional) – The desired data type for the array. Default is float.

• missing_value (scalar, optional) – The value to use for missing data. Default is NaN.

• plot (bool, optional) – If True, the grid array will be plotted. Default is False.

• reverse_lat (bool, optional) – If True, latitude will be sorted from large to small. Default is True.

Returns:

(grid_array, stand_grids_lon, stand_grids_lat, rows_index, cols_index).

Return type:

tuple

easy_vic_build.tools.dpc_func.basin_grid_func.createmaskArray_for_gridshp_intersect_basinshp(grid_shp, basin_shp, grid_res=None, missing_value=nan, plot=False, reverse_lat=True)

Build a boolean mask for grid cells outside a basin polygon.

Parameters:

• grid_shp (geopandas.GeoDataFrame) – Grid dataset with a geometry column.

• basin_shp (geopandas.GeoDataFrame) – Basin dataset; the first geometry is used for intersection.

• grid_res (float, optional) – Grid resolution used when reconstructing a complete array.

• missing_value (scalar, optional) – Fill value for unassigned cells.

• plot (bool, optional) – If True, plot the generated mask.

• reverse_lat (bool, optional) – If True, output array latitude is ordered from north to south.

Returns:

(grid_shp, grid_array_mask) where grid_array_mask is a 2D mask array aligned with standardized latitude/longitude grids.

Return type:

tuple

easy_vic_build.tools.dpc_func.basin_grid_func.createmaskArray_for_gridshp_intersect_gridshpRef(grid_shp, grid_shpRef, grid_res=None, missing_value=nan, plot=False, reverse_lat=True)

Build a boolean mask for grid cells outside a reference grid extent.

Parameters:

• grid_shp (geopandas.GeoDataFrame) – Grid dataset to be masked.

• grid_shpRef (geopandas.GeoDataFrame) – Reference grid dataset; its unary union defines the valid footprint.

• grid_res (float, optional) – Grid resolution used when reconstructing a complete array.

• missing_value (scalar, optional) – Fill value for unassigned cells.

• plot (bool, optional) – If True, plot the generated mask.

• reverse_lat (bool, optional) – If True, output array latitude is ordered from north to south.

Returns:

(grid_shp, grid_array_mask) where grid_array_mask is a 2D mask array aligned with standardized latitude/longitude grids.

Return type:

tuple

easy_vic_build.tools.dpc_func.basin_grid_func.grids_array_coord_map(grid_shp, reverse_lat=True)

Generate coordinate-to-index mappings for grid arrays.

Parameters:

• grid_shp (GeoDataFrame) – A geospatial dataframe containing a ‘point_geometry’ column with x (longitude) and y (latitude) coordinates.

• reverse_lat (bool, optional) – If True, sorts latitude values in descending order (useful for direct plotting), by default True.

Returns:

(lon_list, lat_list, lon_map_index, lat_map_index).

Return type:

tuple

easy_vic_build.tools.dpc_func.basin_grid_func.intersectGridsWithBasins(grids: Grids, basins: Basins)

Identify and collect grid cells intersecting each basin.

Parameters:

• grids (Grids) – A geospatial grid dataset.

• basins (Basins) – A geospatial dataset containing basin geometries.

Returns:

(basins, intersects_grids) where basins gains an intersects_grids column and intersects_grids is the deduplicated union of all intersecting grid cells.

Return type:

tuple

easy_vic_build.tools.dpc_func.basin_grid_func.build_grid_shp(basin_shp, grid_res_level0, grid_res_level1, grid_res_level2, expand_grids_num=1, plot=False)

Build multi-resolution grid layers for one basin geometry.

Parameters:

• basin_shp (geopandas.GeoDataFrame) – Basin polygon dataset.

• grid_res_level0 (float) – Resolution for level-0 grids.

• grid_res_level1 (float) – Resolution for level-1 grids (main modeling scale).

• grid_res_level2 (float) – Resolution for level-2 grids.

• expand_grids_num (int, optional) – Number of level-1 grid cells to expand beyond basin boundary.

• plot (bool, optional) – If True, plot all generated grid levels.

Returns:

(grid_shp_level0, grid_shp_level1, grid_shp_level2, grid_shp_level3).

Return type:

tuple