User Tools

Site Tools


other_platforms:how_to_use_timeplot

Timeplot

Overview

Timeplot is a Javascript application that allows users to take data files (in Text and XML formats) and create a timeline visualization of that data. It also allows users to overlay events with clickable information bubbles to explain certain events that may have impacted trends in the data. It contains options to improve the display, readability, and organization of the data.

In order to create a fully functional Timeplot, you must place three files on your Web server. If you want to use Timeplot on Domain of One's Own, we have created an installer in Installatron that will automatically unpack those files into a location you choose. The three files are:

  • An HTML file (.html),
  • a Text file (.txt), and
  • an XML file (.xml).

The HTML file links to an external Javascript and contains additional Javascript code that controls the programs functionality and appearance. It also contains the HTML markup to actually display the Timeplot. You can read more about the structure of the HTML file here.

The Text file is the file that holds your raw data. This data will be read by the Javascript code to create the data points on your Timeplot. When plotted correctly, the x-axis of the Timeplot will display dates, and the y-axis will display the data values. Below is an example snippet of what the Text file looks like.

You can read more about the structure of the Text file here.

The XML file contains information about events that you want to plot against your numerical data. It is also read in by the Javascript code in the HTML file. Like the Text file, it is specially structured so that the Javascript can read it. Below is an example snippet of what the XML file looks like.

You can read more about the structure of the XML file here.

Installation

This tutorial walks you through how to install Timeplot using the Installatron tool in Domain of One's Own.

To get started you'll need to login to your control panel by going to the UMW Domains homepage and clicking Login.

14269419746_8706f3e121_z.jpg

Here you'll login with your UMW network id and password.

14292016984_49a6a27b24_z.jpg

Once logged in you'll see your Dashboard for Domain of One's Own. You will need to scroll down until you see a section of the Control Panel labeled “Software/Services. Within this section you will see an icon for Installatron which you should click.

9510985268_fc4605b4bd_c.jpg

When Installatron opens, you will see a list of any applications you've already installed. To install something new, click on the Appilcations Browser button (labeled with a large star).

9508208389_0a55b0d0ca_c.jpg

In the Miscellaneous section, you will see an icon for Timeplot which you should click.

14894866636_f65bea92c5_b.jpg

After clicking the icon, a page will appear with information about Timeplot, links to resources, and a link to install it.

14894920646_085ce38107_z.jpg

Click install this application when you're ready.

A page will appear with a number of settings you can choose/change. The image below shows these settings; here is a rundown of them:

  • Location: You'll need to choose where to install your new application. You can install it at the root of your domain or in a subdomain (which you need to set up first). In addition, you can place your application in a folder (in either your root domain or a subdomain). There may be a default directory entered in the form. You can delete this and choose your own.
  • Version Information & License Agreement: You can leave the version setting as it is, and make sure you've accepted the license agreement.
  • Settings: Make sure you tell us what class this is for and if you're a student/faculty/staff member.

14731302840_1e93e98cea_c.jpg

When you're ready, click Install.

When Timeplot has successfully installed, you will see a summary view that shows you details about your installation, including links to view your new site.

14914969001_2b2102e212_b.jpg

If you click on the link to your site, you should see a basic Timeplot (as seen below), showing the sample data that is included in the install. You may proceed to the Basic Tutorial to learn how to customize the Timeplot with your own data.

Explanation of the HTML File

This is a walk-through of the contents of the HTML file that Timeplot uses. In particular, it walks you through the Javascript in the file.






Start of File and External Javascript

At the top of the file, you will see code to begin the HTML page and call an external Javascript file. This code is required for your Timeplot to work. You shouldn't edit or change the code or the URL.

<html>
<head>
 
<!-- This is the call to the timeline's API code. You should not edit it. -->
<script src="http://api.simile-widgets.org/timeplot/1.1/timeplot-api.js" type="text/javascript"></script>

Javascript

Below the call to the external javascript, you will see a block of javascript that contains information about the Timeplot to be displayed on the page. It begins with a tag to start the script:

<!-- This tag indicated the start of the javascript block -->
<script>

