opendata: Open data from files, research platforms, online forms, and...

In R4VN: Health Data Analysis and Publication-Ready Reporting

Open data from files, research platforms, online forms, and databases

Description

Reads local/remote files and connects to supported research data sources. Existing file and REDCap behavior is retained. Additional connectors support KoboToolbox, Google Forms, Google Sheets, Microsoft Forms/Excel, and MySQL/MariaDB.

Usage

opendata(
  file = NULL,
  api = NULL,
  url = NULL,
  token = NULL,
  vars = NULL,
  obs = NULL,
  active = FALSE,
  labels = c("factor", "labelled", "numeric"),
  header = TRUE,
  sep = NULL,
  sheet = 1,
  range = NULL,
  skip = 0,
  na = c("", "NA"),
  encoding = "UTF-8",
  check.names = FALSE,
  records = NULL,
  fields = NULL,
  forms = NULL,
  events = NULL,
  quiet = FALSE,
  uid = NULL,
  server = NULL,
  form = NULL,
  access_token = NULL,
  question_names = c("id", "title"),
  sheet_id = NULL,
  drive_id = NULL,
  item_id = NULL,
  table = NULL,
  page_size = 1000L,
  host = "localhost",
  port = 3306L,
  dbname = NULL,
  database = NULL,
  user = NULL,
  password = NULL,
  query = NULL,
  ssl_ca = NULL,
  ssl_cert = NULL,
  ssl_key = NULL,
  db_timeout = 10,
  bigint = "integer64",
  ...
)

Arguments

file	File path or web URL. A bare file name is first resolved in the current working directory and, when not found there, in R4VN's bundled inst/extdata examples. Thus opendata("ivf_v3_vi.dta") opens the example Stata file shipped with R4VN. For Google Forms or Microsoft Forms exports, this may be the exported CSV/XLSX file. Omit when a direct API/database connector is used.
api	Optional source name: "redcap", "kobo", "googleform", "gsheet", "msexcel", "msforms", "mysql", or "mariadb". Common aliases are accepted.
url	API/project/form/sheet URL when applicable.
token	REDCap or KoboToolbox API token. For Google/Microsoft, use access_token; token is also accepted as a fallback.
vars	Optional variables to retain.
obs	Optional observations to retain. missing(x) is supported.
active	Logical; also place a working copy in active memory.
labels	How imported value labels are handled: "factor", "labelled", or "numeric".
header	Logical; first text/spreadsheet row contains names.
sep	Text-file delimiter. Defaults from extension.
sheet	Excel/online workbook sheet name or number.
range	Excel/online workbook cell range such as "A1:H500".
skip	Number of rows to skip for local files.
na	Strings interpreted as missing.
encoding	Text encoding.
check.names	Logical; make names syntactically valid.
records, fields, forms, events	Optional REDCap filters.
quiet	Logical; suppress summary messages.
uid	KoboToolbox asset UID. May be inferred from a Kobo project URL.
server	KoboToolbox server. Defaults to the Global server and may be inferred from url.
form	Google Forms form ID. May be inferred from a compatible form URL.
access_token	OAuth bearer token for Google or Microsoft APIs.
question_names	Google Forms variable naming: stable question "id" (default) or sanitized question "title".
sheet_id	Google Sheets spreadsheet ID. May be inferred from url.
drive_id, item_id	Microsoft Graph drive/item identifiers for the Excel workbook containing Microsoft Forms responses.
table	Microsoft Excel table name, or MySQL/MariaDB table name.
page_size	Number of records requested per API page.
host	MySQL/MariaDB server host.
port	MySQL/MariaDB TCP port, usually 3306.
dbname, database	MySQL/MariaDB database name. database is a friendly alias of dbname.
user, password	MySQL/MariaDB credentials. A read-only database account is strongly recommended.
query	Optional read-only SQL query. Use this instead of table for server-side filtering. Write/DDL statements are rejected.
ssl_ca, ssl_cert, ssl_key	Optional SSL CA/certificate/key paths for MySQL/MariaDB.
db_timeout	Database connection timeout in seconds.
bigint	How 64-bit database integers are returned; passed to RMariaDB.
...	Additional arguments for the existing format-specific local reader.

Details

Existing local-file and REDCap behavior is unchanged. When file is a bare file name that does not exist in the current working directory, opendata() also looks in the package's bundled extdata directory. This makes the teaching dataset available simply as opendata("ivf_v3_vi.dta") after R4VN is installed.

KoboToolbox uses API v2 and Token authentication. Google Forms direct access uses the official Forms API and OAuth. Google Sheets public share links can be read without OAuth when the sheet is accessible to anyone with the link; private sheets can be read with an OAuth access token.

Google Forms and Microsoft Forms response files exported to CSV/XLSX can be opened directly with opendata(file). api = "googleform" or api = "msforms" may also be supplied together with file as a friendly alias; in that case the normal file reader is used.

Microsoft Forms direct response access is handled through its linked Excel workbook via Microsoft Graph. MySQL/MariaDB uses DBI + RMariaDB and closes the database connection automatically before returning.

Value

A data frame.

Examples

# Bundled R4VN teaching dataset (Stata format).
if (requireNamespace("haven", quietly = TRUE) ||
    requireNamespace("readstata13", quietly = TRUE)) {
  ivf <- opendata("ivf_v3_vi.dta", quiet = TRUE)
  head(ivf)
}

## Not run: 
# Existing REDCap behavior
redcap <- opendata(
  api = "redcap",
  url = "https://example.org/api/",
  token = "REDCAP_TOKEN",
  active = TRUE
)

# KoboToolbox
kobo <- opendata(
  api = "kobo",
  uid = "aBcDeFg123",
  token = "KOBO_TOKEN",
  active = TRUE
)

# Public Google Sheet using only a share link
gsheet <- opendata(
  api = "gsheet",
  url = "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit?gid=0",
  active = TRUE
)

# Named tab and range from a public Google Sheet
gsheet2 <- opendata(
  api = "gsheet",
  url = "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit",
  sheet = "Responses",
  range = "A1:H500"
)

# Google Forms / Microsoft Forms: easiest route after exporting responses
gform_export <- opendata("google-form-responses.xlsx")
msform_export <- opendata("microsoft-form-responses.xlsx")

# Direct Google Forms API (OAuth token required)
gform <- opendata(
  api = "googleform",
  form = "FORM_ID",
  access_token = "GOOGLE_OAUTH_ACCESS_TOKEN"
)

# Microsoft Forms linked Excel workbook via Microsoft Graph
msform <- opendata(
  api = "msforms",
  item_id = "WORKBOOK_ITEM_ID",
  access_token = "MS_GRAPH_ACCESS_TOKEN"
)

# MySQL table
mysql_data <- opendata(
  api = "mysql",
  host = "db.example.org",
  dbname = "research",
  user = "reader",
  password = "PASSWORD",
  table = "participants"
)

# MySQL read-only query
mysql_subset <- opendata(
  api = "mysql",
  host = "db.example.org",
  database = "research",
  user = "reader",
  password = "PASSWORD",
  query = "SELECT id, age, sex FROM participants WHERE age >= 18"
)

## End(Not run)

R4VN documentation built on Sept. 30, 2026, 5:13 p.m.