TB-Vis
Help File
www.tbinsight.cs.rpi.edu
TB-Vis Help File
Rensselaer Polytechnic institute
www.tbinsight.cs.rpi.edu
Contents
What are host pathogen maps: .................................................................................................................... 2
Example of a tree map .............................................................................................................................. 2
Getting Started:............................................................................................................................................. 3
The Menu Bar............................................................................................................................................ 5
Data input : ................................................................................................................................................... 6
Control Panel :............................................................................................................................................... 7
Tree-map visualizer: .................................................................................................................................. 7
Controls: ................................................................................................................................................ 7
Dataset Summary:............................................................................................................................... 11
Drawing TB-VIS Map: .................................................................................................................................. 12
Controls on the map : ............................................................................................................................. 14
Context Menu ......................................................................................................................................... 15
Subgraphing ............................................................................................................................................ 16
Saving .......................................................................................................................................................... 17
Settings: ...................................................................................................................................................... 18
1
What are host pathogen maps:
Host-pathogen maps provide a graphical representation of strain and patient associations.
Patients are represented as nodes within nested rectangles depicting MTBC strains as typed by
various biomarkers. The visualization displays each strain by telescopic boxes depending on the
number of biomarkers uploaded. The host-pathogen maps are based on the design of treemaps. In an analogy to how tree-maps are applied to visualize the activity of a stock exchange,
genetically identical strains of MTBC can be thought of as a company and patients who acquire
a strain of tuberculosis can be thought of as buyers purchasing that company’s stock. The treemap hierarchy captures the genetic hierarchy imposed by the biomarkers much like tree-map
represents sectors of the stock market. The size of the box reflects the number of patients with
that strain. The patient nodes within the box can reflect patient properties critical for molecular
epidemiology investigations such as country of birth, drug resistance, and risk factors.
Example of a tree map
Fig. 1: Host-pathogen tree-map of patients infected with East-Asian (Beijing) strains in the NYC
dataset. The sections of the host-pathogen tree-map are: A) Tabbed pane, B) Display panel, C) Legend
panel, D) Query panel, E) Search panel.
The above figure shows the host pathogen map for the New York City data. The tree map has the
following features
2
Tabbed pane: Each unique value of the selected header in the spit by control spits up into a tab in the
display. In this figure there is one tab for every continent. The selected tab displays the tree map
corresponding to the tab.
Display Panel: The display panel holds tree-map for the selected tab. The tree map or the host pathogen
map contains levels of boxes .It contains circles inside the inner most box .The display panel has sliders
that can be used to zoom in and zoom out, search text area that can used to search for a particular data
within the tree map, color and box legends for the tree map .
Boxes: There can be multiple levels of boxes in the tree map. The boxes are nested inside each other
thus representing a hierarchy. In the above example the outer box represents spoligotype, and inner
box represents RFLP of MTBC strains. The host-pathogen map shows the predominance of East-Asian
(Beijing) strains in patients from East Asia and the US. Possible outbreaks are indicated by boxes with
many patients.
Circles : Circles are located in the inner most box. Each circle represents an individual record in this case
patients. Circles can be colored by any header that has a maximum of 12 unique entries in it.
Getting Started:
The TB-VIS tool can be accessed from the TB insight website. The following link will directly lead to the
software Web page
http://tbinsight.cs.rpi.edu/run_tb_vis.html
Alternatively if you are on the TB insight home page Click on Run TB-Vis under the TB-Vis menu.
Once you are on the webpage click on the “Launch” button to access the tool. The tool has been
implemented using Web services so the tool can be accessed only from the website. It is not possible to
have a local copy of the tool on your hard disk.
3
Click here to start
TB VIS
Fig 2 : Shows the tbinsight home page from which links to the Run TB-VIS Webpage
4
Press Launch to
download TB-VIS
Fig 3 : Shows the Run TB-Vis web page with the Launch button that should be clicked to download TBVis
Things to do when there is problem with downloading the tool :
The previous versions (Cache memory) needs to be cleared to download and use a new version .The
previous versions can be deleted by
Start menu -> run -> javaws –viewer -> This will open Java Cache viewer -> delete the Java applications
in that window
Now please go back to the link and download the new version using the ‘Launch” button.
The Menu Bar
The menu bar will have the File, Setting and Help menu
File Menu :
File -> Open Data File: Allows the user to open a local data file from their machine. Acceptable file
formats are tab delimited .txt files. Rows with blank entries will be thrown out.
File -> Open Demo File: Allows the user to choose a demo file packaged with the software.
File -> Save Tool Output: Opens a new window where the user can select images of the output from the
different tools. These images can then be saved to the users' machine
5
File -> Quit: Closes the entire program.
Setting Menu
Settings -> Settings: Opens a new window where the user can change the settings of all the tools.
Help Menu
Help -> Help: Opens a window where the user can view help for each tool as well as this help file.
Help -> About: Opens a small window with general information about the program as well as the
current version.
Data input :
The TB-VIS tool is currently designed to accept data in the form of Tab separated text file(.txt) (TSV)and
comma separated . More file type support will be extended in the future.
Data file on the computer can be loaded by going to File -> Open Data File, alternatively try one
of our demo files by going to File -> Open Demo File. When a data file is selected, a new tab will
be added to the main window for every available tool. At this time the tree-map visualizer is the
only available tool. Click on a tab to open the controls for that tool.
Select the open
data file and
load the data file
Fig 4 : Shows the TB-VIS tool home page which has the file , setting and help menu.
6
JNLP will prompt permission question to access the computer. Hit Allow to all permission or security
questions asked.
Control Panel :
Tree-map visualizer:
After the data is being loaded into the software . A “Tree-map Visualizer” tab opens open and this tab
has two divisions “Controls” and “Dataset summary”.
Step 1 : Click the Treemap visualizer
Step 2: Click here to begin
analysis
Data file appears
here
Fig 5 : Shows the Trremap visualizer page that has the controls and the dataset summary tabs
Controls:
A control panel is provided to customize the tree map . The control panel provides controls to change
layering and coloring in the visualisation.
7
The controls panel is divided into several sections. First, on the left:

