Neon GTD User Guide
Neon is a framework and provides middleware services to widget developers. As a way to demonstrate Neon, a number of widgets are provided within a single-page demo application, along with a dataset that the widgets can operate on.
The demo widgets are not really intended to be an end-user application. They exist to show off what Neon provides. The individual widgets do not know about each other; they are independent visual representations of the data. What Neon does is provide a common Data Access API so they can all get the data the same way, and an Interaction API so that they can set and respond to Filters. What this means to you is that you can create a widget and add it to a common application without needing to understand the internals of the other widgets or what they are doing. You just use the Data API, respond to data change events, and send out data change events, and Neon tracks the data to keep all the widgets in sync.
To start up and begin using the Neon demo app, refer to the instructions in the Neon Overview
When you connect to the Neon demo application, you will be presented with a screen with several widgets on it. They will not do anything without a dataset, so the first step is to select the dataset.
Click on the 'Choose Dataset' button on the upper left. Select 'Earthquakes' from the menu. The other datasets are not delivered with Neon Demo application. If you are interested in the Earthquakes dataset, you can learn more about it from http://earthquake.usgs.gov/earthquakes/feed/v1.0/csv.php. The USGS web page will tell you what all the columns mean and allow you to download other datasets.
If you want to use your own dataset that you've already loaded into Mongo, select Custom from the dropdown menu and fill in the appropriate connection and configuration fields.
The demo application comes with 5 widgets, 4 of which are used in the Earthquakes dataset. They are:
- The Timeline widget: This provides a histogram of events over the entire range of the data. The widget can be used to select (i.e. Filter) a particular time period of interest.
- The Line/Bar graph widget: Data can be plotted in either line (over time) or bar (by category) chart form, with X and Y axis configuration options for both. As discussed below, you can select what parts of the data that you want to show in this widget.
- The Tag Cloud widget: Unfortunately, the Earthquakes dataset does not have any data that is appropriate for this widget, so it is automatically hidden. If any of the data columns had data containing 'tags' or other groups of information, the widget would show them, changing the size of each tag according to the frequency.
- The Map widget: Data on the map is shown either in heatmap (default) or point format. When there are more than several hundred data points, the heat map shows the data better. Note for both modes a Point Limit field is set to prevent large datasets from crippling the application, but this limit can be increased or removed for smaller datasets.
- The Circular Heat widget: The circular heat chart accumulates the data as a function of what day of the week and what hour of the day the events occurred in.
Here, we use the Timeline widget to look at a particular time range. Left-click and hold on the Timeline widget to start the beginning of the time range and drag to set the end of the time range. When you release the mouse, the other widgets will update based on the time range selected. Note that the number of records changed to 1998 (rather than the original number) and the map has changed. In Neon terminology, we have added a Filter to the data; Neon is using the Alerting API to let the other widgets know that the data has changed, and uses the Data API to apply the Filter to those widgets. Note that there is a new 'Filter' tag icon on the upper right that is used to clear widget filters.
Try clicking in the middle of the selected time range and dragging it left and right. The other widgets will update appropriately. Note that earthquakes seem pretty well distributed over days of the week and hour of the day. Many data sets will show definite daily and hourly patterns, but it's reasonable that earthquakes don't depend on the time of day!
The Line/Bar Graph widget can be used to plot most types of data in the dataset. Click the gear icon to open the chart configuration options; then select 'net' under Categorize By to plot based on the network that the earthquake was reported on. Finally, try changing the Y-axis aggregation field to 'Average' to see average magnitude per day for each network. Note that selecting the wrong type of field (e.g. a non-numeric field for Y-axis or a non-string field for Categorize By) may produce junk results, it's up to the user to find a combination of fields that makes sense given the data. The bar graph can be configured in a similar fashion, which is discussed later.
After you've selected your field combination and plotted multiple series on the line chart, you can mouse over to display tooltips showing the exact counts for each series per day. The line chart will display the 10 series with the highest total counts first, and then combine the rest into an "Other" category.
If you want to de-clutter the line chart and only display the exact series you want, simply click on the legend icons to hide or show a particular series. The series will be hidden from the plot, allowing you to focus on only the data that matters to you.
The map widget can be zoomed in and out using either the mouse scroll wheel or the + and - buttons. You can pan by left-clicking and dragging. Try zooming into the Mediterranean, since that is a nice place to vacation, but you might be worried about earthquakes after noticing that they have them there.
Now, add a Filter to the map widget by holding down the shift button and left-clicking and dragging. Rather than the standard pan behaviour, using the shift button results in selecting a region and creating a geographic Filter. The other widgets will update and only show data corresponding to that Filter. One of the questions we might have is: "Just how strong are those earthquakes in that place I want to visit?" To determine that, we can plot them in the Bar chart, by selecting the gear icon in the Line/Bar widget, switching Chart Type to bar, and changing the X-axis to 'mag' (short for magnitude). Note that depending on what field you select for the bar graph X-axis, the graph can be overwhelmed and will not be able to show all the data.
In addition to the demo widgets, the demo application allows the user to view the raw data and filter it using forms. To view the raw data, click the View Data button at the top of the screen. You can sort the data using any of the columns and change the number of events shown. Click the View Data button a second time to hide it.
The Demo Widgets provide a way to select data geographically and temporally, but it would be nice to add arbitrary Filters in a SQL-like way. When we were looking at the raw data, and at the linechart, there was a 'type' field, which had 'earthquake' (which seems natural enough) but also has 'quarry'. Let's look at that data and see what we can learn about it. Click on the Create Filter button; in the left box, select 'type' from the dropdown. The dropdown has all the columns that were in the raw data. Leave the middle box as it is, which is '='; in the right box, type in 'quarry', without the quotation marks. Finally, click on the 'Add Filter' button to apply your new filter. The data in all the widgets will update, applying the Filter you created to them.
The result of applying the quarry filter is that almost all the data is filtered out, except for some events in the Pacific Northwest of the United States and near Vancouver in Canada. We can zoom into that region.
Since I'm likely to visit California, I'd like to know about quarry events there. Apply a geographic filter to the events, only selecting California. First, it's clear there are relatively few events. Second, if the Line/Bar chart is set to show magnitude, you can see that they are (comparatively) small events (average magnitude between 1 and 2). Third, quarry events only happen during weekdays, which is nice. Note that the dataset is worldwide, so the time is in UTC, so you would need to adjust for local time.
The map widget can show data in point format as well as a heatmap. Click the gear icon on the map widget and change the 'Map Layer' setting from Heatmap (cloud icon) to Point (map marker icon). We can also set what determines the size and color of the point. Here, I've set it so that it shows the size based on 'mag' (magnitude) and the color by 'magType' (how the magnitude was measured).
