Tasks

Base Task Object

Classes:

Task(N_in, N_out, dt, tau, T, N_batch)

The base task class.

class psychrnn.tasks.task.Task(N_in, N_out, dt, tau, T, N_batch)[source]

Bases: ABC

The base task class.

The base task class provides the structure that users can use to define a new task. This structure is used by example tasks PerceptualDiscrimination, MatchToCategory, and DelayedDiscrimination.

Note

The base task class is not itself a functioning task. The generate_trial_params and trial_function must be defined to define a new, functioning, task.

Parameters

N_in (int) – The number of network inputs.
N_out (int) – The number of network outputs.
dt (float) – The simulation timestep.
tau (float) – The intrinsic time constant of neural state decay.
T (float) – The trial length.
N_batch (int) – The number of trials per training update.

Inferred Parameters:

alpha (float) – The number of unit time constants per simulation timestep.
N_steps (int): The number of simulation timesteps in a trial.

Methods:

`accuracy_function`(correct_output, ...)	Function to calculate accuracy (not loss) as it would be measured experimentally.
`batch_generator`()	Returns a generator for this task.
`generate_trial`(params)	Loop to generate a single trial.
`generate_trial_params`(batch, trial)	Define parameters for each trial.
`get_task_params`()	Get dictionary of task parameters.
`get_trial_batch`()	Get a batch of trials.
`trial_function`(time, params)	Compute the trial properties at `time`.

accuracy_function(correct_output, test_output, output_mask)[source]

Function to calculate accuracy (not loss) as it would be measured experimentally.

Output should range from 0 to 1. This function is used by Curriculum as part of it’s default_metric().

Parameters

correct_output (ndarray(dtype=float, shape =(N_batch, N_steps, N_out ))) – Correct batch output. y_data as returned by batch_generator().
test_output (ndarray(dtype=float, shape =(N_batch, N_steps, N_out ))) – Output to compute the accuracy of. output as returned by psychrnn.backend.rnn.RNN.test().
output_mask (ndarray(dtype=bool, shape =(N_batch, N_steps, N_out))) – Mask. mask as returned by func:batch_generator.

Returns

0 <= accuracy <=1

Return type

float

Warning

This function is abstract and may optionally be implemented in a child Task object.

Example

See PerceptualDiscrimination, MatchToCategory, and DelayedDiscrimination for example implementations.

batch_generator()[source]

Returns a generator for this task.

Return type

Generator[tuple, None, None]

Yields

tuple –

stimulus (ndarray(dtype=float, shape =(N_batch, N_steps, N_out ))): Task stimuli for N_batch trials.
target_output (ndarray(dtype=float, shape =(N_batch, N_steps, N_out ))): Target output for the network on N_batch trials given the stimulus.
output_mask (ndarray(dtype=bool, shape =(N_batch, N_steps, N_out ))): Output mask for N_batch trials. True when the network should aim to match the target output, False when the target output can be ignored.
trial_params (ndarray(dtype=dict, shape =(N_batch ,))): Array of dictionaries containing the trial parameters produced by generate_trial_params() for each trial in N_batch.

generate_trial(params)[source]

Loop to generate a single trial.

Parameters

params (dict) – Dictionary of trial parameters generated by generate_trial_params().

Returns

x_trial (ndarray(dtype=float, shape=(N_steps, N_in ))) – Trial input given params.
y_trial (ndarray(dtype=float, shape=(N_steps, N_out ))) – Correct trial output given params.
mask_trial (ndarray(dtype=bool, shape=(N_steps, N_out ))) – True during steps where the network should train to match y, False where the network should ignore y during training.

Return type

tuple

abstract generate_trial_params(batch, trial)[source]

Define parameters for each trial.

Using a combination of randomness, presets, and task attributes, define the necessary trial parameters.

Parameters

batch (int) – The batch number for this trial.
trial (int) – The trial number of the trial within the batch data:batch.

Returns

Dictionary of trial parameters.

Return type

dict

Warning

This function is abstract and must be implemented in a child Task object.

Example

See PerceptualDiscrimination, MatchToCategory, and DelayedDiscrimination for example implementations.

get_task_params()[source]

Get dictionary of task parameters.

Note

N_in, N_out, N_batch, dt, tau and N_steps must all be passed to the network model as parameters – this function is the recommended way to begin building the network_params that will be passed into the RNN model.

Returns

Dictionary of Task attributes including the following keys:

Dictionary Keys

