class eelbrain.Factor(x, name=None, random=False, repeat=1, tile=1, labels=None, default=None)

Container for categorial data.

  • x (Iterable[Any]) – Sequence of Factor values (see also the labels kwarg).

  • name (Optional[str]) – Name of the Factor.

  • random (bool) – Treat Factor as random factor (for ANOVA; default is False).

  • repeat (Union[int, Sequence[int]]) – repeat each element in x, either a constant or a different number for each element.

  • tile (Union[int, Sequence[int]]) – Repeat x as a whole tile many times.

  • labels (Optional[Dict[Any, str]]) – An optional dictionary mapping values as they occur in x to the Factor’s cell labels.

  • default (Optional[str]) – Label to assign values not in label (by default this is str(value)).

  • .name (None | str) – The Factor’s name.

  • .cells (tuple of str) – Ordered names of all cells. Order is determined by the order of the labels argument. if labels is not specified, the order is initially alphabetical.

  • .random (bool) – Whether the factor represents a random or fixed effect (for ANOVA).


The most obvious way to initialize a Factor is a list of strings:

>>> Factor(['in', 'in', 'in', 'out', 'out', 'out'])
Factor(['in', 'in', 'in', 'out', 'out', 'out'])

The same can be achieved with a list of integers plus a labels dict:

>>> Factor([1, 1, 1, 0, 0, 0], labels={1: 'in', 0: 'out'})
Factor(['in', 'in', 'in', 'out', 'out', 'out'])

Or more parsimoniously:

>>> Factor([1, 0], labels={1: 'in', 0: 'out'}, repeat=3)
Factor(['in', 'in', 'in', 'out', 'out', 'out'])

Since the Factor initialization simply iterates over the x argument, a Factor with one-character codes can also be initialized with a single string:

>>> Factor('iiiooo')
Factor(['i', 'i', 'i', 'o', 'o', 'o'])


aggregate(x[, name])

Summarize the Factor by collapsing within the cells of x


Convert the Factor to a list of str

as_var([labels, default, name])

Convert into a Var

copy([name, repeat, tile])

A deep copy

count(value[, start])

Cumulative count of the occurrences of value


An index that is true for all cases whose name ends with substr


Enumerate the occurrence of each cell value throughout the data

floodfill(regions[, empty])

Fill in empty regions in a Factor from the nearest non-empty value


Generate index to conform to another Factor's order


Array with int indices equal to cell


Find an optimized index for a given cell.


Find the index of entries matching one of the *values


Find the index of entries matching one of the values


Find the index of entries not in values


Find the index of entries not in values


Create Var with the length of each label string


An index that is true for all cases whose name matches pattern

repeat(repeats[, name])

Repeat each element repeats times


Reorder the cells of the Factor (in-place)

sort_index([descending, order])

Create an index that could be used to sort this data_object.


An index that is true for all cases whose name starts with substr


A table containing information about categories

tile(repeats[, name])

Construct a Factor by repeating self repeats times


Change one or more labels in place