Reference Graph Visualization

3.2.2.1 Tooltips

var tooltip = svg.append("rect")
    .attr("class","tooltip_bg")
    .attr("id","tooltip_bg")
    .attr("visibility", "hidden")
    .attr("rx", 4)
    .attr("ry", 4)
    .attr("height",16)
    .attr("width",52);

var tooltip_text = svg.append("text")
    .attr("class","tooltip_text")
    .attr("visibility", "hidden");

function show_tooltip(d) {
    if (d.type == "paper") {
        x = d3.event.clientX;
        y = d3.event.clientY;
        tooltip_text
            .text(`${d.display_title}(${d.year})`)
            .attr("visibility","visible")
            .attr("x", x + 11)
            .attr("y", y + 27);
        tooltip
            .attr("visibility","visible")
            .attr("x", x + 8)
            .attr("y", y + 14)
            .attr("width", tooltip_text.node().getComputedTextLength()+8);
    }
}

function hide_tooltip(d) {
    tooltip.attr("visibility", "hidden")
    tooltip_text.attr("visibility", "hidden")
}

3.2.2.2 Filter for Node Background

var defs = d3.select("svg").append("defs");
var filter = defs.append("filter")
    .attr("id", "glow");
filter.append("feGaussianBlur")
    .attr("stdDeviation", "3.5")
    .attr("result", "coloredBlur");

3.2.4.1 Force Layout

var force_link,                   // selection of created svg elements for link representation

    force_node                    // selection of created svg elements for node representation

var kx_mul = 0.15,              // multiplier for attractor force in x direction

    ky_mul = 0.4                // multiplier for attractor force in y direction

var force = d3.layout.force()
    .nodes(nodes)
    .links(links)
    .linkStrength(0.5)
    .gravity(0)
    .distance(50)
    .chargeDistance(700)
    .charge(collab_charge)
    .friction(0.7)
    .size([width, height])
    .on("tick",force_tick);

1. Node Property Helper functions
   

   Several node properties are data-dependent. The following definitions are used to calculate the relevant values for the layout.

   1. Node Significance
      

      Used as basis for other layout properties.

      The significance of authors is determined by the balls they have, and weighted using a fractional-exponent exponential function, to be able to distinguish the less-significant authors better, since there are usually more of them.

      The significance of papers is the number of citations they have. This is weighted logarithmically for similar reasons.

      function node_significance(d) {
          if (d.type == "author")
              // return icon_size * (1 + (d.balls/20);
              return (1 + (Math.pow((d.balls-1), 0.8) * 0.5));
          else
              return (1 + Math.log10(1 + (d.citations || 0)));
      }
      

   2. Node Image Positioning
      

      The node image size depends on the significance.

      function node_image_size(d) {
          return icon_size * node_significance(d);
      };
      

      Used to center the image for a node.

      function node_image_offset(d) {
          return - (node_image_size(d) / 2);
      }
      

   3. Node Charge
      

      For the collaboration layout, the node charge is made dependent on the node significance. This way, it is easier to place lesser-significant nodes around the more central nodes.

      function collab_charge(d) {
          return (node_significance(d) * -300);
      }
      

   4. Node Attractor Targets
      

      The attractor positions of the papers are a virtual grid, where the papers are ordered in x-direction by the first letter of the bibtex key, and in y-direction by the year of publication. The y positions are compressed in a way that recent publications are spaced wider than older publications.

      function set_collab_paper_targets(node) {
          if (node.type == "paper") {
              // node.y_target = (((2016 - node.year))*20) + 200;
              node.y_target = (Math.sqrt(2016 - node.year) * 100) + 200;
              xmin = "A".charCodeAt(0);
              xmax = "Z".charCodeAt(0);
              xnode = node.name.toUpperCase().charCodeAt(0);
              node.x_target = Math.max(((xnode - xmin) / (xmax - xmin)) * width, 1);
          }
      }
      

