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.

sens_type

Sensory type identifier ‘boundary_cell’.

Type:

str

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

sens_type

Sensory type identifier ‘place_cell’.

Type:

str

response_map

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

Type:

np.ndarray

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.

arena

Arena environment.

Type:

Arena

n_cells

Number of sensory cells.

Type:

int

sensory_key

Unique sensory identifier.

Type:

str

rng

Random number generator.

Type:

np.random.Generator

response_map

Spatial response map for all cells.

Type:

np.ndarray

Raises:

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

get_response(agent_data: AgentState | Trajectory)

Get sensory responses for given agent data.

Parameters:

agent_data (AgentState or Trajectory) – Agent data containing coordinates.

Returns:

Sensory responses with shape:

• For Trajectory: (n_batch, n_timesteps, n_cells)

• For AgentState: (n_batch, n_cells)

Return type:

np.ndarray

Raises:

ValueError – If agent_data type is not supported.

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'

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.

sens_type

Sensory type identifier ‘weak_sm_cell’.

Type:

str

response_map

Spatial response map of shape (n_cells, *arena_dimensions).

Type:

np.ndarray

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.

sens_type

Sensory type identifier ‘boundary_cell’.

Type:

str

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

sens_type

Sensory type identifier ‘place_cell’.

Type:

str

response_map

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

Type:

np.ndarray

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.

sens_type

Sensory type identifier ‘weak_sm_cell’.

Type:

str

response_map

Spatial response map of shape (n_cells, *arena_dimensions).

Type:

np.ndarray

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'