Skip to content

autora.experimentalist.utils

array_to_sequence(input)

Convert an array of experimental conditions into an iterable of smaller arrays.

See also

Examples:

We start with an array:
>>> a0 = np.arange(10).reshape(-1,2)
>>> a0
array([[0, 1],
       [2, 3],
       [4, 5],
       [6, 7],
       [8, 9]])

The sequence is created as a generator object
>>> array_to_sequence(a0)  # doctest: +ELLIPSIS
<generator object array_to_sequence at 0x...>

To see the sequence, we can convert it into a list:
>>> l0 = list(array_to_sequence(a0))
>>> l0
[array([0, 1]), array([2, 3]), array([4, 5]), array([6, 7]), array([8, 9])]

The individual rows are themselves 1-dimensional arrays:
>>> l0[0]
array([0, 1])

The rows can be subscripted as usual:
>>> int(l0[2][1])
5

We can also use a record array:
>>> a1 = np.rec.fromarrays([range(5), list("abcde")])
>>> a1 # doctest: +ELLIPSIS
rec.array([(0, 'a'), (1, 'b'), (2, 'c'), (3, 'd'), (4, 'e')],
          dtype=[('f0', '<i...'), ('f1', '<U1')])

This is converted into records:
>>> l1 = list(array_to_sequence(a1))
>>> l1 # doctest: +NORMALIZE_WHITESPACE
[(0, 'a'), (1, 'b'), (2, 'c'), (3, 'd'), (4, 'e')]

The elements of the list are numpy.records
>>> type(l1[0])
<class 'numpy.record'>
Source code in autora/experimentalist/utils.py 
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def array_to_sequence(input: numpy.typing.ArrayLike):
    """
    Convert an array of experimental conditions into an iterable of smaller arrays.

    See also:
        - [sequence_to_array][autora.experimentalist.utils.sequence_to_array]
        - [sequence_to_array][autora.experimentalist.utils.sequence_to_recarray]

    Examples:

        We start with an array:
        >>> a0 = np.arange(10).reshape(-1,2)
        >>> a0
        array([[0, 1],
               [2, 3],
               [4, 5],
               [6, 7],
               [8, 9]])

        The sequence is created as a generator object
        >>> array_to_sequence(a0)  # doctest: +ELLIPSIS
        <generator object array_to_sequence at 0x...>

        To see the sequence, we can convert it into a list:
        >>> l0 = list(array_to_sequence(a0))
        >>> l0
        [array([0, 1]), array([2, 3]), array([4, 5]), array([6, 7]), array([8, 9])]

        The individual rows are themselves 1-dimensional arrays:
        >>> l0[0]
        array([0, 1])

        The rows can be subscripted as usual:
        >>> int(l0[2][1])
        5

        We can also use a record array:
        >>> a1 = np.rec.fromarrays([range(5), list("abcde")])
        >>> a1 # doctest: +ELLIPSIS
        rec.array([(0, 'a'), (1, 'b'), (2, 'c'), (3, 'd'), (4, 'e')],
                  dtype=[('f0', '<i...'), ('f1', '<U1')])

        This is converted into records:
        >>> l1 = list(array_to_sequence(a1))
        >>> l1 # doctest: +NORMALIZE_WHITESPACE
        [(0, 'a'), (1, 'b'), (2, 'c'), (3, 'd'), (4, 'e')]

        The elements of the list are numpy.records
        >>> type(l1[0])
        <class 'numpy.record'>

    """
    assert isinstance(input, (np.ndarray, np.recarray))

    for a in input:
        yield a

sequence_to_array(iterable)

Converts a finite sequence of experimental conditions into a 2D numpy.array.

See also: array_to_sequence

Examples:

A simple range object can be converted into an array of dimension 2:
>>> sequence_to_array(range(5)) # doctest: +NORMALIZE_WHITESPACE
array([[0], [1], [2], [3], [4]])

For mixed datatypes, the highest-level type common to all the inputs will be used, so
consider using [_sequence_to_recarray][autora.experimentalist.utils._sequence_to_recarray]
instead.
>>> sequence_to_array(zip(range(5), "abcde"))  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
array([['0', 'a'], ['1', 'b'], ['2', 'c'], ['3', 'd'], ['4', 'e']],  dtype='<U...')

