cogpy.utils.grid_neighborhood

Module: grid_neighborhood Status: STABLE Last Updated: 2025-09-07 Author: Arash Shahidi, A.Shahidi@campus.lmu.de

Summary:

Utilities for working with per-node neighborhoods on a 2D grid, derived from a position-agnostic footprint (stencil). Includes the GridNeighborhood class which precomputes per-node neighborhood masks and neighbor relations, as well as standalone functions for constructing and manipulating such neighborhoods.

Functions:

make_footprint: Create a binary structuring element (stencil) via morphological iteration. remove_center: Return a copy of the stencil with the center element cleared (set to False). grid_index_array: Create a 2D array of linear indices shaped like the grid. build_neighbor_masks: Construct per-node neighborhood masks from a position-agnostic footprint. build_neighbor_pairs_df: Generate a long-form DataFrame of (reference, neighbor) pairs. adjacency_matrix: Build an adjacency matrix from neighborhood masks. adjacency_edges: Get the adjacency edges (source, destination) for the grid. gather_neighbors: Get grid values of neighbors of a reference node. map_neighbors: Return a function that applies an ensemble function to each node’s neighborhood. apply_neighborfunc: Apply a function to each node’s neighborhood and return the results. apply_neighborfunc: Apply a function to each node’s neighborhood and return the results.

Classes:

GridNeighborhood: Class encapsulating grid neighborhood utilities and precomputations.

attributes:: footprint: The position-agnostic neighborhood stencil. grid_shape: Shape of the grid as (rows, cols). num_nodes: Total number of nodes in the grid. include_mask_per_node: Per-node neighborhood masks including the reference node. exclude_mask_per_node: Per-node neighborhood masks excluding the reference node. neighbor_pairs_df: DataFrame of directed neighbor relations (excluding self). adj: Adjacency matrix of the grid (self excluded). adj_src: Source indices of adjacency edges. adj_dst: Destination indices of adjacency edges.
methods:: get_neighbor_mask: Return the neighborhood mask for a given node. adjacency_matrix: Build an adjacency matrix from the precomputed masks. adjacency_edges: Get the adjacency edges (source, destination) for the grid. neighbor_indices: Get linear indices of neighbors for a given node (self excluded). apply_neighborhoodfunc: Apply a function to each node’s neighborhood and return the results. neighborhood_mapper: Return a function that applies an ensemble function to each node’s neighborhood.

Constants:

None

Example:

>>> from cogpy.utils import grid_neighborhood as gn
>>> footprint = gn.make_footprint(2, 1, 2)
>>> gneigh = gn.GridNeighborhood(AP=16, ML=16, footprint=footprint)
>>> gneigh.grid_shape
(16, 16)
>>> gneigh.num_nodes
256
>>> gneigh.get_neighbor_mask(node_idx=0, exclude=True).shape
(16, 16)
>>> gneigh.adj.shape
(256, 256)
>>> gneigh.neighbor_indices(node_idx=0)
array([ 1,  2, 16, 17, 32])

Functions

`adjacency_edges`(args, *kwargs)	Get the adjacency edges (source, destination) for the grid.
`adjacency_matrix`(grid_shape[, exclude, ...])	Build an adjacency matrix from neighborhood masks.
`apply_neighborfunc`(ensemble_func, ...)	Apply a function to each node's neighborhood and return the results.
`build_neighbor_masks`(footprint, grid_shape)	Construct per-node neighborhood masks from a position-agnostic footprint.
`build_neighbor_pairs_df`(footprint, ...)	Generate a long-form DataFrame of (reference, neighbor) pairs.
`center_index_from_footprint`(footprint)	Return the flat index of the footprint's logical center (row = H//2, col = W//2, etc.) among the True elements.
`gather_neighbors`(grid_values, neighbor_mask, ...)	Get grid values of neighbors of a reference node.
`grid_index_array`(grid_shape)	Create a 2D array of linear indices shaped like the grid.
`make_footprint`([rank, connectivity, niter])	Create a binary structuring element (stencil) via morphological iteration.
`map_neighbors`(ensemble_func, neighbor_mask)	Return a function that applies ensemble_func to each node's neighborhood.
`remove_center`(footprint)	Return a copy of the stencil with the center element cleared (set to False).

Classes

GridNeighborhood(AP, ML[, footprint])

Utilities for working with per-node neighborhoods on a 2D grid, derived from a position-agnostic footprint (stencil).