The majority of your work will be editing and modifying the block of code that follows. Comments in the code help to explain what each piece does. Subsequent tutorials will further explain this code as well as introduce other code you can add to modify and enhance your Timeplot.

   // This declares a variable for your Timeplot. You should not edit it
   var timeplot;
 
     //This begins the primary function that controls your Timeplot. 
     //It is referenced in the body tag of the HTML code below
     function onLoad() {
 
       // This declares a variable for your data source.
       var eventSource = new Timeplot.DefaultEventSource();
 
       // This declares a variable for information about your Timeplot. 
       // It has two properties already (id and datasource). 
       // You may modify or add to this variable depending on how you want your Timeplot to work.
       var plotInfo = [
           Timeplot.createPlotInfo({
              // The id property identifies a unique name for your plot.
               id: "plot1",
               // The datasource property identifies where to find your data and what part of the file to use.
               // By default in this example, we use thefirst column of data in your text file (denoted by the '1').
               dataSource: new Timeplot.ColumnSource(eventSource,1),
           }),
       ];
 
  // This statement creates your Timeplot (using the plotInfo variable you created above) 
  timeplot = Timeplot.create(document.getElementById("myplot"), plotInfo);
 
  // This statement indicates where the text file is located for your data. 
  // The location is relative to the file you are working on, 
  // and the comma (in quotes) indicates that the data is comma-delimited (separated by commas) in the text file.
  timeplot.loadText("data.txt", ",", eventSource);;
 
 
}
 
  // This next variable and function are used to dynamically resize your Timeplot 
  // when the browser window is resided. You should not edit it. 
   var resizeTimerID = null;
      function onResize() {
        if (resizeTimerID == null) {
        resizeTimerID = window.setTimeout(function() {
            resizeTimerID = null;
            timeplot.repaint();
        }, 100);
     }
    }
 
 
</script>

Next, you will see a couple of tags to close the Javascript portion of the page as well as the head section. You should not edit or change these tags.

</script>
 
  </head>

HTML

Below the head section, is the start of the actual body of the page.

<!-- This next tag starts the beginning of the actual HTML of the page.-->
<!-- You will notice it has two Javascript events attached to it. -->
<!-- These events will trigger the Javascript to actually run when the page loads or when it is resized.-->
<!-- You should not edit this portion of the code --> 
  <body onload="onLoad();" onresize="onResize();">

Next, we see a HTML “div” tag which is the container that will actually display your Timeplot.

<!-- This div tag becomes the container for your Timeplot.-->
<!-- The "id" here must match the Javascript statement above that creates the Timeplot.-->
<!-- The style information can be modified to change the size and/or border around the Timeplot. -->
  <div id="myplot" style="height: 150px; border: 1px solid #aaa"></div>

End of File

Finally, there are tags to close the entire body of the file and the entire HTML block.

 </body>
 
</html>

Explanation of the Text File

The text file (which uses a .txt extension) is the file that holds the raw data that the Javascript code reads into the program to create the data points on your Timeplot. When plotted correctly, the x-axis of the Timeplot will display dates and the y-axis will display the range of data values.

In order to successfully create a Timeplot you must use a specific format for the text file. You may either create your text file from scratch (using the format described below) or edit the sample text file that is created when you install Timeplot using Installatron.

To Create a Text File from Scratch

You will need to use a text editing program on your computer to create your text file. On Windows computers we recommend Notepad (free with the Windows operating system). On Macintosh computers we recommend Text Wrangler (Download for free here.)

To Edit the Sample Text Files

OPEN FILE EDITOR

Format of the Text File

Whether you're creating a text file from scratch or modifying the sample file, the ultimate format will be the same. The format of the data file, generally, consists of a single date and its corresponding data values all on a single line. The date and all values should be separated by commas.

