rtgym.agent.sensory.movement_modulated package

Submodules

rtgym.agent.sensory.movement_modulated.direction_cell module

class DirectionCell(arena, **kwargs)

Bases: MMBase

Direction cells with Gaussian tuning to movement direction.

These cells respond to the direction of agent movement with Gaussian tuning curves. Each cell has a preferred direction and fires maximally when the agent moves in that direction.

Parameters:

• arena (Arena) – Arena environment object.

• **kwargs – Additional keyword arguments including: n_cells (int): Number of direction cells. magnitude (float): Maximum magnitude of cell responses. normalize (bool): Whether to normalize cell responses. sorted (bool): Whether to sort cells by preferred directions. Defaults to True. n_bins (int): Number of direction bins for discretization. Defaults to 360. sigma (float): Standard deviation of the Gaussian tuning kernel. Defaults to 2. msigma (float): Standard deviation of magnitude modulation.

sens_type

Sensory type identifier ‘direction_cell’.

Type:

str

get_response(agent_state: AgentState | Trajectory)

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing sensory specifications.

Return type:

dict

sens_type = 'direction_cell'

vis(N, **kwargs)

Visualize the movement modulated cells.

Parameters:

• traj (Trajectory) – Trajectory data for visualization.

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

• *args – Additional positional arguments.

• **kwargs – Additional keyword arguments.

Returns:

Matplotlib figure and axis objects.

Return type:

tuple

rtgym.agent.sensory.movement_modulated.direction_rad module

class DirectionRad(arena, **kwargs)

Bases: DisplacementAbs

Direction cells with raw radian output.

Generates sensory responses based on the direction of agent movement, providing raw directional information in radians. Inherits from DisplacementAbs and converts displacement to directional angles.

Parameters:

• arena (Arena) – Arena environment object.

• **kwargs – Additional keyword arguments including: n_cells (int): Number of direction cells. magnitude (float): Maximum magnitude of cell responses. normalize (bool): Whether to normalize cell responses. sigma_s (float): Temporal smoothing sigma in seconds. Defaults to 0.0. ssigma_s (float): Spatial smoothing sigma in seconds. Defaults to 0.0.

sens_type

Sensory type identifier ‘direction_rad’.

Type:

str

get_responses(traj: Trajectory)

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing sensory specifications.

Return type:

dict

sens_type = 'direction_rad'

rtgym.agent.sensory.movement_modulated.displacement_abs module

class DisplacementAbs(arena, **kwargs)

Bases: MMBase

Absolute displacement signal sensory cells.

Generates sensory responses based on the absolute displacement of the agent. Displacement values may include negative values and represent spatial movement in both x and y directions.

Parameters:

• arena (Arena) – Arena environment object.

• **kwargs – Additional keyword arguments including: n_cells (int): Number of displacement cells (must be even). sigma_s (float): Temporal smoothing sigma in seconds. ssigma_s (float): Spatial smoothing sigma in seconds.

sens_type

Sensory type identifier ‘displacement_abs’.

Type:

str

get_response(agent_data: Trajectory)

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing sensory specifications.

Return type:

dict

sens_type = 'displacement_abs'

rtgym.agent.sensory.movement_modulated.head_direction_cell module

class HeadDirectionCell(arena, **kwargs)

Bases: DisplacementAbs

Head direction cells that respond to agent’s heading direction.

These cells fire when the agent is facing a specific direction, with each cell having a preferred direction. The responses are modeled using Gaussian tuning curves around the preferred directions.

Parameters:

• arena (Arena) – Arena environment object.

• **kwargs – Additional keyword arguments including: n_cells (int): Number of head direction cells. magnitude (float): Maximum magnitude of cell responses. Defaults to 1. normalize (bool): Whether to normalize cell responses. sorted (bool): Whether to sort cells by preferred directions. Defaults to True. n_bins (int): Number of direction bins for discretization. Defaults to 360. sigma (float): Standard deviation of the Gaussian tuning kernel. Defaults to 2.

sens_type

Sensory type identifier ‘head_direction_cell’.

Type:

str

get_response(agent_state: AgentState)

Get the movement modulated responses for the given trajectory.

Parameters:

agent_state – Agent state.

Returns:

Movement modulated responses of shape (n_batches, n_steps, n_cells).

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing sensory specifications.

Return type:

dict

sens_type = 'head_direction_cell'

vis(N, **kwargs)

Visualize the movement modulated cells.

Parameters:

• traj (Trajectory) – Trajectory data for visualization.

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

• *args – Additional positional arguments.

