PALMS+User's+Guide+-+Validation+Calculation

=**Validation Calculation - R2**=

Purpose
The Validation Calculation is used to evaluate the accuracy of the PALMS GPS calculations by comparing the results produced by the PALMS calculation with a "truth file" detailing the actual events:
 * trip starting and ending times
 * pauses within trips
 * modes of transportation
 * sedentary periods
 * locations
 * indoor / outdoor determination

Input Variables
The truth file is a CSV file containing the following columns:


 * **Column Name** ||= **Required?** || **Function** ||
 * Date ||= Y || Date (entered as mm/dd/yyyy) ||
 * Time ||= Y || Time of event (entered as hh:mm:ss) ||
 * TourID ||= N || Unique identifier for each separate event -- stored as string, ||
 * ColdTourID ||= N || In the PALMS validation study, some test were conducted with the GPS starting from a cold start. Those events are noted in this column. Can be left blank. ||
 * Event ||= Y || Must be one of the following:
 * Trip - subject is currently engaged in a trip and moving
 * Pause - subject is engaged in a trip but currently paused (momentary stop)
 * Transition - subject is transitioning between TourIDs -- these "trips" are record but not scored. ||
 * Mode ||= Y || Mode of transportation. Must be one of the following values:
 * Walk
 * Bike
 * Bus
 * Car
 * Stand -- Subject is standing still
 * Unknown -- mode was not recorded by subject ||
 * InBldg ||= Y || Set to 1 if subject is indoors; 0 if outdoors ||
 * InGrge ||= N || Set to 1 if subject is in a parking garage; 0 if not in a garage ||
 * InMall ||= N || Set to 1 if subject is in a shopping mall; 0 if not in a mall ||
 * ColdDevStart ||= N || Set to 1 at the time the GPS was cold started. Remain set to 1 for the duration of the tour. ||
 * StartRoute ||= Y || Location or address of the starting point of a trip ||
 * EndRoute ||= Y || Location or address of the ending point of a trip ||
 * LocName_S ||= N || Name of starting location ||
 * LocAdd_S ||= N || Address of starting location ||
 * LocName_E ||= N || Name of ending location ||
 * Loc_Add_E ||= N || Address of ending location ||

Output Variables
The calculation duplicates the truth file columns listed above and adds the following columns:

Negative values indicated the PALMS trip start is earlier than the Truth start. "unknown" indicates that the difference in times is greater than the value specified as the start/end buffer (default 240 seconds). || Negative values indicated the PALMS trip end is earlier than the Truth end. ||
 * **Column Name** || **Function** ||
 * 01_identifier || Participant identifier ||
 * 17_locationNumber || Location number as assigned by PALMS. -1 indicates subject not at a location. ||
 * 18_tripsNumber || Trip number as assigned by PALMS. 0 indicates subject is stationary and not engaged in a trip. ||
 * 19_tripMode || Mode of transportation as determined by PALMS. ||
 * 20_indoors || Set to 1 if PALMS determined subject is indoors, 0 if outdoors, -1 if unknown ||
 * 21_tripStartOffset || Difference between trip start time as computed by PALMS and the start time in the Truth file in seconds.
 * 22_tripEndOffset || Difference between trip end time as computed by PALMS and the end time in the Truth file in seconds.
 * 23_tripMatch || Set to 1 if PALMS correctly identified that the subject was engaged in a trip. Set to 0 on mis-match. ||
 * 24_tripMatchWithin1 || Set to 1 if start/end times are within times specified as Trip Window 1 (default 10 seconds) ||
 * 25_tripMatchWithin2 || Set to 1 if start/end times are within times specified as Trip Window 2 (default 30 seconds) ||
 * 26_tripMatchWithin3 || Set to 1 if start/end times are within times specified as Trip Window 3 (default 60 seconds) ||
 * 27_tripMatchWithin4 || Set to 1 if start/end times are within times specified as Trip Window 4 (default 120 seconds) ||
 * 28_missedTrip || Set to 1 when PALMS missed detecting a trip logged in the Truth file ||
 * 29_modeMatch || Set to 1 if PALMS correctly identified the mode of transportation. Set to 0 on mis-match. ||
 * 30_inoutMatch || Set to 1 if PALMS correctly determine that the subject was indoors or outdoors. Set to 0 on mis-match. ||
 * 31_locationMatch || Set to 1 if PALMS correctly determined that the subject was at a location. Set to 0 on mis-match. ||

Operation
To use the Validation calculation, it must be first added to your study. You must also add the "Truth File" importer to the study's devices.

Create a participant named "TruthFile" and upload all truth CSV files to that participant's id.

Upload the GPS datasets and optionally the accelerometer dataset for the given participant. Then run the PALMS calculation (GPS, Activity, HR - Process and Merge). When the PALMS calculation completes, select "Validation Study (R_ beta)" from the Calculations menu. Once selected, you will be prompted to enter the following:


 * Participant || Select all participants or one specific participant to include in the results ||
 * Start Date || Earliest date to include in the results ||
 * End Date || Latest date to include in the results ||
 * Match Palms result to Truth || When checked (default) -- for each entry in the truth file, find the corresponding entry in the PALMS result set. ||
 * Only include matching timestamps || Check this box if you want to only include those rows where the timestamp of the row in the result set matches the timestamp of the row in the truth file. ||
 * Include transition periods || Check this box if you want transition periods included and scored in the result. ||
 * Trip start / end buffer (in seconds) || Size of window (in seconds) that PALMS will consider search the truth file for a corresponding start or end point. ||
 * Trip window 1 || Size of window to consider that the trip start / end points match -- default 10 seconds ||
 * Trip window 2 || default 30 seconds ||
 * Trip window 3 || default 60 seconds ||
 * Trip window 4 || default 120 seconds ||
 * Result Name || Enter name of the result set. NOTE: It is recommended that the name starts with "V - " to distinguish it from other result sets. ||

These is an interaction between "Match Palms result to Truth" and "Only include matching timestamps": Once these parameters are entered, press the "Select Result Sets to process" button. A list of result sets (previously produced by the PALMS calculation) will be displayed. Click on the name of the result set to summarize. Then click the "Start Calculation" button.
 * **Match Palms...** || **Only include...** || **Result** ||
 * Checked || Not checked || Result set will contain one row for every row in the Truth file. ||
 * Not checked || Not checked || Result set will contain one row for every row in the PALMS result set. ||
 * Checked or Not checked || Checked || Result set will contain only those rows where the timestamps match. ||

NOTES:
 * 1) The log file for the validation result set contains a summary of the results.
 * 2) Validation results can be viewed using the Data Grid function, but not the Map or Timeline functions.
 * 3) Validation results can be exported as CSV files, but not KML files.