quail.Egg

class quail.Egg(pres=None, rec=None, features=None, dist_funcs=None, meta=None, subjgroup=None, subjname='Subject', listgroup=None, listname='List', date_created=None, recmat=None, list_length=None)

Data object for the quail package

An Egg data object contains the data you need to analyze free recall experiments. This can be a single subject’s data, or a group of subjects. An Egg is comprised of a number of fields: the pres field contains the words/stimuli presented to the subject. The rec field contains the words/stimuli recalled by the subject. The feature field is optional, but may contain a dictionary of features for each stimulus. This field is necessary to run the fingerprint analyses. Related to the features is the dist_funcs dictionary (also optional). This dictionary specifies a set of distance functions required for the fingerprint analyses. Finally, the meta field is an optional dictionary that contains any details useful for identifying the egg object

Parameters:

preslist, np.ndarray, or pd.DataFrame

Presented stimuli/stimulus features. Can be provided as: - Nested list: list (subjects) of lists (lists) of lists (items) of strings or dicts - NumPy array: Same structure as nested list - Pandas DataFrame: Multi-indexed DataFrame where each cell is a dict with ‘item’ key

and optional feature keys. Index should be (subject, list) MultiIndex.

For lists/arrays, each item can be a string representing the stimulus or a dictionary with ‘item’ key for the stimulus name and additional keys for features.

reclist, np.ndarray, or pd.DataFrame

Recalled stimuli/stimulus features. Same format options as pres.

featureslist (subjects) of lists (experiment) of lists (list/block) of strings or dictionaries.

This is DEPRECATED, but left in for legacy support. This is a nested list containing the stimuli/stimulus features. The outer list groups the data into subjects, the middle list groups the data into experiments and the inner list groups the data into stimuli presented together in one block (or list). Each item within the list should be a dictionary representing stimulus features. Each dictionary should contain a text (str) label as the key and a value of the following types: string, int, float, list, array.

dist_funcsdict (optional)

A dictionary of custom distance functions for stimulus features. Each key should be the name of a feature and each value should be a string representation of an inline distance function (e.g. dist_funcs[‘feature_n’] = ‘lambda a, b: abs(a-b)’’)

metadict (optional)

Meta data about the study (i.e. version, description, date, etc.) can be saved here.

subjgrouplist of strings or ints (optional)

String/int variables indicating how to group over subjects. Must be the length of the number of subjects

subjnamestring (optional)

Name of the subject grouping variable. Default is ‘Subject’.

listgrouplist of strings or ints (optional)

String/int variables indicating how to group over list. Must be the length of the number of lists

listnamestring (optional)

Name of the list grouping variable. Default is ‘List’.

recmatlist (subjects) of lists (experiment) of lists (list/block) of ints.

An egg can be optionally created directly from recall matrices. A recall matrix specifies sequences by listing out there indices in the order they were recalled (e.g. [4, 2, 1, None, None]).

list_lengthint

The length of the presented lists. Used to create an egg from a recall matrix (optional). If list_length is not passed, the length of the presented lists is assumed to be the length of the first list passed.

Attributes:

presPandas.DataFrame

A multi-index Pandas DataFrame representing the stimuli presented. The rows of the dataframe created represent distinct presentation blocks and the columns represent stimuli presented within a block. Each cell of the dataframe is a dictionary where the ‘stimulus’ key is a text label of the stimulus and any other text keys are features of the presented stimulus. The dataframe index will be a multi-index, where the first level represents the subject number and the second level represents the list (or presentation block) number.

recPandas.DataFrame

A multi-index Pandas DataFrame representing the stimuli recalled. The rows of the dataframe created represent distinct presentation blocks and the columns represent stimuli presented within a block. Each cell of the dataframe is a dictionary where the ‘stimulus’ key is a text label of the stimulus and any other text keys are features of the presented stimulus. The dataframe index will be a multi-index, where the first level represents the subject number and the second level represents the list (or presentation block) number.

n_subjectsint

Number of subjects in the egg object

n_listsint

Number of lists per subject

list_lengthint

Number of words in the lists

date_createdtime

A timestamp when the egg was created

Methods

analyze([analysis])	Calls analyze function
crack([subjects, lists])	Wraps crack_egg function to take an egg and returns a subset of the subjects
get_pres_features([features])	Returns a df of features for presented items
get_pres_items()	Returns a df of presented items
get_rec_features([features])	Returns a df of features for recalled items
get_rec_items()	Returns a df of recalled items
info()	Print info about the data egg
save(fname[, compression])	Save method for the Egg object

to_dict
to_json

__init__(pres=None, rec=None, features=None, dist_funcs=None, meta=None, subjgroup=None, subjname='Subject', listgroup=None, listname='List', date_created=None, recmat=None, list_length=None)

Methods

__init__([pres, rec, features, dist_funcs, ...])
analyze([analysis])	Calls analyze function
crack([subjects, lists])	Wraps crack_egg function to take an egg and returns a subset of the subjects
get_pres_features([features])	Returns a df of features for presented items
get_pres_items()	Returns a df of presented items
get_rec_features([features])	Returns a df of features for recalled items
get_rec_items()	Returns a df of recalled items
info()	Print info about the data egg
save(fname[, compression])	Save method for the Egg object
to_dict()
to_json()