Table of Contents

  1. Introduction
  2. Getting Started
  3. Layout and Navigation
  4. General Process
  5. Support and Feedback

1. Introduction

This user manual is designed to help users at various levels navigate and utilize the Respondent Driven Sampling (RDS) Monitoring Dashboard efficiently.

2. Getting Started

System Requirements

The application is built using Electron and is currently supported on Windows machines only.

Operating System
  • Windows 7 and later are supported, older operating systems are not supported (and do not work).
  • Both x86 and amd64 (x64) binaries are provided for Windows. Please note, the ARM version of Windows is not supported for now.
Hardware
  • Processor: Intel Pentium 4 or later, SSE2 capable
  • Memory: 512 MB of RAM

Accessing the Dashboard

  • To download the Dashboard, RDS toy datasets, and other tools, please visit the RDS Tools website.

  • Download the .zip file and extract to a convenient folder.

  • Next, open the ui.R file in RStudio. Visit the RStudio website for more information on RStudio.

  • Click the Run App button in the upper right.

3. Layout and Navigation

When the app opens, you will land on the Dashboard page where the core of the program is. (See Figure 1)


Figure 1 Dashboard Home
Figure 1 Dashboard Home


Side Panel
  • The side panel contains four steps with select buttons used to expand and collapse input fields.
Main Panel

  • The main panel is used for displaying data tables and plots, with input fields to customize the plots.

  • After generating different types of plot, tabs will appear at the top of the panel for easy navigation. (See Figure 2)

Figure 2 Navigation Tabs
Figure 2 Navigation Tabs

4. General Process

Step 1: Data Upload

  • Click on Browse to locate and upload a CSV or Excel file (max 10 GB) containing the survey data. (See Figure 3)

    Figure 3 Data Upload
    Figure 3 Data Upload


  • The Data tab will display the table, allowing you to inspect and interact with the data. The search function can be used to show only rows that contain the entered values. Clicking on the title of each column in the data sorts by the value in that column. (See Figure 4)

Figure 4 Data Tab
Figure 4 Data Tab

Step 2: Required Information

  • After importing the data into the dashboard, you must specify which columns (i.e., variables) contain the relevant information to use the dashboard functions. (See Figure 5)

  • This information allows our dashboard to link participants and depict the recruitment process. The necessary variables are:

    • Respondent ID

    • Redeemed coupon code: Code of coupons respondents used to participate. In some cases, this may be the same as Respondent ID.

    • Max coupon count: A maximum number of coupons issued to respondents. If a project issued a maximum of 3 coupons per participant, enter 3.

  • Coupon codes: Once you set value in Max coupon count, the system will determine the number of columns containing issued coupon codes that need to be selected. If Max coupon count=3, there will be three columns that will pop up.


Figure 5 Required Information
Figure 5 Required Information


Step 3: Plot Type

  • Users can select from four types of plot (See Figure 6). Detailed instructions for each type of plot are provided under Plot Types.


    Figure 6 Plot Types
    Figure 6 Plot Types


  • Additional information, such as demographics and geolocation, may be required depending on the type of graph you wish to create.

Step 4: Start Plot

  • After specifying all the essential columns, click the Start Plot button to generate the corresponding plot panels. This action creates a basic plot of the desired type. (See Figure 7)


Figure 7 Start Plot
Figure 7 Start Plot

Plot Types

Data Collection Progress

  • This plot displays the number of participants recruited or participating in the study over time.


    Figure 8 Data Collection Progress
    Figure 8 Data Collection Progress


  • To generate this plot, users are required to select a column containing data collection or interview dates for the Main variable. (See Figure 9)

    Figure 9 Data Collection Progress Plot Variables
    Figure 9 Data Collection Progress Plot Variables


  • A categorical variable may be selected as the Secondary factor. This will produce separate data collection progress plots for each level of the categorical variable.

    Figure 10 Data Collection Progress With Secondary Variable
    Figure 10 Data Collection Progress With Secondary Variable


  • After selecting one or both of the factors, click Plot to generate the plot.

Participant Characteristics

  • This plot illustrates the percentage of participants with the values of a categorical variable. This plot is best used to understand demographic characteristics within a dataset such as race or sex.


    Figure 11 Participant Characteristic
    Figure 11 Participant Characteristic


  • This plot features two select input fields: one for the Main factor and another for an Secondary factor. Selecting only the Main factor generates a bar plot showing percentages of values.

  • If a Secondary variable is also selected, the dashboard creates a stacked bar plot illustrating the distribution of main factor values across categories or values of the secondary factor. Both variables must be categorical.


    Figure 12 Participant Characteristic With Secondary Variable
    Figure 12 Participant Characteristic With Secondary Variable

Recruitment Chain

  • This plot visualizes a network graph created by linking participants through coupon distribution.

  • The basic plot, generated by selecting None as the Grouping factor highlights seed and non-seed participants, with seeds represented by larger circles and non-seeds by smaller circles.


    Figure 13 Recruitment Chain
    Figure 13 Recruitment Chain


  • Users have the option to select a categorical variable as the Grouping factor, which colors the nodes representing individual participants according to levels of the variable. (See Figure 14)


    Figure 14 Recruitment Chain With Secondary Variable
    Figure 14 Recruitment Chain With Secondary Variable


  • There are numerous layout options for the recruitment chain display. (See Figure 15 A and B for two of ten options)


    Figure 15A Recruitment Chain With Sphere Layout
    Figure 15A Recruitment Chain With Sphere Layout


    Figure 15B Recruitment Chain With Tree Layout
    Figure 15B Recruitment Chain With Tree Layout

Participant Mapping

  • If participant coordinates (latitude and longitude) are available, the dashboard can be used to generate an interactive map of their location and recruitment chains. (See Figure 16)


    Figure 16 Participant Map
    Figure 16 Participant Map


  • Each participant is depicted by a circle, with lines indicating coupon transactions between them.

  • Participants are assigned an order in the recruitment chain, referred to as a wave. For participants who initiate the chain (seeds), their wave number is 0. Users have the option to filter the network visualization by Wave (See Figure 17) and by Seed ID (See Figure 18).

    • When filtering by Wave, it is advisable to select all wave numbers before the one you are interested in for a more intuitive image. For example, if you are interested in wave 3, you should also select waves 0,1, and 2.


      Figure 17 Participant Map Filtered by Wave
      Figure 17 Participant Map Filtered by Wave


      Figure 18 Participant Map Filtered by Seed
      Figure 18 Participant Map Filtered by Seed

Plot Customization

  • The dashboard enables users to customize several aspects of each plot. At the bottom of each plot, there are tabs that can be selected to make changes. (See Figure 19)


    Figure 19 Plot Customization
    Figure 19 Plot Customization
Plot Title
  • The plot will automatically update to show a title entered in the box.
Font sizes
  • The font size for all of the text on the plot can be adjusted using the sliders.
Modify palette

  • The palette must be 8 colors.

  • Users have the option to clear the current palette and add desired colors incrementally to create a new palette.

  • Click the top bar to set a new color, and Add to include it in the palette. After selecting colors click Set to finalize the palette.

  • This update automatically applies the new color scheme to existing plots as well as new ones.

Display Options

  • The Participant Character plot allows for adjustment of the histogram bar width.

  • The Recruitment Chain plot can be displayed in a variety of layouts. The default is layout_with_fr.

Plot Download

  • Users can use the Download Image button to download a png image of the plot. A window will appear allowing the user to select a location for the file.

  • Users must select a Height and Width for the downloaded image. It is not advisable to go below the default size of 1200 pixels by 1800 pixels for the Data Progress and Participant Character plots, and 900 pixels by 900 pixels for the Recruitment Chain plot. The recommended ratio is of height to width is 2:3 for the Data Progress and Participant Character plots, and 1:1 for the Recruitment Chain plot.

  • The participant map can not be downloaded, but users may screenshot the map.

5. Support and Feedback

For feedback or suggestions, please visit our feedback page.