allensdk.brain_observatory.behavior.trials_processing module¶
-
allensdk.brain_observatory.behavior.trials_processing.calculate_response_latency_list(trials: pandas.core.frame.DataFrame, response_window_start: float) → List[source]¶ per trial, detemines a response latency
Parameters: - trials: pd.DataFrame
contains columns “lick_times” and “change_times”
- response_window_start: float
[seconds] relative to the non-display-lag-compensated presentation of the change-image
Returns: - response_latency_list: list
len() = trials.shape[0] value is ‘inf’ if there are no valid licks in the trial
-
allensdk.brain_observatory.behavior.trials_processing.calculate_reward_rate(response_latency=None, starttime=None, window=0.75, trial_window=25, initial_trials=10)[source]¶
-
allensdk.brain_observatory.behavior.trials_processing.calculate_reward_rate_fix_nans(trials: pandas.core.frame.DataFrame, response_window_start: float) → numpy.ndarray[source]¶ per trial, detemines the reward rate, replacing infs with nans
Parameters: - trials: pd.DataFrame
contains columns “lick_times”, “change_times”, and “start_time”
- response_window_start: float
[seconds] relative to the non-display-lag-compensated presentation of the change-image
Returns: - reward_rate: np.ndarray
size = trials.shape[0] value is nan if calculate_reward_rate evaluates to ‘inf’
-
allensdk.brain_observatory.behavior.trials_processing.construct_rolling_performance_df(trials: pandas.core.frame.DataFrame, response_window_start, session_type) → pandas.core.frame.DataFrame[source]¶ Return a DataFrame containing trial by trial behavior response performance metrics.
Parameters: - trials: pd.DataFrame
contains columns “lick_times”, “change_times”, and “start_time”
- response_window_start: float
[seconds] relative to the non-display-lag-compensated presentation of the change-image
- session_type: str
used to check if this was a passive session
Returns: - pd.DataFrame
- A pandas DataFrame containing:
- trials_id [index]:
Index of the trial. All trials, including aborted trials, are assigned an index starting at 0 for the first trial.
- reward_rate:
Rewards earned in the previous 25 trials, normalized by the elapsed time of the same 25 trials. Units are rewards/minute.
- hit_rate_raw:
Fraction of go trials where the mouse licked in the response window, calculated over the previous 100 non-aborted trials. Without trial count correction applied.
- hit_rate:
Fraction of go trials where the mouse licked in the response window, calculated over the previous 100 non-aborted trials. With trial count correction applied.
- false_alarm_rate_raw:
Fraction of catch trials where the mouse licked in the response window, calculated over the previous 100 non-aborted trials. Without trial count correction applied.
- false_alarm_rate:
Fraction of catch trials where the mouse licked in the response window, calculated over the previous 100 non-aborted trials. Without trial count correction applied.
- rolling_dprime:
d prime calculated using the rolling hit_rate and rolling false_alarm _rate.
-
allensdk.brain_observatory.behavior.trials_processing.create_extended_trials(trials=None, metadata=None, time=None, licks=None)[source]¶
-
allensdk.brain_observatory.behavior.trials_processing.find_licks(reward_times, licks, window=3.5)[source]¶
-
allensdk.brain_observatory.behavior.trials_processing.get_change_time_frame_response_latency(trial)[source]¶
-
allensdk.brain_observatory.behavior.trials_processing.get_even_sampling(data)[source]¶ Get status of even_sampling
Parameters: - data: Mapping
foraging2 experiment output data
Returns: - bool:
True if even_sampling is enabled
-
allensdk.brain_observatory.behavior.trials_processing.get_image_info_from_trial(trial_log, ti)[source]¶
-
allensdk.brain_observatory.behavior.trials_processing.get_ori_info_from_trial(trial_log, ti)[source]¶
-
allensdk.brain_observatory.behavior.trials_processing.get_response_latency(change_event, trial)[source]¶
-
allensdk.brain_observatory.behavior.trials_processing.get_stimulus_attr_changes(stim_dict, change_frame, first_frame, last_frame)[source]¶ Notes
- assumes only two stimuli are ever shown
- converts attr_names to lowercase
- gets the net attr changes from the start of a trial to the end of a trial
-
allensdk.brain_observatory.behavior.trials_processing.get_trial_bounds(trial_log: List) → List[source]¶ Adjust trial boundaries from a trial_log so that there is no dead time between trials.
Parameters: - trial_log: list
The trial_log read in from the well known behavior stimulus pickle file
Returns: - list
Each element in the list is a tuple of the form (start_frame, end_frame) so that the ith element of the list gives the start and end frames of the ith trial. The endframe of the last trial will be -1, indicating that it should map to the last timestamp in the session
-
allensdk.brain_observatory.behavior.trials_processing.get_trial_image_names(trial, stimuli) → Dict[str, str][source]¶ Gets the name of the stimulus presented at the beginning of the trial and what is it changed to at the end of the trial. Parameters ———- trial: A trial in a behavior ophys session stimuli: The stimuli presentation log for the behavior session
Returns: - A dictionary indicating the starting_stimulus and what the stimulus is
changed to.
-
allensdk.brain_observatory.behavior.trials_processing.get_trial_reward_time(rebased_reward_times, start_time, stop_time)[source]¶ extract reward times in time range
-
allensdk.brain_observatory.behavior.trials_processing.get_trial_timing(event_dict: dict, licks: List[float], go: bool, catch: bool, auto_rewarded: bool, hit: bool, false_alarm: bool, aborted: bool, timestamps: numpy.ndarray, monitor_delay: float)[source]¶ Extract a dictionary of trial timing data. See trial_data_from_log for a description of the trial types.
Parameters: - event_dict: dict
Dictionary of trial events in the well-known pkl file
- licks: List[float]
list of lick timestamps, from the get_licks response for the BehaviorOphysExperiment.api.
- go: bool
True if “go” trial, False otherwise. Mutually exclusive with catch.
- catch: bool
True if “catch” trial, False otherwise. Mutually exclusive with go.
- auto_rewarded: bool
True if “auto_rewarded” trial, False otherwise.
- hit: bool
True if “hit” trial, False otherwise
- false_alarm: bool
True if “false_alarm” trial, False otherwise
- aborted: bool
True if “aborted” trial, False otherwise
- timestamps: np.ndarray[1d]
Array of ground truth timestamps for the session (sync times, if available)
- monitor_delay: float
The monitor delay in seconds associated with the session
Returns: - dict
- start_time: float
The time the trial started (in seconds elapsed from recording start)
- stop_time: float
The time the trial ended (in seconds elapsed from recording start)
- trial_length: float
Duration of the trial in seconds
- response_time: float
The response time, for non-aborted trials. This is equal to the first lick in the trial. For aborted trials or trials without licks, response_time is NaN.
- change_frame: int
The frame number that the stimulus changed
- change_time: float
The time in seconds that the stimulus changed
- response_latency: float or None
The time in seconds between the stimulus change and the animal’s lick response, if the trial is a “go”, “catch”, or “auto_rewarded” type. If the animal did not respond, return float(“inf”). In all other cases, return None.
Notes
The following parameters are mutually exclusive (exactly one can be true):
hit, miss, false_alarm, aborted, auto_rewarded
-
allensdk.brain_observatory.behavior.trials_processing.get_trials_from_data_transform(input_transform) → pandas.core.frame.DataFrame[source]¶ Create and return a pandas DataFrame containing data about the trials associated with this session
Parameters: - input_transform:
An instantiation of a class that inherits from either BehaviorDataTransform or BehaviorOphysDataTransform. This object will be used to get at the data needed by this method to create the trials dataframe.
Returns: - pd.DataFrame
A dataframe containing data pertaining to the trials that make up this session
Notes
The input_transform object must have the following methods:
- input_transform._behavior_stimulus_file
- Which returns the dict resulting from reading in this session’s stimulus_data pickle file
- input_transform.get_rewards
- Which returns a dataframe containing data about rewards given during this session, i.e. the output of allensdk/brain_observatory/behavior/rewards_processing.get_rewards
- input_transform.get_licks
- Which returns a dataframe containing the columns time and frame denoting the time (in seconds) and frame number at which licks occurred during this session
- input_transform.get_stimulus_timestamps
- Which returns a numpy.ndarray of timestamps (in seconds) associated with the frames presented in this session.
- input_transform.get_monitor_delay
- Which returns the monitory delay (in seconds) associated with the experimental rig
-
allensdk.brain_observatory.behavior.trials_processing.local_time(iso_timestamp, timezone=None)[source]¶
-
allensdk.brain_observatory.behavior.trials_processing.resolve_initial_image(stimuli, start_frame)[source]¶ Attempts to resolve the initial image for a given start_frame for a trial
Parameters: - stimuli: Mapping
foraging2 shape stimuli mapping
- start_frame: int
start frame of the trial
Returns: - initial_image_category_name: str
stimulus category of initial image
- initial_image_group: str
group name of the initial image
- initial_image_name: str
name of the initial image
-
allensdk.brain_observatory.behavior.trials_processing.trial_data_from_log(trial)[source]¶ Infer trial logic from trial log. Returns a dictionary.
- reward volume: volume of water delivered on the trial, in mL
Each of the following values is boolean:
Trial category values are mutually exclusive * go: trial was a go trial (trial with a stimulus change) * catch: trial was a catch trial (trial with a sham stimulus change)
stimulus_change/sham_change are mutually exclusive * stimulus_change: did the stimulus change (True on ‘go’ trials) * sham_change: stimulus did not change, but response was evaluated
(True on ‘catch’ trials)Each trial can be one (and only one) of the following: * hit (stimulus changed, animal responded in response window) * miss (stimulus changed, animal did not respond in response window) * false_alarm (stimulus did not change,
animal responded in response window)- correct_reject (stimulus did not change,
- animal did not respond in response window)
- aborted (animal responded before change time)
- auto_rewarded (reward was automatically delivered following the change.
- This will bias the animals choice and should not be categorized as hit/miss)