scale#

pypillometry.scale(variables=[], method='z', center=None, scale=None, eyes=[], policy='default')#

Pipeline step for scale() (d | pp.scale(...)).

Scale the signal: subtract center and divide by scale.

method says how center and scale are computed from the usable samples of each channel (under policy) if they are not given:

  • "z" (default): mean and standard deviation (z-scores)

  • "robust": median and median absolute deviation (MAD; the raw MAD, not multiplied by 1.4826), so the result is in units of the MAD and outliers (e.g., artefacts) have little influence

  • "minmax": minimum and range (max - min), so the result lies between 0 and 1

  • "percent": mean and mean / 100, so the result is the change in % of the mean (for a percent change relative to a baseline before each event, see SegmentedEyeData.pupil.baseline_correct)

Parameters:

  • variables (str or list of str, optional) – variables to scale; can be “pupil”, “x”,”y”, “baseline”, “response” or any other variable that is available in the dataset; either a string or a list of strings; available variables can be checked with obj.variables; empty list means all variables

  • method (str) – how center and scale are computed if they are None: "z" (default), "robust", "minmax" or "percent" (see above)

  • center (Union[float, dict, None]) – value to subtract; if None, computed with method; a number (same for all eyes and variables) or one per channel as {"left_pupil": value, ...}

  • scale (Union[float, dict, None]) – value to divide by; if None, computed with method; a number or one per channel as {"left_pupil": value, ...}

  • eyes (str or list of str, optional) – eye(s) to consider; if empty, all available eyes

  • policy (str, MaskPolicy or list of str) – mask policy that decides which samples are used for center and scale (see mask()); default "default" (interpolated samples are used)

  • inplace (bool or None, optional) – if True, make change in-place and return the object; if False, make and return copy before making changes; if None, use the object-level setting (specified in the constructor)

Return type:

EyeData

Returns:

the scaled object (self or a copy, depending on inplace)

Raises:

ValueError – if method is unknown, or scale is 0 or not finite for a channel (e.g., a constant signal, or a MAD of 0)

Notes

The scaling parameters are stored in params["scale"] ({"center": {"left_pupil": ...}, "scale": {...}, "method": {...}}) and used by unscale(). Scaling a variable again combines the parameters, so that unscale() restores the values before the first scale.

Examples

>>> import pypillometry as pp
>>> d = pp.get_example_data("rlmw_002_short")
>>> z = d.scale("pupil", inplace=False)                     # z-scores
>>> r = d.scale("pupil", method="robust", inplace=False)    # units of the MAD
>>> p = d.scale("pupil", method="minmax", inplace=False)
>>> bool(p["left_pupil"].min() == 0 and p["left_pupil"].max() == 1)
True