Overview
In this tutorial, the most important steps for using TRAViz are explained:
1. Include Files2. 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:
<head> ... <link rel="stylesheet" href="traviz_directory/traviz.css" type="text/css"/> <script src="traviz_directory/traviz-min.js"/> ... </head>
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);
traviz.align(yourData);
traviz.visualize();
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.
[ ... edition_i, edition_j, edition_k, ... ]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' (default) |  |
| connectionType: 'joined' |  |
| connectionType: 'majority' |  |
Curve Radius
| curveRadius: 10 (default) |  |
| curveRadius: 5 |  |
Start and End Vertex
| startAndEnd: true | |
| startAndEnd: false |  |
Vertex Styles
| baseColor: '#3E576F' vertexBackground: '#F2F2F2' font: 'Georgia' (default) | |
| baseColor: 'black' vertexBackground: false font: 'Sawasdee' |  |
Normalization
| normalize: true (default) | |
| 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:
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 :-)
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.
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.
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· QUIB· S̄P̄S̄ DS̄ ETIA ̄"TRAViz computes the following layout:
