# Initialization

CATview has to be initialized by: # initialize() CATview.initialize(orientation); Thereby the orientation of CATview can by set with the parameter orientation. Possible values are 'top', 'left', 'bottom' and 'right'. If orientation is not set, the default value 'top' will be used. The orientation affects the positioning and available space for the names- and edges axis as well as the tool icons. On horizontal orientations ('top' or 'bottom') the names axis will be placed left by using the available height. Thus, text witnesses are arranged in rows. In this case the edges axis will be placed at the bottom of CATview by using the available width. For vertical orientations ('left' or 'right') the names axis is located at the top and the edges axis in respect to the orientation at the left or right side. Tool icons are always oriented as the names axis but placed at the opposite side.

Example: Initializing CATview with bottom orientation CATview.initialize("bottom");

# Set and change the basic data - Names of Witnesses

The names in CATview define the number and of course the names of pictured text witnesses. A witness is a specific variant of a text and consists of segments. Its name will be plotted on the names axis and its segments will be represented as rectangles along the edges axis.

Setting the names is done by: # set_names() CATview.set_names(names); This will overwrite the names saved in CATview with them given by the parameter names, an array of strings. Short names, abbreviation or siglums are desirable as they will leave more space for the edges.

Example: Setting three names // names = []
CATview.set_names(["W1", "W2", "W3"]);
// names = ["W1", "W2", "W3"]

A single name can be added by: # add_name() CATview.add_name(name, index); The method will add a witness with the identifier name at a specific position. This position can be defined by the parameter index, with indices starting at 0. If index is undefined, the new name will added as the last one.

Example: Adding a witness "Wnew" at the second position // names = ["W1", "W2", "W3"]
CATview.add_name("Wnew", 1);
// names = ["W1", "Wnew", "W2", "W3"]

A single name can be removed with: # remove_name() CATview.remove_name(index); This will remove a witness at specific position defined by the obligatory parameter index.

Example: Removing the witness at the third position // names = ["W1", "Wnew", "W2", "W3"]
CATview.remove_name(2);
// names = ["W1", "Wnew", "W3"]

A single witness can be renamed with: # replace_name() CATview.replace_name(name, index); This will replace the name of the witness at the position defined by index with name.

Example: Renaming the witness at the second position // names = ["W1", "Wnew", "W3"]
CATview.replace_name("W2", 1);
// names = ["W1", "W2", "W3"]

# Set and change the basic data - Edges

The edges in CATview define an alignment of the witnesses' segments. Each alignment edge is an array with a number for each name that is either -1 or a value between 0 and 1. These values define where and in which color the segments represented by rectangles should be plotted. A value of -1 implies that no segment of the witness matched the others for this edge and thus, no rectangle should be plotted. In contrast, a value between 0 and 1 implies that the witness has a segment for this edge and should be plotted in a color according to the color scale. The color is useful to denote the degree of textual differences between the aligned segments. All edges will be mapped along the edges axis with a consecutively numbering starting at 1.

Setting the edges is done by: # set_edges() CATview.set_edges(edges); This will overwrite the edges currently saved in CATview with the parameter edges, an array of array of numbers.

Example: Setting four edges, whereat only two segments are aligned in the second edge and different colors are applied of segments in the fourth edge. // edges = []
CATview.set_edges([[0, 0, 0], [0, 0, -1], [0, 0, 0], [0, 0.5, 1]]);
// edges = [[0, 0, 0], [0, 0, -1], [0, 0, 0], [0, 0.5, 1]]

A single edge can be added by: # add_edge() CATview.add_edge(edge, index); This method will add the passed edge, an array with a number for each witness, at a specific position. The position can be defined by the parameter index, with indices starting at 0. If index is not set, the new edge will added as the last one.

Example: Adding the edge [0, -1, 1] at the third position // edges = [[0, 0, 0], [0, 0, -1], [0, 0, 0], [0, 0.5, 1]]
CATview.add_edge([0, -1, 0], 2);
// edges = [[0, 0, 0], [0, 0, -1], [0, -1, 0], [0, 0, 0], [0, 0.5, 1]]

A single edge can be removed with: # remove_edge() CATview.remove_edge(index); This will remove an edge at a specific position defined by the obligatory parameter index.

