allensdk.brain_observatory.behavior.stimulus_processing module

allensdk.brain_observatory.behavior.stimulus_processing.add_active_flag(stim_pres_table: DataFrame, trials: DataFrame) → DataFrame

Mark the active stimuli by lining up the stimulus times with the trials times.

Parameters:

stim_pres_tablepandas.DataFrame

Stimulus table to add active column to.

trialspandas.DataFrame

Trials table to align with the stimulus table.

Returns:

stimulus_tablepandas.DataFrame

Copy of stim_pres_table with added acive column.

allensdk.brain_observatory.behavior.stimulus_processing.compute_is_sham_change(stim_df: DataFrame, trials: DataFrame) → DataFrame

Add is_sham_change to stimulus presentation table.

Parameters:

stim_dfpandas.DataFrame

Stimulus presentations table to add is_sham_change to.

trialspandas.DataFrame

Trials data frame to pull info from to create

Returns:

stimulus_presentationspandas.DataFrame

Input stim_df DataFrame with the is_sham_change column added.

allensdk.brain_observatory.behavior.stimulus_processing.compute_trials_id_for_stimulus(stim_pres_table: DataFrame, trials_table: DataFrame) → Series

Add an id to allow for merging of the stimulus presentations table with the trials table.

If stimulus_block is not available as a column in the input table, return an empty set of trials_ids.

Parameters:

stim_pres_tablepandas.DataFrame

Pandas stimulus table to create trials_id from.

trials_tablepandas.DataFrame

Trials table to create id from using trial start times.

Returns:

trials_idspd.Series

Unique id to allow merging of the stim table with the trials table. Null values are represented by -1.

allensdk.brain_observatory.behavior.stimulus_processing.fix_omitted_end_frame(stim_pres_table: DataFrame) → DataFrame

Fill NaN end_frame values for omitted frames.

Additionally, change type of end_frame to int.

Parameters:

stim_pres_tablepandas.DataFrame

Input stimulus table to fix/fill omitted end_frame values.

Returns:

outputpandas.DataFrame

Copy of input DataFrame with filled omitted, end_frame values and fixed typing.

allensdk.brain_observatory.behavior.stimulus_processing.get_flashes_since_change(stimulus_presentations: DataFrame) → Series

Calculate the number of times an images is flashed between changes.

Parameters:

stimulus_presentationspandas.DataFrame

Table of presented stimuli with is_change column already calculated.

Returns:

flashes_since_changepandas.Series

Number of times the same image is flashed between image changes.

allensdk.brain_observatory.behavior.stimulus_processing.get_gratings_metadata(stimuli: Dict, start_idx: int = 0) → DataFrame

This function returns the metadata for each unique grating that was presented during the experiment. If no gratings were displayed during this experiment it returns an empty dataframe with the expected columns. Parameters ———- stimuli:

The stimuli field (pkl[‘items’][‘behavior’][‘stimuli’]) loaded from the experiment pkl file.

start_idx:

The index to start index column

Returns:

pd.DataFrame:

DataFrame containing the unique stimuli presented during an experiment. The columns contained in this DataFrame are ‘image_category’, ‘image_name’, ‘image_set’, ‘phase’, ‘spatial_frequency’, ‘orientation’, and ‘image_index’. This returns empty if no gratings were presented.

allensdk.brain_observatory.behavior.stimulus_processing.get_image_names(behavior_stimulus_file: BehaviorStimulusFile) → Set[str]

Gets set of image names shown during behavior session

allensdk.brain_observatory.behavior.stimulus_processing.get_images_dict(pkl) → Dict

Gets the dictionary of images that were presented during an experiment along with image set metadata and the image specific metadata. This function uses the path to the image pkl file to read the images and their metadata from the pkl file and return this dictionary. Parameters ———- pkl: The pkl file containing the data for the stimuli presented during

experiment

Returns:

Dict:

A dictionary containing keys images, metadata, and image_attributes. These correspond to paths to image arrays presented, metadata on the whole set of images, and metadata on specific images, respectively.

