Skip to content

API Reference

Jump to bottom
William "Billy" Raseman edited this page Nov 3, 2019 · 13 revisions

Parasol API

The API documentation below is meant to give the user an idea of the features available in Parasol. For additional detail about API arguments, see this documentation generated using JSDoc.

# Parasol(data, config)(selector)

Set up a new Parasol object. The selector can also be a d3 selection.

In an HTML script, create charts that we want to link together.

// make a couple empty parallel coordinate charts of class "parcoords"
<body>
<div id="p0" class="parcoords" style="height:200px; width:800px;"></div>
<div id="p1" class="parcoords" style="height:200px; width:800px;"></div>
</body>

Then, use the following form to import data and bind the charts together into a Parasol object.

d3.csv('data/cars.csv').then(function(data) {
  // create Parasol object
  var ps = Parasol(data)('.parcoords')
	  // can chain Parasol API here:
	  // for example,
	  .linked()
  )

The methods described below can be chained to a Parasol object in this manner.

# Parasol.attachGrid(container, columns, options)

To attach an interactive data table using attachGrid(), we need to include the table in the HTML body:

// allocate space for parallel coordinates and SlickGrid data table
<body>
<div id="p0" class="parcoords" style="height:200px; width:800px;"></div>
<div id="p1" class="parcoords" style="height:200px; width:800px;"></div>
<div id="grid" class="slickgrid-container" style="width:100%;height:500px;"> </div>
</body>

Like before, import the data, create Parasol object, and implement the Parasol API. Here, we demonstrate attaching the data table and linking it with the plots:

d3.csv('data/cars.csv').then(function(data) {
  var ps = Parasol(data)('.parcoords')
	  .attachGrid({container: '#grid'})
	  .linked()
  )

# Parasol.cluster(k, displayIDs, palette, vars, options, std, hidden)

Use k-means clustering to partition similar groups of data.

The palette argument defaults to d3.schemeCategory10. For other color options, see the Categorical palettes from d3-scale-chromatic.

Example usage:

// specify three clusters, display on first and second plots (zero-indexed)
ps.cluster({k: 3, displayIDs: [0,1]});

// note, that if there are only two parallel coordinates plots, the follow code will be equivalent
ps.cluster({k: 3});

# Parasol.exportData(selection, filename)

Export selected data to new csv and download. If no filename is specified, the name will default to "parasol_data.csv".

Note: in Parasol, we used the word selection to any user action which selects a subset of the dataset, such as brushing and marking. This is not to be confused with a d3 selection.

Example usage:

// export only brushed data
ps.exportData(selection = 'brushed', filename = 'filename1.csv');

// export only marked data
ps.exportData(selection = 'marked');  // filename will be 'parasol_data.csv'

// export both brushed and marked data
ps.exportData(selection = 'selected', filename = 'filename2.csv');

// export all data
ps.exportData(selection = 'all');  // filename will be 'parasol_data.csv'

# Parasol.updateGrid(data, columns)

Update data displayed in grid.

# Parasol.hideAxes(partition)

Hide a set of axes globally or from specific charts. See related Parasol.showAxes.

// hide the an axis called 'name' from all charts
ps.hideAxes(['name']);

// hide certain axes on specific charts using cars.csv data
var partition = {
    0: ['displacement (cc)'],  // hide one axis from the first chart
    1: ['cylinders', 'power (hp)']  // hide two axes from the second chart
}
ps.hideAxes(partition);

# Parasol.keepData(selection)

Keep only selected data on charts. See related Parasol.removeData.

# Parasol.linked(chartIDs)

Link brush activity between user-specified charts and grid, if it exists. Defaults to linking all charts and grid.

# Parasol.removeData(selection)

Remove selected data on charts. See related Parasol.keepData.

# Parasol.resetSelections(selection)

Reset selections (i.e. brushed or marked data).

# Parasol.setAxesLayout(layout)

Specify the structure (or layout) of the parallel coordinates plots.

// specify which variables (from cars.csv) appear on which chart
ps.setAxesLayout({
  0: ['displacement (cc)', 'power (hp)','0-60 mph (s)'],
  1: ['economy (mpg)', 'cylinders','weight (lb)']
})

# Parasol.showAxes(partition)

Show a set of axes once they have been hidden. See related Parasol.hideAxes.

# Parasol.weightedSum(weights, displayIDs, norm)

Compute individual aggregate scores for each solution based on user specified weights.

Example usage:

  // setup weights (unspecified vars given weight = 0) for cars.csv data
  var weights = {
    "power (hp)": 0.8,
    "weight (lb)": 0.4,
    "0-60 mph (s)": 1
  };

  ps.weightedSum({ weights: weights })

Parcoords API

Parasol builds off the work of Syntagmatic's Parcoords library and BigFatDog's ES6 module of Parcoords. To allow users to conveniently access the Parcoords API while using Parasol, we've created a Parcoords wrapper that seamlessly integrates with the Parasol API. Simply chain any of the following Parcoords methods to a Parasol object just like you would with the Parasol API:

  • alpha()
  • alphaOnBrushed()
  • brushedColor()
  • brushReset()
  • bundleDimension() - note: bundle dimension variable must be visualized on plot for this to work
  • bundlingStrength()
  • color()
  • composite()
  • dimensions()
  • flipAxes()
  • highlight()
  • mark()
  • render()
  • reorderable()
  • scale() - change the axes limits of a parallel coordinates plot
  • shadows()
  • smoothness()
  • unhighlight()
  • unmark()

For additional information on these methods, check out the API references listed at the Parcoords libraries above!

Examples

To alter all charts simultaneously, simply chain the Parcoords API to a Parasol object:

ps.alpha(0.2)  // alter transparency
    .reorderable()  // make axes dynamically reorderable
    .color('#03719c')  // specify color
    .shadows()  // add white shadows so text is more readable
    .brushedColor('#fc5a50')  // color when brushed
    .bundleDimension('cylinders')  // bundle based on number of cylinders (cars.csv)
    .bundlingStrength(0.4)  // strength of bundles
    .smoothness(0.2)  // using Bezier curvers instead of linear polylines
    .render();  // render plot

You can also access each chart of a Parasol object individually using charts. For instance:

ps.charts[0]  // expose the first Parcoords chart within the Parasol object (zero-indexed)
  .reorderable().shadows().render();  // make chart reorderable with shadows
ps.charts[1]  // expose the second Parcoords chart
  .color("rgba(128,0,128,0.3)").alpha(0.6).render()  // make plot transparent purple
  .scale('Percent', [0, 100]);  // change axes limits called "Percent" to min = 0 and max = 100
Clone this wiki locally