4
Building More Complex Static Charts

4.1.1 Building Multiple-Series Line and Area Charts

To build a multiple-series line or area chart, you make multiple calls to the methods, such as the setYSeries( ) method, that load data into the Y-axis series. For example, to load import data for both Mexico and Japan into the same chart, you use the code similar to the following:

MyAxisCh.setYSeries("Japan", ImportsJapan);

MyAxisCh.setYSeries("Mexico", ImportsMexico);

To differentiate between the two series, you can set the color of each series, as shown in the following example:

MyAxisCh.setSeriesColor("Japan", Color.red);

MyAxisCh.setSeriesColor("Mexico", Color.blue);

The following figure shows the resulting multiple-series line chart:

Description of the illustration multiline.gif

By default, Chart Builder positions the legends in the lower right corner of the chart background. For information about changing attributes of the legend, including the positioning, see Section 4.2.

To load multiple series into an area chart, you use the same methods as for line charts. The only difference is that you set the graph type to AREA, as shown in the following example:

MyAxisCh.setSeriesGraphType("Japan", AxisChart.AREA);

MyAxisCh.setSeriesGraphType("Mexico", AxisChart.AREA);

The resulting chart uses the series colors as defined with the setSeriesColor( ) method as the line color, but it uses the default gray as the color of the area, as shown in the following figure:

Description of the illustration multiarea1.gif

To set the color of the area for each series, you allocate an AreaDesc descriptor object for each series and then pass the object to the chart using the setSeriesGraphic( ) method, as shown in the following example:

// Use an AreaDesc descriptor object to set the area and line color and the

// line width for the Japan series.

AreaDesc desc1 = new AreaDesc();

desc1.setLineColor(Color.black);

desc1.setAreaColor(myGreen);

desc1.setLineWidth(2);


// Pass the descriptor object to the chart. 

MyAxisCh.setSeriesGraphic("Japan", desc1);


// Use an AreaDesc descriptor object to set the area and line color and the

// line width for the Mexico series. 

AreaDesc desc2 = new AreaDesc();

desc2.setLineColor(Color.black);

desc2.setAreaColor(myOrange);

desc2.setLineWidth(2);


// Pass the descriptor object to the chart. 

MyAxisCh.setSeriesGraphic("Mexico", desc2);

The following figure shows the resulting chart:

Description of the illustration multiarea2.gif

You can modify an area chart to make an area transparent, which allows the underlying grid to show through and shows the intersections of areas in multiple-series area chart.

To make an area transparent, you use the setAreaTransparency( ) method of the AreaDesc class. You pass a float value (between 0.0 and 1.0) as a parameter to the method. A value of 1.0 is completely opaque; a value of 0.0 is fully transparent.

The following code, added to the AreaDesc descriptor objects for the Mexico and Japan series, sets the transparency of each area to 0.5:

desc1.setAreaTransparency(.5f);

desc2.setAreaTransparency(.5f);

The following figure shows the resulting chart:

Description of the illustration multiarea2_transp.gif

Note that the data from only 2000 and 2001 is shown to display intersections of data more clearly.

4.1.2 Building Clustered and Stacked Bar Charts

Chart Builder supports two types of multiple-series bar charts: clustered bar charts and stacked bar charts. To build either type of chart, you make multiple calls to the setYSeries( ) method, as you do for multiple-series line or area charts.

The following example, which creates a clustered bar chart, shows the calls to the setYSeries( ) method and to the setSeriesGraphType( ) method to set the graph type to BAR:

// Load the data into multiple series.

MyAxisCh.setYSeries("Japan", ImportsJapan);

MyAxisCh.setYSeries("Mexico", ImportsMexico);


//Set the graph type to BAR for each series.

MyAxisCh.setSeriesGraphType("Japan", AxisChart.BAR);

MyAxisCh.setSeriesGraphType("Mexico", AxisChart.BAR);