allensdk.brain_observatory.behavior.stimulus_processing.get_stimulus_metadata(pkl) → DataFrame

Gets the stimulus metadata for each type of stimulus presented during the experiment. The metadata is return for gratings, images, and omitted stimuli. Parameters ———- pkl: the pkl file containing the information about what stimuli were

presented during the experiment

Returns:

pd.DataFrame:

The dataframe containing a row for every stimulus that was presented during the experiment. The row contains the following data, image_category, image_name, image_set, phase, spatial_frequency, orientation, and image index.

allensdk.brain_observatory.behavior.stimulus_processing.get_stimulus_presentations(data, stimulus_timestamps) → DataFrame

This function retrieves the stimulus presentation dataframe and renames the columns, adds a stop_time column, and set’s index to stimulus_presentation_id before sorting and returning the dataframe. :param data: stimulus file associated with experiment id :param stimulus_timestamps: timestamps indicating when stimuli switched

during experiment

Returns:

stimulus_table: dataframe containing the stimuli metadata as well as what stimuli was presented

allensdk.brain_observatory.behavior.stimulus_processing.get_stimulus_templates(pkl: dict, grating_images_dict: dict | None = None, limit_to_images: List | None = None) → StimulusTemplate | None

Gets images presented during experiments from the behavior stimulus file (*.pkl)

Parameters:

pkldict

Loaded pkl dict containing data for the presented stimuli.

grating_images_dictOptional[dict]

Because behavior pkl files do not contain image versions of grating stimuli, they must be obtained from an external source. The grating_images_dict is a nested dictionary where top level keys correspond to grating image names (e.g. ‘gratings_0.0’, ‘gratings_270.0’) as they would appear in table returned by get_gratings_metadata(). Sub-nested dicts are expected to have ‘warped’ and ‘unwarped’ keys where values are numpy image arrays of aforementioned warped or unwarped grating stimuli.

limit_to_images: Optional[list]

Only return images given by these image names

Returns:

StimulusTemplate:

StimulusTemplate object containing images that were presented during the experiment

allensdk.brain_observatory.behavior.stimulus_processing.get_visual_stimuli_df(data, time) → DataFrame

This function loads the stimuli and the omitted stimuli into a dataframe. These stimuli are loaded from the input data, where the set_log and draw_log contained within are used to calculate the epochs. These epochs are used as start_frame and end_frame and converted to times by input stimulus timestamps. The omitted stimuli do not have a end_frame by design though there duration is always 250ms. :param data: the behavior data file :param time: the stimulus timestamps indicating when each stimuli is

displayed

Returns:

df: a pandas dataframe containing the stimuli and omitted stimuli that were displayed with their frame, end_frame, start_time, and duration

allensdk.brain_observatory.behavior.stimulus_processing.is_change_event(stimulus_presentations: DataFrame) → Series

Returns whether a stimulus is a change stimulus A change stimulus is defined as the first presentation of a new image_name Omitted stimuli are ignored The first stimulus in the session is ignored

:param stimulus_presentations

The stimulus presentations table

Returns:

is_change: pd.Series indicating whether a given stimulus is a change stimulus

allensdk.brain_observatory.behavior.stimulus_processing.load_pickle(pstream)

allensdk.brain_observatory.behavior.stimulus_processing.produce_stimulus_block_names(stim_df: DataFrame, session_type: str, project_code: str) → DataFrame

Add a column stimulus_block_name to explicitly reference the kind of stimulus block in addition to the numbered blocks.

Only implemented currently for the VBO dataset. Will not add the column if it is not in the defined set of project codes.

Parameters:

stim_dfpandas.DataFrame

Input stimulus presentations DataFrame with stimulus_block column

session_typestr

Full type name of session.

project_codestr

Full name of the project this session belongs to. As this function is currently only written for VBO, if a non-VBO project name is presented, the function will result in a noop.

Returns:

modified_dfpandas.DataFrame

Stimulus presentations DataFrame with added stimulus_block_name column if the session is from a project that makes up the VBO release. The data frame is return the same as the input if not.

allensdk.brain_observatory.behavior.stimulus_processing.unpack_change_log(change)