sas graphics for java examples using sas appdev studio and the output delivery system

SAS AppDev Studio contains both the older version of graph custom tags as well as the new versions.. It includes a brief how-to section on using webAF as an Interactive Development Envir

The correct bibliographic citation for this manual is as follows: Bohnenkamp, Wendy, and Jackie Iverson

2007 SAS ®

Graphics for Java: Examples Using SAS ®

AppDev Studio™ and the Output Delivery System Cary,

NC: SAS Institute Inc

SAS®

Graphics for Java: Examples Using SAS®

AppDev Studio™ and the Output Delivery System

Copyright © 2007, SAS Institute Inc., Cary, NC, USA

ISBN 978-1-59047-693-2

All rights reserved Produced in the United States of America

For a hard-copy book: No part of this publication may be reproduced, stored in a retrieval system, or

transmitted, in any form or by any means, electronic, mechanical, photocopying, or otherwise, without the prior written permission of the publisher, SAS Institute Inc

For a Web download or e-book: Your use of this publication shall be governed by the terms established by

the vendor at the time you acquire this publication

U.S Government Restricted Rights Notice: Use, duplication, or disclosure of this software and related

documentation by the U.S government is subject to the Agreement with SAS Institute and the restrictions set forth in FAR 52.227-19, Commercial Computer Software-Restricted Rights (June 1987)

SAS Institute Inc., SAS Campus Drive, Cary, North Carolina 27513

Acknowledgments ix

Introduction xi

Part 1 SAS AppDevStudio 1

Chapter 1 Getting Started with SAS AppDev Studio 3

1.1 Tag Libraries for SAS AppDev Studio 3 1.2 Getting Ready to Add Graphs to Your SAS AppDev Studio Project 8

1.3 Your Data 10

1.3.1 Tips and Information 11

Chapter 2 SAS AppDev Studio Custom Tags and Attributes for Basic Graphs 13

2.1 SAS AppDev Studio 2 Tags 15

2.1.1 sasads:Bar 15 2.1.2 sasads:Combination 16 2.1.3 sasads:Pie 16

2.1.4 sasads:Scatter 17 2.1.5 sasads:SegmentedBar 17

2.2 SAS AppDev Studio 3 Tags 18

2.2.1 sas:BarChart 18 2.2.2 sas:BarLineChart 19 2.2.3 sas:LineChart 20 2.2.4 sas:LinePlot 21 2.2.5 sas:PieChart 22 2.2.6 sas:RadarChart 23 2.2.7 sas:ScatterPlot 24

2.3 Common Attributes 25

Chapter 3 SAS AppDev Studio 3 Graph Model Tags 39

3.1 BarChartModel 40 3.2 BarLineChartModel 50 3.3 LineChartModel 64 3.4 LinePlotModel 67 3.5 PieChartModel 74 3.6 RadarChartModel 87 3.7 ScatterPlotModel 92

4.2 Legends 111

4.2.1 Corresponding Graph Models 113

4.3 Line Style Tags 113

4.3.1 Corresponding Graph Models 116

4.4 Text Style Tags 116

4.4.1 Corresponding Graph Models 117

4.5 AxisWallModel 118 4.6 BackgroundFillStyle 119

4.6.1 Corresponding Graph Models 122

4.7 DataElementStyle 123 4.8 DataTipModel 123 4.9 SubgroupLabelModel 124

Chapter 5 Supporting Tags 125

5.1 Fill Tags 126 5.2 Line Tags 130

5.2.1 AxisLineStyle, GridLineStyle, StrokeLineStyle, FrameLineStyle, and OutlineLineStyle

5.2.2 BasicStroke 133

5.3 Text Tags 133

5.3.1 Font 133 5.3.2 LabelTextStyle and ValueTextStyle 134 5.3.3 TextStyle 136

5.3.4 ShadowStyle 136

5.4 Tick Mark Tags 136 5.5 Miscellaneous Tags 137

5.5.1 DiscreteFillColor 137 5.5.2 MarkerStyle 137 5.5.3 ReferenceLineModel 140

Part 2 Output Delivery System 143

Chapter 6 Important Concepts for Getting Started with ODS and Java 145

