Skip to content

dimple.series

Jump to bottom Edit New page
Christabella edited this page Jun 15, 2017 · 18 revisions

This is where the magic happens! Once you've created a chart and added a couple of axes (or more). It's time to draw something on it, and that's what the series does. Formally speaking, a series ties 2 or more axes together and renders a graphic.

Constructor
Properties

#####Methods#####

Constructor

dimple.series(chart, categoryFields, xAxis, yAxis, zAxis, colorAxis, pieAxis, plotFunction, aggregateMethod, stacked) [code] - Initialise the series object for a specific chart and some specific axes. While the series can be created using its constructor, it is advisable to use the factory method in the chart object (addSeries) as this will add it to the chart collection as well as constructing the object. And it will take care of some additional tasks such as mapping axes.

  • chart (Required): The dimple.chart object to which the series will be connected. As well as the chart being passed here, it must also have this series in its series collection.

  • categoryFields (Required): If provided, a separate series will be provided for each distinct value given. For example if adding a line series ... = new dimple.series(myChart, ["Brand"], x, y, null, null, dimple.plot.line, false); each brand would be drawn as a separate line. The following values are acceptable:

    • Null: If set to null, a single series will be drawn aggregating all values.

    • Array of string values: The string values must be field names from the data and a series will be created for every combination of their distinct values. E.g. "Brand 1/Region 1", "Brand 1/Region 2", "Brand 2/Region 1"...

    • Single element array: The string value may be a field name in the data, in which case it will behave like the array above, or it may be a different value in which case the null case will be used but the passed string will be used as the series name, allowing you to color different series independently.

  • xAxis (Required): The axis used to determine the horizontal positioning of the datapoints in the series. This must be an axis which belongs to the passed chart and has its position property set to "x".

  • yAxis (Required): The axis used to determine the horizontal positioning of the datapoints in the series. This must be an axis which belongs to the passed chart and has its position property set to "y".

  • zAxis (Optional): The axis used to determine the scaling of the datapoints in certain types of series. This must be an axis which belongs to the passed chart and has its position property set to "z".

  • colorAxis (Optional): The axis used to determine the dynamic coloring of the datapoints in a series. This must be an axis which belongs to the passed chart and has its position property set to "c".

  • pieAxis (Optional): The axis used for pie charts.

  • plotFunction (Required): This should be one of the static objects from the dimple.plot namespace. This determines the way in which the series is rendered.

  • aggregateMethod (Required): This should be one of the static objects from the dimple.aggregateMethod namespace. This determines the way in which data values are aggregated when calculating the series.

  • stacked (Required): It should be a boolean value indicating whether the series should stack up against a category axis, or whether it should calculate an independent value for each data point.

Example:

// Add some axes
var x = myChart.addCategoryAxis("x", "Brand");
var y = myChart.addMeasureAxis("y", "Sales Volume");
// Add a bar series of average sales volume by brand
myChart.series.push(new dimple.series(myChart, ["Brand"], x, y, null, null, dimple.plot.bar, dimple.aggregateMethod.avg, true));

Properties

dimple.series.afterDraw(shape, data) [code] - This is a callback function called after this series is drawn. Very useful in customizing the default visualization of the series shape.

  • shape: d3 selector of the series element.

  • data: Data passed to this chart.

Example:

// See the example at: http://dimplejs.org/advanced_examples_viewer.html?id=advanced_bar_labels
var s = myChart.addSeries("Owner", dimple.plot.bar);
s.afterDraw = function (shape, data) {
	// Get the shape as a d3 selection
	var s = d3.select(shape),
	rect = {
		x: parseFloat(s.attr("x")),
		y: parseFloat(s.attr("y")),
		width: parseFloat(s.attr("width")),
		height: parseFloat(s.attr("height"))
	};
	// ....
};

dimple.series.aggregate [code] - This should be one of the static objects from the dimple.aggregateMethod namespace. This determines the way in which data values are aggregated when calculating the series.

