Package 'XlsFormUtil'

Generate a flextable from the pretty printed version of the xlsform

Description

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'

Usage

fct_create_flextable(xlsformpath, label_language, logic)

Arguments

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.

Value

a flextable ready to be printed in an Rmd template for word - using officedown.

Examples

fct_create_flextable(
  xlsformpath = system.file("demo.xlsx", package = "XlsFormUtil"),
  label_language = NULL )

---

Prepare a summary estimation of the interview duration.

Description

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;

Usage

fct_interview_duration(
  xlsformpath,
  label_language = NULL,
  wpm = 180,
  maxmodalities = 7,
  resptimeclose = 4,
  resptimecondopen = 7,
  resptimeopen = 10,
  avrgrepeat = 3
)

Arguments

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.

Value

a list with a summary review in a visual format as a gpplot2 chart

Examples

## 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))

---

Render Word version of an xlsform

Description

Us the built in template and functions from the package to generate a word version of the xlsform

Usage

fct_render_prettyprint(
  dir,
  xlsformfile,
  label_language = NULL,
  logic = TRUE,
  estimation = TRUE,
  wpm = 180,
  maxmodalities = 7,
  resptimeclose = 4,
  resptimecondopen = 7,
  resptimeopen = 10,
  avrgrepeat = 3
)

Arguments

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.

Details

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

Value

a word document

Examples

# fct_render_prettyprint( dir =  system.file("", package = "XlsFormUtil"),
#   xlsformfile = "demo.xlsx",
#   label_language = NULL )

---

Combine the xlsform in single table for pretty printing

Description

Combine the xlsform in single table for pretty printing

Usage

fct_tabulate_form(xlsformpath, label_language = NULL, logic = TRUE)

Arguments

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.

Value

a single data frame

Examples

# fct_tabulate_form()

prettyform <- fct_tabulate_form( xlsformpath = system.file("demo.xlsx", 
                                              package = "XlsFormUtil") )

knitr::kable(utils::head(prettyform, 10))

---

Generate a consolidated xlsform from a list of xlsform in order to quickly flag differences

Description

Note that comparison is done for a selected language

Usage

fct_xlsform_compare(listfile, label_language, fileout = NULL)

Arguments

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

Value

a file

Examples

## 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)

---

fct_xlsfrom_language

Description

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

Usage

fct_xlsfrom_language(xlsformpath)

Arguments

xlsformpath

path to the file with xlsform

Value

label_language

Examples

## 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

Description

Run the Shiny Application

Usage

run_app(
  onStart = NULL,
  options = list(),
  enableBookmarking = NULL,
  uiPattern = "/",
  ...
)

Arguments

onStart	A function that will be called before the app is actually run. This is only needed for shinyAppObj, since in the shinyAppDir case, a global.R file can be used for this purpose.
options	Named options that should be passed to the runApp call (these can be any of the following: "port", "launch.browser", "host", "quiet", "display.mode" and "test.mode"). You can also specify width and height parameters which provide a hint to the embedding environment about the ideal height/width for the app.
enableBookmarking	Can be one of "url", "server", or "disable". The default value, NULL, will respect the setting from any previous calls to enableBookmarking(). See enableBookmarking() for more information on bookmarking your app.
uiPattern	A regular expression that will be applied to each GET request to determine whether the ui should be used to handle the request. Note that the entire request path must match the regular expression in order for the match to be considered successful.
...	arguments to pass to golem_opts. See '?golem::get_golem_options' for more details.

Value

a shiny app

Examples

# run_app()

---