Title: | XlsFormUtil |
---|---|
Description: | Output nicely printed version of an xlsform This approach allows to develop a questionnaire and offer version for revision based on an a master version maintained directly within the xlform format. |
Authors: | Edouard Legoupil [aut, cre] |
Maintainer: | Edouard Legoupil <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.0.900 |
Built: | 2024-11-20 04:21:46 UTC |
Source: | https://github.com/unhcr-americas/XlsFormUtil |
Note that better legibility, it is advised to put the select question with many possible answers - typically something like "what is your country of origin?" - as 'select_from_file'
fct_create_flextable(xlsformpath, label_language, logic)
fct_create_flextable(xlsformpath, label_language, logic)
xlsformpath |
path to the file with xlsform |
label_language |
Language to be used in case you have more than one. If not specified, the 'default_language' in the 'settings' worksheet is used. If that is not specified and more than one language is in the XlsForm, the language that comes first within column order will be used. |
logic |
TRUE per default put to FALSE to take out the printing of constraints. |
a flextable ready to be printed in an Rmd template for word - using officedown.
fct_create_flextable( xlsformpath = system.file("demo.xlsx", package = "XlsFormUtil"), label_language = NULL )
fct_create_flextable( xlsformpath = system.file("demo.xlsx", package = "XlsFormUtil"), label_language = NULL )
When designing a questionnaire, it is key to keep the interview duration under control. Ideally less than 20 minutes for a phone interview and less than 40 minutes for a face to face interview.
The function is designed to provide a rough estimate (aka a guesstimate...) of the interview duration in order to assess this element of questionnaire design quality. If the questionnaire takes too long, then one needs to trim it or split it into multiple ones...
The estimations provided in that function are based on a series of assumptions and accounts for the following elements:
* the time needed to read the label of the questions - or the note - Questions hint are not accounted for as they tips for enumerator and not to be read to respondent;
* the time needed to read the question modalities - as there's nothing in xlsform that tells whether the enumerator is expected to read loudly the potential answers in case of closed question, the function has a parameter to account for it;
* the time need to answer the question - here we are accounting for 3 distinct situations, each of them with a different potential duration: - close questions - open questions and open questions set up under skip logic so typically - the "if other, specify" - each comes with distinct response time;
* the time needed when we have a "repeat" block - typically questions repeated for a family roster;
fct_interview_duration( xlsformpath, label_language = NULL, wpm = 180, maxmodalities = 7, resptimeclose = 4, resptimecondopen = 7, resptimeopen = 10, avrgrepeat = 3 )
fct_interview_duration( xlsformpath, label_language = NULL, wpm = 180, maxmodalities = 7, resptimeclose = 4, resptimecondopen = 7, resptimeopen = 10, avrgrepeat = 3 )
xlsformpath |
path to the file with xlsform |
label_language |
Language to be used in case you have more than one. If not specified, the 'default_language' in the 'settings' worksheet is used. If that is not specified and more than one language is in the XlsForm, the language that comes first within column order will be used. |
wpm |
word per minute - an average 180 word per minute (per default) required to read loudly the text |
maxmodalities |
if more than 7 potential answers for a select question (per default)- then we assume that those modalities will not be read by the enumerator - but rather selected based on an open answer - and not be accounted for the modalities duration estimation |
resptimeclose |
an average 4 seconds (per default) for respondent to reply for closed questions |
resptimecondopen |
an average of 7 seconds (per default) to reply to conditional text question (accounting for question type of "other, please specify"). |
resptimeopen |
an average of 10 seconds (per default) to reply to open text question. |
avrgrepeat |
In case of repeat questions, an average 3 repeat (per default) is accounted for. |
a list with a summary review in a visual format as a gpplot2 chart
## Generate the summary chart result <- fct_interview_duration( xlsformpath = system.file("demo.xlsx", package = "XlsFormUtil"), label_language = NULL, # wpm word per minute - an average 180 word per minute (per default) required #to read loudly the text wpm = 180, # maxmodalities if more than 7 potential answers for a select question #(per default)- then we assume that those modalities will not be read by the # enumerator - but rather selected based on an open answer - and not be # accounted for the modalities duration estimation maxmodalities = 7 , # resptimeclose an average 4 seconds (per default) for respondent to reply for # closed questions resptimeclose = 4, # resptimecondopen an average of 7 seconds (per default) to reply to conditional # text question (accounting for question type of "other, please specify"). resptimecondopen = 7, # resptimeopen an average of 10 seconds (per default) to reply to open text # question. resptimeopen = 10, # avrgrepeat In case of repeat questions, an average 3 repeat (per default) is # accounted for. avrgrepeat = 3 ) result[["plot"]] result[["totaldur"]] knitr::kable(head(result[["variables"]], 15))
## Generate the summary chart result <- fct_interview_duration( xlsformpath = system.file("demo.xlsx", package = "XlsFormUtil"), label_language = NULL, # wpm word per minute - an average 180 word per minute (per default) required #to read loudly the text wpm = 180, # maxmodalities if more than 7 potential answers for a select question #(per default)- then we assume that those modalities will not be read by the # enumerator - but rather selected based on an open answer - and not be # accounted for the modalities duration estimation maxmodalities = 7 , # resptimeclose an average 4 seconds (per default) for respondent to reply for # closed questions resptimeclose = 4, # resptimecondopen an average of 7 seconds (per default) to reply to conditional # text question (accounting for question type of "other, please specify"). resptimecondopen = 7, # resptimeopen an average of 10 seconds (per default) to reply to open text # question. resptimeopen = 10, # avrgrepeat In case of repeat questions, an average 3 repeat (per default) is # accounted for. avrgrepeat = 3 ) result[["plot"]] result[["totaldur"]] knitr::kable(head(result[["variables"]], 15))
Us the built in template and functions from the package to generate a word version of the xlsform
fct_render_prettyprint( dir, xlsformfile, label_language = NULL, logic = TRUE, estimation = TRUE, wpm = 180, maxmodalities = 7, resptimeclose = 4, resptimecondopen = 7, resptimeopen = 10, avrgrepeat = 3 )
fct_render_prettyprint( dir, xlsformfile, label_language = NULL, logic = TRUE, estimation = TRUE, wpm = 180, maxmodalities = 7, resptimeclose = 4, resptimecondopen = 7, resptimeopen = 10, avrgrepeat = 3 )
dir |
directory where the xlsform is located |
xlsformfile |
name of the file for the xlsform |
label_language |
language to sue to generate the pretty print - for instance _"Español (es)"_, _"Français (fr)"_ or _"English (en)"_ . If not specified, the 'default_language' in the 'settings' worksheet is used. If that is not specified and more than one language is in the XlsForm, the language that comes first within column order will be used. |
logic |
TRUE per default put to FALSE to take out the printing of constraints. |
estimation |
TRUE FALSE add an estimation of interview dration |
wpm |
word per minute - an average 180 word per minute (per default) required to read loudly the text |
maxmodalities |
if more than 7 potential answers for a select question (per default)- then we assume that those modalities will not be read by the enumerator - but rather selected based on an open answer - and not be accounted for the modalities duration estimation |
resptimeclose |
an average 4 seconds (per default) for respondent to reply for closed questions |
resptimecondopen |
an average of 7 seconds (per default) to reply to conditional text question (accounting for question type of "other, please specify"). |
resptimeopen |
an average of 10 seconds (per default) to reply to open text question. |
avrgrepeat |
In case of repeat questions, an average 3 repeat (per default) is accounted for. |
When customizing and adjusting a household survey questionnaire during the design phase, it's often necessary to have one testing version (i.e. encoded in [xlsform](http://xlsform)) and a more legible version in word that can be then shared with non-technical experts for them to comment and review.
Moving between a paper version and an encoded-machine ready version is not smooth. Instead of having the master version in word and updating once while the xlsform, it's more convenient to generate a word output to collect feedback in word tracking mode.
The default _prettyprinting_ template brings in a single grid different parts of the xlsform. The _prettyprinting_ can be done separately for each different language in case the 'xlsform' includes more than one. The template increases legibility for both __question blocks__:
1. begin_group –> depending on the level are output with a different style of heading level 2. begin_repeat –> displayed as a header but with a specific distinct color and note
and within each block, each __question details__ is included:
1. question code & type 2. question label & hint 3. if select_one or select_multiple, modalities code and label as a nested table 4. if present - question constraint with warning message as well as related question skip logic
a word document
# fct_render_prettyprint( dir = system.file("", package = "XlsFormUtil"), # xlsformfile = "demo.xlsx", # label_language = NULL )
# fct_render_prettyprint( dir = system.file("", package = "XlsFormUtil"), # xlsformfile = "demo.xlsx", # label_language = NULL )
Combine the xlsform in single table for pretty printing
fct_tabulate_form(xlsformpath, label_language = NULL, logic = TRUE)
fct_tabulate_form(xlsformpath, label_language = NULL, logic = TRUE)
xlsformpath |
path to the file with xlsform |
label_language |
Language to be used in case you have more than one. If not specified, the 'default_language' in the 'settings' worksheet is used. If that is not specified and more than one language is in the XlsForm, the language that comes first within column order will be used. |
logic |
TRUE per default put to FALSE to take out the printing of constraints. |
a single data frame
# fct_tabulate_form() prettyform <- fct_tabulate_form( xlsformpath = system.file("demo.xlsx", package = "XlsFormUtil") ) knitr::kable(utils::head(prettyform, 10))
# fct_tabulate_form() prettyform <- fct_tabulate_form( xlsformpath = system.file("demo.xlsx", package = "XlsFormUtil") ) knitr::kable(utils::head(prettyform, 10))
Note that comparison is done for a selected language
fct_xlsform_compare(listfile, label_language, fileout = NULL)
fct_xlsform_compare(listfile, label_language, fileout = NULL)
listfile |
list of full path to multiple xlsform files - ll assumed to be in the same folder. The first one will be used as the master to compare the other to |
label_language |
Language to be used in case you have more than one. If not specified, the 'default_language' in the 'settings' worksheet is used. If that is not specified and more than one language is in the XlsForm, the language that comes first within column order will be used. |
fileout |
if specified defined the full path name of the file to save the xlsform _compare output |
a file
## With 2 files check <- fct_xlsform_compare( listfile = c( system.file("demo.xlsx", package = "XlsFormUtil"), system.file("demo_adapt1.xlsx", package = "XlsFormUtil") ), label_language = NULL, fileout = NULL) # variablescompare, knitr::kable(utils::head(as.data.frame(check[1]), 10)) # choicescompare knitr::kable(utils::head(as.data.frame(check[2]), 10, 10)) ## With 3 files check <- fct_xlsform_compare( listfile = c( system.file("demo.xlsx", package = "XlsFormUtil"), system.file("demo_adapt1.xlsx", package = "XlsFormUtil"), system.file("demo_adapt2.xlsx", package = "XlsFormUtil") ), label_language = NULL, fileout = NULL)
## With 2 files check <- fct_xlsform_compare( listfile = c( system.file("demo.xlsx", package = "XlsFormUtil"), system.file("demo_adapt1.xlsx", package = "XlsFormUtil") ), label_language = NULL, fileout = NULL) # variablescompare, knitr::kable(utils::head(as.data.frame(check[1]), 10)) # choicescompare knitr::kable(utils::head(as.data.frame(check[2]), 10, 10)) ## With 3 files check <- fct_xlsform_compare( listfile = c( system.file("demo.xlsx", package = "XlsFormUtil"), system.file("demo_adapt1.xlsx", package = "XlsFormUtil"), system.file("demo_adapt2.xlsx", package = "XlsFormUtil") ), label_language = NULL, fileout = NULL)
Retrieve a factor with all label languages used in a specific xlsform. Used in the app to retrieve the language to consider based on the form
fct_xlsfrom_language(xlsformpath)
fct_xlsfrom_language(xlsformpath)
xlsformpath |
path to the file with xlsform |
label_language
## With different language fct_xlsfrom_language( xlsformpath = system.file("demo.xlsx", package = "XlsFormUtil")) ## without language fct_xlsfrom_language( xlsformpath = system.file("KoBoXLSFormExamples.xlsx", package = "XlsFormUtil"))
## With different language fct_xlsfrom_language( xlsformpath = system.file("demo.xlsx", package = "XlsFormUtil")) ## without language fct_xlsfrom_language( xlsformpath = system.file("KoBoXLSFormExamples.xlsx", package = "XlsFormUtil"))
Run the Shiny Application
run_app( onStart = NULL, options = list(), enableBookmarking = NULL, uiPattern = "/", ... )
run_app( onStart = NULL, options = list(), enableBookmarking = NULL, uiPattern = "/", ... )
onStart |
A function that will be called before the app is actually run.
This is only needed for |
options |
Named options that should be passed to the |
enableBookmarking |
Can be one of |
uiPattern |
A regular expression that will be applied to each |
... |
arguments to pass to golem_opts. See '?golem::get_golem_options' for more details. |
a shiny app
# run_app()
# run_app()