Skip to content

dimple.axis

Jump to bottom Edit New page
John Kiernander edited this page Jun 16, 2013 · 12 revisions

A chart can include as many axes as are required. Only the first 2 x-axes and the first 2 y-axes will render, however more axes may be added and used for positioning series.

#####Constructor#####

#####Properties#####

#####Methods#####

Constructor

dimple.axis(chart, position, categoryFields, measure) [code] - Initialise the axis for a particular chart. While the axis can be created using its constructor, it is advisable to use the range of factory methods in the chart object (addAxis, addMeasureAxis, addPctAxis, addCategoryAxis and addColorAxis) as this will add it to the chart collection as well as constructing the object.

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

  • position (Required): A string value indicating the positioning of the axis. It must be one of the following values:

    • "x": Creates an axis for determining horizontal positioning. The first x axis created will cross the first y axis at zero. The second will be positioned at the top of the chart. Any further x axes will be hidden but can still be used for positioning.

    • "y": Creates an axis for determining vertical positioning. The first y axis created will cross the first x axis at zero. The second will be positioned at the right of the chart. Any further y axes will be hidden but can still be used for positioning.

    • "z": Creates an axis for determining scale of elements. This axis does not render any visual elements and currently only affects bubble plots.

    • "c": This provides an axis for dynamically coloring a series based on a measure value. This requires at least a measure to be set, and will often require the axis colors property to be set. Adding a color axis is easier via the dimple.chart.addColorAxis helper method.

  • categoryFields (Optional): Although the categoryFields and measure parameters are optional at least 1 must be provided. Either a single string value or an array of string values will be accepted for categoryFields. The following options are accepted values for categoryFields:

    • Single string value: This string value must be a field name from the data and its distinct values will be used to create an ordinal axis. E.g. "Brand 1", "Brand 2"...

    • Array of two string values: The string values should be field names in the data, and will create a clustered axis. The first category will define the axis values, the second will provide the nested points.

    • Null: If set to null, the measure must be provided. This will create a linear numerical axis.

  • measure (Optional): Although the categoryFields and measure parameters are optional at least 1 must be provided. Either null or a single string value will be accepted. The following options are accepted values for measure:

    • Single string value: e.g. .addAxis("x", null, "Sales Volume"). This string value must be a field name from the data. If the field is numerical the values will be aggregated, otherwise a distinct count of values will be used.

    • Null: e.g. .addAxis("x", "Brand", null). If set to null, the categoryFields parameter must be provided. This will create an ordinal axis.

The other possible parameter combination not discussed above is to provide both categoryFields and a measure. E.g. .addAxis("x", "Brand", "Sales Volume"). This will create a scaled ordinal axis for charts such as a Mekko.

Example:

// Add a Brand ordinal axis on "x"
myChart.axes.push(new dimple.axis(myChart, "x", "Brand", null));
// Add a Sales Volume linear numerical axis on "y"
myChart.axes.push(new dimple.axis(myChart, "y", null, "Sales Volume"));

Properties

dimple.axis.categoryFields [code] - The fields whose unique combinations will be used to create an ordinal axis. The following options are accepted values for categoryFields:

  • Single string value: This must be a field name from the data and its distinct values will be used to create an ordinal axis. E.g. "Brand 1", "Brand 2"...

  • Array of two string values: The string values should be field names in the data, and will create a clustered axis. The first category will define the axis values, the second will provide the nested bars.

  • Null: If set to null, the measure must be provided. This will create a linear numerical axis.

Example:

// Add an axis to the chart object
var myAxis = myChart.addCategoryAxis("x", "Brand");
// Add a second category field (this is just an example, it would be better passed as an array to the constructor)
myAxis.categoryFields.push("Region");

dimple.axis.chart [code] - The dimple.chart object to which the chart will be connected. As well as the chart being passed here, it must also have this axis in its dimple.chart.axes collection.

This will probably be largely unused as the chart is set during the constructor or factory methods. It is maintained in the public API to find an axes parent.