2. Node Dragging Behaviour
   

   Dragging is provided by a d3.js behavior, but the default event handlers are not used.

   var drag = d3.behavior.drag()
       .origin(function(d) { return d; })
       .on("dragstart", dragstarted)
       .on("drag", dragged)
       .on("dragend", dragended);
   

   Instead, the following handlers are implemented. Note that they rely on undocumented internals (the meaning of the individual bits of the fixed property). These are copied from the original functions.

   function dragstarted(d) {
       d3.event.sourceEvent.stopPropagation();
       d3.select(this).classed("dragging", true);
       // force.d3_layout_forceDragstart(d);
       d.fixed |= 2; // set bit 2
   }
   

   function dragged(d) {
       // d3.select(this).attr("cx", d.x = d3.event.x).attr("cy", d.y = d3.event.y);
       // d.x = d3.event.x, d.y = d3.event.y;
       d.px = d3.event.x, d.py = d3.event.y;
       force.resume(); // restart annealing
   }
   

   function dragended(d) {
       d3.select(this).classed("dragging", false);
       // force.d3_layout_forceDragend(d);
       d.fixed &= ~6; // unset bits 2 and 3
   }
   

3. Highlight on Hover
   

   When hovering over a node, all non-connected nodes should be faded out to better highlight the currently selected node.

   The following function is for mouseover and mouseout handlers, respectively, and change the class of the non-highlighted mode to be faded out.

   The argument determines wether to return a fade-in or a fade-out handler.

   function highlight_nodes(highlight_p) {
       return function(d0) {
           force_node
               .filter(function(d) {
                   var match =
                       ( d == d0) ||
                       ((d0.type == "paper") && d0.authors.includes(d)) ||
                       ((d0.type == "author") && d0.papers.includes(d));
                   return !match;
               })
               .classed("faded", highlight_p);
       }
   }
   

4. Force Layout Creation
   

   Here is the force layout initialization. It must be called after data is available. See 3.2.4.1.4 for what actually happens, and Force Layout Tick Handler for the tick event handler that is attached.

   It follows the examples here, and here.

   d3.js's enter selection mechanism is used to get the actually created svg DOM nodes for the links (lines) and the nodes (groups). The creation is handled functions for the specific node types. Labels are created in the same way all node types, but link to scholar searches for authors, and pdf files for papers.

   Also cause computation of the attractor targets.

   To help converging, the layout is initialized by setting all the nodes with attractor targets to their calculated target positions.

   function update_force_layout() {
       force.stop();
   
       force.links(links)
           .nodes(nodes);
   
       force_link = link_container.selectAll(".link")
       // .data(force.links(), function(d) {return d.source.name + "-" + d.target.name});
           .data(force.links());
   
       force_link
           .enter().append("line")
           .attr("class", "link");
   
       force_link.exit().remove();
   
       force_node = node_container.selectAll(".node")
           .data(force.nodes(), function(d) {return d.name+d.state+d.bibtype+d.citations+d.balls});
       // .data(force.nodes());
       force_node
           .enter().append("g")
           .attr("class", "node")
           .on("mouseover.tool_tip", show_tooltip)
           .on("mouseout.tool_tip", hide_tooltip)
           .on("mouseover.highlight", highlight_nodes(true))
           .on("mouseout.hightlight", highlight_nodes(false))
           .call(draw_node)
           .call(drag)
       ;
   
       force_node.exit().remove();
   
       force.start().alpha(1);
   }
   

   The creation of all the objects and setting the attributes beneath the node element itself is delegated into draw_node

   function draw_node(node) {
       node.filter(function(n) {return n.type == "author"})
           .call(draw_author_node);
   
       node.filter(function(n) {return n.type == "paper"})
           .call(draw_paper_node);
   
       node.append("g")
           .append("a")
           .attr("xlink:href",function(d) {
               if (d.type == "author")
                   return "http://scholar.google.com/scholar?q=" + encodeURIComponent(d.name)
               else
                   return d.key+".pdf"})
           .append("text")
           .attr("dx", 12)
           .attr("dy", 16)
           .attr("text-anchor", "middle")
           .text(function(d) { return d.name });
   }
   

   1. Author Nodes
      

      Author nodes are represented by a generic image.

      function draw_author_node(node) {
          node.append("image")
              .attr("xlink:href", "graph-assets/user.png")
              .attr("x", node_image_offset)
              .attr("y", node_image_offset)
              .attr("width", node_image_size)
              .attr("height", node_image_size);
      }
      

   2. Paper Nodes
      

      For papers that have already been started reading, show an identicon. Otherwise, an empty placeholder. This should make it easier to recognize papers by their identicon over time, also visualizing where there are still "gaps" in the research.

      A small symbol represents the publication type, e.g. conference paper, journal paper, PhD Thesis, etc. For now, only one symbol is used, though. This symbol shall eventually be made optional, since it crowds the whole layout quite a bit. Also, this symbol is hidden by default. See 3.2.5.

      In order to make distinguishing the papers easier, md5 and jdenticon are used to calculate hash values of the bibtex key. The hash is stored in the DOM attribute data-jdenticon-hash. This is a non-standard attribute so far, and is accessed by the modified jdenticon code.

      The identicon gets a white background, to make it easier to distinguish visually.

      A small circle should surround the icon which represents the personal reading state.

      Clicking the label will open a pdf.

      function draw_paper_node(node) {
          // glow
          // node.append("rect")
          //     .attr("x", node_image_offset)
          //     .attr("y", node_image_offset)
          //     .attr("width", node_image_size)
          //     .attr("height", node_image_size)
          //     .attr("class", function(d) {
          //         var s= "node_bg_glow " + d.type;
          //         if (d.type == "paper" && d.state) s = s + " " + d.state;
          //         return s;
          //     });
      
          // white background circle with colored stroke
          node.append("circle")
              .attr("r", function(d) {return node_image_size(d) / 2.2})
              .attr("class", function(d) {
                  var s = `node_bg ${d.type}`;
                  if (d.state) s = s + " " + d.state;
                  return s;
              })
          ;
      
          //jdenticon for partially read papers
          node.filter(function(n) { return (n.state && n.state != "unread")})
              .append("g")
              .attr("class", "jdenticon")
              .attr("data-width", jdenticon_size)
              .attr("data-height", jdenticon_size)
              .attr("data-jdenticon-hash", function(d) { return md5(d.name)})
              .attr("transform", function(d) { return "scale(" + node_significance(d) * (icon_size / jdenticon_size)  + ")"; });
      
          //type symbols
          node.append("image")
              .attr("xlink:href", "graph-assets/note.svg")
              .attr("class", "pub_type")
              .attr("x", node_image_offset)
              .attr("y", node_image_offset)
              .attr("width", function(d) {return node_image_size(d) / 2.5})
              .attr("height", function(d) {return node_image_size(d) / 2.5})
              .attr("visibility", "hidden");
      
      }
      

