Tools for Integrated Management of Childhood Illnesses (TIMCI)

timci is a R package for managing, exporting Markdown reports and visualising in a Shiny app the data collected by ODK for the different studies of the TIMCI project (Tools for Integrated Management of Childhood Illnesses).

The TIMCI project is funded by Unitaid and led by PATH, in partnership with the Swiss Tropical and Public Health Institute (swiss TPH).

The overall goal of the TIMCI project is to reduce morbidity and mortality in sick children attending primary care facilities, while supporting the rational and efficient use of diagnostics and medicines by healthcare providers. The project is conducted in three African countries (Kenya, Senegal and Tanzania) and two Asian countries (the Indian state of Uttar Pradesh (UP) and Myanmar).

Country	Research partner
Kenya	University of Nairobi (UoN)
India	King's College Medical University (KGMU)
Myanmar	Burnet Institute (BI)
Senegal	Université Cheikh Anta Diop de Dakar (UCAD)
Tanzania	Ifakara Health Institute (IHI)

Table of contents

• Getting started
• Run a generic Shiny app
• Run the TIMCI Shiny app
• Generate R Markdown reports for TIMCI (manual)
• Generate R Markdown reports for TIMCI (automated pipeline)
• Valuable resources

Getting started

This package was developed on a Windows 10 operating system, with R version 4.0.2 (2020-06-22), RStudio version 1.4.1106 and Rtools40.

• CRAN mirrors to download R and RTools
• Link to download RStudio

Prerequisites

You need to have the following R packages installed: ruODK, hash, shiny, qrcode, readxl, ggplot2, dplyr, viridis, pryr, flexdashboard, magrittr, scales, tidyr, DT, data.table, openxlsx, rmarkdown, stringr, qwraps2, digest, readr, fs, emayili, tinytex.

ruODK

To install RuODK, which is the R client that the timci package uses to simply interact with the Application Programming Interface (API) of ODK Central, please follow the instructions provided here.

When trying to upgrade RuODK, if you encounter difficulties to upgrade some of the dependencies (e.g., sf package), you can switch dependencies and build_vignettes from TRUE to FALSE.

if (!requireNamespace("remotes")) install.packages("remotes")
remotes::install_github(
    "ropensci/ruODK@main", 
    dependencies = FALSE, 
    upgrade = "always",
    build_vignettes = FALSE)

TinyTex LaTeX distribution

TinyTeX is a custom LaTeX distribution. It is needed to compile R Markdown documents to PDF. To install TinyTeX from the tinytex package, please proceed as follow:

install.packages("tinytex")
tinytex::install_tinytex()

emayili

This package is required to send emails using a gmail address.

Installation of timci from GitHub

To install the timci package on your workstation, you can

• either download the master branch as a ZIP and build the package locally

• or install the latest released version (preferred option)

install.packages("devtools")

library(devtools)
devtools::install_github("thaliehln/timci")

An index of available documentation for the timci is displayed using the help() function

help(package="timci")

Setup of the connection to ODK Central

You need to setup ruODK by creating environment variables in a ~/.Renviron file that will contain the OData service URL of your main project as well as your credentials (username and password) on ODK Central.

ODKC_SVC="https://.../v1/projects/.../forms/....svc"
[email protected]
ODKC_PW=...
TZ="Europe/Zurich"

For more information about ruODK, the detailed documentation is available here

For more information about the ODK Central API, the detailed documentation is available here

Setup specific to the TIMCI project

For the TIMCI project, you need to set the following environment variables in your ~/.Renviron file.

TIMCI_COUNTRY="Tanzania"
TIMCI_IS_RCT=1

TIMCI_RCTLS_PID=14
TIMCI_PII_PW=...
TIMCI_RCTLS_PP=...
TIMCI_CRF_FACILITY_FID="01-TIMCI-CRF-Facility"
TIMCI_CRF_DAY7_FID="01c-TIMCI-CRF-Day7"
TIMCI_CRF_HOSPIT_FID="01b-TIMCI-CRF-Hospital"
TIMCI_CRF_DAY28_FID="01d-TIMCI-CRF-Day28"
TIMCI_WEEKLY_FA_FID="01e-TIMCI-weekly-FA"

TIMCI_PILOT_RCTLS_PID=7
TIMCI_PILOT_RCTLS_PP=...

TIMCI_SPA_PID=2
TIMCI_SPA_CGEI_FID="02-TIMCI-SPA-CGEI"
TIMCI_SPA_FA_FID="03-TIMCI-SPA-Fassmt"
TIMCI_SPA_SCO_FID="05-TIMCI-SPA-SCO"
TIMCI_SPA_HCPI_FID="04-TIMCI-SPA-HCPi"
TIMCI_TF_FID="07-TIMCI-timeflow"

TIMCI_PILOT_SPA_PID=2

TIMCI_QUAL_PID=12
TIMCI_QUAL_PP=...
TIMCI_QUAL_CGIDI1_FID="08a-TIMCI-cg-idi-invitation"
TIMCI_QUAL_CGIDI2_FID="08b-TIMCI-cg-idi-encryption-list"
TIMCI_QUAL_CGIDI3_FID="08c-TIMCI-cg-idi-interview"

TIMCI_WD_FID="99-TIMCI-withdrawal"

EMAIL_UN=...
EMAIL_PW=...

• TIMCI_COUNTRY is an environment variable that sets the name of your country (India, Kenya, Myanmar, Senegal and Tanzania).

