ReadSweep: Read the Sensor Data Recorded During a Sweep
In patrickreidy/ag501: Carstens AG501 Electromagnetic Articulograph

Description Usage Arguments Details Value

Read the head-corrected (and biteplane-rotated) position and rotation data from a .txt file and its metadata from the header of a .pos file.

1 2	ReadSweep(pos = "", txt = "", sweep = NULL, sensors = character(), dropExtra = TRUE, simplify = TRUE)

`pos`	A character vector of paths to `.pos` files.
`txt`	A character vector of paths to `.txt` files.
`sweep`	A character vector, the path to and basenames (without extensions) of sweeps. The names of the `.pos` and `.txt` files for the sweeps will be constructed by appending the appropriate file extensions. Default is `NULL`. If not `NULL`, then `-.pos` and `-.txt` completions of `sweep` override any provided values of the `pos` and `txt` arguments.
`sensors`	A character vector, names for sensors that were attached to the participant and connected to sockets in the Carstens Sensin box. The position of a name in this vector is interpreted as the number of the socket to which the sensor was connected. Default is `character()`. See `FormatSensors` and `FormatChannels`.
`dropExtra`	If `TRUE`, then the `extra` channel for each sensor is dropped from the data, since this channel is only a placeholder for future development by Carstens and contains no data. If `FALSE`, then the `extra` channels are kept.
`simplify`	If `TRUE`, then the data tables for the sweeps are row-binded together into a single data table. If `FALSE`, then the data tables for the sweeps are returned as elements of a list.

ReadSweep is vectorized over pos, txt, and sensors. pos and txt should be vectors of the same length ordered such that the positions on these vectors correspond to the .pos and .txt files, respectively, of the same sweep. Alternatively, multiple sweeps can be specified by passing a character vector to the sweep argument. If multiple sweeps are specified, and if sensors is a character vector, then the elements of sensors are recycled as the sensor-names for each sweep. To specify different sensor names for each sweep, sensors should be a list with the same length as the number of sweeps and whose elements are character vectors.

A list or nested data frame with the following variables:

Sweep: A character, the name of the sweep, which identifies files with .pos and .txt extensions.
Format: A character, the data format defined by Carstens.
SamplingRate: A numeric, the number of samples recorded per second by the AG501.
SweepsaverBuild: A character, the version and revision number of the Sweepsaver application, which records the amplitude values detected by the sensor coils in the AG501.
SweepsaverVersion: A numeric, the version number of the Sweepsaver application.
SweepsaverRevision: A numeric, the revision number of the Sweepsaver application.
SweepsaverTimestamp: A datetime, the date and time when the sweep was recorded by the Sweepsaver application, in YYYY-MM-DD HH:MM:SS format.
CalcposBuild: A character, the version and revision number of the Calcpos application, which transforms the amplitude values recorded by Sweepsaver into raw position data that has not been corrected for head movement.
CalcposVersion: A numeric, the version number of the Calcpos application.
CalcposRevision: A numeric, the revision number of the Calcpos application.
CalcposTimestamp: A datetime, the date and time when the raw position data was computed by Calcpos.
NormposBuild: A character, the version and revision number of the Normpos application, which transforms the raw position data by removing head movement. If the Carstens biteplane was used to compute a rotation matrix, then Normpos also rotates and translates the data so that the participant's biteplane lies within the x-y plane and so that the participant's upper incisors lie at the origin of the coordinate system.
NormposVersion: A numeric, the version number of the Normpos application.
NormposRevision: A numeric, the revision number of the Normpos application.
NormposTimestamp: A datetime, the date and time when the head-correction and biteplane-rotation were applied by Normpos.
TaxonomicDistanceMean: A numeric, the mean of the taxonomic distances, averaging across samples. The taxonomic distance of each sample is, roughly, the difference between the measured position and the expected position relative to a reference object.
TaxonomicDistanceStdDev: A numeric, the standard deviation of taxonomic distances for the sweep.
PostFilters: A data frame that records the low-pass Kaiser filters that were applied to the data channels of the active sensors, during postprocessing by the Calcpos and Normpos applications. Includes the following columns:
- Socket: A numeric, the number of the socket in the Sensin box to which the physical sensor was connected.
- Sensor: A character, the name of the sensor whose data channels were low-pass filtered. See: FormatChannels.
- Name: A character, the name of the filter applied to the sensor's data channels. See: CarstensFilters.
- Application: A character, the application that applied the low-pass filter to the data.