Calculations on Geopoints
[Updated February 22, 2019]
NOTE: This content is now obsolete. Please refer to this blog post for more up to date content.
The calculation column in XLSForms allows you write expressions that, when evaluated, set the response for a particular question. Calculations are supported in most of the questions types such as integers, text, date etc For example, the Calculation expression below will sum the number of girls and boys in a class, so the field user does not need to enter the total number.
Calculations are pretty straight-forward once you understand the operators you can use. This help topic has a nice table with all the operators supported. I also really like Hanna's Blog Post
It may not be obvious how to use Calculations against geopoint questions, but it is possible! Calculating a geopoint will literally move the map to the computed location. For example, say you have a list of wells and you want the user to select one of them, to set the X/Y coordinates of the well in a geopoint question.
To Calculate a geopoint, the most important aspect is understanding how geopoints are internally represented in Survey123 for ArcGIS. The format is simple: a space-separated list of valid latitude (decimal degrees) and longitude (decimal degrees). For example, this is how a geopoint question, under the covers, is managed within the Survey123 app:
43.221 -117.342
A geopoint object requires at least the latitude and longitude, but additional values can be added for its elevation (in meters), horizontal accuracy (in meters) etc
43.221 -117.342 34 2
Of course, that is not what the field user sees, because they see a map... but you need to know how a geopoint object is stored if you want to work with Calculations and Geopoints. If your calculation generates a string like that, the map in your geopoint question will center itself there. You can also set the value of a geopoint question using the default column.
Ok, so lets look at this step by step through an example. Pretend we want to build a survey where the user selects a city from a list and have the map automatically center at that city.
The location of every city is encoded in the cities choice list. Note that the coordinates of their location are in the name column. I separated coordinates with an underscore because spaces are not allowed in the name column.
The calculation expression parses this value to extract and format the data to be passed to the geopoint question. For that, the substr function is used. I had to put care into ensuring that the different values encoded started and ended at fixed positions in the string. That is, I reserved the first 10 characters for the latitude, then I added the separator, and then I left the rest of characters for the longitude etc If needed, I would add extra zeros at the end to make sure the coordinates had exactly the expected number of characters. There are some functions like split, that would theoretically help us parse strings with more flexibility, but at the moment they are not yet supported in Survey123. To properly build the string representing the geopoint object, I used the concat() function.
type name label calculation choice_filter
| select_one continent | continent | Continent | ||
| select_one cities | cities | City | continent=${continent} | |
| geopoint | location | Map | concat(substr(${cities}, 0,10)," ",substr(${cities}, -10)) |
Encoding the coordinates in a choice list will work well for small numbers of points. Storing the coordinates in a CSV file and using pulldata() to get them is recommended if you plan to work with large lists.
Survey123 Connect for ArcGIS includes two sample XLSForms that will help you play with the concept of calculating geopoints. To open the Samples follow these steps:
- Open Survey123 Connect or ArcGIS
- Click on New Survey
- Select the Samples category from the dialog and look for the Calculate Location from Choice List, or Calculate Location from CSV
If you would like to block field users from overwriting the location set by your calculation, you can set your geopoint question to read-only.
So far, we have learned how a calculation can set the value of a geopoint, but you can also do the reverse. That is, you can use a calculation to extract data from a geopoint question, such as the X,Y and Z values and use them in your own expressions. This technique uses the pulldata() function and it is described in more detail in thehttps://community.esri.com/groups/survey123/blog/2016/11/03/extracting-information-from-geopoint-que... blog post.