6.1 Java Scriptlet Code 146 6.2 General JSP Structure 146 6.3 General JSP Requirements 148 6.4 Connecting and Data Extraction 148 6.5 A Few Last Notes about Data 151 Chapter 7 Creating Graphs 153

7.1 Types of Bar Charts 154

7.1.1 Horizontal Bar Charts 154 7.1.2 Vertical Bar Charts 155

7.2 Types of Pie Charts 156

7.2.1 Pie Charts 157 7.2.2 Donut Charts 158 7.2.3 Star Charts 159

7.3 Contour Plots 159 7.4 Types of Maps 160

7.4.1 Block Maps 160 7.4.2 Choropleth Maps 161 7.4.3 Prism Maps 162 7.4.4 Surface Maps 163

7.5 Types of Plots 163

7.5.1 Bubble Plots 164 7.5.2 Plots 165

7.6 Three-Dimensional Graphs 166

7.6.1 Scatter Plots 166 7.6.2 Surface Plots 167

Chapter 8 Parameters for Colors 169

Chapter 9 Parameters for Text 207

10.2 PROC GCONTOUR 268

10.2.1 Non-supported parameters 272

10.3 PROC GMAP 273

10.3.1 Summary 277 10.3.2 Non-supported parameters 278

10.4 PROC GPLOT 278

10.4.1 Summary 289 10.4.2 Non-supported parameters 289

10.5 PROC G3D 290

10.5.1 Summary 298 10.5.2 Non-supported parameters 298

Part 3 Putting It Together 299

Chapter 11 Final Reports 301

11.1 Report 1: Using SAS AppDev Studio 3 Tags 301 11.2 Report 2: Using ODS 307

11.3 Conclusions 310 Appendix A SAS/GRAPH Samples and WORK Data Sets 313 References 315

Index 317

Thanks to Aimee for inspiration, Andrew for support, Jackie for courage, Mom for believing, and the readers for their interest

Wendy Bohnenkamp

Until I started this, I never knew just how much time and effort go into writing a book This is hard work, and I first have to say thank you to Wendy for putting up with me as a writing partner Without her knowledge, skill, and drive, this book would never have been finished Next, I need to thank my family for their encouragement and support And finally, I have to say thanks to the people who buy this book If the examples in this book make their job easier, then it will have been worth the effort

Jackie Iverson

The idea for this book started glimmering every time we would lament to each other about the lack of good examples The conversation always ended with “someone should write a book.”

This book is intended to be that source for examples We walk you though the basics and help to get you familiar with things that may be new to you or new to SAS®9 The book can be used by programmers at all experience levels

This book covers only the graph objects in SAS AppDev Studio, and it is assumed that you already know how to use SAS AppDev Studio to create and deploy a JavaServer Page (JSP) or servlet application A basic level of SAS ODS programming knowledge is also needed to understand the example code in Part 2

SAS®9 and SAS AppDev Studio 3 were released while we were writing this book All examples have been tested on SAS®9 SAS AppDev Studio contains both the older version of graph custom tags as well as the new versions Therefore we briefly cover version 2 tags, but concentrate more on the version 3 tags

There are many parameters and attributes to cover, so the intent is to provide a reference tool to help you build your own graphs We’ve focused on what we feel are the two main ways programmers are using SAS®9 to create graphs using Java

There are four main sections to this book The first is what you are reading now Just a

“Hi how are you?” and a “Here’s the intent of this book.” The second section covers webAF and SAS AppDev Studio It includes a brief how-to section on using webAF as

an Interactive Development Environment (IDE) and briefly discusses SAS AppDev Studio 2 tags and their options Then it covers the tags and the nesting properties of SAS AppDev Studio 3 tags The third section is intended for SAS programmers who want to

do some reporting but who are not that familiar with custom tags This section covers using Output Delivery System (ODS) statements and the Java Device Driver to create graphs Then we wrap everything up in the fourth section to include reference and appendix materials

This book is not intended to give you all the answers to all the questions about SAS graphs It is also not a “best practice” type of cookbook We are merely trying to put together a reference volume that enables you to see what you can and cannot do to make your graphs more visually appealing For instance, when you are combining ODS and JSP files, you get a very diverse environment We have decided to simplify our examples