5. Force Layout Tick Handler
   

   This is the "hot loop" that actually updates all the svg elements according to the internal simulation. It implements the attraction forces and updates the position of the svg nodes as well as their links.

   function force_tick(e) {
       var kx = e.alpha * kx_mul;
       var ky = e.alpha * ky_mul;
   
       nodes.forEach(function(node) {
           if (node.x_target)
               node.x += (node.x_target - node.x) * kx;
           if (node.y_target)
               node.y += (node.y_target - node.y) * ky;
       });
   
       force_link.attr("x1", function(d) { return d.source.x; })
           .attr("y1", function(d) { return d.source.y; })
           .attr("x2", function(d) { return d.target.x; })
           .attr("y2", function(d) { return d.target.y; });
   
       force_node.attr("transform", function(d) { return "translate(" + d.x + "," + d.y + ")"; });
   }
   

3.2.5.1 Display of Publication Type Symbols

var controls = d3.select("#footer")
    .append("div");

// controls.append("label")
//     .text("Display Type of Publication");

// controls.append("input")
//     .attr("type", "checkbox")
//     // .attr("name", "show_symbols")
//     .on("click", toggle_symbols);

function toggle_symbols() {
    if (this.checked)
        d3.selectAll(".pub_type").attr("visibility", "visible");
    else
        d3.selectAll(".pub_type").attr("visibility", "hidden");
}

3.2.6.1 Read Files on Drag'n'Drop

d3.select("svg")
    .on("dragover", function() {
        d3.event.preventDefault(); })
    .on("drop", function() {
        d3.event.preventDefault();
        var files=d3.event.dataTransfer.files;
        if (files.length == 1) {
            var f = files[0];
            console.log("Filename: " + f.name);
            console.log("Type: " + f.type);
            console.log("Size: " + f.size + " bytes");
            reader.readAsText(f);
        }
    });

var reader = new FileReader();
reader.onload = function(event) {
    var content = event.target.result;
    console.log("File loaded");
    load_bibtex(content);
};

reader.onerror = function(event) {
    console.error("Unable to read file (Code: " + event.target.error.code + ")");
};

function load_bibtex(content) {
    var entries = parse_bibtex_file(content);
    var result = analyze_bibtex_entries(entries);
    nodes = result.nodes;
    links = result.links;

    nodes.forEach(function(node) {
        set_collab_paper_targets(node)  /* set the target coordinates for the papers */
        if (node.x_target) node.x = node.x_target;
        if (node.y_target) node.y = node.y_target;
    });

    update_layout();
}

