The function must accept (x, ...) and return a data.frame in long form with columns at least id,time and one of (angle) or (x,y)
Value
`name`, invisibly. Called for its side effect of registering the dialect for `read_tracks(dialect = )`.
Details
`x` is whatever was passed to [read_tracks()]: a data frame, or one file path. The dialect is the only reader of that file, and is called once per file when `read_tracks()` is given several paths. A table returned without an id column is one trajectory, named after its file in a multi-file import. Numeric columns returned as text are coerced strictly (see "Malformed values" in [read_tracks()]) using the decimal mark sniffed from the file; a dialect that knows better can set `attr(out, "decimal")`.
Numeric time is read as a frame index unless the dialect says its time column is in seconds, with `attr(out, "time_unit") <- "seconds"` (or `"frames"`, to rule out `time_type = "seconds"`). See "Time units from a dialect" in [read_tracks()].
A dialect that derives each position from several points can report what it left out with `attr(out, "attrition")`: a data frame with columns `source`, `point`, `masked`, `frames`, `frames_no_position`, `score_min` and `partial`, one row per point, with whole non-negative counts and one `frames` and one `frames_no_position` value (the per-file totals, repeated on each row). See "Masked points" in [read_tracks()].
A dialect can keep facts about the file it read (a header block, the units of its columns) with `attr(out, "source_meta")`: a list with distinct names other than `source` and `path`. [read_tracks()] stores one record per file in `Tracks@meta$source_meta`, each the dialect's list with the file's name (`source`) and path (`path`) in front. The records are a plain list in file order, not named by file, because files in different folders share names.
A loader that reads files can take `read_tracks(read_opts = )` by declaring a `read_opts` argument: it receives the non-`NULL` entries (`decimal`, `delim`, `sheet`, `ext`) and must honour them or stop. A table it returns without `attr(, "decimal")` is coerced with `read_opts$decimal`, else the file's sniffed mark. Without that argument, any `read_opts` stop the load.
Examples
# dtrack writes headerless, tab-separated frame, x, y (and a flag) columns
dtrack_loader <- function(x) {
d <- utils::read.delim(x, header = FALSE, colClasses = "numeric")
data.frame(id = tools::file_path_sans_ext(basename(x)),
frame = d[[1]], x = d[[2]], y = d[[3]])
}
register_loader_dialect("dtrack", dtrack_loader, overwrite = TRUE)
list_loader_dialects()
#> [1] "anymaze" "deeplabcut" "dtrack" "ethovision"
#> [5] "idtrackerai_wide" "sleap" "toxtrac" "trackmate"
#> [9] "trex"
untar(system.file("extdata", "tracks.tar.gz", package = "radiatR"),
exdir = tempdir())
track_dir <- file.path(tempdir(), "tracks")
read_tracks(file.path(track_dir, "10_10_point02.txt"), dialect = "dtrack")
#> Tracks: 1 trajectories, 299 observations
#> Columns: id='id', time='frame', angle='angle' (radians), x='x', y='y'
#> id frame x y angle
#> 1 10_10_point02 1 469.83 379.47 0.6794034
#> 2 10_10_point02 2 477.73 386.58 0.6803267
#> 3 10_10_point02 3 479.31 388.95 0.6817012
#> 4 10_10_point02 4 482.48 400.81 0.6931992
#> 5 10_10_point02 5 484.85 406.34 0.6975293
#> 6 10_10_point02 6 484.06 417.40 0.7115858