by putting everything in a single JSP instead of using servlets, macros, stored processes, etc We wanted to focus on the attributes, parameters, and options that make graphs convey what you really want them to convey

Because we are focusing on the look of the graph, we chose data that helped to illustrate the specific graph attribute This produced graphs that may not represent a real world situation So don’t get hung up on trying to analyze the graph; just look at what it is trying to show Appendix A contains data layouts of the SAS samples and WORK data sets that were used to produce the graphs Most of the time we used data sets from the SAS/GRAPH samples library to make it easy for you to reproduce the graph Part 3,

“Putting It Together,” explains where to find the sample data sets If we had to create or modify the data to get a particular attribute to show more clearly, we included the SAS code in Appendix A

Each sample that produces output has been tested in our local development environment

We have tried to provide you with information on what works and what may not We included things that did not work for us, because in your environment or in future updates they could If you see an option or parameter that you like, give it a try SAS offers many opportunities for creativity We hope to give you a jump start on the path to great graphs Ready to tackle those SAS graphs?

P a r t 1

SAS AppDev Studio

Chapter 1 Getting Started with SAS AppDev Studio 3

Chapter 2 SAS AppDev Studio Custom Tags and Attributes for Basic Graphics 13

Chapter 3 SAS AppDev Studio 3 Graph Model Tags 39

Chapter 4 Nested Tags for Graph Models 99

Chapter 5 Supporting Tags 125

C h a p t e r 1

Getting Started with SAS AppDev Studio

1.1 Tag Libraries for SAS AppDev Studio 3

1.2 Getting Ready to Add Graphs to Your SAS AppDev Studio Project 8 1.3 Your Data 10

1.3.1 Tips and Information 11

1.1 Tag Libraries for SAS AppDev Studio

In this section we are going to look at creating graphs in a JavaServer Page (JSP) using the SAS Custom Tag Library This tag library comes with the SAS AppDev Studio product, which includes webAF as the development environment tool You can use webAF or another Java Interactive Development Environment (IDE), such as Eclipse, to utilize the tag libraries and API components that come with SAS AppDev Studio

SAS AppDev Studio 2.x and SAS AppDev Studio 3 use separate tag libraries SAS

AppDev Studio 3 introduced some major enhancements to the graphics components We’ll look at the most commonly used graphs in each version

The easiest way to add graphs to your JSP or servlet project in SAS AppDev Studio is to

use the Component Palette The graph components are on the Graphics tab You can

change the palette by clicking the down arrow on the toolbar title bar

We will be working with graphs on the SAS JSP/Servlet (Version 3) and SAS

JSP/Servlet (Version 2) palettes

The version 2 tag library is part of SAS AppDev Studio 3 When you create a new SAS AppDev Studio 3 project, you can choose to include the version 2 tag library so that these tags are available in the component palette

When you upgrade an existing webAF 2 project to use webAF 3 components, your old SAS AppDev Studio 2 tags (which have a sasads prefix) will still be in your project and will not be automatically updated to SAS AppDev Studio 3 tags (with a sas prefix) In other words, if you have a sasads:Bar chart in your project, it will not automatically be converted to a sas:BarChart if you move to webAF 3

Here is an overview and comparison of the graphs available in both versions Remember that sasads tags are from SAS AppDev Studio 2, whereas sas tags are from the more

recent SAS AppDev Studio 3

sasads:Bar sas:BarChart

Here is a direct comparison of the default bar charts Notice that the default for

sasads:Bar is a three-dimensional chart, whereas the sas:BarChart is two-dimensional Both have several options that can enhance the appearance

sasads:SegmentedBar

The sasads:SegmentedBar tag really does not have

an equivalent in SAS AppDev Studio 3 However, you can mimic this graph by using the various model attributes with the sas:BarChart tag

sasads:Combination

The sasads:Combination tag can be used in several different ways to perform similarly to a

sas:BarLineChart, sas:LineChart, or sas:ScatterChart tag

sas:BarLineChart

This sas:BarLineChart tag has no direct partner in SAS AppDev Studio 2 tags

sas:LineChart

In SAS AppDev Studio 3, line charts can

