NVSS   User Manual

Author:Aleks Aris ()
If you have any comment or question, send an email to the author.

NVSS Web page: http://www.cs.umd.edu/hcil/nvss
Human-Computer Interaction Lab
University of Maryland, College Park

1. Introduction

NVSS (Network Visualization by Semantic Substrates) provides a novel approach to network visualization and enables users to specify regions to group nodes and place nodes within each region, and then control link visibility. The specification of layout is called a Semantic Substrates, which users can create using a module of NVSS called The Substrate Designer.

2. System Requirements

NVSS is written in Java using the JUNG and Piccolo libraries. As a result, NVSS works on any platform that Java runs on. Java WebStart is required for NVSS versions that are downloaded over the internet and automatically installed on the client, where it runs as an application.

3. Installation and Running

For the Java WebStart version of NVSS, simply click on the download link, and NVSS will be downloaded and automatically installed on your machine. It is a good idea to have a directory ready for NVSS input files (files representing the networks) and substrate files.

4. Input Data Formats

NVSS uses network data and attribute data as described in the following subsections.
Feel free to download the sample dataset
friendship.zip, which illustrates all formats in this section.

4.1 Network data

NVSS uses the following format for network data:
HCIL Network Visualization Data File Format - version 1.

4.2 Data Model

Data Model is stored in a text file, where each line contains three items, where items are delimited by a TAB character. The first item is the attribute name, the second item is the attribute type (one of: INTEGER, DOUBLE, STRING, and DATE), and the third item is the attribute label. See the Data Model file in the example dataset (see
sec 4) to see all details regarding the format of this file. These files are usually named as "dataset name Data Model.txt" (e.g. "Friendship Data Model.txt").

4.3 Attribute Value Converter (AVC)

For each placement attribute, an axis converter is used, where the default one is the identity axis converter. The axis converter is used when more meaningful values could be presented to the user. For example, if 5-year periods are grouped and they are given a group number representing year ranges, those numbers would not be very meaningful to users. Instead, the year ranges they represent could be displayed by using an AVC (Attribute Value Converter) file (see Figure A). An AVC file could be created using a spreadsheet program, such as Microsoft Excel, and saving it as a TAB delimited text file. This text file will need to be uploaded into the place below the attribute in the placement selector method dialog every time it needs to be applied. In an AVC file, A1 is the name of the attribute, the values of which will be converted. B1 is a name describing what the converted value represents. A2 is the type of the attribute to be converted, while B2 is the type of the converted attribute (usually STRING).

AVC File
Figure A Example AVC File

5. The User Interface

NVSS has a main module that allows load and editing of a Semantic Substrate. The editing and creating of a Semantic Substrate is accomplished via another module called Substrate Designer.

The NVSS main module leads to the visualization module. The following subsections illustrate all these three modules.

5.1 NVSS Main

Figure 1 NVSS Main module of NVSS

Users load an already created substrate by pressing the "Load" button, which populates the text field below it. Then, users load the nodes and links file. They press "Create Graph". At this stage, NVSS reports compatibility problems with the graph if any. Then, users press "Launch" to combine the substrate with the internally created network to launch the NVSS Visualization Module with the substrate applied to the created network.

Note that "Launch" is enabled only after "Create Graph" is pressed. Changing the Nodes file or the Links file will require pressing "Create Graph" again to create the new graph.

"Edit" is available only after "Load" is pressed because "Edit" applies to an already loaded substrate.

To create a new substrate, press "New". A prompt will ask for the location of a "Data Model File". This file is necessary to create a new substrate (see sec 5.2). The data model file can be manually created in a text editor or can be generated by specifying the "Nodes file" and then pressing "Create Data Model File" button. The prompt will ask for the name of the "data model". Usually, the name of the dataset (e.g. "friendship") is appropriate. After this entry, a file chooser will appear to save the "Data Model File". The file chooser suggests the same location as the "Nodes file" and "name of the data model Data Model.txt" as the name of the data model file.

Users can use subset of the nodes file as long as they check the "superset" checkbox to indicate that the links file is a superset of links that are needed in this dataset.

Users can save the current setting of the substrate, nodes, links files and the superset checkbox state via File->Save Project. They can load the settings via File->Load Project. This makes the startup process very fast.

Alternatively, web locations can be specified in the project file instead of file locations on the local computer. Provided that the local computer has internet connectivity, these files can be accessed via File->Open Project. NVSS will read the files over the internet. This eliminates the need to download dataset files to client machines except the project file, which can make the startup process even faster.

5.2 The Substrate Designer

The Substrate Designer is accessible though the NVSS Main module. When users press the "New" or "Edit" button, NVSS Main launches an instance of the Substrate Designer. "New" launches the Substrate Designer with a new blank substrate, while "Edit" launches it with the already loaded substrate ("Edit" button is disabled until users load a substrate using the "Load" button.) When users press the "New" button, they are prompted to specify an "Data Model File" (see section 4.2). The data model file is an integral part of a semantic substrate. The data model file defines the "data model" to be used, which provides the attributes available for grouping nodes into regions and placing nodes within them.

