# autora.experimentalist.utils

## array_to_sequence(input)

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

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:
>>> l0[2][1]
5

We can also use a record array:
>>> a1 = np.rec.fromarrays([range(5), list("abcde")])
>>> a1
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
[(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 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: >>> l0[2][1] 5 We can also use a record array: >>> a1 = np.rec.fromarrays([range(5), list("abcde")]) >>> a1 rec.array([(0, 'a'), (1, 'b'), (2, 'c'), (3, 'd'), (4, 'e')], dtype=[('f0', '>> l1 = list(array_to_sequence(a1)) >>> l1 [(0, 'a'), (1, 'b'), (2, 'c'), (3, 'd'), (4, 'e')] The elements of the list are numpy.records >>> type(l1[0]) """ 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.

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]
>>> 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='>> sequence_to_array("abcde") # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS array([['a'], ['b'], ['c'], ['d'], ['e']], dtype='>> sequence_to_array(["abc", "de"]) # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS array([['abc'], ['de']], dtype='

## sequence_to_recarray(iterable)

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

Examples:

A simple range object is converted into a recarray of dimension 2:
>>> sequence_to_recarray(range(5)) # doctest: +NORMALIZE_WHITESPACE
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
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 rec.array([(0,), (1,), (2,), (3,), (4,)], dtype=[('f0', '>> sequence_to_recarray(zip(range(5), "abcde")) # doctest: +NORMALIZE_WHITESPACE rec.array([(0, 'a'), (1, 'b'), (2, 'c'), (3, 'd'), (4, 'e')], dtype=[('f0', '>> sequence_to_recarray("abcde") # doctest: +NORMALIZE_WHITESPACE rec.array([('a',), ('b',), ('c',), ('d',), ('e',)], dtype=[('f0', '>> sequence_to_recarray(["abc", "de"]) # doctest: +NORMALIZE_WHITESPACE rec.array([('abc',), ('de',)], dtype=[('f0', '