Axis settings

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.

Supported axis types

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.

  • Category axis ( X-axis only. String values )
  • Linear axis ( X or Y-axis. Numeric values )
  • Date axis ( X or Y-axis. Date values )
  • Logarithmic axis ( X or Y-axis. Numeric values )

By default the X-Axis is a category axis and the Y-Axis a linear axis.

Category axis (X-axis only)

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)
    // ...

Linear (numeric) axis

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)
    // ...

Date axis

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.

Formatting patterns for different zoom levels

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

  1. get a reference to the date axis
  2. create a DateDataTypeFormatter object
  3. change the value of the “day” format of the DateDataTypeFormatter object using the appropriate method. Each “zoom level” has its own method. See the table at the end of this section for a listing of all available methods.
  4. attach the newly created formatting pattern to the axis.

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

Detailed explanation of the code shown above

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

Logarithmic axis

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

  1. with a linear Y-axis and
  2. with a logarithmic Y-axis

Please note the different rendering of the graph.

10
100
1000
10000
100000
1000000
10000000
100000000
1000000000

Primary and secondary axis

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.

Adding data to a secondary 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.

Configuring the value range

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.

Overriding the minimum and maximum default settings with only one Y-axis

Minimum and maximum values can be set specifically using one of these functions:

  • setAxisMinimumAsNumber( axisIdentity, number ) - Set the axis minimum to a numeric value
  • setAxisMinimumAsString( axisIdentity, datum, pattern ) - Set the axis minimum of a date axis to a date value which is interpreted via a pattern
  • setAxisMaximumAsNumber( axisIdentity, number ) - Set the axis maximum to a numeric value
  • setAxisMinimumAsString( axisIdentity, datum, pattern ) - Set the axis maximum of a date axis to a date value which is interpreted via a pattern

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")
    // ...

Overriding the minimum and maximum default settings with multiple Y-axes

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)
    // ...

Configuring tickmarks

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.

Configuring tickmark text

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")
    // ...

Setting the number of tickmarks

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)
    // ...

Setting the number of sub-tickmarks

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)
    // ...

Displaying the first / last tickmark

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)
    // ...

Axis caption

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")
    // ...

Swapping axes

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.

Set axis position

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)
    // ...

Numeric and logarithmic X-axis

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.