Line charts and bar charts can have three axes: X-axis, Y-axis and 2nd Y-axis. Each axis is of a specific type. The type of the axis determines how values are displayed in the chart.
Adding data to a 2nd Y axis has already been explained in the line chart and bar chart chapters of this documentation. This part of the documentation now concentrates on the different configuration options for the axis itself.
This document refers only to line charts and bar charts for the simple reason that a pie chart does not have any axes.
ArcadiaCharts includes four different types of axes. The axis types differ in respect of the way they display values and how they can be configured.
By default the X-Axis is a category axis and the Y-Axis a linear axis.
A category axis contains string values. These values are placed at uniform intervals in the order in which they appear in the value set. They are neither sorted nor displayed with variable intervals. This axis type is the default for the X-axis if no higher order axis can be selected.
A category axis is automatically selected if your X-values are of type String. If your X-values are of type Date or String you can specify a category axis with the setAxisType()
command. The following example sets the X-axis type to “category”:
new ac.ACLineChartBuilder() // ... .setAxisType(ac.AxisIdentity.X_AXIS, ac.AxisType.CATEGORY) // ...
The linear axis is the default for the Y-axis if no other axis type is specified. A linear axis can only display numeric values (integer or float). The values are displayed at uniform intervals.
new ac.ACLineChartBuilder() // ... .setAxisType(ac.AxisIdentity.X_AXIS, ac.AxisType.LINEAR) // ...
new ac.ACLineChartBuilder() // ... .setAxisType(ac.AxisIdentity.X_AXIS, ac.AxisType.DATE) // ...
The behavior of a date axis differs in many ways compared with the other axis types. The most important difference is that the tickmarks are spaced non-uniformly, while the spacing of the other axis types is uniform. This is specifically the case when months or years are displayed. The distance between January 1st and February 1st is greater (31 days) than between February 1st and March 1st (28/29 days). The distance between 2008 and 2009 is also slightly greater (leap year) than between 2009 and 2010.
The ValueSet for a date axis has to contain objects of type <javadoc>java.util.Date</javadoc>. When converting string values, the GWT-class
<javadoc GWT-1.6-doc>com.google.gwt.i18n.client.DateTimeFormat</javadoc> with the method parse
is very useful.
In the JavaScript version of arcadiaCharts, date values can only be created by the CSV-importer. There is no other way of creating them than in GWT. Please see the corresponding section in the reference manual for a detailed description of how to create date values with the csv-importer.
The date axis has different “zoom levels” which are implemented according to the value range. The format of the tickmarks varies depending on whether years, months, days, hours or minutes are displayed. The standard formats are:
Zoom Level | Format |
---|---|
Year | “yyyy” |
Month | “MMM yy” |
Day | “dd.MM.yyyy” |
Hour | “HH:mm” |
Minute | “mm:ss” |
More information about formatting patterns in general can be found in the corresponding section of the reference manual.
If you would like to change one of the standard formats, for instance to change the “day” format to “dd-MM-yy”, you need to
DateDataTypeFormatter
objectThe code below shows the different steps. You will find an explanation further down.
var chart = new ac.ACLineChartBuilder() .setData(someData) // ... .build(); // The formatting code can only be used _after_ the chart has been created // but before it is added to the DOM. // get axis reference var dateAxis = chart.getPrimaryAxis(ac.AxisOrientation.HORIZONTAL); // create DateDataTypeFormatter object var formatter = new ac.DateDataTypeFormatter(); // set new format for zoom-level "day" formatter.setFormattingDayPattern("dd'-'MM'-'yy"); // attach new formatting pattern to axis dateAxis.setLabelFormatter(formatter); chart.addToDom('chart');
In order to work directly on an axis you have to reference that axis first. This is done via the .getPrimaryAxis( AxisOrientation )
or .getSecondaryAxis( AxisOrientation )
methods of the chart. The methods take the AxisOrientation
as a parameter. This can be either ac.AxisOrientation.HORIZONTAL
or ac.AxisOrientation.VERTICAL
.
The primary
axis is the first axis if two axes of the same orientation are present (for example when two Y-axes are present). Please note that when you swap axes with swapAxes()
the orientation changes accordingly.
The table summarizes the different axis retrieval methods. Add the prefix ac. to AxisOrientation if you are using the JavaScript version, e.g. ac.AxisOrientation.VERTICAL.
Axis | retrieval method |
---|---|
X | chart.getPrimaryAxis( AxisOrientation.HORIZONTAL ) |
Y | chart.getPrimaryAxis( AxisOrientation.VERTICAL ) |
Y2 | chart.getSecondaryAxis( AxisOrientation.VERTICAL ) |
If no changes have been made, the DateDataTypeFormatter has the default formatting patterns as listed below. If you would like to change one or all of them, you have to use the appropriate method (e.g. setFormattingMonthPattern()
for changing the month format of the date axis). Each “zoom level” has its own method for changing the formatting pattern.
Level | Default Formatting Pattern | Change using DateDataTypeFormatter method |
---|---|---|
Minute | “mm:ss” | setFormattingMinutePattern( “mm:ss” ) |
Hour | “HH:mm” | setFormattingHourPattern( “HH:mm” ) |
Day | “dd.MM.yyy” | setFormattingDayPattern( “dd.MM.yyy” ) |
Month | “MMM yy” | setFormattingMonthPattern( “MMM yy” ) |
Year | “yyyy” | setFormattingYearPattern( “yyyy” ) |
new ac.ACLineChartBuilder() // ... .setAxisType(ac.AxisIdentity.X_AXIS, ac.AxisType.LOGARITHMIC) // ...
Exponential functions often ascend very steeply. This results in a graphical display where for small X-values the Y-values cannot be distinguished.
To solve this problem the Y-axis can be configured to display the values on a logarithmic scale. This means that instead of 0, 1, 2… the Y-axis has the values of 10power0, 10power1, 10power2 as shown in the example below.
The logarithmic axis distorts the graph and displays a exponential curve as a straight line with a gradient of 1.
Example:
In the example below the the same values are displayed
Please note the different rendering of the graph.
10 100 1000 10000 100000 1000000 10000000 100000000 1000000000
The figure at the beginning of this chapter shows a primary (1st) and secondary (2nd) Y-Axis. Each axis can have one or more ValueSets attached to it. A secondary axis is drawn automatically as soon as it has a ValueSet attached to it. Secondary axes can be used in line charts and bar charts. Each axis can have its own configuration, e.g. value range, caption, spacing etc. If the axis position of one axis is changed with setAxisPosition() the other axis will change its position as well.
A secondary axis can be quite useful for displaying ValueSets with highly disparate value ranges in one chart together. The two examples below display exactly the same data. The left one has only one Y-Axis; the right chart demonstrates how the display changes when one of the two ValueSets is attached to a secondary Y-axis.
The assignment of a ValueSet to a second Y-axis is achieved with the command addToSecondaryAxisByTitle( ValueSetTitle )
new ac.ACLineChartBuilder() // ... .addToSecondaryAxisByTitle('Temperature') // ...
The ValueSetTitle is either the title of a manually created ValueSet (not supported in JavaScript version) or the identification string of the data column in CSV.
The value range is the selection of values which is displayed by the axis. In many cases it does not make sense to start the axis caption at the value zero, for instance if the range of values is such that the lower values are irrelevant. The value range is determined automatically on the basis of the current ValueSet. For example if you have values ranging from 5500 to 7500 the axis range will be from 5000 to 8000.
Minimum and maximum values can be set specifically using one of these functions:
Example (numeric value)
Setting the lower value of the Y-axis to 10 and the upper value to 50:
new ac.ACLineChartBuilder() // ... .setAxisMinimumAsNumber(ac.AxisIdentity.Y_AXIS, 10) .setAxisMaximumAsNumber(ac.AxisIdentity.Y_AXIS, 50) // ...
Example (date value)
Setting the lower date value of the X-axis to January 1st 2008 and the upper date value of the X-axis to May 31st 2010:
new ac.ACLineChartBuilder() // ... .setAxisMinimumAsString(ac.AxisIdentity.X_AXIS, "01-01-2008", "dd-MM-yyy") .setAxisMaximumAsString(ac.AxisIdentity.X_AXIS, "05-31-2008", "dd-MM-yyy") // ...
Changing minimum and maximum settings with multiple axes (e.g. a primary and secondary Y-axis) may require an additional step:
arcadiaCharts tries to align zero values of parallel axes to the same level, so positive and negative values lie within the same area. If you wish to use one of the axes for both positive and negative values (like, for example, a climate chart with temperatures below and above zero) while the other axis doesn´t need negative values (the precipitation axis in our chart doesn´t need negative values since there is no negative rainfall), you may need to disable this functionality.
new ac.ACLineChartBuilder() // ... .setAlignZeroLines(false) // ...
This method is set to “true” as default, so there is no need to enable it.
Setting the maximum an minimum values is the same as for a single axis:
new ac.ACLineChartBuilder() // ... .setAxisMinimumAsNumber(ac.AxisIdentity.Y_AXIS, -10) .setAxisMaximumAsNumber(ac.AxisIdentity.Y_AXIS, 100) .setAxisMinimumAsNumber(ac.AxisIdentity.Y2_AXIS, 0) .setAxisMaximumAsNumber(ac.AxisIdentity.Y2_AXIS, 50) // ...
Tickmark configuration is described in detail the line chart, bar chart and pie chart sections of this manual. Therefore we just give a brief overview here.
In the following example the tickmarks for the X-axis are formatted to display the first 3 characters only (eg. only Jan for January) and the Y-axis is formatted to display a number with a descriptive string such as “12 °C” The secondary Y-axis is formatted to display a number with a descriptive string such as “122 mm”.
new ac.ACLineChartBuilder() // ... .setAxisTickmarkFormattingPattern(ac.AxisIdentity.X_AXIS, "<###") .setAxisTickmarkFormattingPattern(ac.AxisIdentity.Y_AXIS, "#0 °C") .setAxisTickmarkFormattingPattern(ac.AxisIdentity.Y2_AXIS, "#0 mm") // ...
Tickmarks are the large, labeled tickmarks.
Tickmarks can be set manually using the function “setAxisDesiredTickmarks( AxisIdentity, int )”. This setting isn´t binding. arcadiaCharts tries to use this value, but overrides it if it´s not possible to render an axis with this number of tickmarks correctly.
new ac.ACLineChartBuilder() // ... .setAxisDesiredTickmarks(ac.AxisIdentity.X_AXIS, 6) .setAxisDesiredTickmarks(ac.AxisIdentity.Y_AXIS, 6) // ...
Sub-tickmarks are the smaller tickmarks between the labeled tickmarks.
The sub-tickmarks are set manually using the function “setAxisNumberOfSubTicks( AxisIdentity, int )”.
new ac.ACLineChartBuilder() // ... .setAxisNumberOfSubTicks(ac.AxisIdentity.X_AXIS, 3) .setAxisNumberOfSubTicks(ac.AxisIdentity.Y_AXIS, 3) // ...
For design reasons it makes sense in some cases to omit or enforce the display of the first or last tickmark. This is achieved with setAxisDisplayFirstTick(AxisIdentity, boolean) and .setAxisDisplayLastTick(AxisIdentity, boolean)
In the following example the display of the first and last tickmark of the Y-axis is enforced:
new ac.ACLineChartBuilder() // ... .setAxisDisplayFirstTick(ac.AxisIdentity.Y_AXIS, true) .setAxisDisplayLastTick(ac.AxisIdentity.Y_AXIS, true) // ...
The axis caption is a descriptive string which is displayed alongside the axis. Each axis (Y, Y2 and X-axis) can have its own caption.
Example:
The following example sets the caption for the X-axis and the first and secondary Y-axes.
new ac.ACLineChartBuilder() // ... .setAxisCaption(ac.AxisIdentity.X_AXIS, "Date") .setAxisCaption(ac.AxisIdentity.Y_AXIS, "Temperature") .setAxisCaption(ac.AxisIdentity.Y2_AXIS, "Precipitation") // ...
new ac.ACLineChartBuilder() // ... .swapAxes() // ...
Executing the command swapAxes() swaps the axes. The X-axis becomes the Y-axis. The Y-axis becomes the X-axis. The figure illustrates the effect.
The default position of an axis can be altered using the setAxisPosition() command. An axis can only be re-positioned in the same orientation. The X-axis can only be positioned TOP or BOTTOM; the Y-axis can only be positioned LEFT or RIGHT. Other orientations are possible in combination with swapAxes(). If you would like to position the X-axis at the right of the chart, for instance, you have to use swapAxes() first to give the X-axis a vertical orientation and then position it with setAxisPosition().
Syntax:
.setAxisPosition( AxisIdentity, AxisPosition )
Position can be LEFT RIGHT TOP BOTTOM
Example:
new ac.ACLineChartBuilder() // ... .setAxisPosition(ac.AxisIdentity.X_AXIS, ac.AxisPosition.TOP) .setAxisPosition(ac.AxisIdentity.Y_AXIS, ac.AxisPosition.RIGHT) // ...
In all chart types the default X-axis type is category. In addition to that line charts support date, linear and logarithmic X-axis types.
In the example below all three charts present the same data.
Xvalue;Y1Value 1,23 5,26 25,27 125,21
Since the X-values are numeric they can be assigned to a category axis (which is the default for the X-axis) but also to a linear or a logarithmic axis.