Transitions¶
The transitions module contains utilties to iterate over and mask
transitions between recalled items. The
psifr.transitions.transitions_masker()
does most of the work
here.
Module to analyze transitions during free recall.
-
psifr.transitions.
count_category
(pool_items, recall_items, pool_category, recall_category, pool_test=None, recall_test=None, test=None)¶ Count within-category transitions.
- Parameters
pool_items (list) – List of the serial positions available for recall in each list. Must match the serial position codes used in recall_items.
recall_items (list) – List indicating the serial position of each recall in output order (NaN for intrusions).
pool_category (list) – List of the category of each item in the pool for each list.
recall_category (list) – List of item category in recall order.
pool_test (list, optional) – List of some test value for each item in the pool.
recall_test (list, optional) – List of some test value for each recall attempt by output position.
test (callable) – Callable that evaluates each transition between items n and n+1. Must take test values for items n and n+1 and return True if a given transition should be included.
- Returns
actual (int) – Count of actual within-category transitions.
possible (int) – Count of possible within-category transitions.
Examples
>>> from psifr import transitions >>> pool_items = [[1, 2, 3, 4]] >>> recall_items = [[4, 3, 1, 2]] >>> pool_category = [[1, 1, 2, 2]] >>> recall_category = [[2, 2, 1, 1]] >>> transitions.count_category( ... pool_items, recall_items, pool_category, recall_category ... ) (2, 2)
-
psifr.transitions.
count_distance
(distances, edges, pool_items, recall_items, pool_index, recall_index, pool_test=None, recall_test=None, test=None, count_unique=False)¶ Count transitions within distance bins.
- Parameters
distances (numpy.array) – Items x items matrix of pairwise distances or similarities.
edges (array-like) – Edges of bins to apply to distances.
pool_items (list of list) – Unique item codes for each item in the pool available for recall.
recall_items (list of list) – Unique item codes of recalled items.
pool_index (list of list) – Index of each item in the distances matrix.
recall_index (list of list) – Index of each recalled item.
pool_test (list of list, optional) – Test value for each item in the pool.
recall_test (list of list, optional) – Test value for each recalled item.
test (callable) – Called as test(prev, curr) or test(prev, poss) to screen actual and possible transitions, respectively.
count_unique (bool, optional) – If true, only unique values will be counted toward the possible transitions. If multiple items are avilable for recall for a given transition and a given bin, that bin will only be incremented once. If false, all possible transitions will add to the count.
- Returns
actual (pandas.Series) – Count of actual transitions made for each bin.
possible (pandas.Series) – Count of possible transitions for each bin.
See also
rank_distance()
Calculate percentile rank of transition distances.
Examples
>>> from psifr import transitions >>> distances = np.array([[0, 1, 2, 2], [1, 0, 2, 2], [2, 2, 0, 3], [2, 2, 3, 0]]) >>> edges = np.array([0.5, 1.5, 2.5, 3.5]) >>> pool_items = [[1, 2, 3, 4]] >>> recall_items = [[4, 2, 3, 1]] >>> pool_index = [[0, 1, 2, 3]] >>> recall_index = [[3, 1, 2, 0]] >>> actual, possible = transitions.count_distance( ... distances, edges, pool_items, recall_items, pool_index, recall_index ... ) >>> actual (0.5, 1.5] 0 (1.5, 2.5] 3 (2.5, 3.5] 0 dtype: int64 >>> possible (0.5, 1.5] 1 (1.5, 2.5] 4 (2.5, 3.5] 1 dtype: int64
-
psifr.transitions.
count_lags
(list_length, pool_items, recall_items, pool_label=None, recall_label=None, pool_test=None, recall_test=None, test=None, count_unique=False)¶ Count actual and possible serial position lags.
- Parameters
list_length (int) – Number of items in each list.
pool_items (list) – List of the serial positions available for recall in each list. Must match the serial position codes used in recall_items.
recall_items (list) – List indicating the serial position of each recall in output order (NaN for intrusions).
pool_label (list, optional) – List of the positions to use for calculating lag. Default is to use pool_items.
recall_label (list, optional) – List of position labels in recall order. Default is to use recall_items.
pool_test (list, optional) – List of some test value for each item in the pool.
recall_test (list, optional) – List of some test value for each recall attempt by output position.
test (callable) – Callable that evaluates each transition between items n and n+1. Must take test values for items n and n+1 and return True if a given transition should be included.
count_unique (bool, optional) – If true, only unique values will be counted toward the possible transitions. If multiple items are avilable for recall for a given transition and a given bin, that bin will only be incremented once. If false, all possible transitions will add to the count.
- Returns
actual (pandas.Series) – Count of actual lags that occurred in the recall sequence.
possible (pandas.Series) – Count of possible lags.
See also
rank_lags()
Rank of serial position lags.
Examples
>>> from psifr import transitions >>> pool_items = [[1, 2, 3, 4]] >>> recall_items = [[4, 2, 3, 1]] >>> actual, possible = transitions.count_lags(4, pool_items, recall_items) >>> actual -3 0 -2 2 -1 0 0 0 1 1 2 0 3 0 dtype: int64 >>> possible -3 1 -2 2 -1 2 0 0 1 1 2 0 3 0 dtype: int64
-
psifr.transitions.
count_pairs
(n_item, pool_items, recall_items, pool_test=None, recall_test=None, test=None)¶ Count transitions between pairs of specific items.
-
psifr.transitions.
percentile_rank
(actual, possible)¶ Get percentile rank of a score compared to possible scores.
- Parameters
actual (float) – Score to be ranked. Generally a distance score.
possible (numpy.ndarray or list) – Possible scores to be compared to.
- Returns
rank – Rank scaled to range from 0 (low score) to 1 (high score).
- Return type
float
Examples
>>> from psifr import transitions >>> actual = 3 >>> possible = [1, 2, 2, 2, 3] >>> transitions.percentile_rank(actual, possible) 1.0
-
psifr.transitions.
rank_distance
(distances, pool_items, recall_items, pool_index, recall_index, pool_test=None, recall_test=None, test=None)¶ Calculate percentile rank of transition distances.
- Parameters
distances (numpy.array) – Items x items matrix of pairwise distances or similarities.
pool_items (list of list) – Unique item codes for each item in the pool available for recall.
recall_items (list of list) – Unique item codes of recalled items.
pool_index (list of list) – Index of each item in the distances matrix.
recall_index (list of list) – Index of each recalled item.
pool_test (list of list, optional) – Test value for each item in the pool.
recall_test (list of list, optional) – Test value for each recalled item.
test (callable) – Called as test(prev, curr) or test(prev, poss) to screen actual and possible transitions, respectively.
- Returns
rank – Distance percentile rank for each included transition. The rank is 0 if the distance was the largest of the available transitions, and 1 if the distance was the smallest. Ties are assigned to the average percentile rank.
- Return type
list
See also
count_distance()
Count transitions within distance bins.
Examples
>>> from psifr import transitions >>> distances = np.array([[0, 1, 2, 2], [1, 0, 2, 2], [2, 2, 0, 3], [2, 2, 3, 0]]) >>> edges = np.array([0.5, 1.5, 2.5, 3.5]) >>> pool_items = [[1, 2, 3, 4]] >>> recall_items = [[4, 2, 3, 1]] >>> pool_index = [[0, 1, 2, 3]] >>> recall_index = [[3, 1, 2, 0]] >>> transitions.rank_distance( ... distances, pool_items, recall_items, pool_index, recall_index ... ) [0.75, 0.0, nan]
-
psifr.transitions.
rank_lags
(pool_items, recall_items, pool_label=None, recall_label=None, pool_test=None, recall_test=None, test=None)¶ Calculate rank of absolute lag for free recall lists.
- Parameters
pool_items (list) – List of the serial positions available for recall in each list. Must match the serial position codes used in recall_items.
recall_items (list) – List indicating the serial position of each recall in output order (NaN for intrusions).
pool_label (list, optional) – List of the positions to use for calculating lag. Default is to use pool_items.
recall_label (list, optional) – List of position labels in recall order. Default is to use recall_items.
pool_test (list, optional) – List of some test value for each item in the pool.
recall_test (list, optional) – List of some test value for each recall attempt by output position.
test (callable) – Callable that evaluates each transition between items n and n+1. Must take test values for items n and n+1 and return True if a given transition should be included.
- Returns
rank – Absolute lag percentile rank for each included transition. The rank is 0 if the lag was the most distant of the available transitions, and 1 if the lag was the closest. Ties are assigned to the average percentile rank.
- Return type
list
See also
count_lags()
Count actual and possible serial position lags.
Examples
>>> from psifr import transitions >>> pool_items = [[1, 2, 3, 4]] >>> recall_items = [[4, 2, 3, 1]] >>> transitions.rank_lags(pool_items, recall_items) [0.5, 0.5, nan]
-
psifr.transitions.
transitions_masker
(pool_items, recall_items, pool_output, recall_output, pool_test=None, recall_test=None, test=None)¶ Iterate over transitions with masking.
Transitions are between a “previous” item and a “current” item. Non-included transitions will be skipped. A transition is yielded only if it matches the following conditions:
(1) Each item involved in the transition is in the pool. Items are removed from the pool after they appear as the previous item.
(2) Optionally, an additional check is run based on test values associated with the items in the transition. For example, this could be used to only include transitions where the category of the previous and current items is the same.
The masker will yield “output” values, which may be distinct from the item identifiers used to determine item repeats.
- Parameters
pool_items (list) – Items available for recall. Order does not matter. May contain repeated values. Item identifiers must be unique within pool.
recall_items (list) – Recalled items in output position order.
pool_output (list) – Output values for pool items. Must be the same order as pool.
recall_output (list) – Output values in output position order.
pool_test (list, optional) – Test values for items available for recall. Must be the same order as pool.
recall_test (list, optional) – Test values for items in output position order.
test (callable, optional) –
Used to test whether individual transitions should be included, based on test values.
test(prev, curr) - test for included transition
test(prev, poss) - test for included possible transition
- Yields
prev (object) – Output value for the “from” item on this transition.
curr (object) – Output value for the “to” item.
poss (numpy.array) – Output values for all possible valid “to” items.
Examples
>>> pool = [1, 2, 3, 4, 5, 6] >>> recs = [6, 2, 3, 6, 1, 4] >>> masker = transitions_masker( ... pool_items=pool, recall_items=recs, pool_output=pool, recall_output=recs ... ) >>> for prev, curr, poss in masker: ... print(prev, curr, poss) 6 2 [1 2 3 4 5] 2 3 [1 3 4 5] 1 4 [4 5]