fed3bandit API#

Summary of functions#

This is the main module for analysis of the bandit task.

Functions

load_sampledata()

Loads sample data from a bandit task that has the specification shared in Arduino example

filter_data(data_choices[, skip])

Filters the data to only show pokes "Left" or "Right" events, which are pokes that did not occur during time out, or during pellet dispensing.

binned_paction(data_choices[, window])

Bins actions from fed3 bandit file

count_pellets(data_choices)

Counts the number of pellets in fed3 data file

count_pokes(data_choices)

Counts the number of pokes in fed3 data file

pokes_per_pellet(data_choices)

Calculates pokes per pellets from fed3 bandit file

reversal_peh(data_choices, min_max[, ...])

Calculates the probability of poking in the high probability port around contingency switches from fed3 data file

win_stay(data_choices)

Calculates the win-stay probaility

lose_shift(data_choices)

Calculates the lose-shift probaility

side_prewards(data_choices)

Returns whether the relationship

side_nrewards(data_choices)

Returns whether the relationship

create_X(data_choices, metric, n_timesteps)

Creates matrix of choice (event) and the value of a specific metric during immediately previous events.

logit_regr(X_df)

Fits a statsmodels logistic regression based on the output of create_X and returns the regression oject

API Reference#

This is the main module for analysis of the bandit task.

load_sampledata()#

Loads sample data from a bandit task that has the specification shared in Arduino example

Returns:

sample_data – Sample data

Return type:

pd.DataFrame

filter_data(data_choices, skip=[])#

Filters the data to only show pokes “Left” or “Right” events, which are pokes that did not occur during time out, or during pellet dispensing.

Parameters:

data_choices (pandas.DataFrame) – The fed3 data file

Returns:

filtered_data – Filtered fed3 data file

Return type:

pd.DataFrame

binned_paction(data_choices, window=5)#

Bins actions from fed3 bandit file

Parameters:

  • data_choices (pandas.DataFrame) – The fed3 data file

  • window (int) – Sliding window by which the probability of choosing left will be calculated

Returns:

p_left – Probability of choosing left. Returns pandas.Series of length data_choices.shape[0] - window

Return type:

pandas.Series

true_probs(data_choices, offset=5, alt_left='Session_type', alt_right='Device_Number')#

Extracts true reward probabilities from Fed3bandit file

Parameters:

  • data_choices (pandas.DataFrame) – The fed3 data file

  • offset (int) – Event number in which the extraction will start

Returns:

  • left_probs (pandas.Series) – True reward probabilities of left port

  • right_probs (pandas.Series) – True reward probabilities of right port

count_pellets(data_choices)#

Counts the number of pellets in fed3 data file

Parameters:

data_choices (pandas.DataFrame) – The fed3 data file

Returns:

c_pellets – total number of pellets

Return type:

int

count_left_pokes(data_choices)#

Counts the number of left pokes in fed3 data file

Parameters:

data_choices (pandas.DataFrame) – The fed3 data file

Returns:

all_pokes – total number of left pokes

Return type:

int

count_right_pokes(data_choices)#

Counts the number of right pokes in fed3 data file

Parameters:

data_choices (pandas.DataFrame) – The fed3 data file

Returns:

all_right_pokes – total number of right pokes

Return type:

int

count_pokes(data_choices)#

Counts the number of pokes in fed3 data file

Parameters:

data_choices (pandas.DataFrame) – The fed3 data file

Returns:

all_pokes – total number of pellets

Return type:

int

count_invalid_pokes(data_choices, reason=['all'])#

Counts the number of invalid pokes.

Parameters:

  • data_choices (pandas.DataFrame) – The fed3 data file

  • reason (list of str) – List with conditions of why pokes were invalid. Options are: “timeout”, “pellet”, “dispense”, “short”. See notes for full explanation.

Returns:

count – Number of invalid pokes

Return type:

int

pokes_per_pellet(data_choices)#

Calculates pokes per pellets from fed3 bandit file

Parameters:

data_choices (pandas.DataFrame) – The fed3 data file

Returns:

ppp – pokes per pellets

Return type:

int

accuracy(data_choices, return_avg=True, alt_left='Session_type', alt_right='Device_Number')#

Calculates pokes per pellets from fed3 bandit file

Parameters:

  • data_choices (pandas.DataFrame) – The fed3 data file

  • return_avg (bool) – If True, returns the average accuracy of data_choices. If False, returns np.array of bool of

Returns:

ppp – pokes per pellets

Return type:

int

iti_after_win(data_choices)#

Calculates latency to next poke after a pellet delivery

Parameters:

data_choices (pandas.DataFrame) – The fed3 data file

Returns:

iti_win – Latency to next poke after every pellet delivery (“Pellet” event)

Return type:

pandas.Series

iti_after_loss(data_choices)#

Calculates latency to next poke after the end of a time out

Parameters:

data_choices (pandas.DataFrame) – The fed3 data file

Returns:

iti_loss – Latency to next poke after the end of a time out

Return type:

pandas.Series

reversal_peh(data_choices, min_max, return_avg=False, alt_right='Device_Number')#

Calculates the probability of poking in the high probability port around contingency switches from fed3 data file

Parameters:

  • data_choices (pandas.DataFrame) – The fed3 data file

  • min_max (tuple) – Event window around the switches to analyze. E.g. min_max = (-10,11) will use a time window of 10 events before the switch to 10 events after the switch.

  • return_avg (bool) – If True, returns only the average trace. If False, returns all the trials.

Returns:

  • c_days (int) – days in data file

  • c_pellets (int) – total number of pellets

  • c_ppd (int) – average pellets per day

win_stay(data_choices)#

Calculates the win-stay probaility

Parameters:

data_choices (pandas.DataFrame) – The fed3 data file

Returns:

win_stay_p – win-stay probability

Return type:

int

lose_shift(data_choices)#

Calculates the lose-shift probaility

Parameters:

data_choices (pandas.DataFrame) – The fed3 data file

Returns:

lose_shift_p – lose-shift probability

Return type:

int

side_prewards(data_choices)#

Returns whether the relationship

Parameters:

data_choices (pandas.DataFrame) – The fed3 data file

Returns:

  • left_reward (int) – win-stay probability

  • right_reward (int) – lose-shift probability

side_nrewards(data_choices)#

Returns whether the relationship

Parameters:

data_choices (pandas.DataFrame) – The fed3 data file

Returns:

  • left_reward (int) – win-stay probability

  • right_reward (int) – lose-shift probability

create_X(data_choices, metric, n_timesteps)#

Creates matrix of choice (event) and the value of a specific metric during immediately previous events. This arranges the format to run a logistic regression (or other GLM).

Parameters:

  • data_choices (pandas.DataFrame) – The fed3 data file

  • metric (array_like) – The metric (e.g. previous choice, previous reward, etc.) that may influence choice.

  • n_feats (int) – Number of events in past to be included

Returns:

X_df – Matrix with choice and metric for the past n_timesteps events

Return type:

pandas.DataFrame

logit_regr(X_df)#

Fits a statsmodels logistic regression based on the output of create_X and returns the regression oject

Parameters:

X_df (pd.DataFrame) – Output of create_X function

Returns:

c_regr – statsmodel logistic regression object, see https://www.statsmodels.org/dev/generated/statsmodels.discrete.discrete_model.Logit.html

Return type:

statsmodels.regression

Extending fed3bandit#

FED3Bandit is a actively being developed. We will keep adding more analysis features. If you have any request, please open an issue on GitHub and we will try to implement it in a future release.