gpl reference guide

7/22/2019 GPL Reference Guide

1/149

i

GPL Reference Guide


2/149

For more information about SPSS software products, please visit our Web site athttp://www.spss.com or contact

SPSS Inc.233 South Wacker Drive, 11th FloorChicago, IL 60606-6412Tel: (312) 651-3000Fax: (312) 651-3668

SPSS is a registered trademark and the other product names are the trademarksof SPSS Inc.for its proprietary computer software. No material describing such software may be producedor distributed without the written permission of the owners of the trademark and license rightsin the software and the copyrights in the published materials.

The SOFTWARE and documentation are provided with RESTRICTED RIGHTS. Use,duplication, or disclosure by the Government is subject to restrictions as set forth in subdivision(c) (1) (ii) of The Rights in Technical Data and Computer Software clause at 52.227-7013.Contractor/manufacturer is SPSS Inc., 233 South Wacker Drive, 11th Floor, Chicago, IL60606-6412.

General notice: Other product names mentioned herein are used for identification purposes onlyand may be trademarks of their respective companies.

TableLook is a trademark of SPSS Inc.Windows is a registered trademark of Microsoft Corporation.DataDirect, DataDirect Connect, INTERSOLV, and SequeLink are registered trademarks ofDataDirect Technologies.Portions of this product were created using LEADTOOLS 1991-2000, LEAD Technologies,Inc. ALL RIGHTS RESERVED.LEAD, LEADTOOLS, and LEADVIEW are registered trademarks of LEAD Technologies, Inc.Portions of this product were based on the work of the FreeType Team (http://www.freetype.org).

A portion of the SPSS software contains zlib technology. Copyright 1995-2002 by Jean-loupGailly and Mark Adler. The zlib software is provided as-is, without express or impliedwarranty. In no event shall the authors of zlib be held liable for any damages arising from theuse of this software.

A portion of the SPSS software contains Sun Java Runtime libraries. Copyright 2003 by SunMicrosystems, Inc. All rights reserved. The SunJava Runtime libraries include code licensedfrom RSA Security, Inc. Some portions of the libraries are licensed from IBM and are available athttp://oss.software.ibm.com/icu4j/. Sun makes no warranties to the software of any kind.

GPL Reference GuideCopyright 2005 by SPSS Inc.All rights reserved.Printed in the United States of America.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in anyform or by any means, electronic, mechanical, photocopying, recording, or otherwise, withoutthe prior written permission of the publisher.


3/149

Contents

1 Introduction to GPL 1

Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Brief Overview of GPL Algebra. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

How Coordinates and the Algebra Interact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Statement and Function Reference 11

Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11GRAPH Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

SOURCE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

DATA Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

TRANS Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

SCALE Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

COORD Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

GUIDE Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

ELEMENT Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

base Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

base.aesthetic Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

base.all Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

base.coordinate Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

begin Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

bin.dot Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

bin.quantile.letter Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

bin.rect Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

binCount Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

binStart Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

binWidth Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

closed Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

cluster Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

col Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45collapse Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

color Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

color.brightness Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

color.hue Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

color.saturation Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

csvSource Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

iii


4/149

dataMinimum Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

dataMaximum Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

delta Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

end Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53eval Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

exclude Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

exponent Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

gridlines Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

In Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

include Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

jump Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

label Function (For Graphic Elements) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

label Function (For Guides) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

map Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

max Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

min Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

missing.gap Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

missing.interpolate Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

missing.wings Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

notIn Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

origin Function (For Graphs). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

origin Function (For Scales) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

position Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

preserveStraightLines Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

reflect Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

region.confi.smooth Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

region.spread.confi Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66region.spread.range Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

region.spread.sd Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

region.spread.se Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

reverse Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

scale Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

shape Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

size Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

smooth.cubic Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

smooth.linear Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

smooth.loess Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

smooth.mean Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

smooth.spline Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77smooth.step Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

smooth.quadratic Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

sort.data Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

sort.natural Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

sort.statistic Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

iv


5/149

sort.values Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

split Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

start Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

startAngle Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82summary.count Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

summary.count.cumulative Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

summary.max Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

summary.min Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

summary.mean Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

summary.percent Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

summary.percent.cumulative Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

summary.sum Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

summary.sum.cumulative Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

texture.pattern Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

ticks Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

transparency Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

transpose Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

userSource Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

values Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

3 Examples 97

Using the Examples in Your Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Summary Bar Chart Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Simple Bar Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Simple Bar Chart of Counts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Simple Horizontal Bar Chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Simple Bar Chart With Error Bars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Simple Bar Chart with Bar for All Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Stacked Bar Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Clustered Bar Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Clustered and Stacked Bar Chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Bar Chart Using an Evaluation Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Paneled Bar Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

3-D Bar Chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Error Bar Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Histogram Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Histogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Frequency Polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Stacked Histogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Cumulative Histogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

v


6/149

High-Low Chart Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Simple Range Bar for One Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Simple Range Bar for Two Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

High-Low-Close Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Scatter/Dot Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Simple 1-D Scatterplot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Simple 2-D Scatterplot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Simple 2-D Scatterplot with Fit Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Grouped Scatterplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Scatterplot Matrix (SPLOM). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Bubble Plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Scatterplot with Border Histograms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Scatterplot with Border Boxplots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Dot Plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

2-D Dot Plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Line Chart Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Simple Line Chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Simple Line Chart with Points. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Line Chart of Date Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Line Chart With Step Interpolation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Fit Line. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Line Chart from Equation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Line Chart with Separate Scales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Line Chart in Parallel Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Pie Chart Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Pie Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Paneled Pie Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Boxplot Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

1-D Boxplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Boxplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Boxplot With Overlaid Dot Plot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Multi-Graph Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Scatterplot with Border Histograms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Scatterplot with Border Boxplots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Stocks Line Chart with Volume Bar Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Histogram with Dot Plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

vi


7/149

Appendix

A GPL Constants 135

Color Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Shape Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Size Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Pattern Constants. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Bibliography 137

Index 138

vii


8/149


9/149

ChapterIntroduction to GPL

The Graphics Production Language (GPL) is a language for creating graphs. It is a concise

and flexible language based on the grammar described in The Grammar of Graphics. Rather

than requiring you to learn commands that are specific to different graph types, GPL provides a

basic grammar with which you can build any graph. For more information about the theory that

supports GPL, seeThe Grammar of Graphics, 2nd Edition(Wilkinson, 2005).

Following is a GPL example that creates a simple bar chart. A summary of the GPL follows

the picture.

Note:To run the examples that appear in the GPL documentation, they must be incorporated into

the syntax specific to your application. For more information, see Using the Examples in Your

Applicationin Chapter 3 on p. 97.

Figure 1-1GPL for a simple bar chart

SOURCE: s=userSource(id("Employeedata"))

DATA: jobcat=col(source(s), name("jobcat"), unit.category())

DATA: salary=col(source(s), name("salary"))

SCALE: linear(dim(2), include(0))

GUIDE: axis(dim(2), label("Mean Salary"))

GUIDE: axis(dim(1), label("Job Category"))

ELEMENT: interval(position(summary.mean(jobcat*salary)))

Figure 1-2Simple bar chart

1


10/149

2

Chapter 1

Each line in the example is a statement. One or more statements make up a block of GPL. Each

statement specifies an aspect of the graph, such as the source data, relevant data transformations,

coordinate systems, guides (for example, axis labels), graphic elements (for example, points and

lines), and statistics.

Statements begin with a labelthat identifies the statement type. The label and colon (:) that

follow it are the only items that delineate the statement. No other characters are needed, so

multiple statements can appear on one line. Note that all quotes must be quotation marks. You

cannot use single quotes in GPL.

Consider the statements in the example:

SOURCE. This statement specifies the file or dataset that contains the data for the graph. In the

example, it identifies userSource, which is a data source defined by the application that is

calling the GPL. The data source could also have been a comma-separated values (CSV) file.

DATA. This statement assigns a variable to a column or field in the data source. In the

example, theDATAstatements assignjobcatandsalaryto two columns in the data source. The

statement identifies the appropriate columns by using thenamefunction. The strings passed tothe namefunctioncorrespond to variable namesin the userSource. These could also be the

column header strings that appear in the first line of a CSV file. Note that jobcatis defined as

a categorical variable. If a measurement level is not specified, it is assumed to be continuous.

SCALE. This statement specifies the type of scale for the graph dimensions and the range for

the scale, among other options. In the example, it specifies a linear scale on the second

dimension (they axis in this case) and indicates that the scale must include 0. Linear scales

do not necessarily include 0, but many bar charts do. Therefore, its explicitly defined.

GUIDE. This statement handles all of the aspects of the graph that arent directly tied to the

data but help to interpret the data, such as axis labels and reference lines. In the example, the

GUIDEstatements specify labels for the xand y axes. An axis is identified by a dim function.

The first two dimensions of any graph are the xand y axes.

ELEMENT. This statement identifies the graphic element type, variables, and statistics. The

example specifiesinterval, which creates the bars in the graph. position()specifies the

location of the bars. These appear at each category in the jobcat, and the height of the bars is

the mean ofsalaryfor each job category. The contents ofposition()use GPL algebra. For

more information, seeBriefOverview of GPL Algebraon p. 3.

Details about all of the statements and functions appear in Statement and Function Reference

on p. 11.

Concepts

This section contains conceptual information about GPL. Although the information is useful forunderstanding GPL, it may not be easy to grasp unless you first review some examples. You can

find examples in Exampleson p. 97.


11/149

3

Introduction to GPL

Brief Overview of GPL Algebra

Before you can use all of the functions and statements in GPL, it is important to understand

its algebra. The algebra determines how data are combined to specify the position of graphicelements in the graph. That is, the algebra defines the graph dimensions or the data frame in

which the graph is drawn. For example, the frame of a basic scatterplot is specified by the values

of one variable crossed with the values of another variable. Another way of thinking about the

algebra is that it identifies the variables you want to analyze in the graph.

The GPL algebra can specify only one variable. However, if it includes more than one variable,

you must use one of the following operators:

Cross (*). The cross operator crosses all of the values of one variable with all of the values

of another variable. A result exists for every case (row) in the data. The cross operator

is the most commonly used operator. It is used whenever the graph includes more than

one axis, with a different variable on each axis. Each variable on each axis is crossed with

each variable on the other axes (for example, A*B results in A on thexaxis and B on the y

axis when the coordinate system is 2-D). Crossing can also be used for paneling (faceting)

when there are more crossed variables than there are dimensions in a coordinate system.

That is, if the coordinate system were 2-D rectangular and three variables were crossed, the

last variable would be used for paneling (for example., with A*B*C, C is used for paneling

when the coordinate system is 2-D).

Nest (/). The nest operator nests all of the values of one variable in all of the values of another

variable. The difference between crossing and nesting is that a result exists only when there is

a corresponding value in the variable that nests the other variable. Nesting always results in

paneling, regardless of the coordinate system.

Blend (+). The blend operator combines all of the values of one variable with all of the values

of another variable. For example, you may want to combine two salary variables on one axis.Blending is often used for repeated measures, as in salary2004+salary2005.

Crossing and nesting add dimensions to the graph specification. Blending combines the values

into one dimension. How the dimensions are interpreted and drawn depends on the coordinate

system. SeeHow Coordinates and the Algebra Interact on p. 5 for details about the interaction

between the coordinate system and the algebra.

Rules

Like elementary mathematical algebra, GPL algebra is associative and distributive. That is:

(X*Y)*Z = X*(Y*Z)

(X/Y)/Z = X/(Y/Z)

(X+Y)+Z = X+(Y+Z)

X*(Y+Z) = X*Y+X*Z

X/(Y+Z) = X/Y+X/Z

However, GPL algebra is not commutative.


12/149

4

Chapter 1

Operator Precedence

The nest operator takes precedence over the other operators, and the cross operator takes

precedence over the blend operator. Like mathematical algebra, the precedence can be changed

by using parentheses. You will almost always use parentheses with the blend operator because

you will want to blend the variables before crossing or nesting the result with other variables. :

(A+B)*C

Unity Variable

The unity variable (indicated by 1) is a placeholder in the algebra. When a scale is created for the

unity variable, unity is located in the middle of the scale but no other values exist on the scale.

The unity variable is needed only when there is no explicit variable in a specific dimension and

you need to include the dimension in the algebra.

For example, assume a 2-D rectangular coordinate system. If you are creating a graph showing

the count in eachjobcatcategory,summary.count(jobcat)appears in the GPL specification.

Counts are shown along the y axis, but there is no explicit variable in that dimension. If you want

to panel the graph, you need to specify something in the second dimension before you can include

the paneling variable. Thus, if you want to panel the graph by columns using gender, you need

to change the specification to summary.count(jobcat*1*gender). If you want to panel by

rows instead, there would be another unity variable to indicate the missing third dimension. The

specification would change to summary.count(jobcat*1*1*gender).

User Constants

The algebra can also include user constants, which are quoted string values (for example.,

"2005"). When a user constant is included in the algebra, it is like adding a new variable, withthe variables value equal to the constant for all cases. The effect of this depends on the algebra

operators and the function in which the user constant appears.

In the positionfunction, the constants can be used to create separate scales. For example, in

the following GPL, two separate scales are created for the paneled graph. By nesting the values

of each variable in a different string and blending the results, two different groups of cases with

different scale ranges are created.

ELEMENT: line(position(date*(calls/"Calls"+orders/"Orders")))

Constants can also be used in thepositionfunction to create a category of all cases when the

constant is blended with a categorical variable. Remember that the value of the user constant is

applied to all cases, so thats why the following works:

ELEMENT: interval(position(summary.mean((jobcat+"All")*salary)))

Aesthetic functions can also take advantage of user constants. Blending variables creates multiple

graphic elements for the same case. To distinguish each group, you can mimic the blending in the

aesthetic functionthis time with user constants.

ELEMENT: point(position(jobcat*(salbegin+salary), color("Beginning"+"Current")))


13/149

5

Introduction to GPL

User constants are not required to create most charts, so you can ignore them in the beginning.

However, as you become more proficient with GPL, you may want to return to them to create

custom graphs.

How Coordinates and the Algebra Interact

The algebra defines the dimensions of the graph. Each crossing results in an additional dimension.

Thus,gender*jobcat*salaryspecifies three dimensions. How these dimensions are drawn

depends on the coordinate system and any functions that may modify the coordinate system.

Some examples may clarify these concepts. The relevant GPL statements are shown, with a

link to expand the full specification.

1-D Graph

COORD: rect(dim(1))

ELEMENT: point(position(salary))

Full Specification


DATA: salary = col(source(s), name("salary"))

COORD: rect(dim(1))

GUIDE: axis(dim(1), label("Salary"))

ELEMENT: point(position(salary))

Figure 1-3Simple 1-D scatterplot

The coordinate system is explicitly set to one-dimensional, and only one variable appears

in the algebra.

The variable is plotted on one dimension.

2-D Graph

ELEMENT: point(position(salbegin*salary))


14/149

6

Chapter 1

Full Specification


DATA: salbegin=col(source(s), name("salbegin"))

DATA: salary=col(source(s), name("salary"))GUIDE: axis(dim(2), label("Current Salary"))

GUIDE: axis(dim(1), label("Beginning Salary"))


Figure 1-4Simple 2-D scatterplot

No coordinate system is specified, so it is assumed to be 2-D rectangular.

The two crossed variables are plotted against each other.

Another 2-D Graph

ELEMENT: interval(position(summary.count(jobcat)))

Full Specification




GUIDE: axis(dim(2), label("Count"))


ELEMENT: interval(position(summary.count(jobcat)))


15/149

7

Introduction to GPL

Figure 1-5Simple 2-D bar chart of counts


Although there is only one variable in the specification, another for the result of the count

statistic is implied (percent statistics behave similarly). The algebra could have been written

as jobcat*unity.

The variable and the result of the statistic are plotted.

A Paneled 2-D Graph

ELEMENT: interval(position(summary.mean(jobcat*salary*gender)))

Full Specification



DATA: gender=col(source(s), name("gender"), unit.category())



GUIDE: axis(dim(3), label("Gender"))



ELEMENT: interval(position(summary.mean(jobcat*salary*gender)))


16/149

8

Chapter 1

Figure 1-6Paneled 2-D bar chart


There are three variables in the algebra, but only two dimensions. The last variable is used for

paneling (also known as faceting).

The first variable is plotted against the result of the summary statistic calculated on the second

variable for each category in the paneling variable.

A 3-D Graph

COORD: rect(dim(1,2,3))

ELEMENT: interval(position(summary.mean(jobcat*gender*salary)))

Full Specification








GUIDE: axis(dim(2), label("Gender"))




17/149

9

Introduction to GPL

Figure 1-73-D bar chart

The coordinate system is explicitly set to three-dimensional, and there are three variablesin the algebra.

The three variables are plotted on the available dimensions.

Note that the variable being analyzed appears as the third dimension in the algebra when

using a 3-D coordinate system (its the second dimension in a 2-D system).

A Clustered Graph

COORD: rect(dim(1,2), cluster(3))

ELEMENT: interval(position(summary.mean(gender*salary*jobcat)), color(gender))

Full Specification











18/149

10

Chapter 1

Figure 1-8Clustered 2-D bar chart

The coordinate system is explicitly set to two-dimensional, but it is modified by theclusterfunction.

Theclusterfunction indicates that clustering occurs along dim(3), which is the dimension

associated withjobcatbecause it is the third variable in the algebra.

The variable in dim(1) identifies the variable whose values determine the bars in each cluster.

This is gender.

The variables are plotted using the modified coordinate system. Note that the graph would be

a paneled graph if you removed the clusterfunction. The charts would look similar and

show the same data, but their coordinate systems would differ.


19/149

ChapterStatement and Function Reference

This section provides detailed information about the various statements that make up GPL and the

functions that you can use in each of the statements.

Statements

There are general categories of GPL statements.

Data definition statements. Data definition statements specify the data sources, variables, and

optional variable transformations. All GPL code blocks include at least two data definition

statements: one to define the actual data source and one to specify the variable extracted from

the data source.

Specification statements. Specification statements define the graph. They define the axis scales,

coordinates systems, text, graphic elements (for example., bars and points), and statistics. All

GPL code blocks require at least one ELEMENTstatement, but the other specification statements

are optional. GPL uses a default value when the SCALE, COORD, and GUIDEstatements are

not included in the GPL code block.

Control statements. GPL currently includes one control statement. The GRAPHstatement allows

you to group multiple graphs in a single page display. For example, you may want to addhistograms to the borders on a scatterplot.

Data Definition Statements

SOURCE Statement,DATA Statement,TRANS Statement

Specification Statements

SCALE Statement,COORD Statement,GUIDE Statement,ELEMENT Statement,GRAPH

Statement

GRAPH Statement

Syntax

GRAPH:

. A function for specifying the GRAPHstatements that mark the beginning and end of

the individual graph.

11


20/149

12

Chapter 2

Description

This statement is optional. Its needed only when you want to group multiple graphs in a single

page display or you want to customize a graphs size. TheGRAPHstatement is essentially a

wrapper around the GPL that defines a particular graph. There is no limit to the number of

graphs that can appear in a GPL block.

Grouping graphs is useful for related graphs, like graphs on the borders of histograms.

However, the graphs do not have to be related. You may simply want to group the graphs for

presentation.

Examples

Figure 2-1Scaling a graph

GRAPH: begin(scale(50%,50%))

Figure 2-2Example: Scatterplot with border histograms

GRAPH: begin(origin(10.0%, 20.0%), scale(80.0%, 80.0%))


GRAPH: end()


ELEMENT: interval(position(summary.count(bin.rect(salbegin))))

GRAPH: end()


COORD: transpose()

ELEMENT: interval(position(summary.count(bin.rect(salary))))

GRAPH: end()

Valid Functions

begin Function,end Function

SOURCE Statement

Syntax

SOURCE: =

. User-defined name for the data source.

. A function for extracting data from various data sources.

Description

Defines a data source for the graph. There can be multiple data sources, each specified by a

differentSOURCE statement.


21/149

13

Statement and Function Reference

Examples

Figure 2-3Example: Reading a CSV file

SOURCE: mydata = csvSource(path("C:\\Data\\demo.csv"))

mydatais an arbitrary name. It will be used to refer to the dataset in other parts of the GPL. The

csvSourcefunction takes a path to a comma-separated value (CSV) file as its argument.

Valid Functions

csvSource Function,userSource Function

DATA Statement

Syntax

DATA: =

. User-defined name for the variable.

. A function indicating the data sources.

Description

Defines a variable from a specific data source. The GPL statement must also include a SOURCE

statement. The name identified by the SOURCEstatement is used in the DATAstatement to indicate

the data source from which a particular variable is extracted.

Examples

Figure 2-4Example: Specifying a variable from a data source

DATA: age = col(source(mydata), name("age"))

ageis an arbitrary name. In this example, the variable name is the same as the name that appears

in the data source. Using the same name avoids confusion. The col function takes a data source

and data source variable name as its arguments. Note that the data source name was previously

defined by a SOURCEstatement and is not enclosed in quotes.

Valid Functions

col Function

TRANS Statement

Syntax

TRANS: varname =


22/149

14

Chapter 2

varname. A string that specifies a name for the variable that is created as a result of the

transformation.

. A valid function.

Description

Defines a new variable whose value is the result of a data transformation function.

Valid Functions

collapse Function,eval Function

SCALE Statement

Syntax

SCALE:

. A valid scale type.

Description

Defines the scale for a particular dimension or aesthetic (such as color).

Examples

Figure 2-5Example: Specifying a linear scale

SCALE: linear(dim(2), max(50000))

This example defines a linear scale on the second dimension (the y axis) and sets the maximum

value for that scale to 50000.

Scale Types

There are several scale types available in GPL.

Scale Types

cat Scale,linear Scale,log Scale,pow Scale,safelog Scale,safepower Scale,time Scale

cat Scale

Syntax

cat(dim(), )

-or-


23/149

15


cat(aesthetic(aesthetic.), )

. An integer indicating the dimension to which the scale applies.

. One or more valid functions.

. An aesthetic type indicating the aesthetic to which the scale applies. This is an

aesthetic created as the result of an aesthetic function in the ELEMENTstatement, often used for

distinguishing groups of graphic elements, as in clusters and stacks.

Description

Creates a categorical scale. Note that the scale can be associated with a dimension (such as an

axis or panel facet) or an aesthetic (as in the legend). By default, a categorical scale is created

for a categorical variable. You usually dont need to specify the scale unless you want to use a

function to modify the scale (for example, to sort the categories on the scale).

Examples

Figure 2-6Example: Specifying the scale for a dimension and sorting categories

SCALE: cat(dim(1), sort.natural())

Figure 2-7Example: Specifying the scale for an aesthetic and including categories

SCALE: cat(aesthetic(aesthetic.color), include("IL"))

Note: The excludefunction is not supported for aesthetic scales.

Applies To

SCALE Statement

Valid Functions

exclude Function,include Function,map Function,reverse Function,sort.data Function,

sort.natural Function,sort.statistic Function,sort.values Function,values Function

linear Scale

Syntax

linear(dim(), )




24/149

16

Chapter 2

Description

Creates a linear scale. By default, a linear scale is created for a continuous variable. You usually

dont need to specify the scale unless you want to use a function to modify the scale (for example,

to specify the range of the scale).

Example

Figure 2-8Example: Specifying a maximum value for the linear scale

SCALE: linear(dim(2), max(50000))

Applies To

SCALE Statement

Valid Functions

dataMinimum Function,dataMaximum Function,include Function,max Function,min Function,

origin Function (For Scales),reverse Function

log Scale

Syntax

log(dim(), )



Description

Creates a logarithmic scale. If a base is not explicitly specified, the default is base 10.

Example

Figure 2-9Example: Specifying the scale and a base

SCALE: log(dim(2), base(2))

Applies To

SCALE Statement

Valid Functions

base Function,dataMinimum Function,dataMaximum Function,include Function,max Function,

min Function,origin Function (For Scales)


25/149

17


pow Scale

Syntax

pow(dim(), )

. A numeric value indicating the dimension to which the scale applies.


Description

Creates a power scale. If an exponent is not explicitly specified, the default is 0.5.

Example

Figure 2-10Example: Specifying the scale and an exponent

SCALE: pow(dim(2), exponent(2))

Applies To

SCALE Statement

Valid Functions

dataMinimum Function,dataMaximum Function,exponent Function,include Function,max

Function,min Function,origin Function (For Scales)

safelog Scale

Syntax

safelog(dim(), )



Description

Creates a safe logarithmic scale. Unlike a regular log scale, the safe log scale uses a modified

function to handle 0 and negative values. If a base is not explicitly specified, the default is base 10.

sign(x) * log(1 + abs(x))

So, if you assume the axis value is 99, the result of the transformation is:

sign(-99) * log(1 + abs(-99)) = -1 * log(1 + 99) = -1 * 2 = -2


26/149

18

Chapter 2

Example

Figure 2-11Example: Specifying the scale and a base

SCALE: safelog(dim(2), base(2))

Applies To

SCALE Statement

Valid Functions

base Function,dataMinimum Function,dataMaximum Function,include Function,max Function,

min Function

safepower Scale

Syntax

safepower(dim(), )



Description

Creates a safe power scale. Unlike a regular power scale, the safe power scale uses a modified

function to handle negative values. If an exponent is not explicitly specified, the default is 0.5.

When the exponent is apositivenumber, the safe power formulas are:

If (x>=0):

pow(1+x, exponent)-1

If (x=0):

1-pow(1+x, exponent)

If (x


27/149

19


Example

Figure 2-12Example: Specifying the scale and an exponent

SCALE: safepower(dim(2), exponent(10))

Applies To

SCALE Statement

Valid Functions

dataMinimum Function,dataMaximum Function,exponent Function,include Function,max

Function,min Function

time Scale

Syntax

time(dim(), )



Description

Creates a time scale.

Example

Figure 2-13Example: Specifying a maximum value for the time scale

SCALE: time(dim(1), max("12/31/2005"))

Applies To

SCALE Statement

Valid Functions

dataMinimum Function,dataMaximum Function,max Function,min Function,origin Function

(For Scales)

COORD Statement

Syntax

COORD:

. A valid coordinate type.


28/149

20

Chapter 2

Description

Specifies a coordinate system for the graph. You can also embed coordinate systems.

Examples

Figure 2-14Example: Polar coordinates for pie charts

COORD: polar.theta(dim(1))

Figure 2-15Example: 3-D rectangular coordinates


Figure 2-16Example: Embedded coordinate systems for paneled pie chart

COORD: rect(dim(2), polar.theta(1))

Coordinate Types

There are several coordinate types available in GPL.

Coordinate Types

parallel Coordinate Type,polar Coordinate Type,polar.theta Coordinate Type,rect Coordinate

Type

parallel Coordinate Type

Syntax

parallel(dim(), )

. One or more integers (separated by commas) indicating the graph dimension or

dimensions to which the parallel coordinate system applies. The number of integers equals the

number of dimensions for the coordinate systems frame, and the integers are always in sequential

order. For example, parallel(dim(1,2,3,4))indicates that the first four variables in the

algebra are used for the parallel coordinates. Any others are used for faceting. If no dimensions

are specified, all variables are used for the parallel coordinates.

. One or more valid functions. These are optional.

Description

Creates a parallel coordinate system. A graph using this coordinate system consists of multiple,

parallel axes showing continuous data across multiple variables, resulting in a plot that is similar

to a profile plot.


29/149

21


When you use a parallel coordinate system, you cross each continuous variable in the algebra.

A line graphic element is the most common element type for this graph. The graphic element is

always distinguished by some aesthetic so that any patterns are readily apparent.

Examples

Figure 2-17Example: Parallel coordinates graph

COORD: parallel()

ELEMENT: line(position(var1*var2*var3*var4), color(catvar1))

Applies To

COORD Statement

Valid Functions

reflect Function,transpose Function

polar Coordinate Type

Syntax

polar(dim(), , )

. An integer indicating the dimensions to which the polar coordinates apply. This is

optional and is assumed to be the first two dimensions.


. Another coordinate system embedded in the polarcoordinate system. This

is optional.

Description

Creates a polar coordinate system. This differs from the polar.theta coordinate system in that it

is two dimensional. One dimension is associated the radius, and the other is associated with

the theta angle.

Examples

Figure 2-18Example: Polar line chart

COORD: polar()

ELEMENT: line(position(date*close))

Applies To

COORD Statement


30/149

22

Chapter 2

Valid Functions

reflect Function,reverse Function,transpose Function

polar.theta Coordinate Type

Syntax

polar.theta(dim(), , )

. An integer indicating the dimension. This is optional and required only when

polar.thetais not the first or outermost dimension. Otherwise, it is assumed to be the first

dimension.


. Another coordinate system embedded in thepolar.theta coordinate

system. This is optional.

Description

Creates a polar.theta coordinate system, which is the coordinate system for creating pie charts.

polar.theta differs from the polar coordinate system in that it is one dimensional. This is the

dimension for the theta angle.

Examples

Figure 2-19Example: Pie chart

COORD: polar.theta()ELEMENT: interval.stack(position(summary.count(1)), color(jobcat))

Applies To

COORD Statement

Valid Functions

reflect Function,reverse Function,startAngle Function,transpose Function

rect Coordinate Type

Syntax

rect(dim(), , )

. One or more integers (separated by commas) indicating the graph dimension or

dimensions to which the rectangular coordinate system applies. The number of integers equals

the number of dimensions for the coordinate systems frame, and the integers are always in

sequential order (for example, dim(1,2,3)and dim(4,5)).


31/149

23



. Another coordinate system within therectcoordinate system. This is

optional.

Description

Creates a rectangular coordinate system. By default, a rectangular coordinate system is 2-D,

which is the equivalent of specifying rect(dim(1,2)). To create a 3-D coordinate system,

use rect(dim(1,2,3)). Similarly, use rect(dim(1))to specify a 1-D coordinate system.

Changing the coordinate system also changes which variable in the algebra is summarized for a

statistic. The statistic function is calculated on the second crossed variable in a 2-D coordinate

system and the third crossed variable in a 3-D coordinate system.

Examples

Figure 2-20Example: 2-D bar chart

COORD: rect(dim(1,2))


Figure 2-21Example: 3-D bar chart



GUIDE Statement

Syntax

GUIDE:

. A valid guide type.

Description

Specifies a guide for the graph. Guides provide additional information about the graph; they help

interpret the graphic element or elements in the graph. Therefore, an axis is a guide because it

labels the categories and values in a graph (but is separate from the scale on which the data are

drawn). A title is a guide because it describes the graph. A legend is a guide because it providescolor swatches to match a category name to specific graphic elements in the graph.

Examples

Figure 2-22Example: Axis

GUIDE: axis(dim(2), label("Mean Current Salary"))


32/149

24

Chapter 2

Guide Types

There are several different types of guides.

Guide Types

axis Guide Type,legend Guide Type,text.footnote Guide Type,text.subfootnote Guide Type,

text.subsubfootnote Guide Type,text.subtitle Guide Type,text.title Guide Type

axis Guide Type

Syntax

axis(, )

. The graph dimension on which the axis appears.

. One or more valid functions. Use the null()function to hide the axis.

Description

Specifies the axis for a particular dimension. Do not confuse the axis with the scale. They are

separate parts of the graph and are handled with separate GPL statements. The axis helps interpret

the scale with labels and tick marks, but the axis does not change the scale. For information

about scales, seeSCALE Statement on p. 14.

Examples

Figure 2-23

Example: Specifying an axis label

GUIDE: axis(dim(2), label("Mean Current Salary"))

Applies To

GUIDE Statement

Valid Functions

delta Function,gridlines Function,label Function (For Guides),start Function,ticks Function

legend Guide Type

Syntax

legend(aesthetic(aesthetic.), )

. An aesthetic associated with the legend. The aesthetic identifies the legend,

which was created as the result of an aesthetic function in the ELEMENTstatement.

. One or more valid functions. Use thenull()function to hide the legend.


33/149

25


Description

Specifies properties of the legend associated with a specific aesthetic. The aesthetic itself is

defined by an aesthetic function in the ELEMENTstatement. The aesthetic function must use

multiple values, as when using a variable to control the aesthetic or when blending user constants

to control the aesthetic (such as color("2004"+"2005")). For example, in a stacked bar

chart, there may be a variable that controls the color aesthetic, with each value of the variable

corresponding to a specific color.

Note that the aesthetic also has a scale, which is controlled by a specific scale type. If the

aesthetic variable is a categorical variable or one or more string values are arguments of the

aesthetic function, use the cat scale to specify features like the order of the categories in the

legend. If the aesthetic variable is a continuous variable, use any of the other scales, depending on

your requirements. For more information, seeSCALE Statementon p. 14.

Examples

Figure 2-24Example: Specifying a legend title

GUIDE: legend(aesthetic(aesthetic.color), label("Gender"))

ELEMENT: interval(position(summary.count(jobcat)), color(gender))

Applies To

GUIDE Statement

Valid Functions

label Function (For Guides)

text.footnote Guide Type

Syntax

text.footnote()


Description

Specifies the footnote for the graph.

Examples

Figure 2-25Example: Specifying the footnote text

GUIDE: text.footnote(label("Some Text"))


34/149

26

Chapter 2

Applies To

GUIDE Statement

Valid Functions


text.subfootnote Guide Type

Syntax

text.subfootnote()


Description

Specifies the second-level footnote for the graph. That is, the subfootnote appears below the

footnote.

Examples

Figure 2-26Example: Specifying the second-level footnote text

GUIDE: text.subfootnote(label("Some Text"))

Applies To

GUIDE Statement

Valid Functions


text.subsubfootnote Guide Type

Syntax

text.subsubfootnote()


Description

Specifies the third-level footnote for the graph. That is, the subsubfootnote appears below the

subfootnote.


35/149

27


Examples

Figure 2-27Example: Specifying the third-level footnote text

GUIDE: text.subsubfootnote(label("Some Text"))

Applies To

GUIDE Statement

Valid Functions


text.subtitle Guide Type

Syntax

text.subtitle()


Description

Specifies the subtitle for the graph.

Examples

Figure 2-28Example: Specifying the subtitle text

GUIDE: text.subtitle(label("Some Text"))

Applies To

GUIDE Statement

Valid Functions


text.title Guide Type

Syntax

text.title()



36/149

28

Chapter 2

Description

Specifies the title for the graph.

Examples

Figure 2-29Example: Specifying the title text

GUIDE: text.title(label("Salary by Gender"))

Applies To

GUIDE Statement

Valid Functions


ELEMENT Statement

Syntax

ELEMENT:

. A valid element type.

Description

Specifies a graphic element used to draw the graph. Graphic elements are the bars, points, lines,etc., that make up a graph. There can be multiple ELEMENTstatements in the same block of GPL

to create multiple graphic elements. If the variables in the element statements differ, they are

blended to create the graph.

For example, assume the GPL includes the following ELEMENTstatements:

ELEMENT: point(position(x*y))

ELEMENT: point(point(position(x2*y2)))

In the resulting graph, dimension 1 uses x+x2, and dimension 2 uses y+y2.

Examples

Figure 2-30Example: Scatterplot

ELEMENT: point(position(x*y))

Figure 2-31Example: Line chart

ELEMENT: line(position(x*y))


37/149

29


Figure 2-32Example: Bar chart of means

ELEMENT: interval(position(summary.mean(x*y)))

Element Types

There are several different types of elements for drawing data on a graph.

area Element

Syntax

area.()

. A method that specifies what should happen when two area graphic elements

overlap each other. The collision modifier is optional.

. One or more valid functions. The positionfunction is required.

Description

Specifies an area graphic element.

Examples

Figure 2-33Example: Area chart

ELEMENT: area(position(summary.mean(jobcat*gender)))

Collision Modifiers

stack Collision Modifier

Valid Functions

closed Function,color Function,color.brightness Function,color.hue Function, color.saturation

Function,jump Function,label Function (For Graphic Elements),missing.gap Function,missing.interpolate Function,missing.wings Function,position Function,preserveStraightLines

Function,shape Function,size Function,split Function,texture.pattern Function,transparency

Function

Applies To

ELEMENT Statement


38/149

30

Chapter 2

bar Element

Description

baris an alias for interval. For the syntax and other examples, see interval Element.

Examples

Figure 2-34Example: Bar chart

ELEMENT: bar(position(summary.mean(jobcat*gender)))

interval Element

Syntax

interval.()

. A method that specifies what should happen when two interval graphic

elements overlap each other. The collision modifier is optional.


Description

Specifies an interval (bar) graphic element, as would be used in a bar chart, histogram, or error

bar chart.

Examples

Figure 2-35Example: Bar chart


Figure 2-36Example: Histogram

ELEMENT: interval(position(bin.rect(summary.count(salary))))

Figure 2-37Example: Error bar chart of standard deviation

ELEMENT: interval(position(region.spread.sd(jobcat*salary)), shape(shape.ibeam))

Figure 2-38Example: Stacked bar chart

ELEMENT: interval.stack(position(summary.mean(jobcat*salary)), color(gender))

Collision Modifiers



39/149

31


Valid Functions

color Function,color.brightness Function,color.hue Function,color.saturation Function,label

Function (For Graphic Elements),position Function,shape Function,size Function,split

Function,texture.pattern Function,transparency Function

Applies To

ELEMENT Statement

line Element

Syntax

line.()

. A method that specifies what should happen when two line graphic elements

overlap each other. The collision modifier is optional.


Description

Specifies a line graphic element. If multiple cases have the same value, the line is drawn through

the mean of the values.

Examples

Figure 2-39Example: Line chart of continuous variables

ELEMENT: line(position(salbegin*salary))

Figure 2-40Example: Line chart of summary statistic

ELEMENT: line(position(summary.mean(jobcat*salary)))

Collision Modifiers


Valid Functions


Function,jump Function,label Function (For Graphic Elements),missing.gap Function,

missing.interpolate Function,missing.wings Function,position Function,preserveStraightLines

Function,shape Function,size Function,split Function,transparency Function

Applies To

ELEMENT Statement


40/149

32

Chapter 2

path Element

Syntax

path()


Description

Specifies a path graphic element. The path graphic element connects alldata points. Therefore, it

can cross back on itself when there are multiple cases with the same value. This behavior is what

distinguishes the path element from the line element. Additionally, paths can have variable sizes,

so another variable can control the thickness of the path at any particular point.

Examples

Figure 2-41Example: Line chart drawn through all values

ELEMENT: path(position(salbegin*salary))

Figure 2-42Example: Creating a line chart with variable widths

ELEMENT: path(position(salbegin*salary), size(educ))

Valid Functions


Function,label Function (For Graphic Elements),missing.gap Function,missing.interpolate

Function,missing.wings Function,position Function,preserveStraightLines Function,shapeFunction,size Function,split Function,transparency Function

Applies To

ELEMENT Statement

point Element

Syntax

point.()

. A method that specifies what should happen when two points overlap each

other. The collision modifier is optional.


Description

Specifies a point graphic element, as would be used in a scatterplot.


41/149

33


Examples

Figure 2-43Example: Scatterplot


Figure 2-44Example: Dot plot

ELEMENT: point.dodge.symmetric(position(bin.dot(salary)))

Collision Modifiers

dodge.asymmetric Collision Modifier,dodge.symmetric Collision Modifier,stack Collision

Modifier

Valid Functions




Applies To

ELEMENT Statement

schema Element

Syntax

schema()


Description

Specifies a schema (boxplot) graphic element.

Examples

Figure 2-45Example: Boxplot

ELEMENT: schema(position(bin.quantile.letter(jobcat*salary)))

Valid Functions





42/149

34

Chapter 2

Applies To

ELEMENT Statement

Collision Modifiers

Collision modifiers specify what happens when two graphic elements overlap.

dodge.asymmetric Collision Modifier

Syntax

.dodge.asymmetric


Description

Moves graphic elements next to other graphic elements that appear at the same value, rather than

positioning them over one another. The graphic elements are arranged asymmetrically. That is,

the graphic elements are stacked on top of one another, with the graphic element on the bottom

positioned at a specific value on the scale. dodge.asymmetricis typically used for 1-D dot

plots.

Examples

Figure 2-46Example: 1-D Dot plot

ELEMENT: point.dodge.asymmetric(position(bin.dot(salary)))

Valid Element Types

point Element

dodge.symmetric Collision Modifier

Syntax

.dodge.symmetric


Description

Moves graphic elements next to other graphic elements that appear at the same value, rather than

positioning them over one another. The graphic elements are arranged symmetrically. That is,

the graphic elements extend in two directions from a central position. dodge.asymmetric

is typically used for 2-D dot plots.


43/149

35


Examples

Figure 2-47Example: 2-D Dot plot

ELEMENT: point.dodge.symmetric(position(bin.dot(salary*jobcat)))

Valid Element Types

point Element


Syntax

.stack


Description

Stacks graphic elements that would normally be drawn over each other or overlapping.

Examples

Figure 2-48Example: Stacked bar chart

ELEMENT: interval.stack(position(summary.mean(jobcat*salary)), color(gender))

Valid Element Types

area Element,interval Element,line Element,point Element

Functions

Functions are used within GPL statements. Functions can also be embedded in other functions.

Aesthetic Functions

color Function,color.brightness Function,color.hue Function,color.saturation Function,shape

Function,size Function,texture.pattern Function,transparency Function

Coordinate Functions

reflect Function,transpose Function

Data Functions

col Function


44/149

36

Chapter 2

Data Source Functions

csvSource Function,userSource Function

Density (Binning) Functions

bin.dot Function,bin.quantile.letter Function,bin.rect Function

Graph Control Functions

begin Function,end Function

Percentage Base Functions

base.aesthetic Function,base.all Function,base.coordinate Function

Sort Functions

sort.data Function,sort.natural Function,sort.statistic Function,sort.values Function

Statistic Functions

region.confi.smooth Function, region.spread.confi Function, region.spread.range

Function,region.spread.sd Function,smooth.cubic Function,smooth.linear Function,

smooth.loess Function,smooth.mean Function,smooth.spline Function,smooth.step

Function,smooth.quadratic Function,summary.count Function, summary.count.cumulative

Function,summary.max Function,summary.min Function,summary.mean Function,

summary.percent Function, summary.percent.cumulative Function,summary.sum Function,summary.sum.cumulative Function

Transformation Functions

collapse Function,eval Function

Missing Value Functions for Lines and Areas

missing.gap Function,missing.interpolate Function,missing.wings Function

Other Functions

base Function,binCount Function,binStart Function,binWidth Function,closed Function,cluster

Function,dataMinimum Function,dataMaximum Function,delta Function,exclude Function,

exponent Function,gridlines Function,In Function,include Function,jump Function,label

Function (ForGraphic Elements),label Function (For Guides),map Function,max Function,min

Function,notIn Function,origin Function (For Graphs),origin Function (For Scales),position

Function,preserveStraightLines Function,reverse Function,scale Function,start Function,

startAngle Function,ticks Function,values Function


45/149

37


base Function

Syntax

base()

. A numeric value indicating the base for the logarithmic scale.

Description

Specifies a base for the logarithmic scale.

Examples

Figure 2-49Example: Specifying a different base for a logarithmic scale

SCALE: log(dim(2), base(2))

Applies To

log Scale,safelog Scale

base.aesthetic Function

Syntax

base.aesthetic(aesthetic(aesthetic.))

. An aesthetic whose associated variable is used as the percentage base.

Description

Specifies that the percentage is based on the count across the result of an aesthetic function.

Summing the percentages of all of the graphic elements with a specific aesthetic equals 100%.

For example, all blue bars sum to 100%, and all red bars sum to 100%.

Examples

Figure 2-50

Example: Using a variable across clusters as the percentage base

ELEMENT: COORD: rect(dim(1,2), cluster(3))

ELEMENT: interval(position(summary.percent(summary.count(jobcat*1*gender),

base.aesthetic(aesthetic(aesthetic.color)))), color(jobcat))

Applies To

summary.percent Function, summary.percent.cumulative Function


46/149

38

Chapter 2

base.all Function

Syntax

base.all()

-or

base.all(acrossPanels())

Description

Specifies that the percentage is based on the total count. Summing the percentages of all of the

graphic elements in the chart or in each panel equals 100%. If you are using paneling and want to

specify the total count across all panels as the percentage base, use the acrossPanelsfunction.

Examples

Figure 2-51Example: Specifying the total count of one panel as the percentage base


ELEMENT: interval(position(summary.percent(summary.count(jobcat),

base.all())))

Figure 2-52Example: Specifying the total count in each panel as the percentage base



base.all())))

