params_from_gs: Download tabular survey parameters from Google Spreadsheets

In maxheld83/shinySurvey: What the Package Does (One Line, Title Case)

Description

When googlesheets4::gs4_has_token(), returns updated ss from sheet, otherwise local copy from last run. See googlesheets4::read_sheet() for details.

Usage

params_from_gs(
  sheet,
  ss = getOption("shinySurvey.ss"),
  dir = getOption("shinySurvey.dir"),
  update = googlesheets4::gs4_has_token(),
  ...
)

Arguments

sheet	Sheet to read, in the sense of "worksheet" or "tab". You can identify a sheet by name, with a string, or by position, with a number. Ignored if the sheet is specified via range. If neither argument specifies the sheet, defaults to the first visible sheet.
ss	Something that identifies a Google Sheet: its file ID, a URL from which we can recover the ID, an instance of googlesheets4_spreadsheet (returned by gs4_get()), or a dribble, which is how googledrive represents Drive files. Processed through as_sheets_id().
dir	[character(1)] giving the directory to store serialised sheet. Should be under version control.
update	[logical(1)] giving whether the file in dir should be updated. Under the default googlesheets4::gs4_has_token(), the data will be updated whenever a token is available.
...	Arguments passed on to googlesheets4::read_sheet range A cell range to read from. If NULL, all non-empty cells are read. Otherwise specify range as described in Sheets A1 notation or using the helpers documented in cell-specification. Sheets uses fairly standard spreadsheet range notation, although a bit different from Excel. Examples of valid ranges: "Sheet1!A1:B2", "Sheet1!A:A", "Sheet1!1:2", "Sheet1!A5:A", "A1:B2", "Sheet1". Interpreted strictly, even if the range forces the inclusion of leading, trailing, or embedded empty rows or columns. Takes precedence over skip, n_max and sheet. Note range can be a named range, like "sales_data", without any cell reference. col_names TRUE to use the first row as column names, FALSE to get default names, or a character vector to provide column names directly. If user provides col_types, col_names can have one entry per column or one entry per unskipped column. col_types Column types. Either NULL to guess all from the spreadsheet or a string of readr-style shortcodes, with one character or code per column. If exactly one col_type is specified, it is recycled. See Details for more. na Character vector of strings to interpret as missing values. By default, blank cells are treated as missing data. trim_ws Logical. Should leading and trailing whitespace be trimmed from cell contents? skip Minimum number of rows to skip before reading anything, be it column names or data. Leading empty rows are automatically skipped, so this is a lower bound. Ignored if range is given. n_max Maximum number of data rows to parse into the returned tibble. Trailing empty rows are automatically skipped, so this is an upper bound on the number of rows in the result. Ignored if range is given. n_max is imposed locally, after reading all non-empty cells, so, if speed is an issue, it is better to use range. guess_max Maximum number of data rows to use for guessing column types. .name_repair Handling of column names. By default, googlesheets4 ensures column names are not empty and are unique. There is full support for .name_repair as documented in tibble::tibble().

Value

A tibble

Storing parameters on goooglesheets

On the one hand, it is best to keep all survey application parameters (such as response options) under source control management (SCM). On the other hand, some study collaborators may want to frequently and easily change parameters, and be unable or unwilling to use SCM.

This function allows such "non-tech" collaborators to edit survey parameters in a Google Spreadsheet online, while regularly committing their contributions to the source.

To use this function:

1. Set up a Google Spreadsheet; authorize collaborators and optionally add write protections and notifications for the developer where appropriate.

2. Let collaborators edit the Google Spreadsheet.

3. Whenever an edit has been made, the developing collaborator can pull updates from Google Spreadsheets using this function from her local development machine (or wherever (googlesheets4::gs4_has_token()) and commit the result as a deparsed tibble.

Ensure that changing entry parameters will not compromise data collection, the database schema or analysis.

Best for tabular data

This helper pertains only to those survey parameters best edited and represented in tabular form, such as dropdown options in different languages and the like. Longer strings (several sentences), especially with markup, are awkward in spreadsheets and deparsed tibble::tribble()s and better served via strings_from_mdfile().

maxheld83/shinySurvey documentation built on May 21, 2020, 3:26 p.m.