Plugin: Colored ribbon

[przmv]

Color regions that comprise the ribbon can be different for each date. User supplies an array of numeric values and color palette (gradient), where each numeric value encodes a position in the palette interval.

[danvk]

Here's a screenshot:

[danvk]

it's interesting that the x-values of the ribbons are tied to the data whereas the y-values are not (the ribbon doesn't move with y-panning and y-zooming). Why did you choose to do it this way?

[danvk]

Seems like a useful plugin, thanks! I have a few questions about the API, though.

[rykerwilliams]

+1 on being useful. I use this type of functionality a lot, accomplished via the callbacks. Looks cool.

[przmv]

@danielkrizian Please explain some of the usecases for this plugin. Especially:

Why the palette / data distinction? Why not just pass in a list of colors for each rectangle?

[danielkrizian]

it's interesting that the x-values of the ribbons are tied to the data whereas the y-values are not (the ribbon doesn't move with y-panning and y-zooming). Why did you choose to do it this way?

The idea behind ribbon (inspired by it's use in financial applications, see charts in The Economist magazine) is to analyze the relationship of different states (their start, end and duration) in connection to other time series. For example, employment rate during recessions (the latter state visualized as red in the red/none ribbon along x axis). Another example, long/short/no investment position in a stock (represented by green/red/no ribbon) in relation to its stock price. In that light, different colors of ribbon mark different states of a discrete/categorical variable over time, hence over the x-axis.

The above realization that ribbon just encodes/maps a categorical variable over time into a set of colors helps answer the second question:

Why the palette / data distinction? Why not just pass in a list of colors for each rectangle?

As @pshevtsov pointed out, the advantage of the distinction is that the visualization can be completely data-driven. In other words, it helps to separate the data from the visualization choices/functions. Let's take the very common scenario where the analyst has a data table, where one of the columns is a categorical variable taking values over time: ycat= [1, 0, 2, 0, 2, 1, ...] from a finite set {0, 1, 2}. It seems natural to pass the original data table of observations (along with other series in other columns), and provide the visualization specification separately as a mapping/function between the set {0, 1, 2} and colors {#foo, #bar, #baz}.

To summarize, lines represent (most often) continuous variables. Ribbons represent categorical variables. Both types of objects are time series.

Note: One could theoretically have multiple ribbons on a single chart, drawn at different y-positions (as y-position doesn't matter from the data point of view), but let's keep it simple at this point and stick to a single ribbon.

[danvk]

do you want to throw if this isn't the case? Does it always represent misconfiguration?

[danvk]

Overall this looks good. One other use case that might be nice to hit is where you want to just highlight a particular range of dates, e.g. http://dygraphs.com/tests/highlighted-region.html. For that case, it's easier to just specify start & stop values, rather than 0/1 for every x-value in the chart. Not something that needs to be addressed in this PR, anyway.

All of the charts in tests/ribbon.html look identical to me. Is that expected? Also, I noticed that if I pan to the right in any of them, I see a sea of red.

[danvk]

palette (sp)

[danielkrizian]

One other use case that might be nice to hit is where you want to just highlight a particular range of dates, e.g. http://dygraphs.com/tests/highlighted-region.html. For that case, it's easier to just specify start & stop values, rather than 0/1 for every x-value in the chart.

Vector encoding for each x position (in this case using binary 0/1, but could be an integer domain enumeration) is arguably more general use case than start & stop values. The first can denote multiple regions and multiple colors in a single vector. The latter is a special case for single region and single color. Again, visualization is often data driven, so that one column of the the data table (aligned with x and y column) bears information about both position and colours of the ribbon.

[przmv]

@danvk Oh, I forgot to update tests with new parameters introduced in 1bd7876 that's why all the ribbons looked the same.

[danvk]

I'd like to merge this, but it really does need some high-level documentation, either in ribbon.js or ribbon.html. If I were a user looking at the source to ribbon.html, I wouldn't have any idea what was going on.

[danielkrizian]

Ok, the existing feature called shaded regions (example here http://rstudio.github.io/dygraphs/gallery-shaded-regions.html) specifies from, to, and color for each region:

dygraph(nhtemp, main = "New Haven Temperatures") %>% 
  dySeries(label = "Temp (F)", color = "black") %>%
  dyShading(from = "1920-1-1", to = "1930-1-1", color = "#FFE6E6") %>%
  dyShading(from = "1940-1-1", to = "1950-1-1", color = "#CCEBD6")

Above can be clunky to write if you have hundreds of regions in the graph.

Enter the ribbon. Instead of supplying the from, to and color parameters individually through the function call arguments, contain the information within the data object in the form of additional column of the data table.

The example ribbon graph should showcase hundreds of different colors, to distinguish itself clearly from "highlighted region" (or "shaded region") feature.

[danielkrizian]

@pshevtsov , following can be included in the <div> of the ribbon.html to document the use, in addition to the source code of the examples:

Description:

Ribbon is a horizontal band of colors that runs through the chart. It can useful to visualize categorical variables (http://en.wikipedia.org/wiki/Categorical_variable) that change over time (along the x-axis). For example multiple states of economy like "bust","recession", "recovery", "boom" can be encoded as [0, 1, 2, 3] respectively (or normalized as [0, 0.33, 0.66, 1]) and assigned colors ["red","orange","green","purple"].

Arguments:

data:
Array of numeric values in the range from 0 to 1. Ribbon data array must be of same length as number of rows of Dygraph raw data table. Each of the values (0-1) scales to a position in the palette array scale (see palette argument below). For example, if palette is defined as ["transparent", "#ef2929", "#8ae234"], then 0 is the leftmost position ("#ef2929") on the palette scale, 1 is the rightmost position ("#8ae234") and 0.5 is the middle position ("#ef2929")

parser:
Function (function (data, dygraph)) returning the array of numeric values. Function arguments: raw data, dygraph instance. Provide it if the ribbon data, i.e. encodings are part of the dygraph raw data table rather than supplied separately through ribbon data argument. See example 2.

options:
Object with the following properties:

• palette:
  array of hexadecimal color codes. Default: ["transparent", "#ef2929", "#8ae234"]. Pick colors from e.g. http://www.w3schools.com/tags/ref_colorpicker.asp
• top:
  vertical position of the top edge of the ribbon relative to chart height. Value in the range from 0 (bottom edge of the chart) to 1 (top edge of the chart). E.g. 0.5 places the top edge of the ribbon at the 50% height of the chart.
• bottom:
  vertical position of the bottom edge of the ribbon relative to chart height. See top.