Figure 2-53Example: Specifying the total count across all panels as the percentage base



base.all(acrossPanels()))))

Applies To


base.coordinate Function

Syntax

base.coordinate(dim())

. An integer indicating the graph dimension whose associated variable is used as the

percentage base.


47/149

39


Description

Specifies that the percentage base is based on the individual values along a specific dimension.

Summing the percentages of all of the graphic elements with a particular value on the specified

dimension equals 100%. For example, you may do this to specify that the segments in each

stacked bar sum to 100%.

Examples

Figure 2-54Example: Making each stack equal 100%

ELEMENT: interval.stack(position(summary.percent(summary.count(jobcat*1*gender),

base.coordinate(dim(1)))), color(gender))

Figure 2-55Example: Making each cluster equal 100%

COORD: rect(dim(1,2), cluster(3))ELEMENT: interval(position(summary.percent(summary.count(gender*1*jobcat),

base.coordinate(dim(3)))), color(gender))

Applies To


begin Function

Syntax

begin()


Specifies the start of the GPL block that defines a particular graph.

Examples

Figure 2-56Example: Scaling a graph by 50%

GRAPH: begin(scale(50%,50%))

Figure 2-57

Example: Defining a particular graph

GRAPH: begin()

ELEMENT: line(position(x*y))