Example: Removing the edge at the fourth position // edges = [[0, 0, 0], [0, 0, -1], [0, -1, 0], [0, 0, 0], [0, 0.5, 1]]
CATview.remove_edge(3);
// edges = [[0, 0, 0], [0, 0, -1], [0, -1, 0], [0, 0.5, 1]]

A single edge can be replaced with: # replace_edge() CATview.replace_edge(edge, index); This will replace the edge at the position defined by index with the passed edge. The new edge must have the same dimensions as the old one.

Example: Replacing the edge at the third position // edges = [[0, 0, 0], [0, 0, -1], [0, -1, 0], [0, 0.5, 1]]
CATview.replace_edge([0, 0, 0], 2);
// edges = [[0, 0, 0], [0, 0, -1], [0, 0, 0], [0, 0.5, 1]]

# Draw and redraw CATview

CATview offers several functions to draw or redraw it or specific groups of elements respectively. Initiating an initial drawing is necessary and can be done after CATview was initialized and the basic data (names and edges) is set.

Draw CATview with: # draw_svg() CATview.draw_svg(); This will remove all content of the HTML-tag that has the id "CATview" and draw CATviews components into this tag as a single svg image. Thereby, width and height of the HTML-tag are used for CATviews dimensions. If the width or height changes, you have to ensure to call CATview.draw_svg(); again.

To redraw the alignment only, call: # draw_alignment() CATview.draw_alignment(); This will remove all rectangles and draw new ones according to the saved edges and the current level of detail.

To redraw the search results call: # draw_search_results() CATview.draw_search_results(); This will remove each highlighting of rectangles that represents a search result and draw new ones according to CATviews search_results and search_mode attributes and the current level of detail.

To redraw the scroll spy call: # draw_scroll_spy() CATview.draw_scroll_spy(index); This will remove the marking for the scroll spy and draw a new one at the position defined by the parameter index. The marking will be placed at the edge with position index + 1. If the position is beyond the current level of detail, the scroll spy is not drawn. How to redraw the scroll spy automatically within a text representation will be illustrated in section Adding a Scrollspy

To redraw the tool icons call: # draw_tool_icons() CATview.draw_tool_icons(); This will remove the tool icons and draw new ones according to the currently defined tools.

To limit the view to a subset of edges and redraw the corresponding content elements call: # refresh_content() CATview.refresh_content(from, to); This function is build to redraw the content after limiting it to a specific range of edges by setting the level of detail. The parameters from and to define that range as indices. If not set, the current level of detail is maintained. The function will remove all content elements, i.e. rectangles for edges, highlighting of search results and the scroll spy marking, and than redraw them according the level of detail.

# Levels of Detail

CATview can display different levels of detail by the built-in zoom. This zoom is enabled by default and can be triggered by using the mouse wheel. Per default the maximum zooming factor allows to increase the size of the edges as far as only ten of them can be displayed. It is automatically calculated when calling CATview.draw_svg() and depends on the available size for the edges axis. The enlarged excerpt can be moved via drag'n'drop.

To set the maximum zooming factor call: # set_max_zoom() CATview.set_max_zoom(max); The parameter max defines the maximum zooming factor, whereat 1 means no zooming is possible. The larger max the more the size of edges can be increased. If max is not set, the default value will allow to increase the size of the edges as far as only ten of them can be displayed.

Example: limiting the maximum zooming factor that edges can be enlarged about three times their default size CATview.set_max_zoom(3);

# Click on Edges Callback

CATview can react to clicks on the rectangles that represent the segments. For this purpose, a click behavior has to be defined that CATview can call when a click happens.

To set a click on edge behavior call: # set_click_on_edge_callback() CATview.set_click_on_edge_callback(callback); The obligatory parameter callback describes the behavior as a JavaScript function. When clicking on a rectangle CATview calls this function and pass the index of the witness and the edge as numbers.

Example: setting the click on edge behavior // add a callback that will jump to a segment when clicking in the corresponding rectangle
CATview.set_click_on_edge_callback(function(wit, edge){
document.querySelectorAll('.edge')[edge].scrollIntoView();
});


This simple behavior will pick up all HTML-tags that have the class "edge" and jump to that one with the same index as passed by parameter edge.

# Adding a Scrollspy

The scroll spy is a component to visualize a specific position within the alignment by an orange marking, e.g. pointing to the scrolling position in a larger text representation of the witnesses. To set the position and redraw the scroll spy use CATviews function CATview.draw_scroll_spy().