N_batch (int) – The number of trials per training update.
N_in (int) – The number of network inputs.
N_out (int) – The number of network outputs.
dt (float) – The simulation timestep.
tau (float) – The unit time constant.
T (float) – The trial length.
alpha (float) – The number of unit time constants per simulation timestep.
N_steps (int): The number of simulation timesteps in a trial.

Note

The dictionary will also include any other attributes defined in your task definition.

Return type

dict

get_trial_batch()[source]

Get a batch of trials.

Wrapper for next(self._batch_generator).

Returns

stimulus (ndarray(dtype=float, shape =(N_batch, N_steps, N_in ))): Task stimuli for N_batch trials.
target_output (ndarray(dtype=float, shape =(N_batch, N_steps, N_out ))): Target output for the network on N_batch trials given the stimulus.
output_mask (ndarray(dtype=bool, shape =(N_batch, N_steps, N_out ))): Output mask for N_batch trials. True when the network should aim to match the target output, False when the target output can be ignored.
trial_params (ndarray(dtype=dict, shape =(N_batch ,))): Array of dictionaries containing the trial parameters produced by generate_trial_params() for each trial in N_batch.

Return type

tuple

abstract trial_function(time, params)[source]

Compute the trial properties at time.

Based on the :data:’params’ compute the trial stimulus (x_t), correct output (y_t), and mask (mask_t) at time.

Parameters

time (int) – The time within the trial (0 <= time < T).
params (dict) – The trial params produced by generate_trial_params()

Returns

x_t (ndarray(dtype=float, shape=(N_in ,))) – Trial input at time given params.
y_t (ndarray(dtype=float, shape=(N_out ,))) – Correct trial output at time given params.
mask_t (ndarray(dtype=bool, shape=(N_out ,))) – True if the network should train to match the y_t, False if the network should ignore y_t when training.

Return type

tuple

Warning

This function is abstract and must be implemented in a child Task object.

Example

See PerceptualDiscrimination, MatchToCategory, and DelayedDiscrimination for example implementations.

Implemented Example Tasks

Delayed Discrimination Task

Classes:

DelayedDiscrimination(dt, tau, T, N_batch[, ...])

Delayed discrimination task.

class psychrnn.tasks.delayed_discrim.DelayedDiscrimination(dt, tau, T, N_batch, onset_time=None, stim_duration_1=None, delay_duration=None, stim_duration_2=None, decision_duration=None)[source]

Bases: Task

Delayed discrimination task.

Following a fore period, the network receives an input, followed by a delay. After the delay the network receives a second input. The second input channel receives noisy input that is inversely ordered compared to the input received by the first input channel. The network must respond by activating the output node that corresponds to the input channel with the greater input as the first stimulus.

Takes two channels of noisy input (N_in = 2). Two channel output (N_out = 2) with a one hot encoding (high value is 1, low value is .2).

Loosely based on Romo, R., Brody, C. D., Hernández, A., & Lemus, L. (1999). Neuronal correlates of parametric working memory in the prefrontal cortex. Nature, 399(6735), 470.

Parameters

dt (float) – The simulation timestep.
tau (float) – The intrinsic time constant of neural state decay.
T (float) – The trial length.
N_batch (int) – The number of trials per training update.
onset_time (float, optional) – Stimulus onset time in terms of trial length T.
stim_duration_1 (float, optional) – Stimulus 1 duration in terms of trial length T.
delay_duration (float, optional) – Delay duration in terms of trial length T.
stim_duration_2 (float, optional) – Stimulus 2 duration in terms of trial length T.
decision_duration (float, optional) – Decision duration in terms of trial length T.

Methods:

`accuracy_function`(correct_output, ...)	Calculates the accuracy of `test_output`.
`generate_trial_params`(batch, trial)	Define parameters for each trial.
`trial_function`(t, params)	Compute the trial properties at `time`.

accuracy_function(correct_output, test_output, output_mask)[source]

Calculates the accuracy of test_output.

Implements accuracy_function().

Takes the channel-wise mean of the masked output for each trial. Whichever channel has a greater mean is considered to be the network’s “choice”.

Returns: 0 <= accuracy <= 1. Accuracy is equal to the ratio of trials in which the network made the correct choice as defined above.
Return type: float

generate_trial_params(batch, trial)[source]

Define parameters for each trial.

Implements generate_trial_params().

Parameters

batch (int) – The batch number that this trial is part of.
trial (int) – The trial number of the trial within the batch batch.

Returns

Dictionary of trial parameters including the following keys:

Dictionary Keys