GRAPH: end()

Valid Functions

origin Function (For Graphs),scale Function


48/149

40

Chapter 2

Applies To

GRAPH Statement

bin.dot Function

Syntax

bin.dot(, )

. Graph algebra, such as x*y.


Description

Creates irregularly spaced bins of graphic elements with nearly identical values. When data are

sparse,bin.dotcenters the bins on the data. This function is typically used to create a dot plot.

Examples

Figure 2-58Example: Creating a 1-D dot plot

ELEMENT: point.stack.asymmetric(position(bin.dot(salary)))

Valid Functions

binCount Function,binStart Function,binWidth Function

Applies To

position Function,region.spread.sd Function,region.spread.se Function, summary.count

Function, summary.count.cumulative Function,summary.max Function,summary.mean Function,

summary.min Function,summary.percent Function,summary.percent.cumulative Function,

summary.sum Function, summary.sum.cumulative Function

bin.quantile.letter Function

Syntax

bin.quantile.letter()




49/149

41


Description

Calculates the five statistics used in box plots. The data are binned appropriately as a result of the

statistical calculation. bin.quantile.letteris used with the schema element to generate a

box plot.

Examples

Figure 2-59Example: Creating a box plot

ELEMENT: schema(position(bin.quantile.letter(jobcat*salary)))

