Skip to content

2. How to install

Jump to bottom
Máximo Ramírez edited this page Nov 10, 2017 · 6 revisions

Technology requirements

  • Android 4.2 and above.
  • Internet connection not required to census, sample, survey or aggregate data.
  • Internet connection required to transfer data to a central server based on ODK Aggregate.
  • Spreadsheets to design questionnaires.
  • ODK 2.0 suite of tools to convert questionnaires to XForms. Recommended rev 126

Steps to install and configure EpiSample

  • Design geographical hierarchy.
  • Install EpiSample on Android.
  • Rename Android devices for Wi-Fi Direct communication.
  • Link device with ODK Aggregate.
  • Setup interviewer/device information.
  • Load place name list.
  • Configure Collect module.
  • Select team leader device.
  • Protect administration settings.
  • Configure Navigate module (setup household survey questionnaire).

Before installing EpiSample

EpiSample allows enumerators to easily select a specific geographic region from a list of hundreds or even thousands of place names by traversing through a hierarchical list that starts from the highest geographic level (for example, Province) to the lowest level (for example, "EA" or Enumeration Area).

The list of regions is formatted to match how ODK Collect implements secondary instance definitions through Cascading Selects. So if you used such a list in previous ODK Collect surveys, the same list can be re-used for EpiSample.

Geographic regions are defined in a CSV file called config.csv that must be located in the following folder in the Android device (internal storage or sdcard):

/episample/survey/metadata/placeName/config.csv

The config.csv file must contain a geographic hierarchy as follows:

Hierarchy Name Hierarchy ID Area Name Hierarchy ID Nesting Reference
Province 1 Province 1
Province 2 Province 2
Province 3 Province 3
District 1 District 1 1
District 2 District 2 1
District 3 District 3 2
District 4 District 4 2
District 5 District 5 3
Chiefdom 1 Chiefdom 1 1
Chiefdom 2 Chiefdom 2 1
Chiefdom 3 Chiefdom 3 2
Chiefdom 4 Chiefdom 4 2
Chiefdom 5 Chiefdom 5 3
EA 1 EA 1 1
EA 2 EA 2 1
EA 3 EA 3 2
EA 3 EA 4 2
EA 3 EA 5 3

This hierarchy represents the following geographical structure:

  • Country
  • Province 1
    • District 1
      • Chiefdom 1
        • EA 1
        • EA 2
      • Chiefdom 2
        • EA 3
        • EA 4
    • District 2
      • Chiefdom 3
        • EA 5
      • Chiefdom 4
  • Province 2
    • District 3
      • Chiefdom 5
    • District 4
  • Province 3
    • District 5

Finally, the config.csv file is a comma separated CSV file without headers:

Province,1,Province 1,
Province,2,Province 2,
Province,3,Province 3,
District,1,District 1,1
District,2,District 2,1
District,3,District 3,2
District,4,District 4,2
District,5,District 5,3
Chiefdom,1,Chiefdom 1,1
Chiefdom,2,Chiefdom 2,1
Chiefdom,3,Chiefdom 3,2
Chiefdom,4,Chiefdom 4,2
Chiefdom,5,Chiefdom 5,3
EA,1,EA 1,1
EA,2,EA 2,1
EA,3,EA 3,2
EA,3,EA 4,2
EA,3,EA 5,3

Of course, hierarchy levels (in the previous example Province, District, Chiefdom and Enumeration Area or EA) can be completely customized according to the geopolitical reality of a concrete geographical area.

How to install EpiSample on an Android device

  1. If EpiSample, ODK Collect or ODK Survey were previously installed on the current device, uninstall them and remove any folder (from the device internal storage or sdcard) related to any of these applications:
/episample
/opendatakit
/odk
  1. Install EpiSample App from the Google Play Store (This manual was produced by using the 1.0.5 version).
  2. Run EpiSample once to create the EpiSample folder and database on the device (internal storage or sdcard).
  3. Copy config.csv file to the Android device (internal storage or sdcard):
/episample/survey/metadata/placeName/config.csv

Before configuring EpiSample

As it was commented in the Features section of the about page, EpiSample:

Send out multiple teams with multiple devices to conduct a census and aggregate all of the census data onto one device (such as a team leader device) for sampling, without the need for a laptop, Internet or cables.