• **kwargs – Additional keyword arguments.

Returns:

Matplotlib figure and axis objects.

Return type:

tuple

rtgym.agent.sensory.movement_modulated.mm_base module

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

Bases: object

Base class for movement modulated sensory cells.

Provides common functionality for sensory modalities that respond to movement parameters such as speed, direction, and acceleration. These cells are temporally modulated based on agent movement.

Parameters:

• arena (Arena) – Arena environment object.

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

• t_res (float) – Temporal resolution in milliseconds.

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

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

• **kwargs – Additional keyword arguments including: magnitude (float): Base magnitude for cell responses. msigma (float): Standard deviation for magnitude variation.

arena

Arena environment.

Type:

Arena

t_res

Temporal resolution.

Type:

float

sensory_key

Unique sensory identifier.

Type:

str

n_cells

Number of sensory cells.

Type:

int

magnitude

Magnitude values for each cell.

Type:

np.ndarray

msigma

Magnitude standard deviation.

Type:

float

rng

Random number generator.

Type:

np.random.Generator

Raises:

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

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing sensory specifications.

Return type:

dict

print_specs()

Print specifications of this sensory modality.

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

sens_type = 'mm_base'

vis(traj, N, *args, **kwargs)

Visualize the movement modulated cells.

Parameters:

• traj (Trajectory) – Trajectory data for visualization.

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

• *args – Additional positional arguments.

• **kwargs – Additional keyword arguments.

Returns:

Matplotlib figure and axis objects.

Return type:

tuple

rtgym.agent.sensory.movement_modulated.speed_cell module

class SpeedCell(arena, **kwargs)

Bases: DisplacementAbs

Speed cells that encode movement speed.

Generates sensory responses based on the absolute speed (velocity magnitude) of agent movement. Each cell outputs a 1D value representing the agent’s speed, regardless of direction. Inherits from DisplacementAbs and converts displacement to speed.

Parameters:

• arena (Arena) – Arena environment object.

• **kwargs – Additional keyword arguments including: n_cells (int): Number of speed cells. sigma_s (float): Temporal smoothing sigma in seconds. ssigma_s (float): Spatial smoothing sigma in seconds. normalize (bool): Whether to normalize cell responses.

sens_type

Sensory type identifier ‘speed_cell’.

Type:

str

get_response(agent_data: AgentState | Trajectory | Any)

Get speed responses for given agent data.

Converts displacement to speed and duplicates across all cells. Each cell outputs the same speed value but can be modified by smoothing.

Parameters:

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

Returns:

Speed responses.

Return type:

np.ndarray

Raises:

ValueError – If agent_data type is not supported.

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing speed cell specifications.

Return type:

dict

sens_type = 'speed_cell'

vis(N=5, max_vel=1.0, n_bins=10, cmap='jet', *args, **kwargs)

Visualize speed response curves.

Plots speed vs response for the first N cells.

Parameters:

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

• max_vel (float) – Maximum speed for visualization range.

• n_bins (int) – Number of speed bins to plot.

• cmap (str) – Colormap for visualization.

• *args – Additional positional arguments.

• **kwargs – Additional keyword arguments.

Module contents

class DirectionCell(arena, **kwargs)

Bases: MMBase

Direction cells with Gaussian tuning to movement direction.

These cells respond to the direction of agent movement with Gaussian tuning curves. Each cell has a preferred direction and fires maximally when the agent moves in that direction.

Parameters:

• arena (Arena) – Arena environment object.

• **kwargs – Additional keyword arguments including: n_cells (int): Number of direction cells. magnitude (float): Maximum magnitude of cell responses. normalize (bool): Whether to normalize cell responses. sorted (bool): Whether to sort cells by preferred directions. Defaults to True. n_bins (int): Number of direction bins for discretization. Defaults to 360. sigma (float): Standard deviation of the Gaussian tuning kernel. Defaults to 2. msigma (float): Standard deviation of magnitude modulation.

sens_type

Sensory type identifier ‘direction_cell’.

Type:

str

get_response(agent_state: AgentState | Trajectory)

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing sensory specifications.

Return type:

dict

sens_type = 'direction_cell'

vis(N, **kwargs)

Visualize the movement modulated cells.

Parameters:

• traj (Trajectory) – Trajectory data for visualization.

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

• *args – Additional positional arguments.

• **kwargs – Additional keyword arguments.

Returns:

Matplotlib figure and axis objects.

Return type:

tuple

class DirectionRad(arena, **kwargs)

Bases: DisplacementAbs

Direction cells with raw radian output.