stimulus_1 (float) – Start time for stimulus one. onset_time.
delay (float) – Start time for the delay. onset_time + stimulus_duration_1.
stimulus_2 (float) – Start time in for stimulus one. onset_time + stimulus_duration_1 + delay_duration.
decision (float) – Start time in for decision period. onset_time + stimulus_duration_1 + delay_duration + stimulus_duration_2.
end (float) – End of decision period. onset_time + stimulus_duration_1 + delay_duration + stimulus_duration_2 + decision_duration.
stim_noise (float) – Scales the stimlus noise. Set to .1.
f1 (int) – Frequency of first stimulus.
f2 (int) – Frequency of second stimulus.
choice (str) – Indicates whether f1 is ‘>’ or ‘<’ f2.

Return type

dict

trial_function(t, params)[source]

Compute the trial properties at time.

Implements trial_function().

Based on the params compute the trial stimulus (x_t), correct output (y_t), and mask (mask_t) at time.

Parameters

time (int) – The time within the trial (0 <= time < T).
params (dict) – The trial params produced by generate_trial_params().

Returns

x_t (ndarray(dtype=float, shape=(N_in ,))) – Trial input at time given params. First channel contains f1 during the first stimulus period, and f2 during the second stimulus period, scaled to be between .4 and 1.2. Second channel contains the frequencies but reverse scaled – high frequencies correspond to low values and vice versa. Both channels have baseline noise.
y_t (ndarray(dtype=float, shape=(N_out ,))) – Correct trial output at time given params. The correct output is encoded using one-hot encoding during the decision period.
mask_t (ndarray(dtype=bool, shape=(N_out ,))) – True if the network should train to match the y_t, False if the network should ignore y_t when training. The mask is True for during the decision period and False otherwise.

Return type

tuple

Match to Category Task

Classes:

MatchToCategory(dt, tau, T, N_batch[, N_in, ...])

Multidirectional decision-making task.

class psychrnn.tasks.match_to_category.MatchToCategory(dt, tau, T, N_batch, N_in=16, N_out=2)[source]

Bases: Task

Multidirectional decision-making task.

On each trial the network receives input from units representing different locations on a ring. Each input unit magnitude represents closeness to the angle of input. The network must determine which side of arbitrary category boundaries the input belongs to and respond accordingly.

Takes N_in channels of noisy input arranged in a ring with gaussian signal around the ring centered at 0 at the stimulus angle. N_out channel output arranged as slices of a ring with a one hot encoding towards the correct category output based on the angular location of the gaussian input bump.

Loosely based on Freedman, David J., and John A. Assad. “Experience-dependent representation of visual categories in parietal cortex.” Nature 443.7107 (2006): 85-88.

Parameters

dt (float) – The simulation timestep.
tau (float) – The intrinsic time constant of neural state decay.
T (float) – The trial length.
N_batch (int) – The number of trials per training update.
N_in (int, optional) – The number of network inputs. Defaults to 16.
N_out (int, optional) – The number of network outputs. Defaults to 2.

Methods:

`accuracy_function`(correct_output, ...)	Calculates the accuracy of `test_output`.
`generate_trial_params`(batch, trial)	Define parameters for each trial.
`trial_function`(t, params)	Compute the trial properties at `time`.

accuracy_function(correct_output, test_output, output_mask)[source]

Calculates the accuracy of test_output.

Implements accuracy_function().

Takes the channel-wise mean of the masked output for each trial. Whichever channel has a greater mean is considered to be the network’s “choice”.

Returns: 0 <= accuracy <= 1. Accuracy is equal to the ratio of trials in which the network made the correct choice as defined above.
Return type: float

generate_trial_params(batch, trial)[source]

Define parameters for each trial.

Implements generate_trial_params().

Parameters

batch (int) – The batch number that this trial is part of.
trial (int) – The trial number of the trial within the batch batch.

Returns

Dictionary of trial parameters including the following keys:

Dictionary Keys

angle (float) – Angle at which to center the gaussian. Randomly selected.
category (int) – Index of the N_out category channel that contains the angle.
onset_time (float) – Stimulus onset time. Set to 200.
input_dur (float) – Stimulus duration. Set to 1000.
output_dur (float) – Output duration. The time given to make a choice. Set to 800.
stim_noise (float) – Scales the stimlus noise. Set to .1.

Return type

dict

trial_function(t, params)[source]

Compute the trial properties at time.

Implements trial_function().

Based on the params compute the trial stimulus (x_t), correct output (y_t), and mask (mask_t) at time.

Parameters

time (int) – The time within the trial (0 <= time < T).
params (dict) – The trial params produced by generate_trial_params().

