rtgym.agent.sensory.spatial_modulated package

Submodules

rtgym.agent.sensory.spatial_modulated.boundary_cell module

class BoundaryCell(arena, **kwargs)

Bases: SMBase

Boundary cells that respond based on distance to walls.

These cells fire based on the distance to the nearest boundary in any direction. Note: This implementation may not be biologically realistic as it responds to boundaries in all directions simultaneously.

Parameters:

• arena (Arena) – Arena environment object.

• **kwargs – Additional keyword arguments including: n_cells (int): Number of boundary cells. res_dist (float): Response distance from boundary in spatial units. Defaults to 10. magnitude (float): Maximum magnitude of cell responses. normalize (bool): Whether to normalize cell responses. center_border_ratio (float): Ratio of center to border cells (0-1). Defaults to 0.5.

Variables:

sens_type (str) – Sensory type identifier ‘boundary_cell’.

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing sensory specifications including

number of cells and response field dimensions.

Return type:

dict

sens_type = 'boundary_cell'

rtgym.agent.sensory.spatial_modulated.diffusion_cell module

Spatial random fields with wall-aware diffusion from grid_and_place.

class DiffusionCell(arena, n_cells, sensory_key, sigma=8, magnitude=None, normalize=False, seed=None, device='cpu', **kwargs)

Bases: SMBase

Smooth random fields in 2D or 3D without averaging through wall cells.

This preserves grid_and_place’s box-kernel diffusion and normalization. It is a separate sensory type because it differs from Gaussian smoothing.

diffusion_smooth(cells, free_mask=None)

sens_type = 'diffusion_cell'

rtgym.agent.sensory.spatial_modulated.grid_cell module

class GridCell(arena, **kwargs)

Bases: SMBase

Grid cell responses for a spatially modulated grid-like field.

get_specs()

Retrieve statistics of the cell responses.

classmethod load_from_dict(state_dict, arena)

Load the GridCell object from a dictionary and reconstruct it.

Parameters:

• state_dict (dict) – Dictionary containing the object’s state.

• arena (Arena) – Arena object to reinitialize the class.

Returns:

Reconstructed GridCell object.

Return type:

GridCell

sens_type = 'grid_cell'

state_dict()

Get the essential attributes of the GridCell object.

Returns:

Dictionary of the essential attributes.

Return type:

dict

rtgym.agent.sensory.spatial_modulated.place_cell module

class PlaceCell(arena, **kwargs)

Bases: SMBase

Place cell sensory responses.

Place cells are neurons that fire when an animal is in specific locations in an environment. Each place cell has a “place field” - a region where it fires maximally. The firing rate typically follows a Gaussian distribution centered on the place field, decreasing with distance from the center.

Place cells are a key component of the brain’s spatial navigation system, discovered by O’Keefe and Dostrovsky in 1971. They are primarily found in the hippocampus and are thought to form a cognitive map of the environment.

This implementation models place cells with Gaussian or difference-of-Gaussian tuning curves. The difference-of-Gaussian option creates more realistic place fields with inhibitory surrounds.

Parameters:

• arena (Arena) – Arena environment object defining the navigation space.

• **kwargs –

  Additional keyword arguments including: n_cells (int): Number of place cells to create. sigma (float or list): Width of place fields in spatial units. If float, all cells

  use same sigma. If list, each cell gets its own sigma. Defaults to 8.

  ssigma (float): Standard deviation of random variation in place field sizes.

  Only used when sigma is float. Defaults to 0.

  dg_ratio (float): Ratio between center and surround Gaussian for

  difference-of-Gaussian fields. Values > 1 create inhibitory surrounds. Defaults to 1 (simple Gaussian).

  magnitude (float): Scaling factor for response amplitudes. Defaults to None. normalize (bool): Whether to normalize responses to [0,1]. Defaults to False.

Variables:

• sens_type (str) – Sensory type identifier ‘place_cell’.

• response_map (np.ndarray) – Spatial response map of shape (n_cells, *arena_dimensions). Contains the firing rate map for each cell across the entire arena.

get_specs()

Get statistical specifications of the place cell population.

Returns:

Dictionary containing population statistics including:

• cell_max_avg: Average maximum firing rate across cells

• cell_min_avg: Average minimum firing rate across cells

• cell_mean_avg: Average mean firing rate across cells

Return type:

dict

sens_type = 'place_cell'

rtgym.agent.sensory.spatial_modulated.sm_base module

class SMBase(arena, n_cells, sensory_key, seed=None, **kwargs)

Bases: object

Base class for spatially modulated sensory cells.

Provides common functionality for all spatial sensory modalities such as place cells, grid cells, and boundary cells. These cells respond based on the agent’s position in space.

Parameters:

• arena (Arena) – Arena environment object.

• n_cells (int) – Number of cells in this sensory modality.

• sensory_key (str) – Unique identifier for this sensory type.

• seed (int, optional) – Random seed for reproducible cell generation.

• **kwargs – Additional keyword arguments.

Variables:

• arena (Arena) – Arena environment.

• n_cells (int) – Number of sensory cells.

• sensory_key (str) – Unique sensory identifier.

• rng (np.random.Generator) – Random number generator.

• response_map (np.ndarray) – Spatial response map for all cells.

Raises:

AssertionError – If instantiated directly (abstract class) or n_cells <= 0.

get_response(agent_data, return_format=None, device=None)

Look up states or trajectories on CPU or from a cached tensor field.

NumPy input keeps the original NumPy result unless tensor output is requested explicitly. Tensor input uses its own device by default.

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing sensory specifications including

number of cells and response field dimensions.

Return type:

dict

classmethod load(file_path, arena)

Load the GridCell object from a file and reconstruct it.

Parameters:

• file_path (str) – Path to the saved file.

• arena (Arena) – Arena object to reinitialize the class.

Returns:

Reconstructed GridCell object.

print_specs()

Print specifications of this sensory modality.

Prints the specifications returned by get_specs() in a formatted manner.

save(file_path)

Save the object to a file, excluding dynamically generated data.

Parameters:

file_path (str) – Path to the file where the object will be saved.

sens_category = 'spatial_modulated'

sens_type = 'sm_base'

to(device, dtype=None)

Cache a tensor response field. Call again after editing response_map.

vis(N=10, cmap='jet', *args, **kwargs)

Visualize the spatially modulated cells.

Parameters:

• N (int) – Number of cells to visualize.

• cmap (str) – Colormap for visualization.

• *args – Additional positional arguments.

• **kwargs – Additional keyword arguments.

Returns:

Visualization of the first N cells.

Return type:

matplotlib figure

rtgym.agent.sensory.spatial_modulated.weak_sm_cell module

class WeakSMCell(arena, **kwargs)

Bases: SMBase

Weakly spatially modulated cells with Gaussian responses.

These cells have broader, weaker spatial tuning compared to place cells, representing cells that are spatially modulated but not strongly place-specific. Each cell has a Gaussian-shaped firing field at a random location.

Parameters:

• arena (Arena) – Arena environment object.

• **kwargs – Additional keyword arguments including: n_cells (int): Number of weakly spatially modulated cells. sigma (float): Sigma of the Gaussian filter in spatial units. magnitude (float): Maximum magnitude of cell responses.

Variables:

• sens_type (str) – Sensory type identifier ‘weak_sm_cell’.

• response_map (np.ndarray) – Spatial response map of shape (n_cells, *arena_dimensions).

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing sensory specifications including

number of cells and response field dimensions.

Return type:

dict

sens_type = 'weak_sm_cell'

Module contents

class BoundaryCell(arena, **kwargs)

Bases: SMBase

Boundary cells that respond based on distance to walls.

These cells fire based on the distance to the nearest boundary in any direction. Note: This implementation may not be biologically realistic as it responds to boundaries in all directions simultaneously.

Parameters:

• arena (Arena) – Arena environment object.

• **kwargs – Additional keyword arguments including: n_cells (int): Number of boundary cells. res_dist (float): Response distance from boundary in spatial units. Defaults to 10. magnitude (float): Maximum magnitude of cell responses. normalize (bool): Whether to normalize cell responses. center_border_ratio (float): Ratio of center to border cells (0-1). Defaults to 0.5.

Variables:

sens_type (str) – Sensory type identifier ‘boundary_cell’.

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing sensory specifications including

number of cells and response field dimensions.

Return type:

dict

sens_type = 'boundary_cell'

class DiffusionCell(arena, n_cells, sensory_key, sigma=8, magnitude=None, normalize=False, seed=None, device='cpu', **kwargs)

Bases: SMBase

Smooth random fields in 2D or 3D without averaging through wall cells.

This preserves grid_and_place’s box-kernel diffusion and normalization. It is a separate sensory type because it differs from Gaussian smoothing.

diffusion_smooth(cells, free_mask=None)

sens_type = 'diffusion_cell'

class GridCell(arena, **kwargs)

Bases: SMBase

Grid cell responses for a spatially modulated grid-like field.

get_specs()

Retrieve statistics of the cell responses.

classmethod load_from_dict(state_dict, arena)

Load the GridCell object from a dictionary and reconstruct it.

Parameters:

• state_dict (dict) – Dictionary containing the object’s state.

• arena (Arena) – Arena object to reinitialize the class.

Returns:

Reconstructed GridCell object.

Return type:

GridCell

sens_type = 'grid_cell'

state_dict()

Get the essential attributes of the GridCell object.

Returns:

Dictionary of the essential attributes.

Return type:

dict

class PlaceCell(arena, **kwargs)

Bases: SMBase

Place cell sensory responses.

Place cells are neurons that fire when an animal is in specific locations in an environment. Each place cell has a “place field” - a region where it fires maximally. The firing rate typically follows a Gaussian distribution centered on the place field, decreasing with distance from the center.

Place cells are a key component of the brain’s spatial navigation system, discovered by O’Keefe and Dostrovsky in 1971. They are primarily found in the hippocampus and are thought to form a cognitive map of the environment.

This implementation models place cells with Gaussian or difference-of-Gaussian tuning curves. The difference-of-Gaussian option creates more realistic place fields with inhibitory surrounds.

Parameters:

• arena (Arena) – Arena environment object defining the navigation space.

• **kwargs –

  Additional keyword arguments including: n_cells (int): Number of place cells to create. sigma (float or list): Width of place fields in spatial units. If float, all cells

  use same sigma. If list, each cell gets its own sigma. Defaults to 8.

  ssigma (float): Standard deviation of random variation in place field sizes.

  Only used when sigma is float. Defaults to 0.

  dg_ratio (float): Ratio between center and surround Gaussian for

  difference-of-Gaussian fields. Values > 1 create inhibitory surrounds. Defaults to 1 (simple Gaussian).

  magnitude (float): Scaling factor for response amplitudes. Defaults to None. normalize (bool): Whether to normalize responses to [0,1]. Defaults to False.

Variables:

• sens_type (str) – Sensory type identifier ‘place_cell’.

• response_map (np.ndarray) – Spatial response map of shape (n_cells, *arena_dimensions). Contains the firing rate map for each cell across the entire arena.

get_specs()

Get statistical specifications of the place cell population.

Returns:

Dictionary containing population statistics including:

• cell_max_avg: Average maximum firing rate across cells

• cell_min_avg: Average minimum firing rate across cells

• cell_mean_avg: Average mean firing rate across cells

Return type:

dict

sens_type = 'place_cell'

class WeakSMCell(arena, **kwargs)

Bases: SMBase

Weakly spatially modulated cells with Gaussian responses.

These cells have broader, weaker spatial tuning compared to place cells, representing cells that are spatially modulated but not strongly place-specific. Each cell has a Gaussian-shaped firing field at a random location.

Parameters:

• arena (Arena) – Arena environment object.

• **kwargs – Additional keyword arguments including: n_cells (int): Number of weakly spatially modulated cells. sigma (float): Sigma of the Gaussian filter in spatial units. magnitude (float): Maximum magnitude of cell responses.

Variables:

• sens_type (str) – Sensory type identifier ‘weak_sm_cell’.

• response_map (np.ndarray) – Spatial response map of shape (n_cells, *arena_dimensions).

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing sensory specifications including

number of cells and response field dimensions.

Return type:

dict

sens_type = 'weak_sm_cell'