survey_app: Launch data entry app
In ericmkeen/suRvey: Data Entry App for Wildlife Surveys

survey_app

R Documentation

Launch data entry app

Description

This function launches a Shiny app designed to optimize data entry during wildlife surveys. The app was designed with marine mammal surveys in mind, but should be generalizable for other contexts and target species. The app should be useful for both stationary and transect-based surveys. Layout has been optimized for touch screens.

Usage

survey_app(
  observers,
  platforms,
  optics,
  landmarks,
  cues,
  species,
  behaviours,
  scan_target = 15,
  gps_interval = 10,
  data_width = 21,
  scroll_height = 475,
  button_size = 200,
  button_padding = 30,
  keypad_size = 250,
  keypad_padding = 20,
  tab_size = 150,
  tab_width = 150,
  comment_1 = "Photo-ID acquired.",
  comment_2 = "Memorable sighting!",
  comment_3 = "Conditions changed dramatically during scan.",
  comment_4 = "Scan cut short early.",
  comment_5 = "Severe revision needed -- fix manually later!",
  comment_6 = "App crashed -- trying again.",
  beeps = FALSE
)

Arguments

`observers`	A character vector of observer names, initials, or codes.
`platforms`	A character vector of platform names or sampling locations.
`optics`	A character vector of optics used to detect wildlife (e.g., `"Binocs"` or `"Naked eye"`). Option handling: If this isn't relevant to your study, provide a single value, e.g., 'eyes'. If you want to make sure that this value is always specified with each sighting, make the first value `"N/A"`. When you do this, you will not be allowed to log a new sighting until a value other than `"N/A"` is selected.
`landmarks`	A character vector of landmarks that a detection can be in line with. This is useful in stationary surveys, to keep track of multiple sightings at once, and to sanity-check bearing angles during analysis. See option handling above.
`cues`	A character vector of detection cues that triggered the sighting. See option handling above.
`species`	A named list of character vectors, each specifying species options for a single type or category of species. For example, in a marine mammal survey, you may have two main types of detection: marine mammals or vessels. You would then have a `species` input like so: `⁠list('MarMam' = c('species1', 'species2', 'etc'), 'Vessel' = c('type1', type2', 'etc')⁠`.
`behaviours`	A named list of character vectors, each specifying the behavior options for each type/category in your `species` list. This list needs to be the same length as the `species` list.
`scan_target`	Beginning of default inputs: target duration of systematic scans, with a default of 15 minutes. When a scan is started, a timer begins. When the `scan_target` duration is exceeded, a sound will indicate that the observer may end the scan. If you do not want to use this feature, set to `Inf`.
`gps_interval`	Interval between GPS position updates, in seconds (default = 10 sec). This feature is only available for devices with GPS enabled (e.g., tablets and the newest laptops). If the device you are using does not support GPS, position updates will be turned off. This feature is in beta – not yet guaranteed to work. The code used to develop this was adapted from this Github account.
`data_width`	The number of data fields expected in your survey data. The default is 20, meaning total `.csv` width will be 23 columns (timestamp and event code account for the other two columns), which will work for the packaged version of this app. We included this as an input in the event that you wish to download and customize the function code; this input makes it easier to adjust the width of your survey data files.
`scroll_height`	This and the next several inputs relate to optimizing display on your specific device. This input defines how 'tall' a scroll box should be, in pixels. Smaller values will work for smaller screens or screens with lower resolution.
`button_size`	Percentage by which to scale font size of buttons in the app. Larger values create more visible button text.
`button_padding`	The margin for buttons, in pixels. Larger values make the buttons larger.
`keypad_size`	Like `button_size` above, the percentage by which to scale the numbers on the app's number keypad.
`keypad_padding`	Like `button_padding` above, this lets you adjust the size of the number keypad buttons.
`tab_size`	The percentage by which to scale the font size of the tab titles.
`tab_width`	The width of tabs, in pixels. If the size or resolution of screen causes the tabset to wrap onto two lines, you can prevent that by adjusting this value down.
`comment_1`	This and the next several inputs allow you to define 'canned' comments that can be efficiently logged on the "Comments" tab using a single touch of a button. This feature can be useful if you regularly log the same type of comment throughout the day during surveys. These canned comments will appear as buttons in the order you specify here. Note that the comment text cannot accepts commas; any commas you enter will be removed before storing the comment in the data file.
`comment_2`	Second canned comment.
`comment_3`	Third canned comment.
`comment_4`	Fourth canned comment.
`comment_5`	Fifth canned comment.
`comment_6`	Sixth canned comment.

Details

Typical workflow:

Open an R script in your working directory and setup your survey_app() function call.
Run it to launch the app.
On the "Effort" tab, update observer positions and "Start scan".
On the "Conditions" tab, update sighting conditions. You will not be able to store conditions until the boundaries of the conditions have been specified. This app uses a concept of 'condition zones' to allow you to describe varying conditions in different regions of your viewshed. A condition zone is a portion of searchable area that has left and right boundary edges (described using compass bearing) and close and far boundary edges (described using an estimated distance). You can store as many condition zones as you need in order to describe condition zones. Subsequent processing functions will sort multiple condition zones from widest to narrowest, which means that you can specify a broad condition zone (1 - 359 degrees, 0 km to 30 km away) then specify narrow condition zones to describe small exceptions to the most prevalent conditions.
On the "Sightings" tab, enter detections while you search. You will not be able to store a sighting unless all required fields at the top of page have been modified.
Use the "Update" tab to update or elaborate upon a sighitng you have already logged. On this tab, you can update your position estimate, add additional group size estimates from other observers, specify other species in the sighting if it is a mixed-species group, and update behaviors. Note that this tab should not be used to correct or fix erroneous data entries. You can do that directly under the "Review" tab. Also note that you will not be able to log an update until you select the sighting you are updating from the table provided in the tab.
On the "Review" tab, check on the data you are entering. Scroll down to see the most recent entries. When you click on a row (or multiple rows), you will have the option to delete it or to copy it. You can then click on another row and paste that row below it. You can then click on individual fields and edit them directly. Each time you make an edit, the data file will be updated. (So be careful!).
When you are ready to end the scan, go back to the "Effort" tab and end the scan.
When you are ready to close the app, just 'X' out of the app window.

