group_segments#

pypillometry.group_segments(segments, meanfct=<function mean>, name=None, channels=None)[source]#

Average the segments of several participants per participant.

Shortcut for concat_segments(segments).average(by="subject"): the result has one column per participant (the average of their trials), with the metadata column "subject". Mean and error over the columns (e.g., group.pupil.plot()) are those across participants.

Parameters:

  • segments (list or dict of SegmentedEyeData) – one object per participant; for a dict, the keys are the names of the participants (otherwise the names of the segments, or numbers if these are not unique)

  • meanfct (callable or None) – function that averages the trials of each participant, called as meanfct(data, axis=1); it must accept an axis argument and ignore masked values (e.g., np.mean or np.ma.median, but not np.median; a warning is logged otherwise). If None, the trials are not averaged (as concat_segments()).

  • name (str) – name of the result (default: "group_" and the name of the first segments)

  • channels (str or list of str, optional) – channels to combine (default: those of the first segments)

Return type:

SegmentedEyeData

Returns:

the averages of the participants (or all their trials)

Examples

One SegmentedEyeData per participant (here: the example recording twice):

>>> import pypillometry as pp
>>> from pypillometry import u
>>> d = pp.get_example_data("rlmw_002_short")
>>> epochs = d.get_epochs("S_", (-500, 2500) * u.ms)
>>> segments = {"S01": d.get_segments(epochs), "S02": d.get_segments(epochs)}
>>> group = pp.group_segments(segments, channels=["left_pupil", "right_pupil"])
>>> group["left_pupil"].shape  # (time points, participants)
(1500, 2)
>>> group.epochs.meta["subject"].tolist()
['S01', 'S02']

Means per participant and condition, then the mean of the participants per condition (here, the condition is the half of the session):

>>> ep = epochs.set_meta("half", np.where(np.arange(len(epochs)) < 5, "first", "second"))
>>> both = pp.concat_segments({"S01": d.get_segments(ep), "S02": d.get_segments(ep)})
>>> means = both.average(by=["subject", "half"]).average(by="half")
>>> means.epochs.meta["n_trials"].tolist()
[10, 10]