Title: | Read Data from Relational Database Management Systems and Health Information Systems |
Version: | 1.0.1 |
Description: | Import Data from Relational Database Management Systems (RDBMS) and Health Information Systems ('HIS'). The current version of the package supports importing data from RDBMS including 'MS SQL', 'MySQL', 'PostGRESQL', and 'SQLite', as well as from two HIS platforms: 'DHIS2' and 'SORMAS'. |
License: | MIT + file LICENSE |
URL: | https://epiverse-trace.github.io/readepi/, https://github.com/epiverse-trace/readepi/, https://github.com/epiverse-trace/readepi |
BugReports: | https://github.com/epiverse-trace/readepi/issues |
Depends: | R (≥ 4.1.0) |
Imports: | checkmate, cli, DBI, dplyr, httr2, odbc, pool, purrr, RMySQL, RSQLite, tidyr |
Suggests: | cyclocomp, DiagrammeR, httptest, kableExtra, knitr, rmarkdown, testthat (≥ 3.0.0) |
VignetteBuilder: | knitr |
Config/Needs/website: | epiverse-trace/epiversetheme |
Config/testthat/edition: | 3 |
Encoding: | UTF-8 |
LazyData: | true |
RoxygenNote: | 7.3.2 |
SystemRequirements: | odbc, libmariadbclient-dev |
NeedsCompilation: | no |
Packaged: | 2025-09-24 13:08:48 UTC; karimmane |
Author: | Karim Mané |
Maintainer: | Karim Mané <karim.mane@lshtm.ac.uk> |
Repository: | CRAN |
Date/Publication: | 2025-10-01 07:00:02 UTC |
Validate user-specified organisation unit ID or name.
Description
Check whether a given organisation unit identifier or name is valid within a DHIS2 instance. If a valid name is provided, the corresponding organisation unit ID is returned. Otherwise, an informative error message is thrown.
Usage
check_org_unit(login, org_unit, org_units = NULL)
Arguments
login |
A httr2 request object preconfigured for authentication carrying the base url, user name, and password. |
org_unit |
A character denoting the name or id of the organisation unit |
org_units |
An optional data frame of organisation units as returned by
the |
Value
The organisation unit ID if the provided organisation unit ID or name exists; otherwise, an error is thrown with a suggestion to use the function that lists all available organisation units from the target DHIS2 instance.
Validate and retrieve program IDs
Description
Checks whether the specified program ID or name is valid in a DHIS2 instance. If the name provided is a valid program name or ID, it returns the corresponding ID; otherwise, an error message is shown and a function listing all available programs is provided.
Usage
check_program(login, program)
Arguments
login |
A httr2 request object preconfigured for authentication carrying the base url, user name, and password. |
program |
A character of the program name to be validated |
Value
The program ID if the provide program name or ID exists; otherwise, an error is thrown with a suggestion to use the function that lists all available programs from the target DHIS2 instance.
Convert numeric values into POSIXct,then into Date
Description
Convert numeric values into POSIXct,then into Date
Usage
convert_to_date(data, target_columns)
Arguments
data |
A data frame with the numeric columns to be converted into Date |
target_columns |
A character vector with the name of the target numeric columns |
Value
A data frame where the specified target columns have been converted into Date
Establish connection to a DHIS2 instance
Description
Establish connection to a DHIS2 instance
Usage
dhis2_login(base_url, user_name, password)
Arguments
base_url |
A character with the base URL of the target DHIS2 instance |
user_name |
A character with the user name |
password |
A character with the user's password |
Value
An httr2_response
object if the connection was successfully
established
Examples
## Not run:
dhis2_log <- dhis2_login(
base_url = "https://play.im.dhis2.org/stable-2-42-1",
user_name = "admin",
password = "district"
)
## End(Not run)
Check whether the user-specified fields are valid
Description
A valid field is the one that corresponds to a column name of the specified table.
Usage
fields_check(fields, table_name, login)
Arguments
fields |
A character vector of column names |
table_name |
A character with the table name |
login |
The connection object obtained from the |
Value
A character vector with the valid fields
Get DHIS2 API version
Description
Get DHIS2 API version
Usage
get_api_version(login)
Arguments
login |
A httr2_response object returned by the |
Value
A numeric with minor version of the API
Examples
## Not run:
# login to the DHIS2 instance
dhis2_login <- login(
type = "dhis2",
from = "https://smc.moh.gm/dhis",
user_name = "test",
password = "Gambia@123"
)
# get the API version
api_version <- get_api_version(login = dhis2_login)
## End(Not run)
Get all data elements from a specific DHIS2 instance
Description
Get all data elements from a specific DHIS2 instance
Usage
get_data_elements(login)
Arguments
login |
A httr2_response object returned by the |
Value
A data frame with the following two columns: the data elements IDs and their corresponding names.
Examples
## Not run:
# establish the connection to the system
dhis2_login <- login(
type = "dhis2",
from = "https://smc.moh.gm/dhis",
user_name = "test",
password = "Gambia@123"
)
# retrieve the data elements
data_elements <- get_data_elements(login = dhis2_login)
## End(Not run)
Get the attribute names and ids of the tracked entities
Description
Use this function to get the ids and names of the features collected about each tracked entities. The ids and names will be used to update the list of query parameters.
Usage
get_entity_attributes(x)
Arguments
x |
A list with the tracked entity attributes |
Value
A data frame with two columns representing the tracked entity attributes IDs and display names.
Get tracked entity attributes
Description
Get tracked entity attributes
Usage
get_entity_data(login, api_version, tracked_entities, org_units)
Arguments
login |
A httr2_response object returned by the |
api_version |
A numeric with the API version obtained from the
|
org_units |
A data frame with all organisation units from target DHIS2
instance. This is the output from the |
Value
A data frame with the tracked entity attributes
Get event data from the newer DHIS2 versions (version >= 2.41)
Description
Get event data from the newer DHIS2 versions (version >= 2.41)
Usage
get_event_data(
login,
api_version,
org_unit,
program,
data_elements,
programs,
program_stages,
org_units
)
Arguments
login |
A httr2_response object returned by the |
api_version |
A numeric with the API version returned by the
|
org_unit |
A character with the organisation unit ID or name |
program |
A character with the program ID or name |
data_elements |
A data frame with the data element IDs and names
obtained from the |
programs |
A data frame with the program IDs and names obtained from the
|
program_stages |
A data frame with the program stages IDs and names
obtained from the |
org_units |
A data frame with the organisation units IDs and names
obtained from the |
Value
A data frame with the data elements obtained from each event
Get event IDs for specific tracked entity
Description
Get event IDs for specific tracked entity
Usage
get_event_ids(tracked_entity)
Arguments
tracked_entity |
A list with tracked entity data |
Value
A data frame of event IDs associated with the specific tracked entity
Transform the organisation units data frame from large to long format
Description
Transform the organisation units data frame from large to long format
Usage
get_org_unit_as_long(login, org_units = NULL)
Arguments
login |
The login object |
org_units |
A data frame of all the organisation units obtained from the
|
Value
A data with three columns corresponding to the organisation unit names, IDs, and levels
Extract the DHSI2 organization unit's hierarchical levels.
Description
The level is a numerical number, with 1 referring to the "Country", 2 "Region", and so on to the deepest level denoting the health care reporting unit.
Usage
get_org_unit_levels(login)
Arguments
login |
A httr2_response object returned by the |
Value
A data frame with three columns containing the organization unit's names, IDs, and their hierarchical levels.
Retrieve DHIS2 organization units, along with their IDs, names, parent IDs, and levels.
Description
Retrieve DHIS2 organization units, along with their IDs, names, parent IDs, and levels.
Usage
get_org_units(login)
Arguments
login |
A httr2_response object returned by the |
Value
A data frame of organization units with the following fields: organisation unit id and name, as well as the corresponding parent organisation unit id, and level.
Get the organization units from a specific DHIS2 instance
Description
Retrieves all organisational reporting units and their levels, then builds a hierarchy for each unit by tracing its ancestries from the deepest level up to the root.
Usage
get_organisation_units(login)
Arguments
login |
A httr2_response object returned by the |
Details
Fetches all organisation units via the
get_org_units()
function,Fetches all organisational unit levels via the
get_org_unit_levels()
function,Filters for organisational units at the deepest level,
Traces the parent hierarchy of each deepest unit up to the root,
Constructs a tabular structure where each row is a full lineage.
Value
A data frame where each row represents a full hierarchy for the last-level unit by keeping the hierarchical organizational unit's name and ID at each level, using the official level names provided by the DHIS2 instance like "Country Name", "Country ID", etc.
Examples
## Not run:
# establish the connection to the system
dhis2_login <- login(
type = "dhis2",
from = "https://smc.moh.gm/dhis",
user_name = "test",
password = "Gambia@123"
)
# fetch the organisation units
org_units <- get_organisation_units(login = dhis2_login)
## End(Not run)
Get organisation units that are associated with a given program
Description
Get organisation units that are associated with a given program
Usage
get_program_org_units(login, program, org_units = NULL)
Arguments
login |
A httr2_response object returned by the |
program |
A character with the program ID or name |
org_units |
A data frame with all organisation units from target DHIS2
instance. This is the output from the |
Value
A data frame with the organisation units associated with the provided program
Examples
## Not run:
# login to the DHIS2 instance
dhis2_login <- login(
type = "dhis2",
from = "https://smc.moh.gm/dhis",
user_name = "test",
password = "Gambia@123"
)
# fetch the organisation units
org_units <- get_organisation_units(login = dhis2_login)
# get the organisation units associated with the following program
'E5IUQuHg3Mg'
target_org_units <- get_program_org_units(
login = dhis2_login,
program = "E5IUQuHg3Mg",
org_units = org_units
)
## End(Not run)
Get program stages for one or more DHSI2 programs
Description
Retrieves the stages associated with specified DHIS2 program IDs, or all programs if none are specified. If any of the supplied program names or IDs are not found, the function displays a message and proceeds with the valid ones.
Usage
get_program_stages(login, programs = NULL, program = NULL)
Arguments
login |
A httr2_response object returned by the |
programs |
A data frame with the program IDs and names obtained from the
|
program |
A character with the program ID or name |
Value
A data frame with the following columns:
-
program_id
: the unique ID of the program -
program_name
: the displayed name of the program -
program_stage_name
: the name of each stage associate with the program -
program_stage_id
: the ID of each program stage
Examples
## Not run:
# establish the connection to the DHIS2 instance
dhis2_login <- login(
type = "dhis2",
from = "https://smc.moh.gm/dhis",
user_name = "test",
password = "Gambia@123"
)
# get the list of all program stages from the DHIS2 instance
all_program_stages <- get_program_stages(
login = dhis2_login,
program = "E5IUQuHg3Mg",
programs = NULL
)
## End(Not run)
get all programs from a given specific DHIS2 instance
Description
The function first fetches all programs from the DHIS2 Aggregate system, then distinguishes the Tracker and Aggregate programs.
Usage
get_programs(login)
Arguments
login |
A httr2_response object returned by the |
Value
A data frame with the following columns: the program ID, the program name, and the program type specifying whether the program is part of the Aggregate or Tracker system.
Examples
## Not run:
# establish the connection to the system
dhis2_login <- login(
type = "dhis2",
from = "https://smc.moh.gm/dhis",
user_name = "test",
password = "Gambia@123"
)
# fetch the programs
programs <- get_programs(login = dhis2_login)
## End(Not run)
Get the request query parameters for a specific API version
Description
Get the request query parameters for a specific API version
Usage
get_request_params(api_version)
Arguments
api_version |
A numeric with the API version |
Value
A data frame with single row containing the query parameters needed to submit a request
Get tracked entity attributes, their corresponding IDs and event IDs
Description
Get tracked entity attributes, their corresponding IDs and event IDs
Usage
get_tracked_entities(login, api_version, org_unit, program, org_units)
Arguments
login |
A httr2_response object returned by the |
api_version |
A numeric with the API version obtained from the
|
org_unit |
A character with the organisation unit ID or name |
program |
A character with the program ID or name |
org_units |
A data frame with all organisation units from target DHIS2
instance. This is the output from the |
Value
A data frame with the tracked entity attributes alongside their events and tracked entity IDs
Examples
## Not run:
# login to the DHIS2 instance
dhis2_login <- login(
type = "dhis2",
from = "https://smc.moh.gm/dhis",
user_name = "test",
password = "Gambia@123"
)
# set the program and org unit IDs
program <- "E5IUQuHg3Mg"
org_unit <- "GcLhRNAFppR"
# get the api version
api_version <- get_api_version(login = dhis2_login)
# get all the organisation units from the DHIS2 instance
org_units <- get_organisation_units(login = dhis2_login)
# get the tracked entity attributes
tracked_entity_attributes <- get_tracked_entities(
login = dhis2_login,
api_version = api_version,
org_unit = org_unit,
program = program,
org_units = org_units
)
## End(Not run)
Establish a connection to the HIS of interest.
Description
The current version of the package supports basic authentication (using the username and password) and personal authentication key (using API key and bearer token).
Usage
login(
from,
type,
user_name = NULL,
password = NULL,
driver_name = NULL,
db_name = NULL,
port = NULL
)
Arguments
from |
The URL to the HIS of interest. For APIs, this must be the base URL (required). |
type |
The source name (required). The current version of the package covers the following RDBMS and HIS types: "ms sql", "mysql", "postgresql", "sqlite", "dhis2", and "sormas". |
user_name |
The user name (optional). |
password |
The user's password (optional). When the password is not
provided (set to |
driver_name |
The driver name (optional). This is only needed for connecting to RDBMS only. |
db_name |
The database name (optional). This is only needed for connecting to RDBMS only. |
port |
The port ID (optional). This is only needed for connecting to RDBMS only. |
Value
A connection object
Examples
# connect to the test MySQL server
## Not run:
login <- login(
from = "mysql-rfam-public.ebi.ac.uk",
type = "mysql",
user_name = "rfamro",
password = "",
driver_name = "",
db_name = "Rfam",
port = 4497
)
## End(Not run)
# connect to a DHIS2 instance
## Not run:
dhi2s_login <- login(
type = "dhis2",
from = "https://smc.moh.gm/dhis",
user_name = "test",
password = "Gambia@123"
)
## End(Not run)
# connect to SORMAS
## Not run:
sormas_login <- login(
type = "sormas",
from = "https://demo.sormas.org/sormas-rest",
user_name = "SurvSup",
password = "Lk5R7JXeZSEc"
)
## End(Not run)
Lookup table
Description
The lookup table is used to establish the correspondence between R operators, provided in an expression, and the DHIS2 or SQL operators.
Usage
lookup_table
Format
A data frame of 11 rows and 3 columns
Check whether the user-provided query is valid
Description
We define a query as valid when it contains either one of the column names of
the table being queried and/or one of the R
operators provided in the
lookup_table
object of the package.
Usage
query_check(query, login, table_name)
Arguments
query |
An R expression that will be converted into an SQL query |
login |
The connection object obtained from the |
table_name |
A character with the table name |
Value
Invisibly returns TRUE
if the query is valid; throws an error
otherwise.
Import data from DHIS2
Description
Import data from DHIS2
Usage
read_dhis2(login, org_unit, program)
Arguments
login |
A httr2_response object returned by the |
org_unit |
A character with the organisation unit ID or name |
program |
A character with the program ID or name |
Value
A data frame that contains both the tracked entity attributes and their event data.
Examples
## Not run:
# login to the DHIS2 instance
dhis2_login <- login(
type = "dhis2",
from = "https://smc.moh.gm/dhis",
user_name = "test",
password = "Gambia@123"
)
program = "E5IUQuHg3Mg"
org_unit = "GcLhRNAFppR"
data <- read_dhis2(
login = dhis2_login,
org_unit = org_unit,
program = program
)
# fetch data from the test DHIS2 instance
dhis2_login <- login(
type = "dhis2",
from = "https://play.im.dhis2.org/stable-2-42-1",
user_name = "admin",
password = "district"
)
org_unit <- "DiszpKrYNg8"
program <- "IpHINAT79UW"
data <- read_dhis2(
login = dhis2_login,
org_unit = org_unit,
program = program
)
## End(Not run)
Import data from relational database management systems (RDBMS).
Description
The function assumes the user has read access to the database.
Importing data from RDBMS requires the installation of the appropriate
driver
that is compatible with the server version hosting the database.
For more details, see the vignette on
how to install the driver.
Usage
read_rdbms(login, query)
Arguments
login |
The connection object obtained from the |
query |
An SQL query or a list with the following elements:
|
Value
A data.frame
with the requested data as specified in the query
argument.
Examples
## Not run:
# establish the connection to the database
rdbms_login <- login(
from = "mysql-rfam-public.ebi.ac.uk",
type = "mysql",
user_name = "rfamro",
password = "",
driver_name = "",
db_name = "Rfam",
port = 4497
)
# import data where query parameters are specified as a list
authors_list <- read_rdbms(
login = rdbms_login,
query = list(table = "author", fields = NULL, filter = NULL)
)
# import data where query parameters is within an SQL query
authors_list <- read_rdbms(
login = rdbms_login,
query = "select * from author"
)
## End(Not run)
Import data from SORMAS
Description
The function returns the following columns by default: case_id,
person_id, sex, date_of_birth, case_origin, country, city, latitude,
longitude, case_status, date_onset, date_admission, outcome, date_outcome,
contact_id, date_last_contact, date_first_contact, Ct_values
.
Usage
read_sormas(login, disease, since = 0)
Arguments
login |
A list with the user's authentication details |
disease |
A character with the target disease name |
since |
A Date value in ISO8601 format (YYYY-mm-dd). Default is |
Details
Note that the some values in the date_of_birth
column of the output object
might not have some missing elements such a missing year (NA-12-26), month
(2025-NA-01) or date (2025-12-NA), or a combination of two missing elements.
Value
A data frame with the case data of the specified disease.
Examples
## Not run:
# establish the connection to the SORMAS system
sormas_login <- login(
type = "sormas",
from = "https://demo.sormas.org/sormas-rest",
user_name = "SurvSup",
password = "Lk5R7JXeZSEc"
)
# fetch all COVID (coronavirus) cases from the test SORMAS instance
covid_cases <- read_sormas(
login = sormas_login,
disease = "coronavirus"
)
## End(Not run)
Request parameters
Description
The request_parameters data frame contains the information related to which request parameters should be used when fetching data from a specific version of DHIS2. It currently contains parameters for versions ranging from 2.22 to 2.42.
Usage
request_parameters
Format
A data frame of 3 rows and 12 columns
Fetch all or specific rows and columns from a table
Description
Fetch all or specific rows and columns from a table
Usage
server_fetch_data(login, query)
Arguments
login |
The connection object obtained from the |
query |
A string with the SQL query |
Value
A data frame with the data of interest
Make an SQL query from a list of query parameters
Description
Make an SQL query from a list of query parameters
Usage
server_make_query(table_name, login, filter, select)
Arguments
table_name |
The name of the table in the server function |
login |
The connection object obtained from the |
filter |
A vector or a comma-separated string of subset of subject IDs |
select |
A vector of column names |
Value
A string with the constructed SQL query from the provided query parameter.
Convert R expression into SQL expression
Description
Convert R expression into SQL expression
Usage
server_make_sql_expression(filter)
Arguments
filter |
A string with the R expression |
Value
A string of SQL expression
Create a subsetting query
Description
Create a subsetting query
Usage
server_make_subsetting_query(filter, target_columns, table)
Arguments
filter |
An expression that will be used to subset on rows |
target_columns |
A comma-separated list of column names to be returned |
table |
The name of the table of interest |
Value
A string with the SQL query made from the input arguments
Display the list of tables in a database
Description
Display the list of tables in a database
Usage
show_tables(login)
Arguments
login |
The connection object obtained from the |
Value
a character
that contains the list of all tables found
in the specified database.
Examples
## Not run:
# connect to the test MySQL server
rdbms_login <- login(
from = "mysql-rfam-public.ebi.ac.uk",
type = "mysql",
user_name = "rfamro",
password = "",
driver_name = "",
db_name = "Rfam",
port = 4497
)
# display the list of available tables from this database
tables <- show_tables(login = rdbms_login)
## End(Not run)
Download the API specification file from SORMAS
Description
Download the API specification file from SORMAS
Usage
sormas_get_api_specification(path = tempdir(), overwrite = TRUE)
Arguments
path |
A character with the path to the folder where the downloaded data
dictionary should be stored. Default is |
overwrite |
A logical used to specify whether to overwrite to overwrite
the existing data dictionary or not. Default is |
Value
Invisibly returns the path to the folder where the file is stored.
When path = NULL
, the file will be stored in the R temporary
folder as: api_specification.json
Examples
# save the SORMAS API specification into the temporary R folder
path_api_specs <- sormas_get_api_specification()
Get case data from a SORMAS instance
Description
Get case data from a SORMAS instance
Usage
sormas_get_cases_data(login, disease, since)
Arguments
login |
A list with the user's authentication details |
disease |
A character with the target disease name |
since |
A Date value in ISO8601 format (YYYY-mm-dd). Default is |
Value
A data frame with the following eight columns: 'case_id', 'person_id', 'date_onset', 'date_admission', 'case_origin', 'case_status', 'outcome', 'date_outcome'. When not available, the 'person_id' and 'date_outcome' will not be returned.
Get contact data from SORMAS
Description
Get contact data from SORMAS
Usage
sormas_get_contact_data(login, since)
Arguments
login |
A list with the user's authentication details |
since |
A Date value in ISO8601 format (YYYY-mm-dd). Default is |
Value
A data frame with the following three columns: 'case_id', 'contact_id', 'date_last_contact', 'date_first_contact'. When not available, 'date_last_contact' will not be returned
Download SORMAS data dictionary
Description
Download SORMAS data dictionary
Usage
sormas_get_data_dictionary(path = tempdir(), overwrite = TRUE)
Arguments
path |
A character with the path to the folder where the downloaded data
dictionary should be stored. Default is |
overwrite |
A logical used to specify whether to overwrite to overwrite
the existing data dictionary or not. Default is |
Value
A character with path to the folder where the data dictionary is
stored. When path = NULL
, the file will be stored in the R
temporary folder as: dictionary.xlsx
Examples
# download and save the data dictionary in the default R temporary directory
path_to_dictionary <- sormas_get_data_dictionary()
Get the list of disease names from a SORMAS instance
Description
Get the list of disease names from a SORMAS instance
Usage
sormas_get_diseases(login)
Arguments
login |
A list with the user's authentication details |
Value
A vector of the list of disease names in a SORMAS instance
Examples
## Not run:
# establish the connection to the SORMAS system
sormas_login <- login(
type = "sormas",
from = "https://demo.sormas.org/sormas-rest",
user_name = "SurvSup",
password = "Lk5R7JXeZSEc"
)
disease_names <- sormas_get_diseases(
login = sormas_login
)
## End(Not run)
Get pathogen tests data from SORMAS
Description
Get pathogen tests data from SORMAS
Usage
sormas_get_pathogen_data(login, since)
Arguments
login |
A list with the user's authentication details |
since |
A Date value in ISO8601 format (YYYY-mm-dd). Default is |
Value
A data frame with the following two columns: 'case_id', 'Ct_values'
Get personal data of cases from a SORMAS instance
Description
Get personal data of cases from a SORMAS instance
Usage
sormas_get_persons_data(login, since)
Arguments
login |
A list with the user's authentication details |
since |
A Date value in ISO8601 format (YYYY-mm-dd). Default is |
Value
A data frame with the following eight columns: 'case_id', 'sex', 'date_of_birth', 'country', 'city', 'latitude', 'longitude'
Check if the value for the base_url argument has a correct structure
Description
Check if the value for the base_url argument has a correct structure
Usage
url_check(base_url)
Value
throws an error if the domain of the provided URL is not valid, (invisibly) TRUE