Home

Overview

The Population Explorer is a simple JavaScript library that facilitates the real-time exploration of data sets using an intuitive user interface. The tool was designed to empower researchers to explore their medical research data in real time. A simple example of the tool is shown below; a live, interactive version can be found here.

Once the page loads, users choose a "Subpopulation" of interest (e.g. a particular study site) or use the default settings to look across the whole population. Next, they define characteristics of interest to generate real-time rates. Both the rates and subpopulations can be updated in real time. This simple tool allows for surprisingly complex queries and facilitates data exploration, data cleaning and hypothesis generation. See the Basic Explorer example for an example using real data. For technical details and an explanation of how to create a population explorer of your own, see the User Guide.

How to Use

The Population Explorer can be used in modern browsers (IE9+, Chrome, Firefox, etc.) either via the global namespace:

<script src="http://d3js.org/d3.v3.min.js"></script>
<script src="http://code.jquery.com/jquery-1.9.1.min.js"></script>
<script src="http://code.jquery.com/ui/1.9.2/jquery-ui.js"></script>	
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/2.3.1/js/bootstrap.min.js"></script>
<script src="https://cdn.rawgit.com/RhoInc/PopulationExplorer/master/populationExplorer.js"></script>	
<script src="https://cdn.rawgit.com/RhoInc/PopulationExplorer/master/basicTable.js"></script>	
<script type='text/javascript' src='populationExplorer.js'></script>

or with an AMD module loader like Require.js:

require.config({paths: {populationExplorer: "populationExplorer"}});

require(["populationExplorer"], function(populationExplorer) {
  // initialize the tool here
  populationExplorer.init(...)
});

As shown above, the tool requires several common JavaScript libraries.:

• d3 (v3+)
• jquery (tested with v1.9.1)
• jquery-ui (tested with v1.9.2)
• bootstrap (tested with v2.3.1)

Making a Chart

Each instance of the population explorer is created with a call to popExplore.init(), a function that configures and renders the tool. The chart shown above is rendered with the following code:

    var dataElement = "body";
    var dataPath = "mockData.csv"
    var settings = {
        "denominator":[
            {"type":"cat","name":"gender","head":"Gender"},
            {"type":"num","name":"age","head":"Age"},
            {"type":"cat","name":"treatment","head":"Treatment"},
        ],
        "numerator":[
            {"type":"cat","name":"outcome","head":"Outcome"},
        ],
        "rowUnits":"enrolled particpants",
        "viz":true,
        "participantTable":{
            "cols":["gender","age","treatment","outcome"],
	        "start":1,
    	    "n":10,
        	"paginate":true
        }
    }
    
    d3.csv(dataPath,function(error,raw){
        popExplore.init(dataElement,raw,settings);
    })

The first argument, "body", tells the function where to draw the chart. This is a simple CSS selector, so it may reference a DOM element name (like in this example) or target an id or class attribute, like ".chart-wrapper".

The second argument, mockData.csv, is a path to the raw data, saved here as a comma delimited file.

The third argument is a JavaScript object that sets a number of options for the chart. All of the possible configuration options are described here. The config object in this example sets some basic options like what dataset fields should be used and how the linked table should be configured.

An interactive version of the sample chart is available here.