Read trackball data from a variety of setups and configurations.
Usage
read_trackball(
paths,
setup = c("of_free", "of_fixed"),
sampling_rate,
col_time = "time",
col_dx = "x",
col_dy = "y",
counts_per_rotation = NULL,
ball_diameter = NULL,
dots_per_cm = NULL,
quiet = TRUE
)Arguments
- paths
Two file paths, one for each sensor (although one is allowed for a fixed setup,
of_fixed).- setup
Which type of experimental setup was used. Expects either
of_freeorof_fixed.- sampling_rate
Sampling rate tells the function how long time it should integrate over. A sampling rate of 60(Hz) will mean windows of 1/60 sec are used to integrate over.
- col_time
Which column contains the information about time. Can be specified either by the column number (numeric) or the name of the column if it has one (character). Should either be a datetime (POSIXt) or seconds (numeric). With two sensors, this must be a clock the two sensors share. In a Bonsai capture that is the PC datetime (column 4), not the per-board device counter (column 3), whose origin is sensor-local and therefore cannot be used to cross-reference the two files. A warning is emitted if
col_timeresolves to a non-datetime column with two sensors.- col_dx
Column name for x-axis values
- col_dy
Column name for y-axis values
- counts_per_rotation
For
of_fixedsetup: the sensor count for a full 360 degree rotation. Can be obtained usingcalibrate_trackball().- ball_diameter
For
of_fixedsetup: the ball diameter (in same units as desired output). Required if usingdots_per_cminstead ofcounts_per_rotation.- dots_per_cm
For
of_fixedsetup: sensor dots-per-cm. Use withball_diameteras an alternative tocounts_per_rotation.- quiet
If
TRUE(default), suppresses informational messages such as the count of malformed rows dropped from each file.
Value
a movement dataframe. time is in seconds from the first sample
both sensors share; see "Time" in read_dataset(). sampling_rate is
the sampling_rate given, the rate of the integration windows, and
source_sampling_rate is NaN, since the sensor has no fixed rate.
Details
Raw Bonsai optical-flow captures are headerless CSV files, optionally preceded
by serial-port junk – a partial row, or a run of noise lines and blanks
before the first complete record – with the layout
dx, dy, device_clock_us, pc_datetime, interval_s. Address their columns by
number (col_dx = 1, col_dy = 2, col_time = 4).
Such captures are not gap-free: on this rig the COM port emits no row while
the ball is still, so multi-second gaps are normal. Readings are integrated
into 1 / sampling_rate windows, and windows containing no reading are
filled with zero motion so the returned time grid is regular regardless of
the gaps in the input. Note that this treats a missing sample as no motion,
which is a property of this logger rather than of optical flow in general; a
sensor that drops samples for other reasons would need its gaps treated as
missing data instead.
With two sensors the output covers only the intersection of the two
recordings - readings from before the second sensor started, or after the
first stopped, are discarded rather than zero-filled. time = 0 is the first
shared sample, and the start_datetime metadata is the wall-clock instant of
that sample.
The sensor has no fixed rate of its own: it reports motion as it happens,
and nothing while the ball is still. The frame's sampling_rate is
therefore the rate of the integration windows, and its
source_sampling_rate is NaN, anicore's marker for a device with no
fixed rate (see anicore::set_metadata()), rather than NA, which would
mean the rate has not been declared.
Examples
# A free-floating ball is tracked by two optical flow sensors,
# so both files are supplied together
paths <- c(
system.file("extdata", "trackball_sensor_1.csv", package = "aniread"),
system.file("extdata", "trackball_sensor_2.csv", package = "aniread")
)
read_trackball(paths, setup = "of_free", sampling_rate = 60, col_time = "t")
#> Warning: `col_time` does not resolve to a datetime column.
#> ! With two sensors, `col_time` must be a clock both sensors share; a per-board
#> device counter has a sensor-local origin and cannot align the two files.
#> ℹ For a Bonsai capture, use the PC datetime column (`col_time = 4`) rather than
#> the device counter (`col_time = 3`).
#> # Keypoints: centroid
#> # Sampling rate: 60 Hz (recorded with no fixed rate)
#> # Time: 00:00:00.000 to 00:00:00.133
#> keypoint time x y
#> <fct> <dbl> <dbl> <dbl>
#> 1 centroid 0 0 0
#> 2 centroid 0.0167 2 2
#> 3 centroid 0.0333 5 5
#> 4 centroid 0.05 6 6
#> 5 centroid 0.0667 6 6
#> 6 centroid 0.0833 7 7
#> 7 centroid 0.1 12 12
#> 8 centroid 0.117 16 16
#> 9 centroid 0.133 22 22