Example:

// Set the series to calculate a mean value
mySeries.aggregate = dimple.aggregateMethod.avg;

dimple.series.barGap [code] - This is a floating point number between 0 and 0.99 which determines the percentage of a bars allocated space on an ordinal axis which will be used for a gap. Setting to 0 will leave no gap between bars while 0.99 will cause the bars to render as hairlines with large gaps. The default is 0.4, meaning bars are 60% of the range band with a 40% gap between (20% on either side of each bar).

Example:

// Set the series to render with equal gaps to bars 
mySeries.barGap = 0.5;

dimple.series.c [code] - The axis used to determine the dynamic coloring of the datapoints in a series. This must be an axis which belongs to the passed chart and has its position property set to "c".

Example:

// Set the color axis of the series
var colorAxis = myChart.addColorAxis("Sales Volume");
mySeries.c = colorAxis;

dimple.series.categoryFields [code] - Unlike the parameters in methods which set this value, using the property directly requires it to be set to either null or an array (it can be a single element array). The following values are acceptable:

  • Null: If set to null, a single series will be drawn aggregating all values. The series will be named "All". To override this use a single element string array below.

  • Array of string values: The string values must be field names from the data (except in the case below) and a series will be created for every combination of their distinct values. E.g. "Brand 1/Region 1", "Brand 1/Region 2", "Brand 2/Region 1"...

  • Single element string array: A single value may either be a field name in which case it will behave as above. Alternatively it may be any other string value in which case it will behave as the Null case above but the series will be named according to the passed value. This allows 2 "total" series to be colored differently if required (for example 2 series, one for min and one for max price could be independently colored).

Example:

// Set the series to split by regions
mySeries.categoryFields = ["Region"];

dimple.series.chart [code] - The dimple.chart object to which the series will be connected. This should be set by the constructor and is included here as a property in case you need a route back from a series to its parent.

Example:

// Add a series to the chart object
var mySeries = myChart.addSeries("Brand", dimple.plot.bar);
// Get myChart via the series
console.log(mySeries.chart);

dimple.series.clusterBarGap [code] - To be documented.

Example:

// To be documented

dimple.series.innerRadius [code] - To be documented.

Example:

// See example at: http://dimplejs.org/examples_viewer.html?id=ring_standard
var myChart = new dimple.chart(svg, data);
myChart.setBounds(20, 20, 460, 360)
myChart.addMeasureAxis("p", "Unit Sales");
var ring = myChart.addSeries("Owner", dimple.plot.pie);
ring.innerRadius = "50%";
myChart.addLegend(500, 20, 90, 300, "left");
myChart.draw();

dimple.series.interpolation [code] - The series.interpolation property allows line interpolations to be applied to both the area and line charts. In addition to all the standard d3 interpolations, dimple also supports a custom interpolation called step. It uses d3's 'step-after' interpolation but shifts it and fills in some points to create a nicer stepped chart.

Example:

// See example at: http://dimplejs.org/examples_viewer.html?id=steps_horizontal
var s = myChart.addSeries(null, dimple.plot.line);
s.interpolation = "step";
myChart.draw();

dimple.series.lineMarkers [code] - Adds markers to the data points on a line type chart (including area charts). By default this value is false.

Example:

// Set the series to render with line markers
mySeries.lineMarkers = true;

dimple.series.lineWeight [code] - This is a numeric value used to determine the weight of the line in a line chart or area chart in pixels. By default this is set to 2 pixels. This will not affect the outline weight of non-line type charts.

Example:

// Set the series to render with heavy lines
mySeries.lineWeight = 5;

dimple.series.outerRadius [code] - To be documented.

Example:

// See example at: http://dimplejs.org/examples_viewer.html?id=ring_multiple
var myChart = new dimple.chart(svg, data);
myChart.setBounds(20, 20, 460, 360)
myChart.addMeasureAxis("p", "Unit Sales");
var outerRing = myChart.addSeries("Channel", dimple.plot.pie);
var innerRing = myChart.addSeries("Price Tier", dimple.plot.pie);
// Negatives are calculated from outside edge, positives from center
outerRing.innerRadius = "-30px";
innerRing.outerRadius = "-40px";
innerRing.innerRadius = "-70px";
myChart.addLegend(500, 20, 90, 300, "left");
myChart.draw();

dimple.series.plotFunction [code] - This should be one of the static objects from the dimple.plot namespace. This determines the way in which the series is rendered.

Example:

// Set the series to render as an area chart
mySeries.plotFunction = dimple.plot.area;

dimple.series.radius [code] - To be documented.

Example:

// See example at: http://dimplejs.org/examples_viewer.html?id=pie_matrix
var myChart = new dimple.chart(svg, data);
myChart.setBounds(95, 25, 475, 335)
myChart.addCategoryAxis("x", "Price Tier");
myChart.addCategoryAxis("y", "Pack Size");
myChart.addMeasureAxis("p", "Unit Sales");
var pies = myChart.addSeries("Channel", dimple.plot.pie);
pies.radius = 25;
myChart.addLegend(240, 10, 330, 20, "right");
myChart.draw();

dimple.series.shapes [code] - Once the chart is drawn and this series is rendered, the shapes property will contain the svg elements allowing you to use standard javascript or d3 to manipulate them.

// Add a series
var mySeries = myChart.addSeries("Brand", dimple.plot.bar);
myChart.draw();
// One way to boost sales...
mySeries.shapes.selectAll("rect").attr("transform", "translate(0, -100)");

dimple.series.stacked [code] - This should be a boolean value indicating whether the series should stack up against a category axis, or whether it should calculate an independent value for each data point.

Example:

// Set the series to stack values
mySeries.stacked = true;

dimple.series.data [code] - If set, this will override the chart data (if provided). This means different data may be drawn on each axis.

Example:

// Override the chart data
mySeries.data = [{"Min": 0.2}, {"Average": 0.72}, {"Max": 0.9}];

dimple.series.x [code] - The axis used to determine the horizontal positioning of the datapoints in the series. This must be an axis which belongs to the passed chart and has its position property set to "x".

Example:

// Set the x-axis of the series
var xAxis = myChart.addCategoryAxis("x", "Brand");
mySeries.x = xAxis;

dimple.series.y [code] - The axis used to determine the horizontal positioning of the datapoints in the series. This must be an axis which belongs to the passed chart and has its position property set to "y".

Example:

// Set the y-axis of the series
var yAxis = myChart.addCategoryAxis("y", "Brand");
mySeries.y = yAxis;

dimple.series.z [code] - The axis used to determine the scaling of the datapoints in certain types of series. This must be an axis which belongs to the passed chart and has its position property set to "z".

Example:

// Set the z-axis of the series
var yAxis = myChart.addMeasureAxis("z", "Sales Volume");
mySeries.z = zAxis;

dimple.series.tooltipFontSize [code] - This is 10px by default, any valid CSS font-size string is valid here.

// Set tooltip font size
mySeries.tooltipFontSize = "14px";

dimple.series.tooltipFontFamily [code] - This is sans-serif by default, any CSS font-family is valid here. Changing this will override the font used for series tooltip.

// Use a serif font instead of default sans-serif
mySeries.tooltipFontFamily = "serif";

Methods

