Technical Documentation

Technical Details

The population explorer is rendered on a web page using d3.js. A call to the initialization function takes the form: popExplore.init(element, data_path, settings), where element is a CSS selector for the HTML element in which to insert the tool, data_path is the file path for the dataset to use to generate the tool, and settings is a JavaScript object specifiying parameters for what components to include in the tool. This settings object can determine what controls to produce and in what section, whether the optional table or graphic is shown, etc.

The code block below shows the call to the function that generated this example:

    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);
    });
);

This code defines 3 controls in the denominator setting, which populates the "Subpopulation" section, and 1 control in the numerator, which populates the "Participant Characteristics" section. Additional configuration for the simple visualization and linked table are also given. Details regarding all parameters that can be specified in the settings object are outlined below:

popExplorer.init(dataElement, raw, settings)

function

Renders a population explorer using the following parameters:

• dataElement - a standard css selector suitable for d3.select().
• raw a json object matching the formatting standards described in d3.csv()
• settings a json object specifying the parameters for the population explorer. Described in detail below.

Settings

object

An object whose properties describe the populationExplorer in its entirety.

settings.numerator

array of object

An array of objects selecting columns from the raw data to be included in the "Participant Characteristics" section. Each selected column is rendered as a set of custom controls, based on the object's settings.

settings.numerator[].name

string

The column from the dataset to be used to create the control.

settings.numerator[].head

string

The label to be used for the control.

settings.numerator[].type

string

Determines the type of control to be rendered. options are:

• cat for categorical variables - creates a checkbox for each distinct value of that variable in the dataset
• num for continuous variables - creates a slider with values spanning the range of that variable in the dataset
• checklist for grouping a number of distinct variables together into a set of checkboxes. If this type is used, names, labels and positive must be set, otherwise they are not used.

settings.numerator[].names

array of string

only applicable if settings.numerator[].type is equal to 'checklist'

An array of strings matching the names of variables from the dataset that should be grouped in the checklist.

settings.numerator[].labels

array of string

only applicable if settings.numerator[].type is equal to 'checklist'

An array of strings to be used as labels for the checkboxes; the order of labels must match the order of their corresponding variables in names.

settings.numerator[].positive

array of string

only applicable if settings.numerator[].type is equal to 'checklist'

An array that determines how the checklist variables are recognized as positive; the array can contain a single value that all positive values must match exactly or two values (minimum and maximum) to determine a numerical range within which all positive values must fall.

settings.denominator

array of object

An array of objects selecting columns from the raw data to be included in the "Subpopulation" section. Each selected column is rendered as a set of custom controls, based on the object's settings. Object settings are the same as those described for settings.numerator.

##settings.viz boolean

A true/false value to determine whether the grid displaying the current selection should display in the Summary section.

default: false

##settings.participantTable object

An object containing settings for how to display the optional Selected Participants table; if this is not specified, or set to null no table will be displayed.

default: null

###settings.participantTable.cols array of string

An array of strings matching the names of columns from the dataset that should be included in the Selected Participants table.

###settings.participantTable.n number

A number that determines how many records should be displayed in the Selected Participants table at a time.

default: 10

###settings.participantTable.start number

First record to show in the table.

default: 1

###settings.participantTable.paginate boolean

A true/false value that determines whether the Selected Participants table should allow pagination.

default: true