The EpiSample App allows to communicate EpiSample instances among different Android devices by using Wi-Fi Direct technology. Therefore, the EpiSample App may be configured as the team leader device or as an enumerator device (In the configuration section in this page will be shown how to do this).

EpiSample Wi-Fi Direct Communication

Therefore, it is useful to rename Android devices in order to identify them during this communication. For renaming the Android devices just follow the next steps:

  1. Go to Android settings.
  2. Tap the Wi-Fi button.
  3. Make sure Wi-Fi is enabled or enable it.
  4. Tap the option button (either the hardware button or the three dots in the upper-right corner, if the device doesn't have a hardware option button).
  5. This should bring up a list of items including Wi-Fi Direct, or an Advanced Settings button which opens this list of items. Click on the Wi-Fi Direct option.
  6. Tap again the option button and then Configure Device.
  7. Enter the device name and tap on Save.

Note: A good practice here is to label all the devices and use this identification in the Wi-Fi Direct configuration.

How to configure EpiSample App

Task 1: Link device with ODK Aggregate

The first task to do is linking the Android device which will transfer the data to the ODK Aggregate server:

  1. Open the EpiSample App.
  2. Tap the option button (either the hardware button or the three dots in the upper-right corner, if the device doesn't have a hardware option button).
  3. This should bring up a list of items including Change Settings. Click on Change Settings.
  4. In the Change Settings view you may configurate:
  • The ODK Aggregate server parameters.
  • The Client settings ??????
  • The interviewer and device information.
  1. In the server section complete the URL, Username and Password parameters (Usually, it is not needed to touch the other server parameters. For a complete description of all the parameters go to the components page).

Task 2: Setup interviewer/device information

The second task is to setup which user will be using this EpiSample instance and from which device. This is done in the Change Settings view too:

  1. In the Change Settings view, scroll down until the interviewer/device info section.
  2. Complete the Interviewer Name, Phone Number and Device Name.

Note: The device name is used to record the name of the device. The name is typicality a name or ID that is physically painted or labeled on the device. This is independent from what is set in the Wi-Fi Direct settings although you can may use the same value.

Task 3: Load place name list

The third task is to load the place name list to the EpiSample database. This is basically parsing the config.cvs file with the geographical hierarchy:

  1. Tap the option button from the home view (either the hardware button or the three dots in the upper-right corner, if the device doesn't have a hardware option button). This should bring up a list of items including Admin Settings. Click on Admin Settings.
  2. Click on Place Name List and then on the Load button.

Task 4: Configure Collect module

The fourth task is to setup the Collect Module settings:

  1. Tap the option button from the home view (either the hardware button or the three dots in the upper-right corner, if the device doesn't have a hardware option button). This should bring up a list of items including Admin Settings. Click on Admin Settings.
  2. Scroll down until the Collect Module Setting section. In this section you may configurate the Collect view:
  • GPS Accuracy Thresholds: You can define here the worst accuracy that points may have. If this parameter is defined to 10 meters, during the collection process if some GPS point has a worse accuracy (ex. 20 meters), the Collect module will warn about it, and if the enumerator records the point anyway, it will be stored as Invalid.

Collect Module Invalid Point

  • Require Comment: The Collect view, among other information allows to attach a comment for each collected point. This parameter indicates whether this comment is mandatory or not.
  • Auto Increment House Number: The Collect view, among other information allows to assign a House Number, which can be whatever number or a sequence of auto increment numbers managed by EpiSample. This parameter indicates if the house number is incremented automatically after saving a point.
  • Allow to Edit Saved Data: EpiSample allows to edit census points directly from the Collect module. Indeed, in the Admin Settings view, there is a parameter called Edit Census inside the User Can Access Main Menu Items section. Note that if you choose to allow to edit saved data, GPS coordinates will be overwritten with the location of the device during editing.
  • Device has low quality GPS: The Collect view, among other information allows to collect the GPS coordinates. In devices that have low GPS quality you may enable this parameter to add a delay while collecting GPS information. Initially, giving more time to the device to collect GPS data increases GPS accuracy.
  • Delay (Minute:Second): If the last parameter is enabled, you can define the duration of the delay while collecting GPS information here. By default it is 30 seconds.

Collect Module GPS Delay

Task 5: Select team leader device

As it was already explained in the Before configuring EpiSample section of this page, EpiSample App may be configured as the team leader device os an enumerator device. Thus, the Send/Receive module allows the data collection team to aggregate all the collected data on the team leader device through Wi-Fi direct technology, i.e. without the need for a laptop, Internet or cables. This configuration is done in the Admin Settings view:

  1. Tap the option button from the home view (either the hardware button or the three dots in the upper-right corner, if the device doesn't have a hardware option button). This should bring up a list of items including Admin Settings. Click on Admin Settings.
  2. Scroll down until the Send/Receive Module Setting section:
  • Device belongs to team lead: In the Android device that will be used by the team leader for data aggregation, this parameter must be enabled.
  • Turn on and off WiFi automatically: In order to save device battery, EpiSample allows to work with the Android Wi-Fi feature disabled. If this parameter is enabled, the App will enable the Android Wi-Fi automatically when required (i.e. when transferring data).

Task 6: Protect administration settings

Because any user may access initially the Admin Settings view, those critical parameters as GPS Accuracy Thresholds or Edit Saved Form could be altered by any field worker. For protecting these settings:

  1. Tap the option button from the home view (either the hardware button or the three dots in the upper-right corner, if the device doesn't have a hardware option button). This should bring up a list of items including Admin Settings. Click on Admin Settings.
  2. Click on Admin Password.
  3. Enter and confirm an administrator password. Thus, any time any user click on the Admin Settings button, EpiSample will require a password for opening this view.

Task 7: Configure Navigate module (setup household survey questionnaire)

As EpiSample is an application built off of ODK 2.0 tools forms must follow the structure of ODK Tables.

Tables is a program that allows you to visualize and edit data, revisiting existing data and syncing it with an ODK Aggregate instance in the cloud. Using Tables as your entry-point to data collection, you will be able to gather data using ODK Survey or ODK Collect, sync it to a server, and have other users download and edit the data on their own devices.

Note: EpiSample is an ODK Survey App.

Therefore, ODK forms are more than just a simple XML file describing the questionnaire structure. In this case, each data collection instrument is a folder containing the following components:

  • episample_form
    • forms
      • episample_form
        • formDef.json
    • definition.csv
    • properties.csv
    • tableSpecificDefinitions.js

These kind of instruments may be designed in a different way with the support of Application Designer. It is not the purpose of this section to explain how to design a survey for EpiSample. Here it is described how to setup this surveys on the EpiSample App. For getting started on how to design these forms, read the page Design a questionnaire.

Data collection instruments are located in the following folder in the Android device (internal storage or sdcard):

/episample/survey/tables

In that folder you may find initially the census directory which is the ODK 2.0 instrument used by EpiSample for collecting geographical points. Of course, this instrument follows the structure of ODK Tables too.

For setting the household survey questionnaire in EpiSample follow the next steps:

  1. Copy the directory with the ODK 2.0 instrument to the tables folder.
/episample/survey/tables/episample_form/forms/episample_form/formDef.json
/episample/survey/tables/episample_form/definition.csv
/episample/survey/tables/episample_form/properties.csv
/episample/survey/tables/episample_form/tableSpecificDefinitions.js
  1. Close completely EpiSample if it is opened and open it again for the App to scan the tables folder.
  2. Tap the option button from the home view (either the hardware button or the three dots in the upper-right corner, if the device doesn't have a hardware option button). This should bring up a list of items including Admin Settings. Click on Admin Settings.
  3. Introduce the administration password if you already protected the administration settings.
  4. Scroll down until the Navigate Module Setting section:
  • Choose Form: Click here to select the form to be used by the Navigate module. If you copied correctly the directory with the ODK 2.0 instrument, it should open a pop-up with the list of instruments available.
  • Show filter by place name icon: The Navigate module allows to filter collected points by type of point (Main points, Additional points, Alternate points, Excluded points, Points not selected and Finalized points. By enabling this option, enumerators will be able to filter by enumeration area.
  • Show mark as finalized by friends: Enumerators can mark points as finalized by a colleague if they find a household which has already been surveyed, and if this parameter is enabled.
Clone this wiki locally