Applies To



summary.min Function,summary.percent Function, summary.percent.cumulative Function,

summary.sum Function, summary.sum.cumulative Function

bin.rect Function

Syntax

bin.rect(, )



Description

Creates rectangular bins for grouping similar cases. bin.rectis the binning method commonly

used in histograms to calculate the count in each bin.

Examples

Figure 2-60Example: Histogram binning

ELEMENT: interval(position(summary.count(bin.rect(salary))))

Figure 2-61Example: Histogram binning with specified bin sizes

ELEMENT: interval(position(summary.count(bin.rect(salary, binWidth(5000)))))

Valid Functions

binCount Function,binStart Function,binWidth Function


50/149

42

Chapter 2

Applies To



summary.min Function,summary.percent Function,summary.percent.cumulative Function,summary.sum Function, summary.sum.cumulative Function

binCount Function

Syntax

binCount()

. An integer indicating the number of bins.

Description

Specifies the number of bins.

Examples

Figure 2-62Example: Defining a specific number of bins

ELEMENT: interval(position(summary.count(bin.rect(salary, binCount(25)))))

Applies To

bin.dot Function,bin.rect Function

binStart Function

Syntax

binStart()

. An integer or quoted date literal indicating the value of the first bin.

Description

Specifies the value of the first bin.