Value

This function will launch a Shiny app.

The first time you run the app, a folder named "data" will be created within your working directory. The app stores data in .csv files within that folder, one .csv for each date (format: yyyy-mm-dd.csv). The first time the app is launched on a given date, that data file will be created. In subsequent launches on the same date, the pre-existing file will be appended with new data.

Rows of data are added to this file as you work within the app. You can close the app at any time without affecting your data file. To close the app, simply 'X' out of the app window. You may also need to press the "Stop" sign in the R/RStudio GUI.

The app logs 6 types of data, described in detail below:

Effort updates, with the following data fields:
1. System timestamp (⁠yyyy-mm-dd hh:mm:ss⁠)
2. Event code (EFF)
3. Effort status (1 = On systematic effort; 2 = Off systematic effort)
4. Observer on data entry duty / primary observer
5. Left observer, if any
6. Right observer, if any
7. Independent observer, if any
8. Research platform / sampling location
Condition updates:
1. System timestamp (⁠yyyy-mm-dd hh:mm:ss⁠)
2. Event code (SEA)
3. Left edge of condition zone (degrees)
4. Right edge of condition zone (degrees)
5. Close/near edge of condition zone (estimated km)
6. Far/distance edge of condition zone (estimated km)
7. Beaufort sea state
8. Visibility (km)
9. Precipitation status
10. Fog status
11. Haze status
12. Horizon smear status (distortion caused by radiant heat)
13. Glare status
14. Left edge of glare, if any (degrees)
15. Right edge of glare, if any (degrees)
New sightings:
1. System timestamp (⁠yyyy-mm-dd hh:mm:ss⁠)
2. Event code (SIT)
3. Unique sighting number (based on all sightings within data files within the "data" folder).
4. Bearing
5. Reticle reading
6. Optical instrument used to measure reticle
7. Estimated distane (km)
8. Landmark in line with the sighting
9. Detection cue
10. Maximum estimate of group size
11. Minimum estimate of group size
12. Best estimate of group size
13. Species type/category
14. Species name
15. Primary behaviour
16. Secondary behaviour
17. Tertiary behaviour
18. Direction of movement
19. Threat interaction? (TRUE or FALSE)
20. Number of calves in group
21. Number of males in group
22. Acoustic status
23. System timestamp of photograph taken of detection at given bearing (useful if, for example, you want to measure pixels in an image to triangulate the position of a detection within a photograph)
Sighting updates:
1. System timestamp (⁠yyyy-mm-dd hh:mm:ss⁠)
2. Event code (UPD)
3. Sighting number being updated
4. New bearing
5. New reticle
6. How reticle was measured (optics)
7. New estimated distance
8. Observer contributing new estimate
9. Whether group size has changed or is just being estimated again
10. Maximum group size estimate
11. Minimum group size estimate
12. Best group size estimate
13. Whether or not this is a mixed-species group
14. Species name of second species in group
15. Percent of group represented by this second species
16. Species name of third species in group
17. Percent of group represented by this second species (ensure that this plus the percentage for species 2 does not exceed 99)
18. Updated primary behaviour
19. Updated secondary behaviour
20. Updated tertiary behaviour
21. Updated threat interaction
22. Updated acoustic status
23. System timestamp of photograph taken of detection at given bearing (useful if, for example, you want to measure pixels in an image to triangulate the position of a detection within a photograph)
Comments:
1. System timestamp (⁠yyyy-mm-dd hh:mm:ss⁠)
2. Event code (COM)
3. Sighting number associated with this sighting, if any
4. The comment
Position updates:
1. System timestamp (⁠yyyy-mm-dd hh:mm:ss⁠)
2. Event code (*)
3. Latitude, decimal degrees
4. Longitude, decimal degrees
5. GPS time

Examples

# Customize settings =======================================

observers <- c('Grace','Janie','Chenoah', 'Ben')

platforms <- c('Inside','Outside')

optics <- c('N/A','Big Eyes', 'Binocs', 'Scope', 'Naked Eye')

landmarks <- c('N/A','Gil Mtn', 'CMP peaks', 'Otter',
               'Twartz', 'Farrant', 'N Fin shore')

cues <- c('N/A','Blow','Vessel','Body','Fluke','Splash','Sound')

species <- list('MarMam' = c('Humpback', 'Fin', 'Dalls porpoise',
                             'Harbour seal', 'Stellars sea lion',
                             'Elephant seal', 'Killer whale'),
                'Vessel' = c('Large rec', 'Small rec', 'CFV', 'Sailing',
                             'Tug only', 'Tug+barge', 'Gitgaat',
                             'Research', 'Cruise', 'Tanker'))

behaviours <- list('MarMam' = c('Active', 'Sleep', 'Feeding',
                                'BNF', 'Milling', 'Robust', 'Fast travel',
                                'RE-TR'),
                    'Vessel' = c('Fast travel', 'Slow travel', 'Fishing',
                                 'With whales', 'Anchored'))

# Launch app =======================================

if(FALSE){ #not run
survey_app(observers,
           platforms,
           optics,
           landmarks,
           cues,
           species,
           behaviours)
}

ericmkeen/suRvey documentation built on Feb. 5, 2025, 7:44 a.m.