g1.sanddance

Transitions elements with flexible timing controls.

g1.sanddance options

It accepts 2 parameters

attrs: changes any HTML / SVG attributes of the selection (e.g. fill, etc)
- fill, stroke for color
- x, y, cx, cy, transform, etc for position (but these are better controlled via the options)
- etc.
options: defines layout options (e.g. x, y, duration, speed, etc)
- x: transition the elements to the x position
- y: transition the elements to the y position
- speed: transition at constant speed in pixels per second
- duration: transition time in milliseconds (overrides speed)
- delay: transition delay in milliseconds (default is 0)
- easing: transition easing in d3-ease method (default is d3.easeLinear)
- filter: filter the selection based on a column value (ex: age > 30)

Examples:

// smoothly changes the fill color to blue in 100 ms
var turn_to_blue = g1.sanddance({ fill: "blue" }, { duration: 100 });
selection.call(turn_to_blue);

// g1.sanddance moves elements to the x, y specified in 100ms
var move = g1.sanddance({}, { x: 200, y: 200, duration: 100 });
selection.call(move);

// transitions at 1000 pixels/sec.
var move_at_constant_speed = g1.sanddance({}, { x: 300, y: 300, speed: 1000 });
selection.call(move_at_constant_speed);

// transitions in 100ms duration.
var move_in_duration = g1.sanddance({}, { x: 400, y: 400, duration: 100 });
selection.call(move_in_duration);

// transitions after 100ms delay.
var move_after_delay = g1.sanddance({}, { x: 300, y: 300, delay: 100 });
selection.call(move_after_delay);

// transitions at ease of d3.easeBounce
var move_easing = g1.sanddance(
  {},
  { x: 300, y: 300, duration: 100, easing: d3.easeBounce },
);
selection.call(move_easing);

// filters the selection
var selection_filtered = g1.sanddance(
  { fill: "red" },
  {
    duration: 100,
    filter: function (d) {
      return d.age > 30;
    },
  },
);
selection.call(selection_filtered);

g1.sanddance.chain

To apply a sequence of sanddances one after another, use g1.sanddance.chain. For example:

// chain sanddances. First, fill everything red, then move x to 200 and y to 100
selection.call(
  g1.sanddance.chain(
    g1.sanddance({ fill: "red" }, { duration: 100 }),
    g1.sanddance({}, { x: 200, y: 100, duration: 100 }),
  ),
);

g1.sanddance layouts

grid

Returns a sanddance that moves elements into a grid. Usage:

// Lay out the elements in a grid
selection.call(
  g1.sanddance(
    {},
    {
      // Create a layout based on the data array
      layout: "grid", // lay out as a grid
      width: 400, // with width 400
      height: 300, // and height 300
      data: data, // using the specified data
      sort: "age", // sorted by the 'age' column
      ascending: false, // in descending order
      duration: 100, // in 100ms
    },
  ),
);

Options:

data: an array that has the data that is used to lay out the elements
width: width of the grid in SVG units
height: height of the grid in SVG units
sort: column name or function(d, i) to sort by
ascending: false reverses the sort order (default: true)

Values can be specified as a scale. Example: fill: can be specified as below.

fill: {
  metric: 'age',
  scheme: 'RdYlGn'
}
// or
fill: {
  metric: 'age',      // same as function(d) { return d.age }
  scale: 'linear',
  domain: [0, 50, 100],
  range: ['red', 'yellow', 'green'],
}

Scales are dictionaries with the following keys:

metric: can be a string column name or a function(d, i) that returns a value for each item in the data
scheme: d3 chromatic color scheme to interpolate to (e.g. 'RdYlGn')
scale: d3 scale to use. Defaults to 'linear'
range: a list that contains the scale’s range
domain: a list that contains the scale’s domain (defaults to the extent of the metric)

// fill as scale config with linear scale
selection.call(
  g1.sanddance(
    {
      fill: {
        metric: function (d) {
          return d.age;
        },
        scale: "linear",
        domain: [0, 100],
        range: ["red", "blue"],
      },
    },
    {
      layout: "grid",
      data: data,
      width: 400,
      height: 300,
      duration: 100,
    },
  ),
);

// fill as scale config with scheme
selection.call(
  g1.sanddance(
    {
      fill: {
        metric: function (d) {
          return d.age;
        },
        scheme: "RdYlGn",
      },
    },
    {
      layout: "grid",
      data: data,
      width: 400,
      height: 300,
      duration: 100,
    },
  ),
);

hexpack

Returns a sanddance that moves elements into a hexpack. Usage:

// Lay out the elements in a hexpack
selection.call(
  g1.sanddance(
    {},
    {
      // Create a layout based on the data array
      layout: "hexpack", // lay out as hexpack
      width: 400, // with width 400
      height: 300, // and height 300
      data: data, // using the specified data
      sort: "age", // sorted by the 'age' column
      ascending: false, // in descending order
      duration: 100, // in 100ms
    },
  ),
);

The values can also be specified as a scale config and the options definitions are same as grid.

g1.sanddance methods

sanddance.update(new_attrs, new_options) returns a new sanddance that updates the old attrs with new_attrs and the old options with new_options.

// The two lines below are the same:
g1.sanddance({ stroke: "blue" }).update({ fill: "red" });
g1.sanddance({ stroke: "blue", fill: "red" });

// Update the options
g1.sanddance({}, { delay: 100 }).update({}, { duration: 100 }),
  g1.sanddance({}, { duration: 100, delay: 100 });

g1.sanddance events

These events are triggered by the sanddance object.

init when the sanddance is initialized
start when the first transition begins (after delay)
end when all transitions are complete

All events set the d3 selection as this. For example:

// sanddance events
selection.call(
  g1
    .sanddance({ fill: "red" })
    .on("init.log", function () {
      console.log("init", this);
    })
    .on("start.log", function () {
      console.log("start", this);
    })
    .on("end.log", function () {
      console.log("end", this);
    }),
);