be created using the sas:LineChart tag In SAS AppDev Studio 2, you might consider using the sasads:Combination tag

sasads:Pie sas:PieChart

As with the bar charts, sasads:Pie defaults to a three-dimensional chart, and sas:PieChart

is two-dimensional Both charts have loads of options to create a number of different looks Additionally, the sas:PieChart tag can create a donut and subgroup data into concentric rings

sasads:Scatter sas:ScatterPlot

SAS AppDev Studio 2 includes the sasads:Scatter tag The equivalent tag in SAS

AppDev Studio 3 is sas:ScatterPlot

sas:LinePlot

The sas:LinePlot tag could be compared

to the previously shown SAS AppDev Studio 2 sasads:Combination tag

sas:RadarChart

The sas:RadarChart tag is a brand-new graph type for SAS AppDev Studio 3

1.2 Getting Ready to Add Graphs to Your

SAS AppDev Studio Project

There are a couple of things you need to consider before you can add graphs to your project One is how to connect to the data In your development environment, everything

is local and easy to get to, but in normal production environments that usually isn’t the case You need to plan your strategy for accessing your SAS server Is security an issue? How many people will be accessing this application? How many people at the same time might need to grab the same data? All these questions should be discussed with both the Web server and SAS server administrators These administrative roles may be filled by the same person or by people from different groups Either way, you must plan and coordinate with them There are so many variables and combinations of system setup that

we can’t cover all of them in this book

For this book, we’ve taken a simple approach and used a basic Java Database

Connectivity (JDBC) connection for SAS AppDev Studio 3 tags and SAS/CONNECT for all others If you need something more elaborate for your environment, review the SAS documentation for SAS Integration Technologies This resource will help you make decisions on setting up security, pooling, connection types, etc

Now that you have the connection, the next step is to create data models Data models allow you to shape the data for graphing For instance, you might need to sort the data alphabetically or by increasing values Data models can also specify the columns, subset the data, and perform other functions

In SAS AppDev Studio 2, one common method is to use a sasads:DataSet tag This allows us to use the connection, specify the data, and shape it Here’s an example:

<sasads:DataSet connection="bbuConnection" dataSet="samples.grains" id="dsBar" scope="session" displayedColumns="country amount" />

In this example, we use the bbuConnection object to connect to our SAS server Then the dataSet attribute is used to define the data set we want to use Here we are using the Grains data set from the Samples library Then, to help shape the data, we use the

displayedColumns attribute This allows us to specify only the columns we will be

needing for the graph

When using the SAS AppDev Studio 3 tags, we need to use different types of models These may seem more complicated than simply using the sasads:DataSet tag, but they are more flexible For sas:BarChart you use a

com.sas.graphics.components.barchart.BarChartTableDataModel Here’s an example:

<jsp:useBean id="barChartTableDataModel1" scope="session"

class="com.sas.graphics.components.barchart.BarChartTableDataModel"> <jsp:setProperty name="barChartTableDataModel1" property="model" value="<%=jdbcTableModelAdaptor%>" />

</jsp:useBean>

<%

barChartTableDataModel1.setCategoryVariable(

new com.sas.graphics.components.ClassificationVariable("COUNTRY")); barChartTableDataModel1.setResponseVariable(

new com.sas.graphics.components.AnalysisVariable("AMOUNT"));

%>

This snippet of code shows the configuration of a data model It references a

JDBCTableModelAdapter and sets properties for the data model, such as the category and response variables to use See Chapter 11, “Final Reports,” for a complete example with SAS AppDev Studio 3 tags

1.3 Your Data

When you are using SAS data sets in SAS graphs, there are specific terms used to describe the types of variables For instance, you may think in terms of an X axis and Y axis However, because we are looking at statistical or computed variable data, most of the time each variable has a role On the X axis you may actually be charting data by a category variable Below are some terms that may help you along the way

Discrete variables

Variables that contain a finite number of specific values that are represented on the chart For example, years, geographical areas, and company divisions are discrete variables

Used in plots (vertical) to identify the depth variable

For more information on terminology and graphing basics, see the SAS OnlineDoc documentation

1.3.1 Tips and Information

Here are a few tips on how to organize your data for maximum performance

