EpiJSON is a generic JSON format for storing epidemiological data.

repijson is an R package that allows conversion between EpiJSON files and R data formats.

This vignette is a demonstration of the package repijson.

Epidemiological data is often stored and transferred as spread-sheets, databases, and text files with little standardisation in row, column and field names. A universal format enabling the coherent storage and transfer of these data is lacking. In many cases where transfer does occur, there is room for misinterpretation and preventable errors may be introduced into reports and analyses.

EpiJSON provides a potential solution for the unambiguous storage and transfer of epidemiological data. repijson facilitates the use of EpiJSON within R.

Installing repijson

To install the development version from github:


Then, to load the package, use:


The EpiJSON format

This is a simplified representation of the EpiJSON format.

#here deliberately not echoed just to show the diagram
epijsonObjectVis(textSize = 5) #textSize 4 is default

The repijson objects used to store EpiJSON are represented in the following diagram.

#here deliberately not echoed just to show the diagram
epijsonObjectVis( attribMeta = 'ejAttribute',
                  attribRecord = 'ejAttribute',
                  attribEvent = 'ejAttribute',
                  labelObject = 'ejObject',
                  labelMeta = 'ejMetadata',
                  labelRecord = 'ejRecord',
                  labelEvent = 'ejEvent',
                  textSize = 5) #textSize 4 is default

First simple example creating an repijson object from a dataframe

toyll is a small example dataframe within the repijson package. It follows the structure of a disease outbreak line list, with individuals in rows and data stored in columns. This is what the first 3 rows and 8 columns look like :


The example below creates an ejObject from the first 3 rows. It assigns the columns "name" and "gender" as record attributes. It defines two events, "admission" and "discharge". The "hospital" column is assigned as an attribute of the first event.

#converting dates to date format
toyll$date.of.admission <- as.POSIXct(toyll$date.of.admission)
toyll$date.of.discharge <- as.POSIXct(toyll$date.of.discharge)
#create ejObject
ejOb <- as.ejObject(toyll[1:3,],
                      define_ejEvent(name="admission", date="date.of.admission",attributes="hospital"),
                      define_ejEvent(name="discharge", date="date.of.discharge")
#display ejObject

Load the required packages for further examples.


Creating example dataframe 1.


Adding some dates, pumps, some genders

simulated <- Snow.deaths
simulated$gender <- c("male","female")[(runif(nrow(simulated))>0.5) +1]
simulated$date <- as.POSIXct("1854-04-05") + rnorm(nrow(simulated), 10) * 86400
simulated$pump <- ceiling(runif(nrow(simulated)) * 5)


Creating example dataframe 2.

exampledata2<- data.frame(id=c(1,2,3,4,5),
                 hospital=c(NA,"St Marys","Whittington",NA,"Whittington"),


Transition 1: data.frame to EpiJSON format

Use the repijson package to convert a data.frame object into a EpiJSON object within R:

eg1 <- as.ejObject(exampledata1,    
    recordAttributes = "gender",    
    eventDefinitions = list(define_ejEvent(date="date", name="Death", location=list(x="x", y="y", proj4string=""), attributes="pump")),

The repijson package does not convert dates represented as strings for you. This is because the process of conversion from character to date-time is fraught with difficulty and the hidden corruption of dates is much worse than being told by R to provide date objects. Here we convert the dates in the example two data to real dates. We use POSIXct as this is more firendly to data.frames.

exampledata2$date.of.onset <- as.POSIXct(exampledata2$date.of.onset)
exampledata2$date.of.admission <- as.POSIXct(exampledata2$date.of.admission)
exampledata2$date.of.discharge <- as.POSIXct(exampledata2$date.of.discharge)
exampledata2$ <- as.POSIXct(exampledata2$
exampledata2$ <- as.POSIXct(exampledata2$
exampledata2$ <- as.POSIXct(exampledata2$

We are now set to convert the exampledata2 dataframe to an EpiJSON object.

eg2 <- as.ejObject(exampledata2, recordAttributes = c("id","name","dob","gender"),
     eventDefinitions = list(define_ejEvent(name="Date Of Onset", date="date.of.onset", 
                             define_ejEvent(name="Hospital admission", date="date.of.admission", 
                                            attributes=list("hospital", "fever", "sleepy")),
                             define_ejEvent(name="Hospital discharge", date="date.of.discharge"),
                             define_ejEvent(name="Contact1", date="", attributes=list("")),
                             define_ejEvent(name="Contact2", date="", attributes=list("")),
                             define_ejEvent(name="Contact3", date="", attributes=list(""))

Transition 2: EpiJSON object to data.frame format

Use the repijson package to convert a JSON object into a data.frame object:

Transition 3: From obkData to an EpiJSON object

These are example data in obkData format


Use the repijson package to convert an obkData object to JSON object into :

eg3 <- as.ejObject(ToyOutbreak)

Transition 4: From an EpiJSON object to obkData

Next function to produce

Transition 5: From an EpiJSON object to spatial

Use the repijson package to convert from an EpiJSON object to spatial (sp). Here we get the location of all the events as a SpatialPointsDataFrame

sp_eg1 <- as.SpatialPointsDataFrame.ejObject(eg1)
text(10,17,"Example from Snow Deaths data")

Try the repijson package in your browser

Any scripts or data that you put into this service are public.

repijson documentation built on May 29, 2017, 2:12 p.m.