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.
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:
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.
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 hundreds or thousands of points.
Please note that as of version 2.6, Web Forms do NOT support calculations on geopoints. Only the Survey123 field app will honor your geopoint calculations. Support for calculations on geopoints were added in Web Forms at version 2.7
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 thePulling data from geopoint questions blog post.