• TIMCI_IS_RCT is an environment variable that indicates if the main data collection is the pragmatic cluster randomised controlled trial (RCT) or the longitudinal observational study (LS). It should be set to 1 in Tanzania and India where the main data collection is the pragmatic cluster RCT, and 0 in Kenya, Myanmar, and Senegal where the main data collection is the LS.

• TIMCI_PII_PW is an environment variable that sets the password of the encrypted archive that is generated by the R pipeline to store confidential information (and in particular, personally identifiable information).

• TIMCI_RCTLS_PID is an environment variable that sets the ODK Central ID for the main data collection (either the pragmatic cluster RCT or the LS).

• TIMCI_RCTLS_PP is an environment variable that sets the ODK Central encryption passphrase for the main data collection (either the pragmatic cluster RCT or the LS).

• TIMCI_CRF_FACILITY_FID is an environment variable that sets the ODK Central ID for the facility form.

• TIMCI_CRF_DAY7_FID is an environment variable that sets the ODK Central ID for the Day 7 follow-up form.

• TIMCI_CRF_HOSPIT_FID is an environment variable that sets the ODK Central ID for the hospitalisation follow-up form.

• TIMCI_CRF_DAY28_FID is an environment variable that sets the ODK Central ID for the Day 28 follow-up form.

• TIMCI_WEEKLY_FA_FID is an environment variable that sets the ODK Central ID for the weekly facility assessment form.

• TIMCI_SPA_PID is an environment variable that sets the ODK Central ID for the Service Provision Assessment (SPA) project.

• TIMCI_QUAL_PID is an environment variable that sets the ODK Central ID for the qualitative study project.

• TIMCI_QUAL_PP is an environment variable that sets the ODK Central encryption passphrase for the qualitative study project.

• TIMCI_SPA_CGEI_FID is an environment variable that sets the ODK Central ID for the SPA caregiver exit interview form.

• TIMCI_SPA_FA_FID is an environment variable that sets the ODK Central ID for the SPA facility assessment form.

• TIMCI_SPA_SCO_FID is an environment variable that sets the ODK Central ID for the SPA sick child observation protocol form.

• TIMCI_SPA_HCPI_FID is an environment variable that sets the ODK Central ID for the SPA healthcare provider interview form.

• TIMCI_TF_FID is an environment variable that sets the ODK Central ID for the time-flow form.

• TIMCI_WD_FID is an environment variable that sets the ODK Central ID for the withdrawal form.

Setup of the automated R Markdown pipeline

pandoc is a document converter that can convert files from one markup format into another (e.g., .docx, .pdf etc). It is an independent piece of software, separate from R. However, it comes bundled with R Studio because the rmarkdown package relies on it for document conversion. Rstudio uses the RSTUDIO_PANDOC environment variable to find where pandoc is installed on your machine. To use rmarkdown in a batch, RSTUDIO_PANDOC needs to be set in your ~/.Renviron file.

RSTUDIO_PANDOC='C:/Program Files/RStudio/bin/pandoc'

Run a generic Shiny app

run_mini_app should work with any ODK Central server

library(timci)
timci::run_mini_app()

Run the TIMCI Shiny app

run_app requests an access to a TIMCI ODK Central server.

library(timci)
timci::run_app()

Generate R Markdown reports for TIMCI (manual)

You should now have the following three files in your working directory: timci_run.R, timci_research_facilities.xlsx and ~/.Renviron

timci_research_facilities.xlsx maps the correspondences between the ODK Collect device identifiers and the health facilities where the research assistants are posted.

timci_run.R contains the R script to generate R Markdown reports for TIMCI. An example is provided here. /!\ The run_rmarkdown function requests an internet access to a TIMCI ODK Central server to work correctly.

Generate R Markdown reports for TIMCI (automated pipeline)

Setup of the Windows task scheduler

Create a .bat file that calls timci_run.R

cd dirname
"...\Rscript.exe" ...\timci_run.R
PAUSE

You should now have four files in your working directory: timci_run.R, timci_daily_routine.bat, timci_research_facilities.xlsx and ~/.Renviron

1. Open the task scheduler

2. Action > Create Task

3. ... (to be completed soon)

Valuable resources

ODK resources

OpenDataKit (ODK) is a free-and open-source software that helps millions of people collect data quickly, accurately, offline, and at scale. ODK Central is the latest cloud-based data clearinghouse ODK solution for digitally captured data.

1. ODK Central setup

2. ODK Central apiary contains a very comprehensive documentation of the ODK Central RESTful API. Note that anything that can be done in the ODK Central's web user interface can be done directly via the API.

3. RuODK is an open-source R client to access and parse data from ODK Central, which is developed and maintained by Florian Mayer for the Western Australian Department of Biodiversity, Conservation and Attractions (DBCA).

4. ODK forum already contains a fantastic amount of information and the core ODK team is very reactive.

R resources

1. Shiny package has extensive documentation on best practices for R Shiny application development.

2. (reproduced as is from the Devtools README) There are a number of fantastic blog posts on writing your first package, including

   • Writing an R package from scratch - Hilary Parker
   • How to develop good R packages - Maëlle Salmon
   • Making your first R package - Fong Chun Chan
   • Writing an R package from scratch - Tomas Westlake

3. (reproduced as is from the Devtools README) Writing R Extensions is the exhaustive, canonical reference for writing R packages, maintained by R core developers.

R cheatsheets / reference guides

Contributing

Pull requests are welcome on the develop branch. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

[GPL-3]