To differentiate between the two series, you can set the color of each series, as shown in the following example:

MyAxisCh.setSeriesColor("Japan", myOrange);

MyAxisCh.setSeriesColor("Mexico", myGreen);

The following figure shows the resulting clustered bar chart:

Description of the illustration multiclustbar.gif

Alternatively, you can specify a stacked bar chart, as shown in the following example:

// Set the graph type to BAR_STACKED for each series.

MyAxisCh.setSeriesGraphType("Japan", AxisChart.BAR_STACKED);

MyAxisCh.setSeriesGraphType("Mexico", AxisChart.BAR_STACKED);

The following figure shows the resulting stacked bar chart:

Description of the illustration multistack.gif

4.1.3 Building Charts with Mixed Graph Types

You can combine different graph types in one chart. For example, you can combine a line for one series and a bar for another series into the same chart. To do so, change the graph type of one or more of the series, as shown in the following example:

// Set the graph type to LINE for one series, to BAR for the other.

MyAxisCh.setSeriesGraphType("Japan", AxisChart.LINE);

MyAxisCh.setSeriesGraphType("Mexico", AxisChart.BAR);

The following figure shows a chart with mixed graph types:

Description of the illustration mixed2.gif

4.1.4 Building Dual-Axis Charts

You may want to combine multiple series in one chart, but want to place each series on a separate vertical scale. In this case, you can use a dual-axis chart, where the labels for one Y-axis series are represented on the Y-axis on the left side of the chart, and the labels for the other Y-axis series are represented on the Y-axis on the right side of the chart.

To build a dual-axis chart, you use the setYSeriesAxis2( ) method to assign a series to the second axis. By default, the first axis is displayed on the right side of the chart; the second axis is displayed on the left side of the chart.

The following example shows an excerpt that loads multiple series and assigns the series named USGS to the second axis:

// Load data into the two Y-axis series.

AxisCh.setYSeries("USGS", ImportsGoodsServices);

AxisCh.setYSeries("Japan", ImportsJapan);

    

// Set the graph type for each series. 

MyAxisCh.setSeriesGraphType("Japan", AxisChart.LINE);

AxisCh.setSeriesGraphType("USGS", AxisChart.BAR);


// Assign the series named "USGS" to the second Y-axis.

MyAxisCh.setYSeriesAxis2("USGS");

The following figure shows the resulting dual-axis chart:

Description of the illustration dualaxis2.gif

4.1.5 Building Mixed-Frequency Charts

You may want to combine multiple series in one chart, but the data for each series may not contain timestamps at the same frequency. For example, you can create a chart where one Y-axis series contains data that is associated with monthly timestamps, while another Y-axis series contains data that is associated with quarterly data. To do so, take the following steps:

1. Load the higher frequency timestamps, in this case the monthly timestamps, into the chart using the setXSeries( ) method. In the following example, the array MonthlyDates has been defined in the application.

   MyAxisCh.setXSeries(MonthlyDates); 
   
   

2. Load the Y-axis series associated with the monthly timestamps, as shown in the following example:

   MyAxisCh.setYSeries("Japan", ImportsJapan);
   
   

3. Using the setYSeriesSparse( ) method, load the Y-axis series associated with the quarterly timestamps. In the following example, QuaterlyDates is the name of the array of timestamps representing the quarterly timestamps and ImpGoodsServices is the name of the Y-axis series:

   AxisCh.setYSeriesSparse("USGS", QuarterlyDates, ImpGoodsServices);
   
   

   See Section 4.4.3 for more information about using the setYSeriesSparse( ) method.

The following figure shows the resulting mixed-frequency chart:

Description of the illustration mixfreq.gif

Note that, in creating this chart, the setYSeriesAxis2( ) method is used to specify a dual-axis chart. See Section 4.1.4 for information about dual-axis charts.

4.3.1 Customizing Legends in Pie Charts