The example image below shows a text file containing data about President George W. Bush' approval ratings. At the top of the file, you'll see a comment block (each comment line denoted by a ”#“), indicating what the data is and where it came from. Right above the data is a comment that indicates what the numerical values below are: dates and approval ratings (in percentages).

You can imagine each line of the file as a row in a spreadsheet and the commas as delimiting the placement of columns:

Timeplot allows you to plot multiple sets of data against the same selection of dates. You can include all of this data in a single text file. Imagine that each time you add a comma, you are adding another column to your “spreadhseet.”

In the images below, you'll see we've added additional ratings for President Bush (corresponding to the same dates) to the text file. The first image shows the regular text file; in the second one, we've added lines to indicate where the “columns” are:

Using the Text File

If you installed Timeplot using Installatron on Domain of One's Own, you'll have received a set of sample files that include the President Bush approval ratings data in .txt file. The file contains all three ratings. You may replace this data with your own data.

In the Basic Tutorial, we will walk you through how to modify the text file so that your data appears in your Timeplot.

Explanation of the XML File

The XML file (which uses the .xml extension) contains information about events that you want to plot against your numerical data. It is also read in by the Javascript code in the main HTML file. It is specially structured so that the javascript can read it.

In order to successfully create a Timeplot you must use a specific format for the XML file. You may either create your XML file from scratch (using the format described below) or edit the sample XML file that is created when you install Timeplot using Installatron.

To Create an XML File from Scratch

An XML file is really just a special “flavor” of a text file, so you will need to use a text editing program on your computer to create your XML file. On Windows computers we recommend Notepad (free with the Windows operating system). On Macintosh computers we recommend Text Wrangler (Download for free here.)

Remember when you save your file to use the .xml extension!

To Edit the Sample Text Files

First log into your Domain of One's Own account at umwdomains.com.

In the Dashboard, scroll down and click on the File Manager. Then select Web Root from the pop up window and click Go. You may want to review the tutorial on the File Manager here.

Once inside find the file folder for your Timeplot; it should look like the image below (although the name of the folder will correspond to whatever sudomain/directory you chose for your install of Timeplot). Double-click and open the folder.

Inside you should see three types files:

  • index.html
  • data.txt
  • events.xml

To make changes to any file, click on it and select Code Editor from the toolbar at the top of the page.

A pop up window will appear. Leave the settings as they are and click Edit in the bottom left corner.

Basic Format of the XML File

Whether you're creating an XML file from scratch or modifying a sample file, the ultimate format will be the same. The format of the file consists, generally, of each event on a single line, with information properly formatted so that it can be read by the Timeplot Javascript.

The image below shows a snippet of the default event XML file that will be created if you you install Timeplot using Installatron on Domain of One's Own. (It shows events that correspond with the President George W. Bush approval ratings data that is contained in the default text file created when you use Installatron to install Timeplot.)

14720861348_64c10e73d8_b.jpg

You can see that each event is contained within an tag titled “event,” and they contain three individual values:

  • start: The date (and time, if appropriate) of the event.
  • title: The title of the event (this will appear in a pop-up bubble on the Timeplot)
  • link: An (optional) URL that users can click on for more information about the event.

Please note that all values must be contained in quotation marks. In addition, you must include the closing forward slash before you close the event tag:

<event start="YOUR DATE GOES HERE" title="YOUR TITLE GOES HERE" link="YOUR URL GOES HERE" />

You may add as many events as you like, using this standard format.

Additional Event Data

There are a few additional values you can add to your events beyond what's contained in the sample file (and example above).

End Dates

If you wish to create an event that has a distinct start and end date (which will appear as a band on the Timeplot instead of just a line), you can add an end date. Simply include an “end” variable in the event tag:

<event start="YOUR START DATE GOES HERE" end="YOUR END DATE GOES HERE" title="YOUR TITLE GOES HERE" link="YOUR URL GOES HERE" />

Descriptions

Instead of including a URL, you may wish to put an actual description of your event, which will be included in the bubble that appears when someone clicks on the event in your Timeplot. You can do this by creating an explicit “open” and “close” event tag, with the description in between:

<event start="YOUR DATE GOES HERE" title="YOUR TITLE GOES HERE" link="YOUR URL GOES HERE">
YOUR DESCRIPTION GOES HERE
</event>

Note that when you use an explicit close tag, you do not need to include the forward slash at the end of the first event tag.

Event Colors

You may wish to color-code your events (to correspond, for example, for different color lines on your Timeplot). If so, you can add a “color” variable to the event tag.

<event start="YOUR DATE GOES HERE" title="YOUR TITLE GOES HERE" color="YOUR COLOR CODE GOES HERE" link="YOUR URL GOES HERE" />

Please note that your color choice must be represented as a hexadecimal code. You can read more about hex color codes here.

A Note about Date/Time Formatting

We recommend you use the following formats for date/time:

  • Date Only: Month DD YYYY (ex.May 10 1961)
  • Date & Time: Month DD YYYY HH:MM:SS GMTOffset (ex. May 10 1961 00:00:00 GMT-0600)

Using the XML File

If you installed Timeplot using Installatron on Domain of One's Own, you'll have received a set of sample files that include event data corresponding to President Bush's approval ratings in .xml file. You may replace the event data with your own.

In the Basic Tutorial, we will walk you through how to modify the XML file so that your events appear in your Timeplot.

Basic Tutorial

Before starting this tutorial, make sure you have installed Timeplot.

This tutorial will walk you through modifying the files that are created when you install Timeplot so that you can plot your own data. By the end, you will have a single data set plotted on a timeline, with visible axis markers, and rollover data information. For additional features, including adding more data sets to your timeline and adding events, please review the Advanced Tutorial.

NOTE

For the purpose of keeping this tutorial simple, we recommend that you edit the Timeplot files in the File Manager that is part of your Domain of One's Own dashboard. This tool works right in your Web browser and allows you to edit files on the Web server directly, so you do not need to edit files locally on your computer and then upload them to the server. One thing to keep in mind is that if you close a file in the File Manager editor, you will lose the ability to “Undo” any changes you've made. You may wish to periodically copy the working code from the editor into a Text editor program on your computer, so that you can easily revert to previous versions if suddenly your Timeplot stops working.

Opening Your Files

First log into your Domain of One's Own account at umwdomains.com.

In the Dashboard, scroll down and click on the File Manager. Then select Web Root from the pop up window and click Go. You may want to review the tutorial on the File Manager here.

Once inside find the file folder for your Timeplot; it should look like the image below (although the name of the folder will correspond to whatever sudomain/directory you chose for your install of Timeplot). Double-click and open the folder.

Inside you should see three files:

To make changes to any file, click on it and select Code Editor from the toolbar at the top of the page.

A pop up window will appear. Leave the settings as they are and click Edit in the bottom left corner.

Editing your Data (Text) File

For the most part, the files that were created when you installed Timeplot, are configured to create the basic features of your Timeplot with little intervention. You will, however, have to replace the sample data with your own.

To start, open the data.txt file following the instructions above about Opening Your Files.

Next, if you haven't already, review the Explanation of the Text File.

It should be clear how to edit/replace the sample data with your own. If you have already collected/formatted your data in a Text file on your computer, you can delete the contents of the sample file and simply copy/paste your data in its place.

At the top of the file, you will see a comment block (denoted by the ”#“ tags) that you can replace with information about your own data.

Below that, you will see the actual numerical data. Replace it with your own data. Make sure to use commas between dates and data and only put one date per line.

One thing to keep in mind is that the sample data contains 3 data sets (approval, disapproval, and unsure ratings). For our purposes, you will only be putting in a single data set, so you will only need one “column” of data . The Timeplot code is, by default, set to process the first “column” so make sure you enter your data in the appropriate location.

If you plan on plotting more than one data set, go ahead and include it now. You will need to proceed to the Advanced Tutorial for information about how to plot those additional sets.

When you are done exit out of the File Manager. Browse to the location of your TimePlot and you should now see your data plotted on the timeline.

Adjusting The Graph

For the purposes of this basic tutorial, there are a few variables that you can change in order to alter the appearance of your graph:

Grid Colors

By default, the grid of the graph to a hexadecimal color of ”#000000“ which corresponds to black. You may replace this value with any hexadecimal color you like. You can read more about hex color codes here.

14732952697_e0557f7cb9_c.jpg

Axis Label Placement

By default, the x- and y-axis labels are placed at the left and top of the graph. You may change these to “bottom” or “right,” if you like.

14732971897_77783672e8_c.jpg

Advanced Tutorial

Once you've created a basic Timeplot, with a single line of data plotted, you may decide that you want to place additional data on your graph. This tutorial will cover adding two different kinds of data:

  • additional numerical data, which will result in a new “line” on your graph and
  • event information, which will result in a line or band for each event you wish to plot.

This tutorial will walk you through adding this additional data.

Creating Additional Lines on a Timeplot

Adding the Data

In order to add an additional plotted data line to your Timeplot, you will need to have a source for the data. The easiest way to do this is to edit your data.txt file and add a “column” to the comma-delimited file.

The two images below demonstrate how to add data to your existing file. The first shows a data file with one “column” of text (President Bush's approval ratings). In the second picture, two additional data sets have been added (disapproval and unsure ratings). You should see how adding an additional data set simply involves appending the numerical data to each data, separating it from the original data with a comma.

14773692529_4d5137fb3d_c.jpg

14937430456_4f1a99d254_c.jpg

Adding the Line

To create additional lines on the graph you will need to add a few lines of code to your HTML file.

First, locate the block of code that starts with the line

var plotInfo = [

You will need to copy the block of text directly below this line:

14960169422_6d332f12a9_c.jpg

Note that in the image above, the red box clearly identify where you should start/end the block you need to copy and paste.

Next, you must paste the block you copied directly below the first one. (In order to fit both blocks in the image below, we've removed the inline comments):

14774081027_9b304bd711_b.jpg

Now, you must edit the second block of data. The image below shows were you should (or can) make edits to the code you just pasted:

14961960945_5ba3d8d5ea_c.jpg

1. You MUST provide a new id for new the new line you are plotting. 2. You MUST indicate what “column” contains your data in your Text file. (See above) In this case, we'll be pulling in the second column for the second line of data. 3. You can change the grid color for the y-axis (valueGeometry). 4. You can change the grid placement for the y-axis (valueGeometry). 5. You can change the grid color for the y-axis (timeGeometry). 6. You can change the grid placement for the y-axis (timeGeometry).

You may add additional data/lines as you need by repeating these steps.

Adding Events to the Timeplot

Adding the Event Data

The first step in adding events to your Timeplot is ensuring that you have your event data ready. As discussed in the tutorial on the XML File, we recommend simply editing the sample file that is created when you install Timeplot using Installatron. Be sure to review that tutorial to be sure that your event data is ready.

Adding the Event Display

To actually add the events to your Timeplot, so that they are displayed on the graph, you will need to add a few blocks of codes in different places.

First, at the top of the program you have to set a new variable that will hold your event data. Place this directly below the line that declares the variable for holding your numerical data.

var eventSource2 = new Timeplot.DefaultEventSource();

The image below shows the placement of the new line of code: 14792703798_84751a9d6d_z.jpg

The next step is to create a new instance of the graph code, this time specifically for the events. You can place this block of code below any blocks that you're previously created for displaying your line data. If you have two lines on your graph, for example, you will have two blocks where you are setting the properties for those lines. The event block of code should go below these. You can copy and paste the code shown below, and you can place it as shown in the image below

Code Block:

Timeplot.createPlotInfo({
      id: "events",
      gridColor: "#000000",
      axisLabelsPlacement: "top",
      eventSource: eventSource2,
      lineColor: "#0000000"
 
      })

Image showing placement: 14792841909_58a44cb39d_z.jpg

Finally, you also need to tell the program where to find the XML file with your events in it. You'll need to add this line of code towards the bottom of the Javascript in your HTML file:

  timeplot.loadXML("events.xml", eventSource2);

Note that we're pointing to the default XML file that was created when you installed Timeplot (events.xml). If you've uploaded another file or renamed the original, you'll need to change that file name here. In addition, make sure the name of the variable name (eventSource2) matches what you added above.

We recommend placing this line of code directly below the line of code that shows where your numerical data is located. The image below illustrates the placement.

{{https://farm6.staticflickr.com/5596/14976511901_73426cea25_b.jpg}

Adding Points on the Timeplot

You may wish to show explicit points (or dots) on your lines, making it visually clearer where each individual data point is plotted. Doing this requires you to add the following line of code for each set of plot information:

dotColor: "#FF0000",

Note that you must declare a color for the dots, and it must be in a hexadecimal format.

We recommend placing the code directly above the line of code that indicates you want to show data values:

14978901072_b37d46f78b_b.jpg

The picture above illustrates the placement of this code, in this case for both sets of data that we've plotted.

Adding Line & Fill Colors to Line Plots

Timeplot allows you to change the color of the lines on your graph as well as fill in a color below each line.

You will need to add a new property for each set of plot information. The lines you need to add are:

lineColor: "#FF0000",
fillColor: "#FF0000",

You can choose whatever hexadecimal color code you like for these properties. We recommend placing the code directly above the line of code that indicates you want to show data values (you may also have a line for showing dots on your lines):

Changing the Color of Events

You may also change the color of the lines/bands created by your event data. Making this change requires editing your event XML file (instead of the HTML file). If you used the default XML file that was installed, the file name will be “events.xml” You may refer to the explanation of the XML File for a reminder about how to access and edit that file.

Once you have the file open, you can simply add a “color” property to each event. You can use different colors, for example, to group events that have a similar theme.

A sample event code BEFORE you add the color would look like this:

<event start="Jan 20 2009 08:00:00 GMT-0600" title="Conclusion of second term" link=""/>

A sample event code AFTER you add the color would look like this:

<event start="Jan 20 2009 08:00:00 GMT-0600" title="Conclusion of second term" color= "#FF0000" link=""/>

Note that the color is, once again, defined as a hexadecimal code. In addition, the value must be placed in quotes.

Make sure you save your XML file when you're done editing it.

other_platforms/how_to_use_timeplot.txt · Last modified: 2015/06/04 19:25 (external edit)