psifr.fr.merge_free_recall#

psifr.fr.merge_free_recall(data, **kwargs)#

Score free recall data by matching up study and recall events.

Parameters:

data (pandas.DataFrame) – Free recall data in Psifr format. Must have subject, list, trial_type, position, and item columns.
merge_keys (list, optional) – Columns to use to designate events to merge. Default is [‘subject’, ‘list’, ‘item’], which will merge events related to the same item, but only within list.
list_keys (list, optional) – Columns that apply to both study and recall events.
study_keys (list, optional) – Columns that only apply to study events.
recall_keys (list, optional) – Columns that only apply to recall events.
position_key (str, optional) – Column indicating the position of each item in either the study list or the recall sequence.

Returns:

merged – Merged information about study and recall events. Each row corresponds to one unique input/output pair.

The following columns will be added:

inputint: Position of each item in the input list (i.e., serial position).
outputint: Position of each item in the recall sequence.
studybool: True for rows corresponding to a unique study event.
recallbool: True for rows corresponding to a unique recall event.
repeatint: Number of times this recall event has been repeated (0 for the first recall of an item).
intrusionbool: True for recalls that do not correspond to any study event.
prior_listint: For prior-list intrusions, the list the item was presented.
prior_positionint: For prior-list intrusions, the position the item was presented.

Return type:

pandas.DataFrame

See also

merge_lists: Flexibly merge study events with recall events. Useful for recall phases that don’t match the typical free recall setup, like final free recall of all lists.

Examples

>>> import numpy as np
>>> from psifr import fr
>>> study = [['absence', 'hollow'], ['fountain', 'piano']]
>>> recall = [['absence'], ['piano', 'hollow']]
>>> raw = fr.table_from_lists([1, 1], study, recall)
>>> raw
   subject  list trial_type  position      item
0        1     1      study         1   absence
1        1     1      study         2    hollow
2        1     1     recall         1   absence
3        1     2      study         1  fountain
4        1     2      study         2     piano
5        1     2     recall         1     piano
6        1     2     recall         2    hollow

Score the data to create a table with matched study and recall events.

>>> data = fr.merge_free_recall(raw)
>>> data
   subject  list      item  input  output  study  recall  repeat  intrusion  prior_list  prior_input
0        1     1   absence    1.0     1.0   True    True       0      False         NaN          NaN
1        1     1    hollow    2.0     NaN   True   False       0      False         NaN          NaN
2        1     2  fountain    1.0     NaN   True   False       0      False         NaN          NaN
3        1     2     piano    2.0     1.0   True    True       0      False         NaN          NaN
4        1     2    hollow    NaN     2.0  False    True       0       True         1.0          2.0

You can also include non-standard columns. Information that only applies to study events (here, the encoding task used) can be indicated using the study_keys input.

>>> raw['task'] = np.array([1, 2, np.nan, 2, 1, np.nan, np.nan])
>>> fr.merge_free_recall(raw, study_keys=['task'])
   subject  list      item  input  output  study  recall  repeat  intrusion  task  prior_list  prior_input
0        1     1   absence    1.0     1.0   True    True       0      False   1.0         NaN          NaN
1        1     1    hollow    2.0     NaN   True   False       0      False   2.0         NaN          NaN
2        1     2  fountain    1.0     NaN   True   False       0      False   2.0         NaN          NaN
3        1     2     piano    2.0     1.0   True    True       0      False   1.0         NaN          NaN
4        1     2    hollow    NaN     2.0  False    True       0       True   NaN         1.0          2.0

Information that only applies to recall onsets (here, the time in seconds after the start of the recall phase that a recall attempt was made), can be indicated using the recall_keys input.

>>> raw['onset'] = np.array([np.nan, np.nan, 1.1, np.nan, np.nan, 1.4, 3.8])
>>> fr.merge_free_recall(raw, recall_keys=['onset'])
   subject  list      item  input  output  study  recall  repeat  intrusion  onset  prior_list  prior_input
0        1     1   absence    1.0     1.0   True    True       0      False    1.1         NaN          NaN
1        1     1    hollow    2.0     NaN   True   False       0      False    NaN         NaN          NaN
2        1     2  fountain    1.0     NaN   True   False       0      False    NaN         NaN          NaN
3        1     2     piano    2.0     1.0   True    True       0      False    1.4         NaN          NaN
4        1     2    hollow    NaN     2.0  False    True       0       True    3.8         1.0          2.0

Use list_keys to indicate columns that apply to both study and recall events. If list_keys do not match for a pair of study and recall events, they will not be matched in the output.

>>> raw['condition'] = np.array([1, 1, 1, 2, 2, 2, 2])
>>> fr.merge_free_recall(raw, list_keys=['condition'])
   subject  list      item  input  output  study  recall  repeat  intrusion  condition  prior_list  prior_input
0        1     1   absence    1.0     1.0   True    True       0      False          1         NaN          NaN
1        1     1    hollow    2.0     NaN   True   False       0      False          1         NaN          NaN
2        1     2  fountain    1.0     NaN   True   False       0      False          2         NaN          NaN
3        1     2     piano    2.0     1.0   True    True       0      False          2         NaN          NaN
4        1     2    hollow    NaN     2.0  False    True       0       True          2         1.0          2.0