Layer Settings: This control allows the user to assign headers to each layer in the
tree-map. This is further broken down into three groups as follows:
Fig 6 : Shows the create graph control which allows the user to assign headers for eac
level in the tree-map.
1. Color By: This drop-down box allows the user to select the column by which
individual data items will be colored. This column may not have more 12 unique
entries. Only valid column selections are shown in the list. If this box is left
empty, items will be colored gray by default.
2. Split By: This drop-down box allows the user to select what column data items
will be split by. Splitting the data produces one tree-map containing all of the
data items, and then one tree-map for each unique entry in the column to split
by, comprised only of data points containing that entry. This column may not
have more than 20 unique entries. Only valid column selections are shown in the
list. If this box is left empty, only one tree-map of all items will be produced.
8
3. Box(es) 1:n : The boxes allow the user to select in order, from outer-most to
inner-most, which columns will be used to construct boxes in the tree-map. Once
a drop down box is filled, a new one will appear. There is no limit to the number
of unique entries in a column chosen for boxes. If no boxes are selected, all data
items will be placed in a single box, Labeled All.
4. Set Graph Name: This is a text box that takes in a name for the graph. This name
can be used to identify the graph when saving it.

Item Color Settings: This control allows the user to assign the colors for each
unique item in the color by header. There are a set of default colors assigned.
These colors can be used as in or changed as per the user’s requirement.
Fig 7: Shows the color by control. This control appears only if Color by option is selected in
the layer controls
9
This will only appear if a Color By option is selected in the Layer Settings area. Here,
a box will appear for each unique entry in the Color By column, allowing you to
select which color data items featuring that entry will be rendered in. If the software
recognizes the Color By column header as a special case, it will apply default colors
accordingly; alternately, they will be assigned in arbitrary order. For more
information on recognized headers, see the Headers section. Regardless, you can
manually change and choose the colors