Example: Redrawing the scroll spy automatically within a text representation: // remember the last edge and the position of the scroll bar
let scroll_pos = 0;
let last_offset_top = 0;
// react on scrolling
window.onscroll = function(){
// get all edges and do nothing if there non
let edges = document.querySelectorAll('.edge');
if(edges.length < 0)
return false;

// get the current position of the scrollbar
let offset_top = window.pageYOffset;

// calculate the offset between the last edge and the scroll bar
let offset_pos = Math.abs(edges[scroll_pos].offsetTop - offset_top);

// get the next edge in scrolling direction and break if there is non
let edge = offset_top > last_offset_top ? scroll_pos + 1 : scroll_pos - 1;
if(edge < 0 || edge >= edges.length)
return true;

// calculate the offset between the this edge and the scroll bar
let offset_edge = Math.abs(edges[edge].offsetTop - offset_top);

// while finding edges with less offset, repeat the code above
while(offset_edge < offset_pos){
scroll_pos = edge;
offset_pos = Math.abs(edges[scroll_pos].offsetTop - offset_top);
edge = offset_top > last_offset_top ? scroll_pos + 1 : scroll_pos - 1;
if(edge < 0 || edge >= edges.length)
break;
offset_edge = Math.abs(edges[edge].offsetTop - offset_top);
}

// remember the current position of the scroll bar
last_offset_top = offset_top;

// refresh the scroll spy in CATview
CATview.draw_scroll_spy(parseInt(scroll_pos));

return true;
}; This example assumes that your text representation is a HTML website with the alignment edges are elements having a class '.edge'. The listener window.onscroll will react on scrolling this website and initiate the following behavior. Calculate the offset between the position of the scroll bar and the edge currently represented by CATviews scroll spy. Calculate this offset for next edge in the direction of scrolling too and compare both. Choose the new edge if the offset is less than that of the current edge and repeat this process until the offset gets greater again. Remember the edge with the lowest offset and pass it to CATview by calling CATview.draw_scroll_spy().

# Highlighting of Search Results

Highlighting search hits in CATview you have found within a text representation is an effective assistance for estimating the distribution of a subject within all witnesses. In order to achieve this, pass the search results to CATview and trigger the drawing.

To set search results call: # set_search_results() CATview.set_search_results(search_results); This will overwrite the currently saved search hits in CATview by the parameter search_results that is an array with pairs consisting of an edge index and an array with the rectangles defined by their names index.

Example: Setting search results let search_results = [
[4, [0]], // set the segment of first witness in fifth edge
[6, [0, 1, 2]], // set the segments of first three witnesses in the seventh edge
[7, [0, 2]]]; // set the segments of first and third witness in the eighth edge
CATview.set_search_results(search_results);

To trigger the drawing after setting the search results call CATviews function CATview.draw_search_results().

# Add extra Segments

Besides the aligned segments defined in section Set and change the basic data - Edges, CATview is also capable of displaying additional segments in a different form. An use case might be that individual segments could not directly be aligned due to changes of the order in one witness, but at least copies of the segments should be displayed at the appropriate positions.

Adding extra segments is done by: # set_extra_segments() CATview.set_extra_segments(segments); This will overwrite all current extra segments. The parameter segments is an array which holds an entry for each of the extra segments consisting of three values: the index of the edge, the index of the witness, and a value between 0 and 1 to color the extra segment according to the color scale.

Example: Setting two extra segments, one at edge 13 for the first witnesses and another at the 16th edge for the second witness with a different color applied. // extra_segments = []
CATview.set_extra_segments([[12, 0, 0.0], [15, 1, 0.5]]);


To (en- and) disable the display of extra segments, call: # toggle_display_extra_segments() CATview.toggle_display_extra_segments(toggle); Set the parameter toggle to false to hide extra segments and to true to show them again. If toggle is unset, the current state will be toggled to the other.

# Add Names to Edges

