,
Trym Nohr Fjørtoft [ctb] | Title: | Connect to the 'nettskjema.no' API of the University of Oslo |
|---|---|
| Description: | Enables users to retrieve data, meta-data, and codebooks from <https://nettskjema.no/>. The data from the API is richer than from the online data portal. Mowinckel (2021) <doi:10.5281/zenodo.4745481>. |
| Authors: | Athanasia Mo Mowinckel [aut, cre]
,
Trym Nohr Fjørtoft [ctb] |
| Maintainer: | Athanasia Mo Mowinckel <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.4.008 |
| Built: | 2024-10-13 03:48:43 UTC |
| Source: | https://github.com/capro-uio/nettskjemar |
Function works on meta-data downloaded from a form. It will return a data.frame in long format with meta-data information from a specific nettskjema form.
codebook(meta_data, form_id)codebook(meta_data, form_id)
meta_data |
form meta-data from |
form_id |
integer. Number of the form to retrieve |
long format tibble with meta-data for a specific nettskjema
## Not run: meta_110000 <- nettskjema_get_meta(110000) codebook(meta_110000) ## End(Not run)## Not run: meta_110000 <- nettskjema_get_meta(110000) codebook(meta_110000) ## End(Not run)
The raw codebook is a list
of answers and questions with
unique ids for both, and the text associated
with them. This information can be retrieved
from the raw nettskjema data. This can be useful
if the nettskjema submission data has been returned
with as_is = TRUE.
get_raw_codebook(form_id, token_name = "NETTSKJEMA_API_TOKEN", ...)get_raw_codebook(form_id, token_name = "NETTSKJEMA_API_TOKEN", ...)
form_id |
integer. Number of the form to retrieve |
token_name |
character. Name to give the token, defaults to 'NETTSKJEMA_API_TOKEN' |
... |
other arguments to |
long format tibble with meta-data for a specific nettskjema
## Not run: form_id <- 100000 get_raw_codebook(form_id) Or if the token is saved in a non-standard name get_raw_codebook(form_id, token_name = "MY_NETTSKJEMA_TOKEN_NAME") ## End(Not run)## Not run: form_id <- 100000 get_raw_codebook(form_id) Or if the token is saved in a non-standard name get_raw_codebook(form_id, token_name = "MY_NETTSKJEMA_TOKEN_NAME") ## End(Not run)
Codebook is by default turned off in Nettskjema, but best practices in handling data is to have it on. This function checks if the codebook of a form has been activated or not
has_codebook(form_id, token_name = "NETTSKJEMA_API_TOKEN")has_codebook(form_id, token_name = "NETTSKJEMA_API_TOKEN")
form_id |
integer. Number of the form to retrieve |
token_name |
character. Name to give the token, defaults to 'NETTSKJEMA_API_TOKEN' |
logical is codebook is turned on
## Not run: has_codebook(110000) ## End(Not run)## Not run: has_codebook(110000) ## End(Not run)
The Nettskjema v2 API requires a token to be registered with IP addresses. This function returns the current IP address.
nettskjema_find_ip(version = c("v4", "v6"))nettskjema_find_ip(version = c("v4", "v6"))
version |
string. ip version to check. one of either "v4" or "v6". |
If you are working through a VPN, the IP address will not be returned as the Nettskjema API sees it. We are looking for solutions to this.
nettskjema_find_ip()nettskjema_find_ip()
With the given API token, will retrieve a list of all the forms you have access to
nettskjema_get_codebook( form_id, as_is = FALSE, token_name = "NETTSKJEMA_API_TOKEN", ... )nettskjema_get_codebook( form_id, as_is = FALSE, token_name = "NETTSKJEMA_API_TOKEN", ... )
form_id |
integer. Number of the form to retrieve |
as_is |
logical. Whether to return the raw content from nettskjema. Default is FALSE. |
token_name |
character. Name to give the token, defaults to 'NETTSKJEMA_API_TOKEN' |
... |
arguments passed to |
list of class nettskjema_meta_data
## Not run: codebook_110000 <- nettskjema_get_codebook(110000) ## End(Not run)## Not run: codebook_110000 <- nettskjema_get_codebook(110000) ## End(Not run)
This function connects to a specific form and fetches all answers.
The responses are placed in a data.frame for easy use.
For large data sets, toggle the incremental option,
which while slow, will be better able to retrieve all responses.
For retrieving responses only from a specific date on, or all responses
after a certain submission, use the from_date and from_submission arguments.
Forms that are anonymous and do not collect personal information do not record date,
and as such the from_date will not work on those and an error will be thrown.
nettskjema_get_data( form_id, information = NULL, token_name = "NETTSKJEMA_API_TOKEN", use_codebook = has_codebook(form_id, token_name), checkbox_type = c("string", "list", "columns"), checkbox_delim = ";", as_is = FALSE, from_date = "", from_submission = "", incremental = FALSE, ... )nettskjema_get_data( form_id, information = NULL, token_name = "NETTSKJEMA_API_TOKEN", use_codebook = has_codebook(form_id, token_name), checkbox_type = c("string", "list", "columns"), checkbox_delim = ";", as_is = FALSE, from_date = "", from_submission = "", incremental = FALSE, ... )
form_id |
integer. Number of the form to retrieve |
information |
character or list vector of additional answer information
to add (One or more of "order", "option", "correct" "preselected"). If the list
is named, the additional information suffixes will be changed to the list names. If NULL (default) nothing is added.
Currently not possible to combine with |
token_name |
character. Name to give the token, defaults to 'NETTSKJEMA_API_TOKEN' |
use_codebook |
logical. Use codebook for retrieving answers (default TRUE). If you have not set up the codebook in nettskjema, then turning this off will return the data as is. |
checkbox_type |
string of either "string" (default), "list" or "columns" for how to handle checkbox answers |
checkbox_delim |
delimiter string if |
as_is |
logical. Whether to return the raw content from nettskjema. Default is FALSE. |
from_date |
date. From which date on should data be fetched for |
from_submission |
integer. From which SubmissionId should data be collected from. |
incremental |
logical. False fetches all at once, TRUE fetches each submission individually. Slower but more stable for larger datasets. |
... |
arguments passed to |
Checkbox types
"string" - returns a delimited character value per submission, where checkbox_delim
denotes the options that the respondent has chosen
"list" - returns a list column, where each submission has a character vector with all the chosen options as separate elements in the list
"columns" - returns checkbox answers as separate binarized columns (column names are appended with response names), where 1 means the option was selected and 0 it was not.
tibble data.frame
## Not run: # Retrieve all data data_110000 <- nettskjema_get_data(110000) # Retrieve all data, and add answer order and option text data_110000 <- nettskjema_get_data(110000, information = list(dummy = "order", text = "option")) # Retrieve all data after a certain date data_110000 <- nettskjema_get_data(110000, from_date = "2019-01-01") # Retrieve all submissions after a specific submission id data_110000 <- nettskjema_get_data(110000, from_submission = "12000000") # For large data data_110000 <- nettskjema_get_data(110000, incremental = TRUE) ## End(Not run)## Not run: # Retrieve all data data_110000 <- nettskjema_get_data(110000) # Retrieve all data, and add answer order and option text data_110000 <- nettskjema_get_data(110000, information = list(dummy = "order", text = "option")) # Retrieve all data after a certain date data_110000 <- nettskjema_get_data(110000, from_date = "2019-01-01") # Retrieve all submissions after a specific submission id data_110000 <- nettskjema_get_data(110000, from_submission = "12000000") # For large data data_110000 <- nettskjema_get_data(110000, incremental = TRUE) ## End(Not run)
The answers in the nettskjema forms have some extra information attached that is not returned by default. This is for instance information on the order of the answer options, the true text, whether the answer is correct or if it is preselected. This function makes it possible to retrieve and add this information to the nettskjema data, using the codebook.
nettskjema_get_extra(data, codebook, information, use_codebook = TRUE, ...)nettskjema_get_extra(data, codebook, information, use_codebook = TRUE, ...)
data |
tibble. Data retrieved from nettskjema |
codebook |
codebook object retrieved by |
information |
character vector of information to add. One or more of "order", "option", "correct" "preselected". |
use_codebook |
logical. Use codebook for retrieving answers (default TRUE). If you have not set up the codebook in nettskjema, then turning this off will return the data as is. |
... |
arguments passed to |
tibble with added columns
## Not run: form_id <- 100000 my_data <- nettskjema_get_data(form_id) cb <- nettskjema_get_codebook(form_id) my_data <- nettskjema_get_extra(my_data, cb, "order") ## End(Not run)## Not run: form_id <- 100000 my_data <- nettskjema_get_data(form_id) cb <- nettskjema_get_codebook(form_id) my_data <- nettskjema_get_extra(my_data, cb, "order") ## End(Not run)
Some Nettskjema have fields for attachments. These
can be downloaded through this function. There
are two naming convention that may be used for the
saved files' names. See output of
nettskjema_list_attachments for idea
of the names used.
nettskjema_get_form_attachments( form_id, filenames = c("standardized", "original"), output_dir = ".", token_name = "NETTSKJEMA_API_TOKEN", from_date = "", from_submission = "", ... )nettskjema_get_form_attachments( form_id, filenames = c("standardized", "original"), output_dir = ".", token_name = "NETTSKJEMA_API_TOKEN", from_date = "", from_submission = "", ... )
form_id |
integer. Number of the form to retrieve |
filenames |
string of either 'standardized' (default) or 'original' indicating which file names to use. |
output_dir |
directory to output the files to |
token_name |
character. Name to give the token, defaults to 'NETTSKJEMA_API_TOKEN' |
from_date |
date. From which date on should data be fetched for |
from_submission |
integer. From which SubmissionId should data be collected from. |
... |
arguments passed to |
'filenames types
"original" - uses file names are they were uploaded to Nettskjema
"standardized" - creates file names based on the submission id and a counter number to uniquely create file names for each submission (in case there are more than one attachment)
invisible named logical if the file was saved successfully
## Not run: form_id <- 1100000 nettskjema_get_form_attachments(form_id) # save files to specific folder nettskjema_get_form_attachments(form_id, output_dir = "~/Desktop") # save using original file names nettskjema_get_form_attachments(form_id, filenames = "original") ## End(Not run)## Not run: form_id <- 1100000 nettskjema_get_form_attachments(form_id) # save files to specific folder nettskjema_get_form_attachments(form_id, output_dir = "~/Desktop") # save using original file names nettskjema_get_form_attachments(form_id, filenames = "original") ## End(Not run)
With the given API token, will retrieve the meta-data connected to a form.
nettskjema_get_meta( form_id, as_is = FALSE, token_name = "NETTSKJEMA_API_TOKEN", ... )nettskjema_get_meta( form_id, as_is = FALSE, token_name = "NETTSKJEMA_API_TOKEN", ... )
form_id |
integer. Number of the form to retrieve |
as_is |
logical. Whether to return the raw content from nettskjema. Default is FALSE. |
token_name |
character. Name to give the token, defaults to 'NETTSKJEMA_API_TOKEN' |
... |
arguments passed to |
list of class nettskjema_meta_data
## Not run: meta_110000 <- nettskjema_get_meta(110000) ## End(Not run)## Not run: meta_110000 <- nettskjema_get_meta(110000) ## End(Not run)
Each unique submission ID in Nettskjema may have some attachments. These can be listed using this function, which will provide the information on where in the Nettskjema API the files are located, their original file names, and a suggested standardized file names for tidier data output.
nettskjema_list_attachments( submission_id, token_name = "NETTSKJEMA_API_TOKEN", ... )nettskjema_list_attachments( submission_id, token_name = "NETTSKJEMA_API_TOKEN", ... )
submission_id |
integer. Unique identifier of a specific Nettskjema submission. |
token_name |
character. Name to give the token, defaults to 'NETTSKJEMA_API_TOKEN' |
... |
arguments passed to |
a tibble with information on attachments available.
## Not run: submission_id <- c(22222, 1232, 21555) nettskjema_list_attachments(submission_id) ## End(Not run)## Not run: submission_id <- c(22222, 1232, 21555) nettskjema_list_attachments(submission_id) ## End(Not run)
The Nettskjema forms has an option
to upload attachments with forms.
These can be retrieved by this function.
Recommended workflow is to first call
nettskjema_list_attachments,
and use the output of this to pass along
to the function. This function is called
by nettskjema_get_form_attachments,
but you can use it to define your own output
file names.
nettskjema_save_attachment(path, output, token_name, ...)nettskjema_save_attachment(path, output, token_name, ...)
path |
Nettskjema API path where the attachment is |
output |
output file name |
token_name |
character. Name to give the token, defaults to 'NETTSKJEMA_API_TOKEN' |
... |
arguments passed to |
nothing. saves attachments to file.
## Not run: submission_id <- c(22222, 1232, 21555) attach_dt <- nettskjema_list_attachments(submission_id) nettskjema_save_attachment(path = attach_dt$path, output = attach_dt$standardized) ## End(Not run)## Not run: submission_id <- c(22222, 1232, 21555) attach_dt <- nettskjema_list_attachments(submission_id) nettskjema_save_attachment(path = attach_dt$path, output = attach_dt$standardized) ## End(Not run)
Given an API token, will retrieve the expiry date of the said token.
nettskjema_token_expiry(token_name = "NETTSKJEMA_API_TOKEN")nettskjema_token_expiry(token_name = "NETTSKJEMA_API_TOKEN")
token_name |
character. Name to give the token, defaults to 'NETTSKJEMA_API_TOKEN' |
character date string
Opens OS browser to create API user.
nettskjema_user_create(ip_version = c("v4", "v6"))nettskjema_user_create(ip_version = c("v4", "v6"))
ip_version |
IP version to look up. Either "v4" (default) or "v6". |
No return value, opens a browser for creating a API user.
## Not run: nettskjema_user_create() # Turn off ip detection nettskjema_user_create(ip = FALSE) ## End(Not run)## Not run: nettskjema_user_create() # Turn off ip detection nettskjema_user_create(ip = FALSE) ## End(Not run)
Save codebook information to a
file for safe keeping. Depending
on the type of codebook (raw or tidy)
the file will either be stored as a
json-file through write_json
or a text table through write.table.
nettskjema_write_codebook(codebook, file, ...) ## Default S3 method: nettskjema_write_codebook(codebook, file, ...) ## S3 method for class 'nettskjema_codebook_raw' nettskjema_write_codebook(codebook, file, pretty = TRUE, ...) ## S3 method for class 'nettskjema_codebook' nettskjema_write_codebook(codebook, file, sep = "\t", ...)nettskjema_write_codebook(codebook, file, ...) ## Default S3 method: nettskjema_write_codebook(codebook, file, ...) ## S3 method for class 'nettskjema_codebook_raw' nettskjema_write_codebook(codebook, file, pretty = TRUE, ...) ## S3 method for class 'nettskjema_codebook' nettskjema_write_codebook(codebook, file, sep = "\t", ...)
codebook |
object of class nettskjema_codebook |
file |
filename or path |
... |
arguments to |
pretty |
logical. If writing json-file, make it pretty |
sep |
character. If writing text table, column delimiter. |
Given the two types of codebooks, writes different types of files.
codebook - writes a tab-separated table
codebook_raw - writes a json-file
no return value. Writes a file to path.
## Not run: form_id <- 1100000 my_cb <- nettskjema_get_codebook(form_id) nettskjema_write_codebook(my_cb, "my/path/codebook_110000.txt") ## End(Not run)## Not run: form_id <- 1100000 my_cb <- nettskjema_get_codebook(form_id) nettskjema_write_codebook(my_cb, "my/path/codebook_110000.txt") ## End(Not run)
Save meta-data information to a file for safe keeping. The function saves the data in json-format, which best preserves the information.
nettskjema_write_meta(meta, file, pretty = TRUE, ...) ## Default S3 method: nettskjema_write_meta(meta, file, pretty = TRUE, ...) ## S3 method for class 'nettskjema_meta_raw' nettskjema_write_meta(meta, file, pretty = TRUE, ...) ## S3 method for class 'nettskjema_meta_data' nettskjema_write_meta(meta, file, pretty = TRUE, ...)nettskjema_write_meta(meta, file, pretty = TRUE, ...) ## Default S3 method: nettskjema_write_meta(meta, file, pretty = TRUE, ...) ## S3 method for class 'nettskjema_meta_raw' nettskjema_write_meta(meta, file, pretty = TRUE, ...) ## S3 method for class 'nettskjema_meta_data' nettskjema_write_meta(meta, file, pretty = TRUE, ...)
meta |
object of class nettskjema_meta class |
file |
file name or path |
pretty |
logical. If json-file should be made "pretty" |
... |
other arguments to |
no return value. Writes a file to path.
## Not run: form_id <- 1100000 my_meta <- nettskjema_get_meta(form_id) nettskjema_write_meta(my_meta, "my/path/meta_110000.json") ## End(Not run)## Not run: form_id <- 1100000 my_meta <- nettskjema_get_meta(form_id) nettskjema_write_meta(my_meta, "my/path/meta_110000.json") ## End(Not run)