Examples

Figure 2-63Example: Specifying the first bin on a continuous scale

ELEMENT: interval(position(summary.count(bin.rect(salary, binStart(10000)))))


51/149

43


Figure 2-64Example: Specifying the first bin on a date scale

ELEMENT: interval(position(summary.count(bin.rect(saledate, binStart("01/20/2003")))))

Applies To


binWidth Function

Syntax

binWidth()

. An integer indicating the width of the bins. If the data being binned are dates, the

integer indicates days.

Description

Specifies the width of the bins.

Examples

Figure 2-65Example: Histogram binning

ELEMENT: interval(position(summary.count(bin.rect(salary, binWidth(1000)))))

Applies To


closed Function

Syntax

closed()

Description

Specifies that the end point of a graphic element is connected to its start point. In polarcoordinates, this results in a closed loop around the center of the coordinate system.

Examples

Figure 2-66Example: Creating a closed line

ELEMENT: line(position(x*y), closed())


52/149

44

Chapter 2

Applies To

area Element,line Element,path Element

cluster Function

Syntax

cluster( ...)

. One or more integers indicating the variable or variables in the algebra along whose

axis the clustering occurs.

Description

Clusters graphic elements along a specific axis. You can also cluster graphic elements on morethan one axis in 3-D charts.

Examples