Single strings are broken into characters:
>>> sequence_to_array("abcde")  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
array([['a'], ['b'], ['c'], ['d'], ['e']], dtype='<U...')

Multiple strings are treated as individual entries:
>>> sequence_to_array(["abc", "de"])  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
array([['abc'], ['de']], dtype='<U...')
Source code in autora/experimentalist/utils.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
def sequence_to_array(iterable):
    """
    Converts a finite sequence of experimental conditions into a 2D numpy.array.

    See also: [array_to_sequence][autora.experimentalist.utils.array_to_sequence]

    Examples:

        A simple range object can be converted into an array of dimension 2:
        >>> sequence_to_array(range(5)) # doctest: +NORMALIZE_WHITESPACE
        array([[0], [1], [2], [3], [4]])

        For mixed datatypes, the highest-level type common to all the inputs will be used, so
        consider using [_sequence_to_recarray][autora.experimentalist.utils._sequence_to_recarray]
        instead.
        >>> sequence_to_array(zip(range(5), "abcde"))  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
        array([['0', 'a'], ['1', 'b'], ['2', 'c'], ['3', 'd'], ['4', 'e']],  dtype='<U...')

        Single strings are broken into characters:
        >>> sequence_to_array("abcde")  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
        array([['a'], ['b'], ['c'], ['d'], ['e']], dtype='<U...')

        Multiple strings are treated as individual entries:
        >>> sequence_to_array(["abc", "de"])  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
        array([['abc'], ['de']], dtype='<U...')

    """
    deque = collections.deque(iterable)
    array = np.array(deque).reshape((len(deque), -1))
    return array

sequence_to_recarray(iterable)

Converts a finite sequence of experimental conditions into a numpy recarray.

See also: array_to_sequence

Examples:

A simple range object is converted into a recarray of dimension 2:
>>> sequence_to_recarray(range(5)) # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
rec.array([(0,), (1,), (2,), (3,), (4,)], dtype=[('f0', '<i...')])

Mixed datatypes lead to multiple output types:
>>> sequence_to_recarray(zip(range(5), "abcde"))  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
rec.array([(0, 'a'), (1, 'b'), (2, 'c'), (3, 'd'), (4, 'e')],
    dtype=[('f0', '<i...'), ('f1', '<U1')])

Single strings are broken into characters:
>>> sequence_to_recarray("abcde")  # doctest: +NORMALIZE_WHITESPACE
rec.array([('a',), ('b',), ('c',), ('d',), ('e',)], dtype=[('f0', '<U1')])

Multiple strings are treated as individual entries:
>>> sequence_to_recarray(["abc", "de"])  # doctest: +NORMALIZE_WHITESPACE
rec.array([('abc',), ('de',)], dtype=[('f0', '<U3')])
Source code in autora/experimentalist/utils.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def sequence_to_recarray(iterable):
    """
    Converts a finite sequence of experimental conditions into a numpy recarray.

    See also: [array_to_sequence][autora.experimentalist.utils.array_to_sequence]

    Examples:

        A simple range object is converted into a recarray of dimension 2:
        >>> sequence_to_recarray(range(5)) # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
        rec.array([(0,), (1,), (2,), (3,), (4,)], dtype=[('f0', '<i...')])

        Mixed datatypes lead to multiple output types:
        >>> sequence_to_recarray(zip(range(5), "abcde"))  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
        rec.array([(0, 'a'), (1, 'b'), (2, 'c'), (3, 'd'), (4, 'e')],
            dtype=[('f0', '<i...'), ('f1', '<U1')])

        Single strings are broken into characters:
        >>> sequence_to_recarray("abcde")  # doctest: +NORMALIZE_WHITESPACE
        rec.array([('a',), ('b',), ('c',), ('d',), ('e',)], dtype=[('f0', '<U1')])

        Multiple strings are treated as individual entries:
        >>> sequence_to_recarray(["abc", "de"])  # doctest: +NORMALIZE_WHITESPACE
        rec.array([('abc',), ('de',)], dtype=[('f0', '<U3')])

    """
    deque = collections.deque(iterable)

    if isinstance(deque[0], (str, int, float, complex)):
        recarray = np.core.records.fromrecords([(d,) for d in deque])
    else:
        recarray = np.core.records.fromrecords(deque)

    return recarray