ƒ Usually, you should presummarize large data sets to improve performance

ƒ If you have a large number of different categories, you might want to subset or group the data to control the number of bars or pie slices shown in the chart Depending on the size of your chart, it is easy to get so many bars that you cannot read the labels

ƒ When there are too many values to represent in a pie chart, the smaller values are automatically grouped into one slice labeled “Other.” By creating your own

“Other” grouping, you can prevent a smaller, but important, category from being hidden

ƒ When you are accessing SAS data, the system often puts a lock on the data set you are using For this reason, be sure to close all connection to the data once you are done Or consider making your connection read-only and investigate how to set up workspace pooling or connection sharing techniques

In short, the saying “Garbage in, garbage out” is so true You need to be careful of how your data is constructed and formatted before you base critical decisions on your output

C h a p t e r 2

SAS AppDev Studio Custom Tags and

Attributes for Basic Graphs

2.1 SAS AppDev Studio 2 Tags 15

2.1.1 sasads:Bar 15 2.1.2 sasads:Combination 16 2.1.3 sasads:Pie 16

2.1.4 sasads:Scatter 17 2.1.5 sasads:SegmentedBar 17 2.2 SAS AppDev Studio 3 Tags 18

2.2.1 sas:BarChart 18 2.2.2 sas:BarLineChart 19 2.2.3 sas:LineChart 20 2.2.4 sas:LinePlot 21 2.2.5 sas:PieChart 22 2.2.6 sas:RadarChart 23 2.2.7 sas:ScatterPlot 24 2.3 Common Attributes 25

SAS AppDev Studio gives the user a number of graphing custom tags to use with JSP pages The tags available in SAS AppDev Studio 2 have been updated in SAS AppDev Studio 3 Although SAS AppDev Studio 2 tags are easier to use because they are not nested, they are limited in what they can and cannot display You might be tempted at first to run with the SAS AppDev Studio 2 tags, but once you get the hang of SAS AppDev Studio 3 tags, we think you’ll jump right in with both feet

In general, the standard convention for SAS AppDev Studio 3 tags looks like this:

<sas:BarChart id="bbuSASBarChart" model="barChartTableDataModel1" scope="session" >

</sas:BarChart>

However, if there are no nested tags, you could use the following convention The difference is that the tag is closed using a single backslash at the end of the invocation of the tag

<sas:BarChart id="bbuSASBarChart" model="barChartTableDataModel1" scope="session" />

Be very careful not to use both conventions at the same time If you accidently use /> and then have nested tags, the compiler won’t recognize the nested tags as being part of that tag group

If you need to nest tags, use the following convention and insert the nested tags where shown

<sas:BarChart id="bbuSASBarChart" model="barChartTableDataModel1" scope="session" >

<nestedTag - enter any valid nested tags here>

</nestedTag>

</sas:BarChart>

Each graph tag has three required attributes The id attribute gives the object a name Each object in your scope must have a unique identifier or name The model attribute specifies the data model The scope attribute defines the limit of the object’s availability, such as session, request, page, or application

<sas:BarChart id="bbuSASBarChart" model="barChartTableDataModel1" scope="session" >

</sas:BarChart>

2.1 SAS AppDev Studio 2 Tags

The following graph examples illustrate the basics of the different graphing custom tags available from SAS AppDev Studio 2 These older tags are still available with SAS AppDev Studio 3 However, as stated before, you might want to convert to the newer SAS AppDev Studio 3 tags The main difference in syntax between the two is the prefix used for the tags The prefix “sasads:” denotes AppDev Studio 2 tags, whereas “sas:” denotes SAS AppDev Studio 3 tags

2.1.1 sasads:Bar

To create a bar chart using the SAS AppDev Studio 2 tags, use the sasads:Bar tag

<sasads:Bar id="bbuBar" model="dsBar" scope="session" />

The sasads:Pie tag creates a pie chart

<sasads:Pie id="bbuPie" model="dsBar" scope="session" />

responseVariableName, and subGroupVariableName

<sasads:SegmentedBar id="bbuSegmentedBar" model="dsBar"

scope="session"

categoryVariableName="year" responseVariableName="amount"

subGroupVariableName="country" />

2.2 SAS AppDev Studio 3 Tags