Figure 2 shows the Substrate Designer with a new substrate. The user has designated a data model file, which defines the "Friendship Data Model".

NVSS Substrate Designer
Figure 2   Substrate Designer with a new blank substrate that uses the user-defined "Friendship Data Model"

Users need to first load the "Nodes File" (If "Nodes File" was specified in NVSS Main just before opening the substrate, it is taken from there automatically). The Substrate Designer analyzes the file to find the minimum and maximum values of attribute values for later use when users define the placement method.

Below the "Nodes File", there is "Background Image." Users can click on it to specify the location of an image file to be used as the background image for the entire substrate. The image will be placed at the top left corner.

Tip: You can use the "Background Image" feature to define map layouts. See section 6.1 for an example.

Below the "Background Image", the left hand side provides details for each region. The bottom part of the Substrate Designer provides substrate level details. The top left part represents the visualization component, where users can visually create and manipulate regions. The following subsections explain each part in the Substrate Designer.

5.2.1 The Visualization Part

Users can draw and manipulate regions in the visualization part. The modes are draw, select, delete, move, resize, move/resize. To switch to a mode, users click on the corresponding button at the top.

To draw regions, users click where they want the top left corner of the region to be, and then drag the mouse to the point where they release, where they want the bottom right corner of the region to be.
Users select a region in this mode by clicking on the region. Information of the selected region is updated on the left hand side.
Users click on the region they want to delete.
Users click on the region they want to move, drag to move the region and release the mousee where they want the region to remain.
Handles (little square shapes on each side and corner of each region) appear in this mode. Users click on the appropriate handle and drag it to resize the region.
Both move and resize functions are available in this mode.
In Figure 3, the user has loaded the "Nodes File", pressed draw, and drew a region on the visualization part.

NVSS Substrate Designer - draw
Figure 3   Drawing a region in the Substrate Designer

5.2.2 Region Details

The panel on the left hand side provides the details of the selected region in the visualization part. The selected region is indicated by a shaded border (as in Figure 3). Details can be set if there is no region. When the user draws a region, default settings of the new region are taken from the details panel. This property can be used to expedite the creation of similar regions as follows:
      Users can create a region and set all its settings. Then, they create the region that is going to be similar. The settings from the previous region are in the region details panel. Hence, they are used as default for the second region. Users just need to make any modifications necessary for the second region. In general, users can select a region with the closest settings before creating a new region to "copy & paste" the settings.

When users create a region on the visualization part, that region is assigned a number (e.g. 1), which is displayed as "Region number" on the details panel (see Figure 3). Users type the "Region label", which will appear on top of the region. "Attribute" and "Attribute value" together determine which nodes will fall into the selected region. Users need to first set the "Attribute" as it determines the type (INTEGER, DOUBLE, STRING, DATE) of the "Attribute Value".

"Attribute" and "Attribute Value" need to be set before the "Placement method" is selected. Currently, there are five placement algorithms provided to be used as part of the placement method:

The first four algorithms affect only one axis, where they leave the other axis free or introduce jitter. For example, GridPlot X will define the x-axis in terms of an attribute. A node's x-coordinate will be determined by this x-axis setting. The node's y-axis will be arbitrary in the sense that it is not derived from an attribute (specifically, nodes will be evenly spaced on the y-axis). GridPlot X Jittered is similar to GridPlot X except that nodes are jittered along the y-axis (moved up or down, separated by no change in location, alternatingly).

After selecting a placement algorithm, users need to define settings for each axis. First they choose an attribute along that axis, then they set the Minimum value, the Maximum value, and the Number of bins (Figure 4). By default, the minimum and maximum values are set according to at the data file provided ("Nodes file") and the "Attribute Value" set for the region. Users may need to override these values, especially if they want a common axis between two or more regions. In GridPlotXY placement method, to swap the settings of the axes, users can press the "Switch Axes" button.

Tip: If your values range from 0 to 9, enter the minimum value as 0 and the maximum value as 9 (and the number of bins 2, 5, or 10). The minimum value is the minimum value in the first bin and the maximum value is the maximum value in the last bin. If you choose the number of bins 2, then the first bin will contain {0,1,2,3,4} and the second bin will contain {5,6,7,8,9} (5 values in each bin; 2 bins; 2x5 = 10 values total).

To use custom bins, click the tab with title "Custom Bins" and put the left values of each bin and the right value of the last bin in comma separated form. For example, if you want to put the values 1..4 in the first bin, 5..6 in the second bin, and 7..10 in the 3rd bin, the custom bin values should be 1,5,7,10. Currently, bins are assumed to chunk continuous values (with numerical attributes, which are INTEGER and DOUBLE) and non-continuous bins are not supported (e.g. 1st bin=5..6, 2nd bin=1..4, and 3rd bin=7..10).

Placement Method Selector
Figure 4   The settings of a placement method

The horizontal axis can be on the top or bottom of the region. Users can specify in the region details.

Fill color determines the background color of the selected region, while node color determines the color of nodes inside the selected region.

X, Y, Width, Height determine the location and size of the selected region. These values can be modified manually to reflect on the visual representation of the region and vice versa.

5.2.3 Substrate Details

