add utility to annotate licks

AllenInstitute / visual_behavior_analysis

Python package for analyzing behavioral data for Brain Observatory: Visual Behavior

Other

21 stars 6 forks source link

add utility to annotate licks #725

Closed dougollerenshaw closed 3 years ago

dougollerenshaw commented 3 years ago

Adds a function to utilities.py that will annotate the licks dataframe with some useful columns (partially stolen from @alexpiet's implementation in visual_behavior_glm (https://github.com/AllenInstitute/visual_behavior_glm/blob/86a816ebc4dcc8d450f83f77611c2ee7afdf7b93/visual_behavior_glm/GLM_fit_tools.py#L1022)

Optionally operates in place.

Example use:

get dataset, view default licks dataframe:

from visual_behavior.data_access import loading
dataset = loading.get_ophys_dataset(915243090)

dataset.licks.head(10)

import annotate_licks:

from visual_behavior.utilities import annotate_licks

return annotated licks df as a new variable:

annotated_licks = annotate_licks(dataset.licks).head(10)
annotated_licks

annotate licks in place:

annotate_licks(dataset.licks, inplace=True)
dataset.licks.head(10)

ALSO: fixes a bug in plotting.event_triggered_raster

alexpiet commented 3 years ago

It would be nice to finish this feature request. https://github.com/AllenInstitute/visual_behavior_analysis/issues/720

[x] Can you add a "bout_rewarded" label?
[x] Can you add a "bout_number" label so its easy to grab all the licks inside a single bout?

https://github.com/alexpiet/licking_behavior/blob/master/src/psy_metrics_tools.py#L54

dougollerenshaw commented 3 years ago

@alexpiet I added two columns to address your comment. I also had to change the input to the function from the licks dataframe to the entire session object so that the function would have access to both licks and rewards.

dougollerenshaw commented 3 years ago

@matchings this conflicts with some of the work you added in PR #726. I propose that we merge this first, then strip the redundant stuff from your PR. Some comments:

I added a boolean column called 'hit' that designates hit-licks. This aligns with the column of the same name in the df you were generating.
I don't have a column called 'lick_in_bout', like yours. But I do have 'licks_in_bout', which is the number of licks in the bout. So to get the equivalent, I think you could just filter on 'licks_in_bout > 1'
This is in visual_behavior.utilities. The function you generated is in visual_behavior.data_access.utilities. I can move my function if you think that's more appropriate location. Let me know in review.

dougollerenshaw commented 3 years ago

@alexpiet Thanks for pointing out the fields that I missed in the docstring in your slack comment. PR is updated with missing information added.