Example:

// Add an axis to the chart object
var myAxis = myChart.addCategoryAxis("x", "Brand");
// Get myChart via the axis
console.log(myAxis.chart);

dimple.axis.colors [code] - The colors property is only applicable to a color axis. The following values are accepted:

  • Null/Undefined: Each series will be allocated a color as usual but the individual data point values will be graded to white based on the measure value.

  • Single color: Each series will be allocated a color as usual but the individual data point values will be graded to the provided color based on the measure value.

  • Color array: Colors are distributed across the value range and elements colored based on their value's position in this line. E.g. in the example above, if Sales Volume ranged from 0 to 100 an element with a Sales Volume of 60 would be graded at 20% of the color change between "#00FF00" and "#0000FF" (which incidentally is #00CC32").

Example:

// Create a Red, Amber, Green scale on Sales Volume using slightly muted colors
myAxis.colors = ["#DA9694", "#FABF8F", "#C4D79B"];

dimple.axis.gridlineShapes [code] - This is intended as a read only property and will be populated during the axis draw to return all the visual elements for the axis gridlines. This makes it easy to edit visual elements using raw d3 capabilities.

Example:

// Change the axis font color after drawing
var myAxis = myChart.addMeasureAxis("x", "Sales Volume");
// Draw the chart
myChart.draw();
// Make the gridlines red
myAxis.gridlineShapes.selectAll("line").attr("stroke", "#FF0000");

dimple.axis.hidden [code] - This only affects axes which would normally be displayed. i.e. the first 2 x-axes or the first 2 y-axes. Setting this to true will cause the axes to not be rendered, it can still be used to position series.

Example:

// Draw a bar chart with no visible axes
var x = myChart.addCategory("x", "Region");
var y = myChart.addMeasureAxis("y", "Sales Volume");
x.hidden = true;
y.hidden = true;
myChart.addSeries("Brand", dimple.plot.bar);
myChart.draw();

dimple.axis.measure [code] - Although the categoryFields and measure properties are optional at least 1 must be provided. Either null or a single string value will be accepted. The following options are accepted values for measure:

  • Single string value: This value must be a field name from the data. If the field is numerical the values will be aggregated, otherwise a distinct count of values will be used.

  • Null: If set to null, the categoryFields property must be provided. This will create an ordinal axis.

Example:

// Add an axis to the chart object
var myAxis = myChart.addMeasureAxis("x", "Sales Volume");
// A last minute change of heart
myAxis.measure = "Sales Value";

dimple.axis.overrideMax [code] - Manually override the maximum axis value. By default the chart will automatically determine the axis bounds. This property allows you to set a specific manual upper bound if you are not happy with the automatically determined value. If overriding an axis bound for an axis set to .showPercent = true the bounds are usually 0 to 1 (not 100).

Example:

// Add a measure axis to the chart object
var myAxis = myChart.addPctAxis("x", "Sales Volume");
// Lock the bounds to -50% to 50%
myAxis.overrideMin = -0.5;	
myAxis.overrideMax = 0.5;

dimple.axis.overrideMin [code] - Manually override the minimum axis value. By default the chart will automatically determine the axis bounds. This property allows you to set a specific manual lower bound if you are not happy with the automatically determined value. If overriding an axis bound for an axis set to .showPercent = true the bounds are usually 0 to 1 (not 100).

Example:

// Add a measure axis to the chart object
var myAxis = myChart.addPctAxis("x", "Sales Volume");
// Lock the bounds to -50% to 50%
myAxis.overrideMin = -0.5;	
myAxis.overrideMax = 0.5;