The bottom part of the Substrate Designer has the settings that concern the substrate. The bottom left determines the visualization size. Users can either type the values in the fields or resize the Substrate Designer (upon which the values will reflect the new size of the visualization part). The bottom right determines the node size. Node size can be a constant or defined in terms of the values of an attribute. There is the choice to apply a transformation on the attribute value if chosen. Currently, the only transformation available is the 5 + sqrt(X) / 5, which works well with a subset of the legal court case citations (values ranging from 1..800).

Tip: Make the coarse adjustments to region size by dragging in the "resize" mode, and then make the minor adjustments by altering the values on the details panel on the left. The coordinate value (X,Y,Width,Height) will be applied when focus is lost. So, to see the effect, click on another textfield.

Tip: The Data Model on a substrate is not supposed to change as many things depend on it. However, sometimes users wish it was possible as it saves time and a harmless change is made (e.g. adding an attribute to the Data Model). There is a secret operation that allows to update the Data Model. Ask Aleks Aris to learn about it.

Substrate Details
Figure 5   Substrate Details

5.3 The Visualization Module

Figure 5 shows an example for a substrate created for the sample dataset. The top region contains males, while the bottom part contains females (set using "Attribute" as "SEX" and "Attribute Value" as "M" for the top region and "F" for the bottom region). The colors for the top region are chosen to be light blue as the fill color (background) and dark blue as the node color to reflect the social stereotypical colors of blue associated with males. Similarly, pink is chosen for the bottom region that contains females. Links in this dataset are directed and indicate one-way friendship.

Figure 6 shows the sample frienship dataset with the example substrate created and applied to it. Once the substrate is created, users can "Load" the substrate on the NVSS Main module (see Figure 1), specify the "Nodes File" and "Links File", press "Create Graph" and then "Launch" to get to this point, i.e. launch the visualization module.

The Visualization Module with the sample dataset
Figure 6   The Visualization Module with the sample dataset and the example substrate applied

Users can change the link colors on the visualization module by clicking to the colors next to links on the control panel on the right hand side. Clicking to the colored boxes next to links brings up a color chooser module to change the color. The colors are updated in the memory copy of the applied substrate. To reuse this modified substrate, users shall save the substrate via the menu (File->Save Substrate).

Users can limit the visible links by using the filters. To activate a filter, users check the box at the far left just above the range filter. This will lead to displaying only outgoing links by the active filter. Users can further limit the range by dragging the left and right arrows on each side. The range is draggable from the middle (the dark yellow part). To switch to incoming links, users check the box "in?". Figure 7 shows an example.

The Visualization Module Filter Illustration
Figure 7   Use of filters in the Visualization Module

Users can activate more than one filter. Filters are restrictive in the sense that they always restrict the available links. In other words, an "AND" (conjunctive) logic is applied when more than one filter is active.

Users can see the details of a node by switching to the "Details" tab on the control panel (the right hand side) and clicking on the node of interest. Figure 8 shows the details of the topmost node.

The Visualization Module Details Illustration
Figure 8   Details tab in the Visualization Module

6. Examples of use illustrating important features

This section illustrates important features of NVSS via examples.

6.1.The background image feature

The background image feature could be used to set an image in the background of the substrate. This way, users can set a geographical map on the background, either to match the entire substrate or a region. Users need to manually adjust the size and the location of the image in the background image map and the region coordinates in the substrate so that they match in size and location. In addition, to place nodes on the map, the GridPlotXY placement method should be used with attributes that provide x and y coordinates for the x- and y-axes, respectively. Finally, the binning parameters should be adjusted so that nodes will appear to match their intended location on the map. Figure 9 illustrates this via the geographical map of an island specified as the background image of the layout. See section 5.2 to see where to define in the Substrate Designer.

Illustrating use of geographical
map layout.
Figure 9   A geographical map is used as the background image on the substrate to support the geographical map layout in the top region.

6.2. Linking web pages to node attributes

You can launch a web location within the default web browser in your system by a click on a node in NVSS. To do so, have an attribute that contains the web url be named as "URL". During the visualization, press and hold SHIFT key and click the LEFT (regular) mouse button. This will open the URL in the default browser of the system. Note that this feature works only for nodes (and not metanodes).

7. FAQ (Frequently Asked Questions)

1. Isn't the Data Model file redundant? After all, the attribute names and types are present in the nodes file.
Answer: No, it is not totally redundant. It has a third item for each attribute determining the attribute label.

2. Why isn't the attribute labels in the Data Model file in the nodes file instead? (Then, we wouldn't need the Data Model file)
Answer: It is not there because the attribute label is a property of the Data Model. The Data Model serves as a template for the data and is essential to create a substrate. In fact, it becomes part of a substrate. However, the data itself doesn't become part of a substrate. In principle, the data is independent of the substrate (in fact, only part of it is dependent, which is the Data Model). The 1st and 2nd rows indicating attribute names and types are put in the nodes and links files for convenience of reading, identifying compatible data and minimizing errors.
The Data Model can be used with multiple data files (nodes and links files). A set of nodes and links files should always be associated with a Data Model.

Last updated on:

Web Accessibility