In this tutorial, the most important steps for using TRAViz are explained:

1. Include Files
2. Add Required Div
3. Initialize TRAViz with your Data
TRAViz Input Data
TRAViz Configuration
Means of Interaction
Supporting Special Characters

1. Include Files

TRAViz requires the JavaScript libraries jQuery, Raphaël and qTip. All TRAViz sources and these libraries are combined and minified in one TRAViz source file. In the Source Code section, you can download the bundle version that you extract into your client folder. Then, include the TRAViz sources into the head environment of the HTML-page with:

		    <link rel="stylesheet" href="traviz_directory/traviz.css" type="text/css"/>
	 	    <script src="traviz_directory/traviz-min.js"/>

2. Add Required Div

As a container for TRAViz, you need to place a DIV with an arbitrary ID into the body of your document:


3. Initialize TRAViz with your Data

	var traviz = new TRAViz("TRAVizContainerDiv",yourConfiguration);
The first line initializes TRAViz. The JSON object "yourConfiguration" is optional and holds desired configuration changes. An overview of the default configurations that can be overwritten is given in: TRAViz Configuration.
With the second line, the texts of the input data will be aligned to each other. The data format is explained in TRAViz Input Data.
The last line creates the interactive visualization in the given DIV "TRAVizContainerDiv".

TRAViz Input Data

The given data must be an array with a JSON entry for each text edition.

Each entry of the array contains an edition ID and the corresponding text snippet. It looks like:
		    edition: 'Some Edition ID',
		    text: 'Some cool and fancy edition text that will be aligned to the other texts and visualized'
For the Genesis 1:1 example the array looks like:
		    edition: "American Standard Version",
		    text: "In the beginning God created the heavens and the earth."
		    edition: "Bible in Basic English",
		    text: "At the first God made the heaven and the earth."
		    edition: "Darby Bible",
		    text: "In the beginning God created the heavens and the earth."
		    edition: "King James Version",
		    text: "In the beginning God created the heaven and the earth."
		    edition: "World English Bible",
		    text: "In the beginning God created the heavens and the earth."
		    edition: "Young's Literal Translation",
		    text: "In the beginning of God`s preparing the heavens and the earth --"
		    edition: "New Life Version",
		    text: "In the beginning God made from nothing the heavens and the earth."

TRAViz Configuration

Below, you can find the standard configuration of TRAViz:

		/* General */
		colors: [ "red", "blue", "green", "rgb(230,230,0)", "orange", "#996600",
                  "purple", "#FF00FF", "#66FFFF", "#339999" ], // colors used to identify the various edition paths		
		normalize: true, // if the sentences shall be normalized or not (remove special characters)		
		lineBreaks: true, // if line breaks are allowed or not (if true, only the width of the given div is used)		
		rtl: false, // if labels should be drawn from right to left (for arabic, hebrew)

		/* Text Vertices */		
		baseColor: '#3E576F', // color used for text and joined connections		
		vertexBackground: '#F2F2F2', // false or a CSS color for the text backgrounds		
		font: 'Georgia', // text font		
		startAndEnd: true, // if start and end vertex are shown and linked to all paths
		collapseLabels: 0, // text labels are only shown for vertices with more than the given value
		interpolateFontSize: false, // if true, the font size of the vertices is interpolated
                                    // between 'fontSizeMin' and 'fontSizeMax', otherwise the font size
                                    // grows by 4px with each edition
		fontSizeMin: 10, // minimum font size
		fontSizeMax: 50, // maximum font size
		fontSizeIncrease: 4, // the number of pixels the labels grow by edition if interpolateFontSize = false
		/* Connections */
		edgeGap: 5, // minimum gap between two connections; required when adjusting the connections horizontally and vertically		
		curveRadius: 10, // radius of the curves
		connectionType: 'all' // how the connections shall be displayed: 
						// 'all' for displaying each individual stream, 
						// 'joined' to merge all parallel connections, or 
						// 'majority' to merge only if more than half of the edges are routed between the same vertices

		/* General Settings */
		majorityPercentage: 0.5, // an edge becomes a majority edge when the given percentage of editions passes it
		editDistance: false, // false (or 0) if only exact matches between two words shall be merged or edit distance dependent on the word lengths computed with the formula 2*editDistance/(|word1|+|word2|)

		/* Interaction */
		splitAndMerge: true, // if the user is allowed to interactively split vertices or merge via drag&drop
		transpositions: true // if (potential) transpositions shall be determined and visualized on mouseover
To overwrite the defaults, e.g. the values for 'interpolateFontSize' and 'fontSizeMax', you just need to initialize TRAViz like:
	var traviz = new TRAViz("someDivName",{
		interpolateFontSize: true,
		fontSizeMax: 72
Below, we show the resultant visualizations for some of the configuration settings.
Connection Type
connectionType: 'all'
connectionType: 'joined'
connectionType: 'majority'
Curve Radius
curveRadius: 10
curveRadius: 5
Start and End Vertex
startAndEnd: true
startAndEnd: false
Vertex Styles
baseColor: '#3E576F'
vertexBackground: '#F2F2F2'
font: 'Georgia'
baseColor: 'black'
vertexBackground: false
font: 'Sawasdee'
normalize: true
normalize: false

Means of Interaction

TRAViz provides several means of interaction to analyze and explore the alignment structure. What's possible? The user can adjust general settings how the Text Variant Graph shall be computed, visualized and interacted with. The major opportunities:

  • Configure Relative Edit Distance (RED):
    In general, TRAViz only aligns exact matches of words of different editions. With a given relative edit distance, the user can adjust how strongly similar words can differ from each other by still aligning them. The relative edit distance for two words A and B is defined as

    RED(A,B) = 2*Levenshtein_distance(A,B)/(|A|+|B|).

    RED(A,B) = 0 is an exact match, RED(A,B) = 0.1-0.2 allows smaller variations (e.g. "beginnings" and "beginning"), and RED(A,B) = 0.3-0.5 allows stronger ones (e.g. "beginnings" and "bigynnyng"). RED(A,B) = 1 is possible, but does not make any sense :-)
  • Majority Definition:
    When visualizing the Text Variant Graph with majority edges, the user can configure, when an edge is drawn as a majority edge. The default value for "majorityPercentage" is 0.5, which means that an edge is drawn as a majority edge if at least half of the editions pass it. A lower value emphasizes these editions that differ strongly from the rest.
  • Split & Merge:
    The user can modify the graph structure ("splitAndMerge: true" in configuration) using the Drag&Drop gestures. Two vertices can be merged when this step does not produce a circle in the graph. Additionally, aligned words can be split. This helps to interactively adjust the alignment and remove potential errors of the alignment algorithm.

  • Transpositions:
    The transposition of words in various editions can be of particular interest for the observer. The configuration "transpositions: true" triggers automated computation of potential transpositions (no differentiation between stopwords and others) and the highlight of these transpositions when hovering a specific word in the graph.

    Supporting Special Characters

    To also align and visualize text editions that contain special characters, TRAViz accepts text snippets that contain HTML codes. For the example
    "NEQ&#183; QUIB&#183; S&#772;P&#772;S&#772; DS&#772; ETIA&nbsp;&#772;"
    TRAViz computes the following layout:
  • vizcovery.org