Returns

x_t (ndarray(dtype=float, shape=(N_in ,))) – Trial input at time given params. For params['onset_time'] < time < params['onset_time'] + params['input_dur'] , gaussian pdf with mean = angle and scale = 1 is added to each input channel based on the channel’s angle.
y_t (ndarray(dtype=float, shape=(N_out ,))) – Correct trial output at time given params. 1 in the params['category'] output channel during the output period defined by params['output_dur'], 0 otherwise.
mask_t (ndarray(dtype=bool, shape=(N_out ,))) – True if the network should train to match the y_t, False if the network should ignore y_t when training. True during the output period, False otherwise.

Return type

tuple

Perceptual Discrimination Task

Classes:

PerceptualDiscrimination(dt, tau, T, N_batch)

Two alternative forced choice (2AFC) binary discrimination task.

class psychrnn.tasks.perceptual_discrimination.PerceptualDiscrimination(dt, tau, T, N_batch, coherence=None, direction=None)[source]

Bases: Task

Two alternative forced choice (2AFC) binary discrimination task.

On each trial the network receives two simultaneous noisy inputs into each of two input channels. The network must determine which channel has the higher mean input and respond by driving the corresponding output unit to 1.

Takes two channels of noisy input (N_in = 2). Two channel output (N_out = 2) with a one hot encoding (high value is 1, low value is .2) towards the higher mean channel.

Loosely based on Britten, Kenneth H., et al. “The analysis of visual motion: a comparison of neuronal and psychophysical performance.” Journal of Neuroscience 12.12 (1992): 4745-4765

Parameters

dt (float) – The simulation timestep.
tau (float) – The intrinsic time constant of neural state decay.
T (float) – The trial length.
N_batch (int) – The number of trials per training update.
coherence (float, optional) – Amount by which the means of the two channels will differ. By default None.
direction (int, optional) – Either 0 or 1, indicates which input channel will have higher mean input. By default None.

Methods:

`accuracy_function`(correct_output, ...)	Calculates the accuracy of `test_output`.
`generate_trial_params`(batch, trial)	Define parameters for each trial.
`trial_function`(t, params)	Compute the trial properties at `time`.

accuracy_function(correct_output, test_output, output_mask)[source]

Calculates the accuracy of test_output.

Implements accuracy_function().

Takes the channel-wise mean of the masked output for each trial. Whichever channel has a greater mean is considered to be the network’s “choice”.

Returns: 0 <= accuracy <= 1. Accuracy is equal to the ratio of trials in which the network made the correct choice as defined above.
Return type: float

generate_trial_params(batch, trial)[source]

Define parameters for each trial.

Implements generate_trial_params().

Parameters

batch (int) – The batch number that this trial is part of.
trial (int) – The trial number of the trial within the batch batch.

Returns

Dictionary of trial parameters including the following keys:

Dictionary Keys

coherence (float) – Amount by which the means of the two channels will differ. self.coherence if not None, otherwise np.random.exponential(scale=1/5).
direction (int) – Either 0 or 1, indicates which input channel will have higher mean input. self.direction if not None, otherwise np.random.choice([0, 1]).
stim_noise (float) – Scales the stimlus noise. Set to .1.
onset_time (float) – Stimulus onset time. np.random.random() * self.T / 2.0.
stim_duration (float) – Stimulus duration. np.random.random() * self.T / 4.0 + self.T / 8.0.

Return type

dict

trial_function(t, params)[source]

Compute the trial properties at time.

Implements trial_function().

Based on the params compute the trial stimulus (x_t), correct output (y_t), and mask (mask_t) at time.

Parameters

time (int) – The time within the trial (0 <= time < T).
params (dict) – The trial params produced by generate_trial_params().

Returns

x_t (ndarray(dtype=float, shape=(N_in ,))) – Trial input at time given params. For params['onset_time'] < time < params['onset_time'] + params['stim_duration'] , 1 is added to the noise in both channels, and params['coherence'] is also added in the channel corresponding to params[dir].
y_t (ndarray(dtype=float, shape=(N_out ,))) – Correct trial output at time given params. From time > params['onset_time'] + params[stim_duration] + 20 onwards, the correct output is encoded using one-hot encoding. Until then, y_t is 0 in both channels.
mask_t (ndarray(dtype=bool, shape=(N_out ,))) – True if the network should train to match the y_t, False if the network should ignore y_t when training. The mask is True for time > params['onset_time'] + params['stim_duration'] and False otherwise.

Return type

tuple