eelbrain.Factor

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

Container for categorial data.

Parameters:

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

  • name (str) – Name of the Factor.

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

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

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

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

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

Variables:

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

  • .cells (tuple of str) – Ordered names of all cells. Order is determined 1) by the order of cells in the labels argument, and 2) for cells that do not occur in labels it is determined by first occurrence in x.

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

Examples

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'])

Methods

aggregate(x[, name])

Summarize the Factor by collapsing within the cells of x

as_labels()

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

endswith(substr)

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

enumerate_cells([name])

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

get_index_to_match(other)

Generate index to conform to another Factor's order

index(cell)

Array with int indices equal to cell

index_opt(cell)

Find an optimized index for a given cell.

isany(*values)

Find the index of entries matching one of the *values

isin(values)

Find the index of entries matching one of the values

isnot(*values)

Find the index of entries not in values

isnotin(values)

Find the index of entries not in values

label_length([name])

Create Var with the length of each label string

lower([name])

All labels to lower-case

matches(pattern)

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

repeat(repeats[, name])

Repeat each element repeats times

sort_cells(order)

Reorder the cells of the Factor (in-place)

sort_index([descending, order])

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

startswith(substr)

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

table_categories()

A table containing information about categories

tile(repeats[, name])

Construct a Factor by repeating self repeats times

update_labels(labels)

Change one or more labels in place

upper([name])

All labels to upper-case