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]