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)[source]¶

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:

Parameters:	pres : list (subjects) of lists (experiment) of lists (list/block) of strings or dictionaries. This is a nested list containing the presented 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 can be a string representing the stimulus or a dictionary representing the stimuli and its features. If dictionaries are passed, identify the stimulus name using the ‘item’ key and a string label. To represent additional stimulus features, use any text (str) label as the key and a value of the following types: string, int, float, list, array. rec : list (subjects) of lists (experiment) of lists (list/block) of strings or dictionaries. This is a nested list containing the recalled 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 can be a string representing the stimulus or a dictionary representing the stimuli and its features. If dictionaries are passed, identify the stimulus name using the ‘item’ key and a string label. To represent additional stimulus features, use any text (str) label as the key and a value of the following types: string, int, float, list, array. features : list (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_funcs : dict (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)’‘) meta : dict (optional) Meta data about the study (i.e. version, description, date, etc.) can be saved here. subjgroup : list of strings or ints (optional) String/int variables indicating how to group over subjects. Must be the length of the number of subjects subjname : string (optional) Name of the subject grouping variable. Default is ‘Subject’. listgroup : list of strings or ints (optional) String/int variables indicating how to group over list. Must be the length of the number of lists listname : string (optional) Name of the list grouping variable. Default is ‘List’. recmat : list (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_length : int 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:	pres : Pandas.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. rec : Pandas.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_subjects : int Number of subjects in the egg object n_lists : int Number of lists per subject list_length : int Number of words in the lists date_created : time A timestamp when the egg was created

pres : list (subjects) of lists (experiment) of lists (list/block) of strings or dictionaries.: This is a nested list containing the presented 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 can be a string representing the stimulus or a dictionary representing the stimuli and its features. If dictionaries are passed, identify the stimulus name using the ‘item’ key and a string label. To represent additional stimulus features, use any text (str) label as the key and a value of the following types: string, int, float, list, array.
rec : list (subjects) of lists (experiment) of lists (list/block) of strings or dictionaries.: This is a nested list containing the recalled 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 can be a string representing the stimulus or a dictionary representing the stimuli and its features. If dictionaries are passed, identify the stimulus name using the ‘item’ key and a string label. To represent additional stimulus features, use any text (str) label as the key and a value of the following types: string, int, float, list, array.
features : list (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_funcs : dict (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)’‘)
meta : dict (optional): Meta data about the study (i.e. version, description, date, etc.) can be saved here.
subjgroup : list of strings or ints (optional): String/int variables indicating how to group over subjects. Must be the length of the number of subjects
subjname : string (optional): Name of the subject grouping variable. Default is ‘Subject’.
listgroup : list of strings or ints (optional): String/int variables indicating how to group over list. Must be the length of the number of lists
listname : string (optional): Name of the list grouping variable. Default is ‘List’.
recmat : list (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_length : int: 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:

pres : Pandas.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.
rec : Pandas.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_subjects : int: Number of subjects in the egg object
n_lists : int: Number of lists per subject
list_length : int: Number of words in the lists
date_created : time: 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

next
to_dict
to_json

analyze(analysis=None, **kwargs)[source]¶: Calls analyze function

crack(subjects=None, lists=None)[source]¶

Wraps crack_egg function to take an egg and returns a subset of the subjects

Parameters:	subjects : list List of subject idxs lists : list List of lists idxs
Returns:	new_egg : Egg data object A mega egg comprised of the input eggs stacked together

get_pres_features(features=None)[source]¶: Returns a df of features for presented items

get_pres_items()[source]¶: Returns a df of presented items

get_rec_features(features=None)[source]¶: Returns a df of features for recalled items

get_rec_items()[source]¶: Returns a df of recalled items

info()[source]¶: Print info about the data egg

save(fname, compression='blosc')[source]¶

Save method for the Egg object

The data will be saved as a ‘egg’ file, which is a dictionary containing the elements of a Egg saved in the hd5 format using deepdish.

Parameters:	fname : str A name for the file. If the file extension (.egg) is not specified, it will be appended. compression : str The kind of compression to use. See the deepdish documentation for options: http://deepdish.readthedocs.io/en/latest/api_io.html#deepdish.io.save