Skip to content

Tutorial 1: Getting started

Jump to bottom
William "Billy" Raseman edited this page May 23, 2019 · 17 revisions

Welcome to your first Parasol tutorial! This tutorial will walk you through making your first Parasol application. In the process, you will learn how to:

  • Create a web page by editing an HTML document
  • Import data and create a Parasol object
  • Create linked, interactive plots and data tables

Download Parasol

Navigate to the Parasol GitHub page and click on the Clone or download. If you are familiar with GitHub Desktop choose that option. If not, no problem, just choose Download ZIP and unzip the folder once it is finished downloading.

Once you have downloaded Parasol, navigate to the parasol-es folder. It should contain the following directories:

  • demo
  • dist
  • img
  • src

We'll just focus on the demo directory for this tutorial.

HTML: Create your webpage

Open tutorial-1.html within the demo directory using your favorite text editor (e.g., Notepad++, Atom). This is an HTML (hypertext markup language) file. With HTML code, developers can design the form and function of a web page with the help of CSS (cascading styling sheets) and a bit of JavaScript. And using HTML allows you to customize the look and feel of the app without having to write much code.

The tutorial-1.html file is empty at first, with some comments included to show you which parts of the file you'll eventually fill in. First, let's add the title to the HTML document.

1. Add title and metadata

At the top of the file, add the following code:

<!doctype html>  
<head>  
    <meta content="text/html;charset=utf-8" http-equiv="Content-Type">
    <meta content="utf-8" http-equiv="encoding">
    <title>Tutorial #1</title>  
</head>

This is pretty boilerplate code which defines HTML metadata and the title of the webpage. You can change the title from "Tutorial #1" to whatever you'd like.

2. Give it some style

Next, let's specify the style of the webpage. In web development, it is often best practice to create a CSS file which specifies the coloring, formatting, font, size, etc. of your webpage. That way, you can reuse CSS files across similar web pages. Don't worry, you won't have to create your own, we've already done the heavy lifting. Add the following code to your script to call the CSS files we've created for Parasol apps:

<link rel="stylesheet" type="text/css" href="parasol.css">
<link rel="stylesheet" type="text/css" href="style.css">

3. Load dependencies

To use Parasol, add these two lines below the rest of your code:

<script src="parasol.standalone.js"></script>
<script src="lib/d3.v5.min.js"></script>

The first line allows you to import Parasol to create interactive, linked parallel coordinate plots. In the second line, we import D3 (data- driven documents). Although D3 is very powerful, here, we are just using to import some data.

4. Add content

Now, we get to the good part, actually adding content--like text, plots, and data tables--to the web page. Note that the HTML <body> tag begins the content of the page, and the </body> tag ends it. So if you want to put more content than in this tutorial, you just need to have that content in between the body tags.

For this example, we'll just provide a description of the application and allocate space for two parallel coordinate plots and a data table.

Add the following code to do so:

<body>
  A simple Parasol application. 
  <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="height:500px; width:100%;"></div>
</body>

Notice that we use <div> tags to divide up the web page. By specifying ids and classes and defining styles for different divs, its easy to edit their form and function. Right now, these divs are empty, but we can use Parasol to bring them to life.

5. Create the interactive plots

Last, we get to put the magic of Parasol to work! Here we are actually going to write the code that creates our specific Parasol visualizations.

First, we need to define a function to visualize the data. The function below called visualize() takes in some data as an argument. Then, it passes that data into the Parasol() function which populates the two "parcoords" divs with parallel coordinates.

<script>
function visualize(data) {
  var ps = Parasol(data)('.parcoords')  // create Parasol object
}

var data = d3.csv('data/cars.csv')  // read in data
data.then(visualize)  // pass data into visualize() function
</script>

Alternatively, you can write the same code more compactly like this...

<script>
  d3.csv('data/cars.csv').then(function(data) {  // read in data and pass to function
    var ps = Parasol(data)('.parcoords')  // create Parasol object
  })
</script>

Use whatever version makes the most sense to you!

6. Viewing and editing your app

Since our app is designed for the web, to view it we need to host it on a server. But what's a server? When you are on the internet, every time you go to a new webpage, the files that make up that page is held in storage on a computer. This computer's job is to "serve" you that webpage and so you, the "client", can access it. Check out this video for a more complete explanation.

If we are creating a web application and want to test it out before hosting it online, we can use our own computer as a makeshift server, which is known as a "localhost" or internal server. There are many ways to do this, but we will use npm (Node Package Manager) to do so.

Download npm and use it to create a localhost

To install npm, follow the directions on this page: https://www.npmjs.com/get-npm. Once you've done so, open a terminal and run npm -v to confirm it has been installed correctly. Next, navigate to the parasol-es directory that you cloned or downloaded from the Parasol GitHub repo.

Run the following command to create a localhost and view your Parasol app: npm run dev

This will open a webpage with links to Parasol application examples. Under the Tutorials header, click on the link for Tutorial 1 to view your progress. Voila! Your app should look like this.

tutorial_figure-1

Editing the application

If it doesn't look right, open the JavaScript console (check out this link about how) to see if you have any errors that you need to fix. If you do have an error, try to correct it in your text editor, save it, and refresh the web page. If you cannot resolve the error and you believe there is an issue with Parasol, please report your problem to the Issues page.

Once your application is up and running, click and drag on any axis to create a brush. To remove a brush, click anywhere on the axis outside the brushed region.

tutorial_figure-2

Brushing is fun, but we can do more than that!

To add an interactive data table and link the plots and tables together, chain the .attachGrid() and .linked() methods to Parasol object in your code.

    var ps = Parasol(data)('.parcoords')  // create Parasol object
      .attachGrid({container: '#grid'})  // attach data table
      .linked()  // link PC plots and data table together

Combined with the rest of the JavaScript, you code should look like this...

<script>
// create function to create visualize PC and data table
function visualize(data) {
  var ps = Parasol(data)('.parcoords')  // create Parasol object
            .attachGrid({container: '#grid'})  // attach data table
            .linked()  // link PC plots and data table together
            // add additional Parasol API below
}

var data = d3.csv('data/cars.csv')  // read in data
data.then(visualize)  // pass data into visualize() function
</script>

Or, if you prefer the more compact notation...

<script>
// create function to create visualize PC and data table
d3.csv('data/cars.csv').then(function(data) {  // read in data and pass to function
  var ps = Parasol(data)('.parcoords')  // create Parasol object
            .attachGrid({container: '#grid'})  // attach data table
            .linked()  // link PC plots and data table together
            // add additional Parasol API below
})
</script>

Save your changes in the text editor and refresh the page. You should see that a table has appeared. If you mouse over any row, you'll notice that a single polyline will be highlighted in the plots above. If you check the boxes on the table, you can mark that polyline.

tutorial_figure-3

To unmark, just uncheck that box. And if you brush on either plot, you'll notice that those changes are reflected in both plots and the data table is updated accordingly. Cool!

If couldn't get your application working, we've provided example code for a working application called tutorial-1_completed.html, which is located in the demo directory. To play around with the working example, double-click on the tutorial-1.html_completed.html in your file explorer to bring up the application in a web browser.

Well that's it for your first Parasol application. Congrats for finishing! In the next tutorial, we'll continue to explore the Parasol API.

Clone this wiki locally