canns.analyzer.data.cell_classification.core.grid_cells

Grid Cell Classification

Implementation of gridness score algorithm for identifying and characterizing grid cells.

Based on the MATLAB gridnessScore.m implementation.

Attributes

x

Classes

GridnessAnalyzer	Analyzer for computing gridness scores from spatial autocorrelograms.
GridnessResult	Results from gridness score computation.

Functions

compute_2d_autocorrelation(rate_map[, overlap])

Compute 2D spatial autocorrelation of a firing rate map.

Module Contents

class canns.analyzer.data.cell_classification.core.grid_cells.GridnessAnalyzer(threshold=0.2, min_orientation=15.0, min_center_radius=2, num_gridness_radii=3)

Analyzer for computing gridness scores from spatial autocorrelograms.

This implements the rotation-correlation method for quantifying hexagonal grid patterns in neural firing rate maps.

Parameters:

• threshold (float, optional) – Normalized threshold for contour detection (0-1). Default is 0.2.

• min_orientation (float, optional) – Minimum angular difference between fields (degrees). Default is 15.

• min_center_radius (int, optional) – Minimum center field radius in pixels. Default is 2.

• num_gridness_radii (int, optional) – Number of adjacent radii to average for gridness score. Default is 3.

Examples

>>> analyzer = GridnessAnalyzer()
>>> # Assume we have a 2D rate map
>>> autocorr = compute_2d_autocorrelation(rate_map)
>>> result = analyzer.compute_gridness_score(autocorr)
>>> print(f"Gridness score: {result.score:.3f}")
>>> print(f"Grid spacing: {result.spacing}")

Notes

Based on gridnessScore.m from the MATLAB codebase.

References

The gridness score algorithm computes correlations between the autocorrelogram and rotated versions at 30°, 60°, 90°, 120°, and 150°. The score is: min(r_60°, r_120°) - max(r_30°, r_90°, r_150°)

This exploits the 60° rotational symmetry of hexagonal grids.

compute_gridness_score(autocorr)

Compute gridness score from a 2D autocorrelogram.

Parameters:

autocorr (np.ndarray) – 2D autocorrelogram of a firing rate map

Returns:

result – Complete gridness analysis results

Return type:

GridnessResult

Raises:

ValueError – If autocorr is not 2D or if center field cannot be detected

min_center_radius = 2

min_orientation = 15.0

num_gridness_radii = 3

threshold = 0.2

class canns.analyzer.data.cell_classification.core.grid_cells.GridnessResult

Results from gridness score computation.

score

Gridness score (range -2 to 2, typical grid cells: 0.3-1.3)

Type:

float

spacing

Array of 3 grid field spacings (distances from center)

Type:

np.ndarray

orientation

Array of 3 grid field orientations (angles in degrees)

Type:

np.ndarray

ellipse

Fitted ellipse parameters [cx, cy, rx, ry, theta]

Type:

np.ndarray

ellipse_theta_deg

Ellipse orientation in degrees [0, 180]

Type:

float

center_radius

Radius of the central autocorrelation field

Type:

float

optimal_radius

Radius at which gridness score is maximized

Type:

float

peak_locations

Coordinates of detected grid peaks (N x 2 array)

Type:

np.ndarray

center_radius: float

ellipse: numpy.ndarray

ellipse_theta_deg: float

optimal_radius: float

orientation: numpy.ndarray

peak_locations: numpy.ndarray | None = None

score: float

spacing: numpy.ndarray

canns.analyzer.data.cell_classification.core.grid_cells.compute_2d_autocorrelation(rate_map, overlap=0.8)

Compute 2D spatial autocorrelation of a firing rate map.

This is a convenience wrapper around the autocorrelation function from the correlation module.

Parameters:

• rate_map (np.ndarray) – 2D firing rate map

• overlap (float, optional) – Overlap percentage (0-1). Default is 0.8.

Returns:

autocorr – 2D autocorrelogram

Return type:

np.ndarray

Examples

>>> rate_map = np.random.rand(50, 50)
>>> autocorr = compute_2d_autocorrelation(rate_map)
>>> print(autocorr.shape)

Notes

Based on autocorrelation.m from the MATLAB codebase.

canns.analyzer.data.cell_classification.core.grid_cells.x