In addition to text witnesses, aligned text segments can also be assigned edge-wise names, which CATview displays when the mouse cursor hovers over a corresponding segment. The edge names can be set during initialization, but also afterwards (don't forget to redraw).

Setting the names for the edges is done by: # set_edge_names() CATview.set_edge_names(names); This will overwrite the currently saved names for edges. The parameter names is an array of strings (one per edge).

Example: Setting the name for all (four) edges // edge_names = []
CATview.set_edge_names(["Introduction", "Materials and Methods", "Results", "Discussion"]);
// edge_names = ["Introduction", "Materials and Methods", "Results", "Discussion"]

# Customize the Appearance

CATview offers functions to customize its basic appearance.

To invert the names axis call: # invert_names_axis() CATview.invert_names_axis(); This will reverse the arrangement of the names and trigger the function CATview.refresh_content().

# To set the rectangle color scale call: # set_color_scale() CATview.set_color_scale(from, to, border); This will overwrite the current scale for the rectangles' colors according to the parameters from and to that are both color codes. If the parameters are not passed, the default values from = "#c1c1e9" and to = "#0000a3" are used. Passing a color code for the parameter border will overwrite the border color. Default value here is border = "#2f2f86". Setting the colors will trigger the function CATview.refresh_content() to display the colors immediately.

Example: Setting the rectangles' color to a gray scale with a black border CATview.set_color_scale("#cccccc", "#555555", "#000000");

To set CATviews background color call: # set_background_color() CATview.set_background_color(color); This will overwrite the current background color of CATview with color and refresh it immediately. The color can be specified with an usual color code as '#ffffff' or with a rgba color code as 'rgba(255, 255, 255, 128)' that allow to define a transparency.

Example: Setting CATviews background color to white and to invisible // set CATviews background color to white
CATview.set_background_color('#ffffff');
// remove CATviews background color by setting the transparency to 0
CATview.set_background_color('rgba(255, 255, 255, 0)');

# Use the Brush

The brushing tool of CATview can be used to select consecutive rectangles, i.e. text segments, and pass that selection to custom functions.

To enable the brush call: # enable_brush() CATview.enable_brush(); This will make it able to draw a box to CATviews area for rectangles. Via mouse this box can be dragged or resized. The brush will be affected by changing the level of detail as it will adopt its size on zooming to keep the same rectangles selected. If a brush callback was already set, it will be triggered every time the set of selected rectangles changes.

To disable the brush call: # disable_brush() CATview.disable_brush();

To set a callback for the brush call: # set_brush_callback() CATview.set_brush_callback(brush_callback); This will overwrite the currently set brush callback with the function passed as brush_callback. The callback will receive the dimension of the brush as four numbers in the order of the starting edge, the ending edge, the starting name and the ending name. When the brush was enabled, the callback will triggered every time the dimensions of the brush change.

Example: Setting the brush callback CATview.set_brush_callback(function(from_edge, to_edge, from_name, to_name){
// log the dimensions of the brush
console.log('Brush goes from (' +
from_edge + ', ' +
from_name + ') to (' +
to_edge + ', ' +
to_name + ')');
}); This simple callback will log the dimensions of CATviews brush every time they change.

# Adding Tools

CATview provides functions to add tool icons and callbacks that will be triggered when clicking on these icons. The icons will be automatically placed in the same orientation as the names axis but at the opposite side. Pre-build as well as custom tools are possible.

To add a custom tool to CATview call: # add_tool() CATview.add_tool(icon, callback, index); The parameter icon defines the symbol representing the tool and be chosen from https://fontawesome.com/v4.7.0/icons by using the four-digit Unicode of an icon. The parameter callback defines the behavior as a function that will be triggered when clicking the icon. With the optional parameter index the tool can be added between the other tools at a specific position, starting at 0.

Example: Adding a tool as the second one for toggling CATviews color scale: // variable to remember the current color scale
let colors = 0;
CATview.add_tool(
'f043', // a tint drop icon
function(){ // the callback
if(colors = 0){
// grayscale with black border
CATview.set_color_scale("#cccccc", "#555555", "#000000");
colors = 1;
} else if (colors = 1){
// green to red with gray border
CATview.set_color_scale("#7de88d", "#d34548", "#888888");
colors = 2;
} else{
// default: shades of blue
CATview.set_color_scale();
colors = 0;
}
},
1 // the position
);

To remove a tool call: # remove_tool() CATview.remove_tool(index); This will remove the tool at the given index.

To add a pre-build tool for inverting the names axis call: # add_tool_invert_names_axis() CATview.add_tool_invert_names_axis(index);

To add a pre-build tool for toggling the search mode call: # add_tool_toggle_search_mode() CATview.add_tool_toggle_search_mode(index);

To add a pre-build tool to enable/disable the brush call: # add_tool_toggle_brush() CATview.add_tool_toggle_brush(index);