PALMS+Users+Guide+-+Location+Files

=**Location File**=


 * NOTE: This is documentation of a work-in-progress and is subject to change.**

Purpose
The location file is a CSV file that defines study-specific and/or participant-specific locations. Future calculations can use this information to match latitude and longitude coordinates to specific locations. These calculations will be able to generate variables such as time spent at locations; trips to/from locations; distances traveled to/from locations; activity at locations; etc.

Input
Locations are defined in a spreadsheet, exported as a CSV file; one row per location. The file contains the following columns:

NOTE: specify ALL for study-specific locations common to all participants. || NOTE: different locations can have different buffer sizes. ||
 * **Column Name** ||= **Required?** || **Format** || **Function** ||
 * participantIdentifier ||= Y || String || The participant identifier for this location.
 * locName ||= Y || String || Name of the location ||
 * locAddress ||= N || String || Address of the location (optional) ||
 * locType ||= N || String || Type of the location. For example: home, school, work, park, playground, shop. (optional) ||
 * locLatitude ||= Y || Decimal degrees || Latitude of the location's center ||
 * locLongitude ||= Y || Decimal degrees || Longitude of the location's center ||
 * buffer ||= Y || Integer || Buffer radius in meters. Points within the buffer will be considered to be at the location.
 * comment ||= N || String || Comment, typically more information about the location (optional) ||

Operation

 * 1) Add the "Location File" importer to the study's devices.
 * 2) Create a participant named "Locations". (All location CSV files will be uploaded to this participant.)
 * 3) Create a spreadsheet with the required columns listed above. We recommend including the optional columns as well -- the entities can be left blank. The column names MUST be as specified. Otherwise the file will be rejected.
 * 4) Enter study-specific locations first, specifying "ALL" as the participantIdentifier.
 * 5) Then for each participant, enter the participant specific locations. Be sure the value of the participantIdentifier cell matches the identifier of the desired participant.
 * 6) When finished, save the spreadsheet as a CSV file.
 * 7) Import the location file. Click the PALMS dataset tab. Select Locations as the participant. Select Location File Importer as the device. Click the Import Datasets button.

Finding a location's latitude and longitude
Google maps contains 3 tools that are useful for determining the latitude and longitude in decimal degrees:
 * LatLng Tooltip - Displays a tooltip next to the mouse cursor showing the latlng directly underneath the cursor.
 * LatLng Marker - Adds an option to the context menu that lets you drop a marker displaying the latlng of the position.
 * Distance Measurement Tool - Measures the distance. Useful for determining the buffer radius.

To use these tools, you must first enable them within Google Maps. Click on the Map Labs link at the bottom left column of the Google Maps screen. For each of the three tools, click their enable button. Click the Save changes button.

To find a location's coordinates, type in the street address in the search box and click the search button. Place the cursor over the desired location. Pressing the shift key will temporarily display the coordinates in a tool tip box. This is useful when you just want to verify coordinates. By right clicking and selecting "Drop a LatLng Marker" displays permanent marker at the location. You can have multiple markers active at one time.

Enter the first number displayed in the locLatitude column and the second number in the locLongitude column. If a minus sign is present, it must be included.

To measure distance to establish a buffer, click on the ruler button at the bottom left corner of the map. Select metric units. Then click on the center of the location. A green marker will appear. Then click on the farthest edge of the desired buffer. A red maker will appear and the distance will be displayed. Enter this number in the buffer column, Click the reset button before establishing the next buffer. Note: You can also use the scale at the bottom of the map to estimate buffer radius. Be sure you are looking at the meters reference.