Update readme.md

document the metrics on the validation screen

readme.md

@@ -115,9 +115,21 @@ Titta.getDefaults('tracker model name');` Supported eye trackers and their corre
 2. Change settings from their defaults if wanted (see [supported options](#supported-options) section below)
 3. Create a Titta instance using this settings struct: `EThndl = Titta(settings);`
 4. Interact with the eye tracker using the below API.
-5. When calling `Titta.calibrate()`, a participant setup and calibration interface is shown. For each screen, several keyboard hotkeys are available to activate certain functionality. By default, the hotkey for each button is printed in the button's label. It can be configured to different keys with the `settings.UI.button` options [listed below](#supported-options). In addition, a few global hotkeys are available. These are documented below in the API documentation of the `Titta.calibrate()` method. A more advanced participant setup and calibration interface intended especially to enable work with non-cooperative subject populations such as infants and primates is provided by the `Titta.calibrateAdvanced()` function.
+5. When calling `Titta.calibrate()`, a participant setup and calibration and validation interface is shown. For each screen, several keyboard hotkeys are available to activate certain functionality. By default, the hotkey for each button is printed in the button's label. It can be configured to different keys with the `settings.UI.button` options [listed below](#supported-options). In addition, a few global hotkeys are available. These are documented below in the API documentation of the `Titta.calibrate()` method. A more advanced participant setup, calibration and validation interface intended especially to enable work with participants who are unable to follow instructions such as infants and non-human primates is provided by the `Titta.calibrateAdvanced()` function. The validation screen of both interfaces lists the data quality of the gaze signal recorded during validation, see below for [a description of the reported data quality metrics](#validation-screen).
 6. Example analysis scripts for the recorded data (fixation classification and AOI analysis) are [also provided](demo_analysis).
 
+### Validation screen
+The validation screens of both `Titta.calibrate()` and `Titta.calibrateAdvanced()` report several data quality metrics for the gaze data recorded during validation. These metrics are also converted to text by `Titta.getValidationQualityMessage()` and this text is stored as a timestamped message in the Titta message stream (see `Titta.getMessages()`) as part of the validation procedure. This message as well as the calibration data from which it is generated is stored to file by most of the data saving functions in Titta (see details in the documentation of each function, it depends on the format's capabilities). See [this script](demo_analysis/a_validationAccuracy.m) for an example of extracting the data quality metrics of a validation from the `.mat` files stored by `Titta.saveData()`.
+
+For validation, by default, 0.5 s of gaze data is collected per validation point (see [`settings.val.collectDuration`](#supported-options)). The metrics calculated for the data of each validation point are decribed below. The metrics are calculated in the private function `getDataQuality()` inside [`Titta.m`](Titta.m) separately for the left and right eye (if both are recorded).
+
+|Metric|data field|description|
+|---|---|---|
+|Offset (accuracy)|`acc1D` and `acc2D`|The "accuracy is the closeness of the gaze position reported by the eye-tracking setup to the actual gaze position of the participant" ([Niehorster, Santini et al., 2020](https://doi.org/10.3758/s13428-019-01307-0)), which in Titta is operationalized as the average offset of the recorded gaze positions from the validation target. `acc1D` is the average of the Euclidian distances of each sample from the target, whereas `acc2D` contains the average signed horizontal and vertical offsets from the target (these can be zero when `acc1D` is not, for instance when the gaze samples spread evenly around a validation target).|
+|SD (precision)|`STD1D`|"Precision is defined as the closeness of a set of repeated gaze position measurements obtained under identical conditions (i.e., obtained from an eye that has not rotated)" ([Niehorster, Zemblys et al., 2020](https://doi.org/10.3758/s13428-020-01400-9)). STD indicates the spatial spread of a sequence of gaze points (more precisely it is a measure of dispersion around the centroid of a sequence of gaze positions). As per equation 2 in [Niehorster, Zemblys et al. (2020)](https://doi.org/10.3758/s13428-020-01400-9), it is computed as the square-root of the sum of the horizontal and vertical variance of the recorded gaze positions.|
+|RMS (precision)|`RMS1D`|RMS in Titta refers to RMS-S2S precision, or "the root mean square of the displacement between successive gaze positions", which loosely speaking gives an indication of how spiky the gaze signal is ([Niehorster, Zemblys et al., 2020](https://doi.org/10.3758/s13428-020-01400-9)).|
+|Data loss|`dataLoss`|Data loss (for an extensive discussion, see [Hooge et al., 2022](https://doi.org/10.3758/s13428-022-02010-3)) is calculated as the percentage of recorded gaze samples that is marked as invalid by the eye tracker.|
+
 ## API
 ### `Titta` class
 Help on each of the below listed static methods, methods and properties can be had inside MATLAB by typing on the commands line `help Titta.<function name>`, e.g. `help Titta.calibrate`. Help on the constructor is had with `help Titta.Titta`.