dimple.axis.position [code] - A string value used to set the position of the chart within the chart. The axis positions are discussed below:

  • "x": An axis for determining horizontal positioning. The first x axis created will cross the first y axis at zero. The second will be positioned at the top of the chart. Any further x axes will be hidden but can still be used for positioning.

  • "y": An axis for determining vertical positioning. The first y axis created will cross the first x axis at zero. The second will be positioned at the right of the chart. Any further y axes will be hidden but can still be used for positioning.

  • "z": An axis for determining scale of elements. This axis does not render any visual elements and currently only affects bubble plots.

  • "c": An axis for dynamically coloring a series based on a measure value. This requires at least a measure to be set, and will often require the axis colors property to be set. Adding a color axis is easier via the dimple.chart.addColorAxis helper method.

Example:

// Add an axis to the chart object
var myAxis = myChart.addCategoryAxis("x", "Brand");
// A last minute change of heart
myAxis.position = "y";

dimple.axis.shapes [code] - This is intended as a read only property and will be populated during the axis draw to return all the visual elements for the axis. This makes it easy to edit visual elements using raw d3 capabilities.

Example:

// Change the axis font color after drawing
var myAxis = myChart.addCategoryAxis("x", "Brand");
// Draw the chart
myChart.draw();
// Set the text color using d3.
myAxis.shapes.selectAll("text").attr("fill", "#FF0000");

dimple.axis.showGridlines [code] - This has 3 accepted vales:

  • true: will always render gridlines (as long as this is an x or y axis).

  • false: will never render gridlines.

  • null (default): will render them for the first x and first y measure axis only.

Example:

// Draw a bar chart with proportional y values
myChart.addCategory("x", "Region");
var y = myChart.addMeasureAxis("y", "Sales Volume");
y.showGridlines = false;
myChart.addSeries("Brand", dimple.plot.bar);
myChart.draw();

dimple.axis.showPercent [code] - If set to true for a non-ordinal axis, the axis will become a 100% measure axis. For example if drawing a stacked bar chart with a category x-axis and a measure y-axis, setting the y-axis to .showPercent = true will stretch all bars to 100% with each segment being stretched to show it's share of bar total.

Example:

// Draw a bar chart with proportional y values
myChart.addCategory("x", "Region");
var y = myChart.addMeasureAxis("y", "Sales Volume");
y.showPercent = true;
myChart.addSeries("Brand", dimple.plot.bar);
myChart.draw();

dimple.axis.titleShape [code] - Once the chart is drawn and this axis is rendered, the titleShape property will contain the svg element for the title allowing you to use standard javascript or d3 to manipulate it.

// Draw the chart
myChart.draw();
// Remove the title
myAxis.titleShape.remove();

Methods

dimple.axis.addGroupOrderRule(ordering, desc) [code] - Add a rule by which the values in a group on a category axis will be ordered. The groups themselves can be ordered using addOrderRule So if the axis shows brands grouped by owner, this would allow you to order the brands,If no order rules are specified the default behaviour is to sort by the dimension itself. If ordering an x-axis or a y-axis and the opposite axis is a measure axis, the corresponding measure will be used for sorting e.g. if plotting countries on x and GDP on y the countries will be drawn by GDP descending. Otherwise 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 myAxis.addGroupOrderRule("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 myAxis.addGroupOrderRule(["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 myAxis = myChart.addCategoryAxis("x", "Country");
// Order countries by continent alphabetically, and then by GDP descending within each continent.
myAxis.addGroupOrderRule("Continent");
myAxis.addGroupOrderRule("GDP", true);

dimple.axis.addOrderRule(ordering, desc) [code] - Add a rule by which the values in a category axis will be ordered. If no order rules are specified the default behaviour is to sort by the dimension itself. If ordering an x-axis or a y-axis and the opposite axis is a measure axis, the corresponding measure will be used for sorting e.g. if plotting countries on x and GDP on y the countries will be drawn by GDP descending. Otherwise 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 myAxis.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 myAxis.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 myAxis = myChart.addCategoryAxis("x", "Country");
// Order countries by continent alphabetically, and then by GDP descending within each continent.
myAxis.addOrderRule("Continent");
myAxis.addOrderRule("GDP", true);
Add a custom footer
Add a custom sidebar
Clone this wiki locally