Labeling and Box Settings: This control allows the user to label the items on the
tree map. This control is option. Tree-maps can allows be drawn without
labeling.
This has two parts:
Fig 8 : Shows the labeling and box setting dialog box
1. Label Items By: Here you may select by which column data items are
labeled (or if they are to be labeled at all). Selecting Auto-generated
labels uses unique numerical IDs generated by the software for each data
10
item. These IDs are consistent throughout the software. Item labels
appear in black or white, depending on the color of the data item.
2. Box(es) 1:n : These only appear if boxing options are selected in the Layer
Settings area. Here you may select two things for each box box selected
in the Layer Settings section: firstly, the color of all boxes on that layer;
and secondly, whether or not to label all boxes on a certain layer. If a box
is labeled, it is labeled with its unique entry in the column the box is
drawn from. Box labels appear in the color of their box.
Dataset Summary:
On the right of the tree-map visualiser is the Dataset panel, which contains a summary of the
dataset and a display of the dataset itself, for quick reference. It contains information like the
number of entries and the number of unique entries under each header which can be useful
when trying to draw tree-map.
11
Fig 9 : Shows the dataset summary which gives a quick reference of the data that has been
loaded.
Drawing TB-Vis tree-maps:
The tool will generate the tree-map(s) on hitting the draw button located at the bottom left of
the display, specified in new tabs adjacent to the Controls panel .
12
Map Legends
Sliders
Hovered
readout
Color
Legends
Selected
read
Search
Fig 10: Shows a tree-map drawn with the given data and the various controls on the map
which can be used to analyze and understand the map
A Few things you can do on the map are :
Sliders: Each output panel features a legend and zoom slider on the right, and on the bottom a
search bar and two interactive readouts. The visualization is boldly located in the center of the
screen.
Selected read: The Selected readout displays information common to all the selected items.
Hovered readout: The Hovered readout displays information relevant to the item the mouse is
currently hovering over.
Search: The search dialog box, searches for the string typed into it in the current tree-map.
Checking “search on all data” searches the entire data file instead of just the current tree map.
13
Map legends: This draws out the legends of the three map indicating the level of boxes at each
level.
Color Legend: Color by shows the colors which are used to color by a particular field.
Controls on the map :
Once the map is drawn there are few controls which could be used to modify the map or get additional
information about the map.
14

Left clicking on the visualization controls item selection. If the user clicks on an item, or on a
box, that item or box is selected. Clicking on a selected item de-selects it. Holding the [Shift] key
while clicking enables selection of multiple items or boxes. [Shift] clicking on a selected item
removes it from the selected group; unmodified clicking when a group is selected de-selects the
entire group in favor of that single item. Holding the [Alt] key while left clicking selects only
boxes.

Dragging the left mouse button across the visualization intelligently selects all items in the
rectangle defined by the drag. With intelligent selections, if a box and all the items it contains
are selected, only the box is selected, as it implies selection of the contained items anyhow. The
exception is that if the box contains only one or two items, the items are selected instead.
Holding [Alt] while dragging selects only boxes, and holding [Ctrl] while dragging selects only
items. Holding [Shift] while dragging prevents de-selection of old selections, as always. Holding
all three, [Shift], [Alt], and [Ctrl] simultaneously instead de-selects all nodes in the rectangle.

Zooming is possible using the slider located between the legend and visualization. Zooming may
be necessary in larger data sets, or when using many layers of boxes, as items which are too
small may not be rendered. Zooming repairs this.

Panning becomes necessary after zooming. To pan, hold either the middle mouse button, or the
left and right mouse buttons simultaneously and drag the mouse.

Right clicking on the visualization brings up a context menu.

Searching highlights all items and boxes matching the searched terms. If you choose to search
on all data, every column in the data point will be searched for matches; otherwise, only
columns used to construct this particular tree will be searched. The number of matched items is
read out beneath the search field. Searches can be converted to selections. For more
information, see Context Menu.
Context Menu
Context menu provides options to change the graph in accordance with the needs of the user.
Right clicking on the visualization brings up the context menu. The context menu provides three
submenus and several options. They are as follows:
Fig 11 : Shows the context menu on right clicking on the tree-map
15

Graph from selection opens a submenu with several choices. For more information see
Subgraphing.
This submenu will not be available if no nodes are selected.

Select search results open a submenu with several options to allow the conversion from search
to selection. The options are
o Replace currently selected: This clears the current selection, and selects instead all
nodes currently searched for.
o Add to currently selected: This keeps the current selection, and in addition selects all
nodes currently searched for.
o Searched AND selected: This pares down the current selection, keeping only nodes
which were also searched for. That is, it takes the logical operator AND over the sets
searched and selected. This submenu will not be available if no nodes are searched.