To specify that a pie chart display a legend and to control its placement, you use the setLegendAlignment( ) method of the Legend class. For pie charts, the following alignments are supported:

• Legend.NORTH: Above the pie chart.

• Legend.SOUTH: Below the pie chart.

• Legend.EAST: To the right of the pie chart.

• Legend.WEST: To the left of the pie chart.

• Legend.DERIVED: The default alignment. DERIVED means that Chart Builder will position the legend in the SOUTH or EAST, depending on the size of the frame and the size of the pie chart.

In addition, you can use methods of the Legend class to set the foreground, background, and edge color of the legend.

The following example positions the legend to the left side (WEST) of the pie chart and it sets the color of the bounding box for the legend to black:

MyPieCh.setLegendAlignment(Legend.WEST);

MyPieCh.setLegendEdgeColor(Color.black);

The following figure shows the resulting pie chart:

Description of the illustration pielegend.gif

As the preceding figure shows, if Chart Builder cannot fit all of the labels in one column in the legend, it divides the labels into two or more columns.

4.3.2 Customizing Labels in Pie Charts

By default, Chart Builder labels the pie slices with the names you provide in an array of PieSliceDesc descriptors. You can customize the information used as a label in the following ways:

• Each label can be extended with the numerical value associated with each pie slice by using the setDeriveLabelVal( ) method. You can control the numerical precision of the derived label value and format the number using currency formats and number separators.

• Each label can be extended with the percentage represented by the pie slice by using the setDeriveLabelPct( ) method. You can control the numerical precision of the derived label percentage.

• Label pie slices with the data value by using the setLabelInteriorVal( ) method. The user-defined labels are placed in a legend. This method invokes the setDeriveLabelVal( ) method.

• Label pie slices with the percentage of the pie represented by the slice by using the setLabelInteriorPct( ). The user-defined labels are placed in a legend. This method invokes the setDeriveLabelPct( ) method.

When you use the setLabelInteriorVal( ) or setLabelInteriorPct( ) method, Chart Builder displays the user-defined names in a legend, even if you do not specify the setLegendAlignment( ) method.

The following example shows how to label pie slices with the value of each slice using the default currency format:

// Use NumberFormat to get the currency format.

nf = NumberFormat.getCurrencyInstance();

// Add the value to the label for each slice.

MyPieCh.setDeriveLabelVal(nf);

The following figure shows the pie chart with the values added to the labels. It adds the value to the names you provide in an array of PieSliceDesc descriptors.

Description of the illustration pielegend_val.gif

The following example shows how to label pie slices with the percentage, to a precision of 2, that is represented by each slice. It adds the percentage to the names you provide in an array of PieSliceDesc descriptors.

// Use NumberFormat to get the percentage.

nf = NumberFormat.getPercentInstance();

// Set the precision to 2.

nf.setMinimumFractionDigits(2);

// Add the percentage to the label for each slice.

MyPieCh.setDeriveLabelPct(nf);

The following figure shows the pie chart with the percentages added to the labels:

Description of the illustration pielegend_pct.gif

You can label the pie slices with the value or the percentage and place the user-defined labels in a legend. The following example uses the setLabelInteriorVal( ) method to label the slices with the values and the setDeriveLabelVal( ) method to display the currency format:

// Use NumberFormat to get the currency format.

nf = NumberFormat.getCurrencyInstance();

// Add the value to the label for each slice.

MyPieCh.setDeriveLabelVal(nf);

// Label the slices with the value only and 

// put the user-defined names in a legend.

MyPieCh.setLabelInteriorVal();

The following figure shows the resulting pie chart with the values displayed in the pie slices and the user-defined labels displayed in a legend:

Description of the illustration pielegend_intval.gif

For information about other methods for customizing legends and labels in pie charts, see the API documentation, especially the Legend class.

For more examples of customizing legends and labels, see the legend subdirectory in Chart Builder demos directory.

4.4.1 Building Charts with Missing Data at the End of a Chart

