readepi: Read data from health information systems

{readepi} is an R package for reading data from several health information systems (HIS) including public repositories, relational database management systems (RDBMS).

{readepi} currently supports reading data from the followings:

RDBMS (Relational Database Management Systems) such as MS SQL, MySQL, and PostgreSQL
REDCap: Research Electronic Data Capture - a secure web application for building and managing online surveys and databases
DHIS2: an open source and web-based platform for managing health information
Fingertips: a repository of public health indicators in England

{readepi} returns a list object containing one or more data frames. {readepi} also has a number of auxiliary functions that allow importing a subset of the original dataset.

{readepi} is developed by Epiverse-TRACE team at the Medical Research Center, The Gambia unit at London School of Hygiene and Tropical Medicine.

Installation

You can install the development version of {readepi} from GitHub with:

if (!require("pak")) install.packages("pak")
pak::pak("epiverse-trace/readepi")
library(readepi)

Quick start

The main function in {readepi} is readepi(). It reads data from a specified source. The readepi() function accepts a user-supplied string (the API’s URL) as argument. Other specific arguments can be provided depending on the data source (see the vignette for more details). The examples below show how to use the readepi() function to import data from a variety of sources.

Reading data from RDBMS and HIS

The readepi() function can import data from a variety of RDBMS, including MS SQL, MySQL, and PostgreSQL. Reading data from a RDBMS requires the following:

A MS SQL driver that is compatible with the version of DBMS of interest. The vignette describes how to install the appropriate driver for each database management system.
Valid Credentials to access the server. The user credential details are expected to be stored in a file that will be supplied as an argument of the readepi() function. Use the show_example_file() function to visualize the structure of the template credential file.

Users can read data from a RDBMS by providing the details of the tables of interest or an SQL query (for more information, see the vignette).

# DEFINE THE PATH TO THE CREDENTIAL FILE
credentials_file <- system.file("extdata", "test.ini", package = "readepi")

# DISPLAY THE STRUCTUTRE OF THE TEMPLATE CREDENTIAL FILE
show_example_file()

# READING FILE FROM A PROJECT IN A REDCap DATABASE
dat <- readepi(
  data_source      = "https://bbmc.ouhsc.edu/redcap/api/",
  credentials_file = credentials_file
)
project_data     <- dat$data # accessing the actual data
project_metadeta <- dat$metadata # accessing the metadata associated with project

# VIEWING THE LIST OF ALL TABLES IN A MySQL DATABASE
show_tables(
  data_source      = "mysql-rfam-public.ebi.ac.uk",
  credentials_file = credentials_file,
  driver_name      = "" # note that this example MySQL server does not require a driver
)

# VISUAIZE FIRST 5 ROWS OF THE TABLE 'AUTHOR'
visualise_table(
  data_source      = "mysql-rfam-public.ebi.ac.uk",
  credentials_file = credentials_file,
  from             = "author", # this is the table name
  driver_name      = ""
)

# READING ALL FILEDS AND RECORDS FROM A MySQL SERVER
dat <- readepi(
  data_source      = "mysql-rfam-public.ebi.ac.uk",
  credentials_file = credentials_file,
  from             = "author", # this is the table name
  driver_name      = ""
)

# READING DATA FROM DHIS2
dat <- readepi(
  data_source        = "https://play.dhis2.org/dev",
  credentials_file   = credentials_file,
  dataset            = "BfMAe6Itzgt",
  organisation_unit  = "Umh4HKqqFp6",
  data_element_group = NULL,
  start_date         = "2014",
  end_date           = "2023"
)

# READING DATA FROM THE FINGERTIPS REPOSITORY
dat <- readepi(
  indicator_id        = 90362,
  area_type_id        = 202,
  parent_area_type_id = 6 # optional
)

Package Vignettes

The vignette of the {readepi} package contains detailed illustrations about the use of each function and the description of every argument. This can be accessed by typing the command below:

# OPEN THE VIGNETTE WITHIN RSTUDIO
vignette("readepi")

# OPEN THE VIGNETTE IN YOUR WEB BROWSER.
browseVignettes("readepi")

Development

Lifecycle

This package is currently a maturing, as defined by the RECON software lifecycle. This means that it can be used in production with the understanding that the interface may still undergo minor changes.

Contributions

Contributions are welcome via pull requests.

Code of Conduct

Please note that the readepi project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

epiverse-trace / readepi

readme