In SAS AppDev Studio 2, you only need a DataSetInterface or sasads:DataSet tag to define your data However, with SAS AppDev Studio 3, each chart type can be built using its own data model Therefore, in each example of a basic graph we have included the code that builds the table data model for each graph type For instance, with the sas:BarChart tag the corresponding table data model is the

com.sas.graphics.components.barchart.BarChartTableDataModel class Using this code allows you to customize your data more than you can by using the sasads:DataSet tag

2.2.1 sas:BarChart

The sas:BarChart tag creates a basic bar chart By customizing the table data model, you can also transform the basic bar chart into a stacked bar chart

to represent different subgroups of data

<jsp:useBean id="barChartTableDataModel1" scope="session"

class="com.sas.graphics.components.barchart.BarChartTableDataModel"> <jsp:setProperty name="barChartTableDataModel1" property="model"

2.2.2 sas:BarLineChart

The sas:BarLineChart tag can create bar charts that have a corresponding line chart attached This enables you

to see two different types of data per category

<jsp:useBean id="barLineChartTableDataModel1" scope="session"

2.2.3 sas:LineChart

The sas:LineChart tag creates a line chart A line chart shows the relationship of one variable to another Typically these variables have only one corresponding value on the vertical axis This type of chart is best suited to business-oriented graphs that plot values against other discrete categorical values

<jsp:useBean id="lineChartTableDataModel1" scope="session"

2.2.5 sas:PieChart

The newer sas:PieChart tags can create three-dimensional pie charts, ringed pie charts, and donut charts Section 3.5 explains how to use attributes to create the various types of pie charts

<jsp:useBean id="pieChartTableDataModel1" scope="session"

class="com.sas.graphics.components.piechart.PieChartTableDataModel"> <jsp:setProperty name="pieChartTableDataModel1" property="model"

2.2.6 sas:RadarChart

The sas:RadarChart tag is new to SAS AppDev Studio The spokes that radiate from the center of the chart can be used to show the frequency of data measures These charts are often used in quality control and market research

<jsp:useBean id="radarChartTableDataModel1" scope="session"

2.2.7 sas:ScatterPlot

You can create a scatter plot using the sas:ScatterPlot tag Scatter plots show a relationship between one variable and another They can be very helpful in revealing trends in the data

<jsp:useBean id="scatterPlotTableDataModel1" scope="session"

2.3 Common Attributes

The following are common attributes that affect the look and feel of SAS AppDev Studio

3 graph tags These attributes can be applied to any of the base level graph tags For each attribute we review the code that creates the output as well as the HTML that is

generated This way if you are familiar with HTML it will give you some idea of how the output is constructed

alignment

To adjust the alignment of a chart within the page you can use the alignment attribute

Valid values:

Top Bottom Middle Left Right

<sas:BarChart id="bbuSASBarChart" model="barChartTDM1" scope="session" alignment="RIGHT" >

</sas:BarChart>

This attribute is applied to the HTML image tag, so it does little to adjust the alignment

on a page by itself You can insert this tag into a HTML table to position the graph on the page

<img name="bbuSASBarChart1" id="bbuSASBarChart1"

alternateText

The alternateText attribute enables you to define text that is displayed when the user hovers over graph areas where data points do not exist, such as the axis areas and labels In the HTML source, this text is defined by the alt attribute applied to the <img> HTML tag

Once this code is rendered, the compiled HTML code looks similar to this:

<img name="bbuSASBarChart" id="bbuSASBarChart"

src="http://localhost:8080/BBU/StreamContentServlet;

jsessionid=0D27E1E4DC8ED61495903F9C4BE9E9DC?

CONTENT_KEY=bbuSASBarChart&SRCID=50196" galleryimg="no"

alt="Alternate Text when Hovering" usemap="#bbuSASBarChart"

width="400" height="300" border="0"/>

Valid values:

Autumn Bright Carnival Commerce Grayscale Industry Magellan Neon Ocean Pastel Picnic Pine Terra Wheat Woodland

<sas:PieChart id="bbuSASPieChart" model="pieChartTDM1"

scope="request"

appliedColorSchemeName="Carnival" >

</sas:PieChart>