Units

Times, distances and angles can be given with units. Multiply a number, tuple or array by a unit from pypillometry.u, or write it as a string:

import pypillometry as pp
from pypillometry import u

d.crop(3 * u.min, 5 * u.min)                    # or ("3 min", "5 min")
d.get_epochs("stim", (-200, 800) * u.ms)
d.pupil.blinks_detect(min_duration="20 ms")
d.plot.plot_pupil(plot_range=(3, 5) * u.min)
d.set_experimental_setup(eye_to_screen_center=60 * u.cm,
                         screen_pitch="-5 deg")

Available units:

Quantity	Units
time	u.ms, u.sec, u.min, u.h, u.samples (converted with the sampling rate)
distance	u.mm, u.cm, u.m, u.inch
angle	u.deg, u.rad

Aliases such as u.seconds, u.s or u.degree work as well.

Internally, everything is stored in ms, mm and radians. Plain numbers (without units) for times are ms everywhere (windows, durations, plot_range), and returned times are in ms unless asked otherwise. Many functions also take a units= argument that says how plain numbers should be read, or in which units a result should be returned (in plotting functions, units= is only the unit of the time axis):

d.get_duration(units="min")
d.events.onset("Start Block 2", units="sec")
d.crop(3, 5, units="min")

Sample indices are units="samples" (aliases: “sample”, “index”, “indices”, “idx”); units=None is not accepted. Converting positions between sample indices and time needs the data object (see Events, intervals and segments); durations (e.g., 10 * u.samples) are converted with the sampling rate.

To convert values yourself, use parse_time(), parse_distance() and parse_angle(), or the Quantity.to() method:

pp.parse_time("2 min")              # 120000.0 (ms)
(2 * u.min).to("sec")               # 120.0 sec
pp.parse_angle("90 deg")            # 1.5707963...