3.2.6.2 Analyze BibTex file

var authors, papers;

function analyze_bibtex_entries(entries) {
    authors = [];
    papers = [];
    var links = [];
    entries.forEach(function(e) {
        if (!e.bibtex.author) { console.error(`BibTeX entry ${e.key} has no author!`); return;}
        as = author_ws_cleanup(e.bibtex.author).split(" and ").map(normalize_author).map(find_author);
        e.authors = as; //replace author list with a list of author objects
        e.type = "paper";
        e.name = e.key;
        if (e.bibtex.state) e.state = e.bibtex.state.toLowerCase();
        e.citations = parseInt(e.bibtex.note) // this is hardcoded right now according to zotero citations plugin
        if (!e.bibtex.title) {
            console.warn(`BibTeX entry ${e.key} has no title, using key instead!`)
            e.display_title = e.key;
        } else
            e.display_title = e.bibtex.title;
        e.year = parseInt(e.bibtex.year);
        e.authors.forEach(function(author) {
            author.papers.push(e);
            links.push({source: author, target: e});
            // this one is deprecated once the old json import is phased out:
            author.balls = (author.balls || 0) + 1;
        });
        papers.push(e);
    });
    return {nodes: papers.concat(authors), links: links};
}

function author_ws_cleanup(a) {
    return a.trim().replace(/\s+/g," ");
}

function find_author(a) {
    var found = authors.find(function(item) {
        return item.last == a.last && item.given == a.given }) ||
        authors.find(function(item) {
            return item.last == a.last && item.given[0] == a.given[0]});
    if (found)
        return found;
    else {
        // initialize author fields here
        a.papers = [];
        a.type = "author";
        a.name = a.last;        // display name
        if (a.given) a.name = a.name + ", " + a.given;
        authors.push(a);
        return a;
    }
}

function normalize_author(s) {
    var c = s.split(", ");
    if (c.length == 1) {        // no commas?
        c = c[0].split(" ");    // split by spaces
        var last = c.pop();
        return {given: c.join(" "), last: last};
    } else
        return {given: c[c.length-1].split(" ")[0], last: c[0]};
}

3.2.6.3 BibTex Parser

start = bibtex

_ "whitespace" = [ \t\n\r]*

name = value:[a-zA-Z0-9_-]+ { return value.join("").toLowerCase() }
number = value:[0-9]+ { return parseInt(value.join(""),10) }
month_const = "jan"/"feb"/"mar"/"apr"/"may"/"jun"/"jul"/"aug"/"sep"/"oct"/"nov"/"dec"

non_brace = value: [^{}]+ { return value.join("") }
non_quote_non_brace = value: [^{}"]+ { return value.join("") }

braced_value = "{" values: (non_brace / braced_value)* "}" { return values.join("") }
quoted_value = "\"" values: (non_quote_non_brace / braced_value)* "\"" { return values.join("") }

//fallback: when encountering an unquoted or unbrace value, assume variable name, without doing substitutions
value = braced_value / quoted_value / number / month_const / name

key = value:[^,]+ { return value.join("") }

field = name:name _ "=" _ value:value { return { name:name, value:value}}
field_with_separator = _ field:field _ "," { return field }

normal_entry = "@" type:name _ "{" _ key:key _ "," fields:(field_with_separator)* _ last_field:field? _ '}'
  { if (last_field) fields.push(last_field);
    var ret = {bibtype: type, key: key, bibtex: {}};
    fields.forEach(function(f) { if (!ret.bibtex[f.name]) ret.bibtex[f.name] = f.value});
  return ret; }

string = "@STRING"i _ "{" _ f:field _ "}" {error("@string directive not supported")}

preamble = "@PREAMBLE"i _ "{" value "}"

comment_body = value:[^@]+ {return value.join("")}

comment_entry = "@COMMENT"i _ comment:braced_value { return comment }

comment = comment_entry / comment_body

entry = string / preamble / comment / normal_entry

bibtex = elements:(entry / comment)* { return elements.filter(function(e) {return typeof(e) == "object"})}

var parse_tree;

function parse_bibtex_file(content) {
    try {
        parse_tree = bibtex_parser.parse(content);
        return parse_tree;
    } catch (e) {
        alert(`Line ${e.location.start.line}, Column ${e.location.start.column}: ${e.message}`);
        throw(e);
    }
}