Generates sensory responses based on the direction of agent movement, providing raw directional information in radians. Inherits from DisplacementAbs and converts displacement to directional angles.

Parameters:

• arena (Arena) – Arena environment object.

• **kwargs – Additional keyword arguments including: n_cells (int): Number of direction cells. magnitude (float): Maximum magnitude of cell responses. normalize (bool): Whether to normalize cell responses. sigma_s (float): Temporal smoothing sigma in seconds. Defaults to 0.0. ssigma_s (float): Spatial smoothing sigma in seconds. Defaults to 0.0.

sens_type

Sensory type identifier ‘direction_rad’.

Type:

str

get_responses(traj: Trajectory)

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing sensory specifications.

Return type:

dict

sens_type = 'direction_rad'

class DisplacementAbs(arena, **kwargs)

Bases: MMBase

Absolute displacement signal sensory cells.

Generates sensory responses based on the absolute displacement of the agent. Displacement values may include negative values and represent spatial movement in both x and y directions.

Parameters:

• arena (Arena) – Arena environment object.

• **kwargs – Additional keyword arguments including: n_cells (int): Number of displacement cells (must be even). sigma_s (float): Temporal smoothing sigma in seconds. ssigma_s (float): Spatial smoothing sigma in seconds.

sens_type

Sensory type identifier ‘displacement_abs’.

Type:

str

get_response(agent_data: Trajectory)

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing sensory specifications.

Return type:

dict

sens_type = 'displacement_abs'

class HeadDirectionCell(arena, **kwargs)

Bases: DisplacementAbs

Head direction cells that respond to agent’s heading direction.

These cells fire when the agent is facing a specific direction, with each cell having a preferred direction. The responses are modeled using Gaussian tuning curves around the preferred directions.

Parameters:

• arena (Arena) – Arena environment object.

• **kwargs – Additional keyword arguments including: n_cells (int): Number of head direction cells. magnitude (float): Maximum magnitude of cell responses. Defaults to 1. normalize (bool): Whether to normalize cell responses. sorted (bool): Whether to sort cells by preferred directions. Defaults to True. n_bins (int): Number of direction bins for discretization. Defaults to 360. sigma (float): Standard deviation of the Gaussian tuning kernel. Defaults to 2.

sens_type

Sensory type identifier ‘head_direction_cell’.

Type:

str

get_response(agent_state: AgentState)

Get the movement modulated responses for the given trajectory.

Parameters:

agent_state – Agent state.

Returns:

Movement modulated responses of shape (n_batches, n_steps, n_cells).

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing sensory specifications.

Return type:

dict

sens_type = 'head_direction_cell'

vis(N, **kwargs)

Visualize the movement modulated cells.

Parameters:

• traj (Trajectory) – Trajectory data for visualization.

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

• *args – Additional positional arguments.

• **kwargs – Additional keyword arguments.

Returns:

Matplotlib figure and axis objects.

Return type:

tuple

class SpeedCell(arena, **kwargs)

Bases: DisplacementAbs

Speed cells that encode movement speed.

Generates sensory responses based on the absolute speed (velocity magnitude) of agent movement. Each cell outputs a 1D value representing the agent’s speed, regardless of direction. Inherits from DisplacementAbs and converts displacement to speed.

Parameters:

• arena (Arena) – Arena environment object.

• **kwargs – Additional keyword arguments including: n_cells (int): Number of speed cells. sigma_s (float): Temporal smoothing sigma in seconds. ssigma_s (float): Spatial smoothing sigma in seconds. normalize (bool): Whether to normalize cell responses.

sens_type

Sensory type identifier ‘speed_cell’.

Type:

str

get_response(agent_data: AgentState | Trajectory | Any)

Get speed responses for given agent data.

Converts displacement to speed and duplicates across all cells. Each cell outputs the same speed value but can be modified by smoothing.

Parameters:

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

Returns:

Speed responses.

Return type:

np.ndarray

Raises:

ValueError – If agent_data type is not supported.

get_specs()

Get specifications of this sensory modality.

Returns:

Dictionary containing speed cell specifications.

Return type:

dict

sens_type = 'speed_cell'

vis(N=5, max_vel=1.0, n_bins=10, cmap='jet', *args, **kwargs)

Visualize speed response curves.

Plots speed vs response for the first N cells.

Parameters:

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

• max_vel (float) – Maximum speed for visualization range.

• n_bins (int) – Number of speed bins to plot.

• cmap (str) – Colormap for visualization.

• *args – Additional positional arguments.

• **kwargs – Additional keyword arguments.