When you use the standard setXSeries( ) and setYSeries( ) methods and you supply more timestamps than Y-axis values, Chart Builder maps the Y-axis series values to the timestamps, beginning with the first timestamp. Timestamps at the end of the chart will be missing associated values.

For example, if you have timestamps for each month of the year, but you do not have data values for November and December, Chart Builder correctly associates the data with the first ten months of the year. You use the setXSeries( ) method to load more timestamps than data and the standard setYSeries( ) method to load the data.

The following example uses the frequency-based setXSeries( ) method to load monthly timestamps from 1999-01-01 to 2001-12-01 into the X-axis. Then, it uses the standard setYSeries( ) method to load data into the Y-axis. Data is available for all months in 1999 and 2000, but not for the last four months of 2001.

MyAxisCh.setXSeries(Calendar.MONTH,

                   java.sql.Date.valueOf("1999-01-01"),

                   java.sql.Date.valueOf("2001-12-01")

                   1);

// Load the Y-axis series.

MyAxisCh.setYSeries("Japan", ImportsJapan); 

The following figure illustrates the resulting chart, one with data for the beginning timestamps, but without data for the ending timestamps, the last four months of 2001:

Description of the illustration sequent0.gif

4.4.2 Building Charts with Missing Data at the Beginning of a Chart

You can build a chart where there is no data to associate with the timestamps at the beginning of the chart, but the data is mapped sequentially to the timestamps.

For example, you have data for the last six months of 1999 and all of 2000. However, to make this chart consistent with other charts, you want to display timestamps for all months in 1999 and 2000. To build the chart, you use the setYSeries( ) method with the startDate parameter, as shown in the following example:

// This example uses the frequency-based method to load the timestamps.

MyAxisCh.setXSeries(Calendar.MONTH,

                   java.sql.Date.valueOf("1999-01-01"),

                   java.sql.Date.valueOf("2000-12-01"),

                   1);

// Load the Y-axis series and set the start date to "1999-07-01".

MyAxisCh.setYSeries("Japan", ImportsJapan, 

                     java.sql.Date.valueOf("1999-07-01"));

The following figure shows the resulting chart:

Description of the illustration sequent.gif

4.4.3 Building a Sparse Series Chart

A sparse series chart is a chart where there is no data for some of the timestamps and the data cannot be mapped sequentially to the timestamps. For example, you may want the chart to display all of the months in a year although you do not have data for the months of February, June, July, and December. To create a sparse series chart, you use the setYSeriesSparse( ) method.

To label more timestamps than data values, you take the following steps:

1. Load the full range of timestamps. In the following example, the frequency-based setXSeries( ) method loads timestamps for each month of one year:

   MyAxisCh.setXSeries(Calendar.MONTH,
   
                      java.sql.Date.valueOf("2001-01-01"),
   
                      java.sql.Date.valueOf("2001-12-01"),
   
                       1);
   
   

2. Define an array of timestamps that map to the data values. The following example defines an array of 4 timestamps:

   java.sql.Date sparseTimestamps[] = {java.sql.Date.valueOf("2001-01-01"),
   
                                        java.sql.Date.valueOf("2001-02-01"),
   
                                        java.sql.Date.valueOf("2001-03-01"),
   
                                        java.sql.Date.valueOf("2001-11-01")
   
                                       };
   
   

3. Load the Y-axis series associated with the timestamps by using the setYSeriesSparse( ) method. In the following example, the array sparseValues contains 4 data values:

   double sparseValues[] = {10.0, 22.5, 6.0, 4.5};
   
    
   
   // Load the Y-axis series associated with the timestamps.
   
   MyAxisCh.setYSeriesSparse("series0", sparseTimestamps, sparseValues);
   
   

The following figure shows a chart displaying the sparse values:

Description of the illustration sparse.gif

Note that you use the setYSeriesSparse( ) method to construct mixed-frequency charts, as discussed in Section 4.1.5.