What is the `e` parameter passed to the d3.js force tick callback function?

Question

below is a normal example of tick function:

function tick(e) {
     nodes
      .each(cluster(10 * e.alpha * e.alpha));
}

who can tell me the definition of "e"? What properties does it have? I can't find any description of "e", and what's the meaning of e.alpha. Yes, I used google but with no results.

---

Thanks for the help you gave below.

I'm copying some code, which use

var force = d3.layout.force()
        .nodes(nodes)
        .size([width, height])
        .charge(-70)
        .gravity(0.1)
        .on("tick", tick)
        .start();

so it's just the case you guess. I'm new to d3, a skim of force.layout API didn't give me any clue. Thanks for your precious time!

Answer 1

Without the full context of your "normal" function, this is a bit of a guess, but here goes:

tick is used in many contexts within d3. The inlcusion of alpha suggests that this is a force layout tick function, which is called by the force layout object on a tick event, in which case e would be the tick event object.

There is not a lot of documentation about the tick event, as most examples don't use it. If you inspect the source code, you will see

// A rudimentary force layout using Gauss-Seidel.
d3.layout.force = function() {                       //line 11
    var force = {},
        event = d3.dispatch("start", "tick", "end"); 
    /* ... */
    force.tick = function() {                        //line 58
        // simulated annealing, basically
        if ((alpha *= .99) < .005) {
          event.end({type: "end", alpha: alpha = 0});
          return true;
        }
        /* code to implement default force layout adjustments */
        event.tick({type: "tick", alpha: alpha});   //line 128
    };
    /* ... */
    return d3.rebind(force, event, "on");           //line 305
};

In other words, the tick event is one of three types of custom event created within the d3 source code using the d3.dispatch process. The tick event in particular is dispatched at the end of the internal tick function, and only contains one custom property: the current alpha parameter within the force layout. In order that these events actually go anywhere, the on method of the event dispatcher object is rebound on to the force layout object, so that the user can register listener functions for the custom events.

If all that is way too much d3 internals for you, just focus on these details:

• e is a custom event object passed to your tick function every time it is called

• e.alpha is the force layout's current alpha value, which by default starts at 0.1 and gets reduced (according to the friction parameter) at each tick until it drops below 0.005 and the layout freezes:

  Internally, the layout uses a cooling parameter alpha which controls the layout temperature: as the physical simulation converges on a stable layout, the temperature drops, causing nodes to move more slowly. Eventually, alpha drops below a threshold and the simulation stops completely, freeing the CPU and avoiding battery drain. (From the API wiki for force.start)