outbreak_time_series_reader module - JohnTigue/idots GitHub Wiki

The outbreak_time_series_reader module is JavaScript which can read data conforming to the Outbreak Time Series Specification (The Spec). It can read all three serializations defined in The Spec.

Relevant convenience utilities are also provided. For example in the JSON format data is grouped primarily by time_interval yet outbreak_time_series_reader provides an index of data sorted by location. Another example: outbreak.time_series.maximums.otss_cases_all is a count of the maximum value of otss_cases_all encountered while reading a Outbreak Time Series document, which is useful information for scaling markers and calibrating dimensions in visualizations.

This is JavaScript code. JavaScript has various naming conventions. OTSS abstract data model names are algorithmically translated to JavaScript names, with JavaScript naming conventions. For example, foo_bar would be translated to fooBar.

Table of Contents

Introduction

outbreak_time_series_reader is a JavaScript module which works with:

  • web browsers (stand alone)
  • the AngularJS framework in a browser
  • node.js, in a server or the command line

This document describe how to code against the outbreak_time_series_reader API. If you are interested in issues related to the raw JSON of the Outbreak Time Series Specification, check out Outbreak Time Series Specification Tutorial.

The main reason to use outbreak_time_series_reader rather than just directly ripping up the data through the JSON object is that you get an easy to use model of the data that you can dot into, yet the data modeled could have come from any one of the three serializations defined in Outbreak Time Series Specification: JSON, XML, and CSV.

Do not underestimate CSV in the browser context, compared to the more common syntax of JSON; in the humanitarian community there are significant use cases where info is exported from spreadsheets to CSV. So, if you code up an outbreak visualization in a browser primarily for a data-in-JSON context but you nonetheless code against the outbreak_time_series_reader API, then folks who know how to export data from a spreadsheet program to CSV will be able to reuse your code without modification. That is, someone who can export CSV from Excell (of course, formatting the data according to the guidelines in The Spec) can immediately use your code. This use case is surprisingly prevalent in the humanitarian community. They will shower you with roses.

Architectural context

outbreak_time_series_reader is just a parsers and object model generator. It is intentionally designed without assumptions of the context within which it will be used. For example it can be used in a node server or in an Angular SPA, but there are no dependencies on those context.

Object model

The outbreak_time_series_reader JavaScript object model is simply the abstract model of the Outbreak Time Series Specification realized in JavaScript. There is a one-to-one correspondence between each part of the abstract model and the various object types described here. There are also conveniences added in, e.g.:

aPopulation.deaths.confirmed === aPopulation.attributes( "deathsConfirmed" ).value;
aPopulation.deaths.suspected === aPopulation.attributes( "deathsSuspected" ).value;

outbreak <a name='outbreak`>

An outbreak has 2 members:

  • metadata
  • `time_series

outbreak.metadata

payload_manifest

This is a quick summary of which data attributes where actually found while parsing a Resource.

outbreak.time_series

A time_series is a sequence of time_intervals, and some metadata.

outbreak.time_series.maximums

After loading an Outbreak Time Series document, 'outbreak.time_series.maximums' will have the maximum encountered value for all population properties found in the docs that begin with the prefix otss_.

So, if the document has data for:

  • otss_cases_all
  • otss_deaths_all
  • otss_basic_reproductive_number

Then there will be the following properties:

  • outbreak.time_series.maximums.otss_cases_all
  • outbreak.time_series.maximums.otss_deaths_all
  • outbreak.time_series.maximums.otss_basic_reproductive_number

If the data has sub-population data, the maximums will be across all sub-populations

Examples 

var anOutbreakReader = require("outbreak_time_series_reader");

// Data loading starts from JSON because the data in CSVW (essentially CSV plus a wee bit of JSON)
anOutbreakReader.read( "https://example.com/an_outbreak.json" );
...

Omolumeter

Omolumeter is an Angular SPA web-app which reads OTSS data and presents it via various visualizations.

Omolumeter is the proof of concept software for OTSS. As such the APIs of the OutbreakService are crude at this time (May 2016) but they do their job. This section documents the APIs for the OutbreakService as implemented in Omolumeter. Point is: Omolumeter and OutbreakService are Angular things – JavaScript yes, but APIs on a higher level than those of outbreak_time_series_reader.

OutbreakService

Deprecated

outbreak.time_series.intervals.bySequence

The array outbreak.time_series.intervals.bySequence should probably not be used. This is the sequence of intervals as they occurred as rows in the CVS files. It is not the temporalIndex; rather, that array is called outbreak.time_series.intervals.byTime. For example, in certain WHO files, the sequence of rows in the CSV is not the same sequence as when those rows (read:intervals) occurred in time.

interval.locations.bySequence

Same problem as outbreak.time_series.intervals.bySequence above.