In the Survey Designer Management Panel you will see the Surveys currently uploaded (if any) and their status: whether they have been Modified or Published as well as their Records validation status. The operations available from this panel include: Survey Edit, Export, Import, Publish, Record validation, Delete. Details on these operations will be covered after the instructions on ho to set up a new survey.
To start setting up your first Survey click on New.
A pop up window will open requesting the user to enter a name for the survey, select the default survey language and choose from a template type. Selecting a Blank template means starting from scratch, with no pre set information loaded. Alternatively, it is possible to choose from templates in which some fields in the Code Lists are prefilled in accordance to pre-set survey specifications.
Note: additional languages can also be added at a later stage by clicking on the UN flag (top right corner) and select and add additional languages for the survey. The user can then switch from one language to another by selecting a language in the drop down menu on the top right corner of the screen. Note that the fields that allow multiple language will show a codified language abbreviation in parenthesis, for example (en) for english.
The user can now proceed to fill in the fields in each of the five tabs of the Survey designer: Survey, Code lists, Species list, Sampling Design and Schema.
In this tab the user is asked to provide general and basic information about the Survey.
The fields to be filled in are as follows:
- Name: (defined when the survey was created)
- Project name (): can be filled in to specify an additional name for the project.
- Description (): can be filled to include any additional note to describe the Survey
NOTE: Mandatory fields are bordered in red, while all others, when clicked, are bordered in blu.
Additional fields: Form versions, Spatial Reference System and Units.
Popup windows open by clicking the icon to the right of field name. Inside of each pop up window, new items can be: created by clicking on the Green “plus” button; moved up or down by clicking the up and down arrow; deleted by clicking the Red “minus” button.
Once finished, close the window by clicking Apply.
Form versions: This field can be used to keep track of successive versions of the Survey forms (for entering data). The user can add a new form version by clicking the Green “plus” button and specifying: Name (e.g. 1.0, 1.1 etc.); Label (a codified label used to express useful information (e.g. date, form version, location [e.g. BP 1.3.2010])); Description (any additional information); Date (usually the date of when that form version was first used .
Spatial Reference Systems (SRS): This field is used to specify the geospatial settings used in the survey by selecting a predefined SRS from the list (bottom left of the window). The user can enter information related to the Spatial Reference System(s) used in the survey by specifying: Id, Label, Description and Well Known Text.
Units: This field is used to define the units of measure that will be used throughout the Survey. A set of predefined units are automatically loaded. They include units to measure for Angles, Areas, Currency, Length, Mass, Ratio and Time. Should the user wish to include additional units he/she may do so by clicking the green “+” button and filling in the relevant fields: Name, Label, Abbreviation, selecting a Dimension, and Conversion factor.
This tab is used to define lists of codified information that will be used throughout the survey to provide options for specific fields during the data entry phase. If the user selected one of the pre-filled templates, several Code lists are loaded automatically. They include codified lists to define, for example, accessibility, land use classes, ownership etc. These fields are set up in accordance to pre-defined classification schemes however the user is free to add, remove or modify them. Code lists can be used to classify a wide range of attributes such as administrative levels, personnel, topographic elements and many more.
Adding a Code list
Code lists can be added in two ways: “manually” or by importing a pre-prepared file in csv format.
To add a code list manually click on the Green “+” button (bottom left corner of the window) and proceed to fill in: Name [mandatory field] (eg. region), Label: (eg. AdmLev-1-Reg), and Description (any additional specification). Then select the List type: whether the code list is flat or hierarchical. A flat list has a binary structure while a hierarchical list allows for sub (nested) levels. [See list types examples below].
Once a code list has been named, the actual items (codes and labels) should be entered.
Code and Label of each item of the code list can be added by clicking the smaller green “+” button and filling in Code [mandatory field] (eg. “1”) and Label (eg. Northern). This should be repeated for as many items there are in the Code list. Each item can then be edited (click on edit icon) or deleted (red “-“) button.
The user can also wish to include a Specify field by clicking the appropriate box. In this way, it will be possible to specify unlisted values in a text input field that will appear next to the code list item in the data entry form.
In order to keep a separate record of the code list, it is suggested to Export the code list by clicking the Export button (at the bottom of the window). This will automatically generate and download a csv file.
In the case of hierarchical Code lists, multple levels can be added by clicking on the “Add level” button.
While the manual process for adding code lists is perfectly legitimate and can be used for simple lists, for more complex list (eg. list that have many items or with a hierarchical structure) it is strongly recommended to prepare them in advance and upload them into Collect by clicking the Import button (at the bottom of the window). When clicking Import a pop up window will open and the user can import a code list (flat or hierarchical) from a csv file. From the same window the user can also download an example file, while clicking on the blue “i” button will open a window with specifications on how to set up the csv file.
To import the csv file, click on Select file, locate the file within your directory and then click on Start import. Upon successful upload an Import completed message will appear, click ok and proceed with a new upload or, if done, click close at the bottom of the window.
Example of Flat Code list
Example of Hierarchical Code list
This tab allows the user to add one or more species lists by uploading a file in csv format. The list should contain all the taxonomical species that the user will select from during data entry. Species lists should be as comprehensive as possible and should be created using all resources available in the country: taxonimical books, expert’s knowledge etc. For security reasons it will not be possible to add species during data entry. Additional species should instead be added to the csv file (by a system administrator) and the updated species list uploaded to Collect.
Adding a Species list:
The species list (CSV file) file should be prepared in advance following the formatting requirements indicated below.
The required columns are:
- no: numeric unique identifier associated to the species
- code: alphanumeric unique identifier code associated to the species
- family: family name of the species
- scientific_name: latin name of the species (genus + [optionally] species name + [optionally] subspecies name e.g. Pinus spp. or Pinus radiata).
Note: An Example file can be downloaded by clicking the button at the bottom center of the screen.
Optionally the user can specify other columns for the vernacular names of the species using the language code (in 3 characters ISO-639-2 format, e.g. ‘swh’ for Swahili, ‘eng’ for English) as header of these columns. The user can specify synonyms using “lat” as header (Latin language). Multiple values are allowed for vernacular names and they need to be separated with a slash ( / ) character.
When the csv file is ready for upload, click New and specify a Name for the list. Then click Import, select the file to be uploaded and wait for the confirmation window. The screen will now show the records present in the species list. Species lists can also be Renamed, Deleted or Exported. If needed, additional species lists can be created and uploaded in the same manner.
This tab is used to define the list of coordinates of each sample point location. This can be done by importing a CSV file that should be prepared following the formatting indicated below:
The csv file should contain:
- levelX_code columns: 1 column for each level X (maximum 3 levels, e.g. if you have 2 levels, cluster and plot, you will have a column “level1_code” with cluster id value and a column “level2_code” for plot id value);
- x: easting
- y: northing
- srs_id: id of the coordinate reference system, the same used as in the Coordinate Reference Systems settings of the survey
The csv file can be uploaded by clicking on the Import button. An Example file can be downloaded by clicking the button at the bottom center of the screen (see below) . If needed, the file can also be Exported.
Additional columns (to a maximum of 10) can be added to the csv file in order to record additional information related to the sampling points (eg. slope , administrative units, etc.) These values can be used as source data for expressions or calculated values in the survey definition.
This tab constitutes the core of the Survey design. It is at this stage that the user defines every item (entity) and related attributes that should be measured. Before starting to work on the Schema it is necessary to have a very clear idea of the logical structure of the survey and a detailed list of the variables to be measure during field work (and in general during the survey) and also decide on the optimal way of measuring each variable.
The first step is to define one (or more) Record type (the highest level of the hierarchical structure of the sampling design, typically the cluster, which contains plots. If the user started to work on the Survey Designer by selecting a blank template, it is now necessary to assign a name to the Record type (click on icon to the right of “Change it to your main tab label”) and give it an appropriate name (typically Cluster), then click Apply. Then don’t forget click Save (at the bottom of the page).
If additional Record types are needed (for example to define variables for a socio economic survey or any other type of survey) the user can do so by clicking on the green “+” button (edit and delete buttons are also available).
At this point Tabs, Entities and Attributes can be added.
Tabs do not have a role in the hierarchical and logical structure, rather they are used to arrange the way the data entry form will appear. At any time click on Preview to display the layout of the data entry form. If more tabs are present, they will be visible at the top of the form.
Entities: When adding an Entity, the user can choose among three types: Single (grouping), Multiple (form layout) or Multiple (table layout).
- Single (grouping): A Single entity is used to record an item (variable) that will appear only once (with a relationship 1:1 with its parent Entity). For example: start date (the date when the measurement work started on any given plot, will necessarily have a 1:1 relationship with its parent entity (for example, the plot). The term “grouping” means that a single entity can also be used to group a number of attributes all depending on the same entity (in our example, starting time, ending time etc.).
- Multiple (Form or Table layout): Multiple Entity are used when the relationship is 1:N meaning that there will be more instances of that entity all related to the parent entity. For example, plot (there will be more plots all referring to the parent entity Cluster, or, another example, tree: there will be more trees referring to the parent entity Plot. The difference between Form and Table layout refers to the graphical representation that the user wishes to give to that entity in the data entry form.
Attributes are always added in relation to an Entity and define the way in which the data is recorded. Attribute types are the following (each one with a unique recognizable label).
- Boolean: check/un-check
- Code: refers to a previously added Code lists
- Coordinate: allows to enter geographical coordinates (See Sampling design section)
- Date: entered in dd/mm/yyyy format
- File: allows to upload a file (eg. photos, notes, etc.)
- Number: numeric value (integer or real)
- Range: allows to define a numerical range
- Taxon: alllows to add a record from a previously addded Species list
- Text: allows to add free text
- Time: entered in hh:mm format
For each of the items that the user wishes to measure in the field, it is necessary to determine whether it is best expressed as an entity or an attribute and of which kind. As an example, a few variables measured at the Cluster level are listed below, indicating the type of considerations needed to determine whether it should be expressed as an entity or attribute.
- Cluster No.: is intended as a unique numerical identifier for each cluster, therefore it should be added as Number attribute.
- Accessibility: if it is used to indicate whether the Cluster was accessible or not, then it could be entered as a Boolean attribute (yes/no); in the case the user wishes to be able to include other “categories” of accessibility, thus it will be entered as a Code attribute.
- Starting Position: is clearly a Coordinate attribute as it indicates the geographical coordinates of where field work for a specific cluster started from.
- Time Study: the intention here is to record multiple information simultaneously: date and starting and ending time of the field work. In this case the most appropriate way is to enter it as a Multiple Entity in Table layout.
- Remarks: is simply allow for a space where notes can be added, clearly a Text attribute.
To add Entities and Attributes right-clicking on the previously created record type folder and make the appropriate choice.
While adding entities and attributes, the user is required to fill in a number of related characteristics, in the main window as for example shown in the image below.
Some of the parameters are common for different types of Entities or Attributes, while others are unique to a specific type. Below is a list of groups of parameters and related explanation.
|Name||attribute’s or Entity’s name|
|Type|| for Boolean (Y/N/Blank or Y/Blank); for Number (numerical type: integer / real); for Text (text box |
style: short= one row / memo= text box)
|Multiple||allows multiple entries for this attribute|
|– Min count||fixes minimum number of entries allowed|
|– Max count||fixes minimum number of entries allowed|
|Required||if checked, the record can be saved only if a valid value is entered for this attribute|
|– Required when||expression that specifies when the attribute is required (when “Required” is not checked)|
|Relevant when||function that determines under what conditions the field is applicable|
|– Hide when not relevant||if checked, the field will be hidden in the data entry form when the condition is not verified|
|Is key||if checked, this attribute serves as a unique identifier|
|Code list||select a code list already created or create one|
|– Strict||if checked, once code list is defined, no additional code options can be added|
|Calculated||if checked, the input field won’t be editable and the value will be generated at runtime according to the specified Default Value|
|Max size MB||defines max allowed size for file upload|
|– Allowed extension||defines allowed extension types for file upload|
|Species list||Select a species list|
|– Highest rank||Defines highest rank in species taxonomy (family, genus, species, sub-species, variety)|
|Auto-complete group||(only for text attributes) if specified, text auto complete will retreive entries from the list of previously digited values|
|Show row number in tables||If checked, it allows to show row number in tables|
|Show count in record summary list||If checked, it allows to Show count in record summary list|
|Units of measurements (only for numerical attributes)|
|Is default||specifies which unit of measure is default|
|Unit||select from the list of unit of measurement (defined in the survey tab)|
|Decimal digits||controls number of decimal digits that will be diplayed|
|Labels and description|
|Single instance||Label if single instance|
|List heading||Label if multiple instances|
|Field number||Additional labeling field|
|Description||Free text description|
|Introduced in version||allows to keep track of since which survey version a specific Entity/Attribute has been added to the schema.|
|Removed since version|| allows to keep track of since which survey version a specific,Entity/Attribute has been removed to the |
|Column||determines the position of the node (entity/attribute) in the field form layout.|
|Column span||determines the number of columns that the node (entity/attribute) should span across *** (click ‘i’ button to view an example|
|Width||sets the width of the column ((blank=default)|
|Label width||sets the width of the label ((blank=default)|
|used to determine how to handle empty values when record is submitted from data entry phase to data cleansing phase|
|Constant value||value that will replace empty field|
|Expression||expression that will calculate the value to replace empty field|
|Apply when||sets the condition for when the replacement should occur|
|used to automatically flag errors during field data collection (using Collect Mobile) or during data entry. Using checks greatly minimizes data entry mistakes and facilitates data cleansing.|
|Type|| Comparison – checks the value entered against a value or range of values |
Custom – freely customizable check with an expression
Distance – (only for coordinate attributes) checks that the coordinate entered is within previously specified limits
Pattern – (only for text attributes) checks that the text is entered according to a predifined format
Uniqueness – checks that the entered values is unique (not repeated) within a specified group of values
|Severity|| Error – blocks the data entry user from submitting the record to data cleansing |
Warning – assigns a warning flag to the record but does not prevent submission to data cleansing
|Message||message to be displayed to flag error/warning|
|Apply when||allows to specify when the check is applicable.|
|Expression||expression that defines the logic of the check|
Once all entities and attributes have been entered and defined, the hierarchical structure of the survey will look similar to the image below.
Data Structure vs. Entry Form
While constructing the hierarchical structure of Entities and Attributes, and their organization in Tabs (folders), it is possible to switch the View mode: Data Structure or Entry Form. The first option will open all the branches and sub-branches to reveal every element and its properties (as in the image above), while the second option will collapse the elements into their respective Folders (image below). The same process can be achieved by clicking the small buttons [+] and [-] to Expand or collapse all nodes. This option becomes useful as the structure becomes more and more complex. The two arrows pointing up and down are used to move nodes accordingly.
At any time it is possible to visualize the appearance of the data entry form by clicking on the Preview button.