View opens a submenu where simple visual settings can be modified. Here, the user can select
to enable or disable Detailed readout or Anti-Aliasing. See Settings for more information on
these settings.
Remove this graph: Selecting this option will close the current graph. This option is only
available when viewing Subgraphs For more information, see Subgraphing.
Invert Selection: This option appears when data is selected; it deselects the currently selected
data and selects everything else.
Select All: This option selects all the data in the graph. It appears only when no data is selected.
Cancel: Closes the context menu.
Subgraphing
Subgraphing allows the user to create more tree-maps from the subset of selected data. There are two
ways to subgraph: using old constraints, and using new constraints. They are described here:

Use new constraints: Selecting this option brings up the tree-map Constraints dialog box.

Use old constraints: Selecting this option brings up a dialog box in which you can name the
subgraph. Pressing Finish herein will create a subgraph from the selected data using the same
constraints as the graph it comes from. Pressing Cancel will close the dialog box without
subgraphing.

Other: This opens a new menu for the creation of subgraphs using tools other than the treemap tool. Selecting a tool from this list opens that tool's graphing dialog, and opens the
subgraph as a child of the currently selected graph. If no other tools are available in the
TBInsight suite, this sub-menu may not be selectable.
Subgraphs are opened in tabs adjacent to their parent graph, and the first generated graph is selected
and displayed.
16
Saving
The File->save option brings the following window.
Fig 10 : Shows the save menu dialog box
The user may use this screen to save graphs generated by any of the TBVis tools. First, the graphs to
save must be selected. This is accomplished by moving the graphs from the first list to the second
list. Clicking on a graph in either list pulls up a preview of the graph in the top right. Multiple
selections are supported using the [Shift] or [Ctrl] keys. In the event that multiple graphs are
selected, the first graph will typically be shown in preview.
17
Once the graphs to save are selected, they appear in a third list where the user can name them. By
default, they use their respective graph's titles. No name can be repeated; if one is, the software
will automatically append a number to the name. Finally, the user must actually save the graphs.
The Save full size check box allows the user to determine how images are created from graphs. If
the box is unchecked, graphs will be saved exactly as they appear within the software; however, if
the box is checked, graphs will be saved as larger images, displaying the entirety of the graph at its
current level of zoom, even if parts are hidden or off-screen within the software.
Finally, there are two options for saving:

Save Individually allows the user to save the images one by one, to whatever directory the
user pleases. This may take some time with many graphs, and due to permissions issues
that arise with Java Web-Start, the user may have to manually name each image here.

Save in .zip places all the rendered images, with their assigned names, into a .zip folder
which can then be saved to the user's hard drive.
Due to permissions issues, the software may appear to hang during saving. This can be mitigated by
waiting. Pressing Cancel at any time cancels saving and closes the dialog.
Settings:
Fig 11 : Shows the settings dialog box
18
Tree-map Visualizer settings can be reached from the settings dialog in the menu bar under
Settings>>Settings by selecting Tree-map Visualizer from the list on the left. Settings for the Treemap Visualizer tool are limited to those regarding label and box appearances; users may select label
font as well as a size range for the labels to appear in, and users may select the amount of padding
between the edge of a box and its children, as well as the width of the stroke which paints the box.
There are two editable fields, one displaying the selected font at its smallest and one at its largest.
Editing the fields to test the appearance of certain strings is encouraged.
If a label is too long for a box, it will be truncated and marked accordingly with an ellipsis. If the
label would be reduced to just an ellipsis, in the case of narrow boxes, the label is removed entirely.
The user may also choose here whether or not to enable:


Detailed readout: Default: OFF; If checked: ON.
Anti-Aliasing: Anti-Aliasing smoothens the visualization, making edges appear more
neatly, at the expense of processing power. As such, disabling Anti-Aliasing will make
the visualization look worse but run faster. Default: ON; If checked: ON.
Changing settings may sometimes require a tree-map graph to be redrawn to display correctly; this
can be triggered by zooming the graph.
Once the settings have been adjusted as desired, the user may press the Apply or OK buttons to
apply the new settings. To reset labeling settings, press the Reset to defaults button, and then Apply
or OK as normal.
19