dimple.axis

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

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, addTimeAxis, addPctAxis, addCategoryAxis, addColorAxis and addLogAxis) 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. new dimple.axis(myChart, "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. new dimple.axis(myChart, "x", "Brand", null). If set to null, the categoryFields parameter must be provided. This will create an ordinal axis.
timeField (Optional): Setting a timeField here will cause this axis to behave as a time axis. Either null or a single string value will be accepted. The following options are accepted values for timeField:
- Single string value: e.g. new dimple.axis(myChart, "x", null, null, "Date"). This string value must be a field name from the data. The values in the timeField must be able to parse to dates. A format for the parsing can be provided to the dateParseFormat otherwise the default browser parse will be used which may cause inconsistency across browsers.
- Null: e.g. new dimple.axis(myChart, "x", "Brand", null, null). If set to null, the categoryFields or measure parameter must be provided. This will create a non-time axis

The other possible parameter combination not discussed above is to provide both categoryFields and a measure. E.g. new dimple.axis(myChart, "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"));
// Add a time axis on "x" for the date field
myChart.axes.push(new dimple.axis(myChart, "x", null, null, "Date"));

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.clamp [code] - This is true by default meaning that the axis will not draw elements outside itself. If set to false values can spill off the end of the axis.

// I want an axis which gives 110%
myAxis.clamp = false;

dimple.axis.fontSize [code] - This is 10px by default as of version 2. In order to get the dimple version 1 handling (where fonts are resized according to the chart size) set this to "auto". Otherwise any valid CSS font-size string may be passed.

// Let's keep it old skool
myAxis.fontSize = "auto";

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

// Use a serif font for this axis
myAxis.fontFamily = "serif";

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.logBase [code] - If a log axis is used, this defines the log base on which the axis is drawn. By default log axes are drawn log 10. It will only affect axes with a measure and the useLog property set to true.

// Add a log axis on Y for unit sales.  By default base 10 is used
// so the ticks will go 10, 100, 1000 etc.
myChart.addLogAxis("y", "Unit Sales");
// Switch to base 2 for values 2, 4, 8, 16 etc. NB. This could have been
// passed as the third parameter above.
myAxis.logBase = 2;

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.title [code] - This allows you to override the default titles for axes. The default value is undefined causing the name of the axis dimension(s) to be used as the title. Alternatively setting this to null will cause no title to be rendered. Or the value can be set to any string and that string will be rendered instead

// Change the title text
myAxis.title = "My Awesome New Title";

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();

dimple.axis.tickFormat [code] - Formatting for the axis, defined as a string using the d3 time formatting or d3 formatting style.

// Display a measure axis' values as percentages 
myAxis.tickFormat = "%";

dimple.axis.ticks [code] - The default value is 10 but this can be changed to any integer to determine the number of ticks drawn on the axis.

// Space out the axis a bit
myAxis.ticks = 5;

dimple.axis.timeField [code] - The field in the data with whose values you would like to draw a time axis. The field should contain date values, its parsing can be controlled with the dateParseFormat.

// Create a time axis on the date field
myAxis.timeField = "Date";

dimple.axis.dateParseFormat [code] - The format of the data in the timeField, defined as a string using the d3 time formatting style. This is not used for display like tickFormat, it should describe the way that dimple needs to parse the dates in the time field into dates. If null is used the dates will be parsed as epoch time integers, however this is epoch time as defined in JavaScript (milliseconds since epoch) not -the more common - Unix definition (seconds since epoch).

// Parse English style dates (as opposed to the American style
myAxis.dateParseFormat = "%d/%m/%Y";

dimple.axis.floatingBarWidth [code] - The width of bars on a time axis in pixels. Because the bars on this sort of axis are positioned centered on a time point the width is arbitrary, this allows you to override the 5 pixel default.

// Draw bars as 2px lines
myAxis.floatingBarWidth = 2;

dimple.axis.timePeriod [code] - The d3 date range definition for a time axis. This (along with the timeInterval) property will instruct the regularity of labels on a time axis. This must be a d3 interval range. Be sure to use the plural versions here. i.e. be sure to use d3.time.months NOT d3.time.month. The plural is a shortcut for a range which this property requires.

// Draw a label for each quarter
myAxis.timePeriod = d3.time.months;
myAxis.timeInterval = 4;

dimple.axis.timeInterval [code] - The number of time periods between each label on a time axis. The time period is defined by the timePeriod.

// Draw a label for each 2 years
myAxis.timePeriod = d3.time.years;
myAxis.timeInterval = 2;

dimple.axis.useLog [code] - Setting this to true will cause a measure axis to become a log axis drawing non-linear values. By default log10 is used meaning the axis ticks will read 10, 100, 1000 etc.

// Add a log axis on Y for unit sales setting the axis to log2 (2, 4, 8, 16 etc)
myChart.addLogAxis("y", "Unit Sales", 2);

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);

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

dimple.axis

Constructor

Properties

Methods

Constructor

Properties

Methods

Clone this wiki locally