Figure 2-67Example: Clustering on the x-axis dimension



In this example, thexaxis becomesjobcat, andgenderis the variable used for clustering. Another

way to look at this is to compare the position of the numbers in dim() to the positions of the

numbers in cluster(). In this case, the 1 in dim and 3 in cluster line up. Therefore, clusteringoccurs on dim(3), and dim(1) specifies thevariable that defines the graphic elements in each

cluster. If you removed the clusterfunction, the chart would look similar, except in this case,

dim(3) would specify a paneling facet and dim(1) would be the xaxis. In a way, the clustering

condenses the dimensions into one graph. Thats why it changes the variables associated with

a particular axis. Although clustering changes the roleof the dimensions, it does not change

the dimensions themselves.


53/149

45


The following 3-D examples used the following designations for the axes:

Figure 2-683-D axes

Figure 2-69

Example: Clustering on the y-axis dimension in a 3-D coordinate system

COORD: rect(dim(1,2,3), cluster(0,4,0))

ELEMENT: interval(position(summary.mean(minority*gender*salary*jobcat)),

color(gender))

In this example, they axis becomesjobcat, andgenderis the variable used for clustering. In this

example, dim(1) is not affected. The first parameter ofclusteris 0, which indicates that dim(1)

is not affected by the clustering. The second parameter ofclusteris 4. This indicates that the

2nd var

gpl reference guide

Documents