dimple.series.addEventHandler(event, handler) [code] - Provide a handler against an event. A single event can be given multiple handlers however execution precedence cannot be guaranteed. The event parameter is the event registered against all data points in the series. The handler will be executed whenever any of them raise the specified event. The parameters are as follows:

  • event (Required): A string value indicating the mouse event to be handled. This will handle any event handled by a d3 SVG object. All possible values at time of writing are shown below, however any new ones will also be handled:

    • "click" - Raised when the user clicks and releases on an element in the series.

    • "mousedown" - Raised when the user clicks but has not yet released on an element in the series.

    • "mouseup" - Raised when the user releases their mouse button

    • "mouseover (also accepts "mouseenter") - Raised once when the cursor moves into an element in the series.

    • "mousemove" - Raised whenever the cursor moves within an element in the series.

    • "mouseout" (also accepts "mouseleave") - Raised once when the cursor moves out of an element in the series.

  • handler (Required): A function handling the event about. The first parameter of the function will receive a dimple.eventArgs object containing details about the user interaction. The function can do anything you like, go wild!

Example:

// Going wild with events
mySeries.addEventHandler("click", function (e) {
	alert("Hey, you clicked " + e.seriesValue + ". Woooooo!");	
});

dimple.series.addOrderRule(ordering, desc) [code] - Add a rule by which the values in the series dimension will be ordered. If no order rules are specified the default behaviour is to sort by the dimension itself. If the values can be parsed as a number or a date then a suitable order will be applied. Order rules will be used in the order they are added. This means that subsequent rules will only be considered if a pair of values evaluate to equal according to the first rule. If all specified rules evaluate to equal for a particular pair the default rule will be applied. If they are still equal their position in the data will be used.

  • ordering (Required): The core field of the rule, there are a number of values which can be passed here. The different cases are discussed below:
    • A dimension. This should be a string name representing a dimension in the data. In this case it is advisable to use a dimension with a lower or equal granularity to the dimension being sorted. For example if sorting countries and specifying mySeries.addOrderRule("Continent") the countries will be grouped by continent and then alphabetically within each. In this example the first five countries would be Afghanistan, Armenia, Azerbaijan, Bahrain and Bangladesh, because Asia is alphabetically first of the continents, and these are the first Asian countries alphabetically. Sorting continents by country would produce unreliable results because the first country encountered is used to sort its respective continent. Numeric values will be summed by the field to be sorted and ordered based on their totals.
    • A function. The function must take 2 parameters and return an integer. Both parameters will receive a data row. This row will have all the fields in the chart data provided, but critically, there will be a single value for the field being sorted and an array of values for every other field (even if there is a single value). Therefore your function should behave accordingly. The function should return a negative value if the contents of the first parameter should appear before the second parameter's contents in the sorted values. If the second should come first, your function should return a positive integer. If they evaluate equally return 0.
    • An array. The array should contain the expected values for the dimension to be sorted. The values will simply be placed in the same order as the array. Therefore if sorting days of the week (which would be default be alphabetic) you could use mySeries.addOrderRule(["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]). Any values not in the list will be appended to the end using following rules (or the default rule).
  • desc (Optional): By default this will be false. If true is passed the values will be returned in reverse order.

Example:

// Draw bars stacked by Country
var mySeries = myChart.addSeries("Country", dimple.plot.bar);
// Order countries by continent alphabetically, and then by GDP descending within each continent.
myStoryboard.addOrderRule("Continent");

dimple.series.getTooltipText(e) [code] - This method is not exposed with the intention of users calling it outside dimple, however it is very useful as an overridable value if you wish to provide your own text for tooltips. The parameter e will receive an dimple.eventArgs object containing information about the hovered element. The function should return a string array for display in the tooltip. Each element in the array represents a single line

Example:

// Use a custom tooltip
mySeries.getTooltipText = function (e) {
	return [
    	"Whatever mixtape cray keffiyeh street art jean shorts. Mumblecore direct trade hella, ",
        "selvage biodiesel before they sold out cardigan kitsch tattooed quinoa Banksy forage ",
        "kogi. DIY ugh keytar bicycle rights try-hard ennui. Cosby sweater PBR squid distillery ",
        "art party. Umami kogi Helvetica, locavore authentic ennui 3."
    ];
};
myStoryboard.addOrderRule("GDP", true);
Add a custom footer
Add a custom sidebar
Clone this wiki locally