WIXLIB

Chapter 1 The S-PLUS LanguageINTRODUCTION TO SPOTFIRE S S-PLUS is a language specially created for exploratory data analysisand statistics. You can use Spotfire S productively and effectivelywithout even writing a one-line program in the S-PLUS language.However, most users begin programming in Spotfire S almostsubconsciously—defining functions to streamline repetitivecomputations, avoid typing mistakes in multi-line expressions, orsimply to keep a record of a sequence of commands for future use.The next step is usually incorporating flow-of-control features to reducerepetition in these simple functions. From there it is a relatively shortstep to the creation of entirely new modules of Spotfire S functions,perhaps building on the object-oriented features that allow you todefine new classes of objects and methods to handle them properly.In this book, we concentrate on describing how to use the language.As with any good book on programming, the goal of this book is tohelp you quickly produce useful S-PLUS functions, and then stepback and delve more deeply into the internals of the S-PLUSlanguage. Along the way, we will continually touch on those aspectsof Spotfire S programming that are either particularly effective (suchas vectorized arithmetic) or particularly troubling (memory use, forloops).This chapter aims to familiarize you with the language, starting with acomparison of interpreted and compiled languages. We then brieflydescribe object-oriented programming as it relates to Spotfire S ,although a full discussion is deferred until Chapter 12, ObjectOriented Programming in Spotfire S . We then describe the basicsyntax and data types in S-PLUS. Programming in Spotfire S doesnot require, but greatly benefits from, programming tools such as texteditors and source control. We touch on these tools briefly in thesection The Spotfire S Programming Environment (page 14).Finally, we introduce the various graphics paradigms, and discusswhen each should be used.2

Introduction to Spotfire S Interpreted vs.CompiledLanguagesLike Java, S-PLUS is an interpreted language, in which individuallanguage expressions are read and then immediately executed. TheSpotfire S interpreter, which carries out the actions specified by theS-PLUS expressions, is always interposed between your S-PLUSfunctions and the machine on which those functions are running.C and Fortran, by contrast, are compiled languages, in which completeprograms in the language are translated by a compiler into theappropriate machine language. Once a program is compiled, it runsindependently of the compiler. Interpreted programs, however, areuseless without their associated interpreter. Thus, anyone who wantsto use your Spotfire S programs needs to have a compatible versionof Spotfire S .The great advantage of interpreted languages is that they allowincremental development. You can write a function, run it, write anotherfunction, run that, then write a third function that calls the previoustwo. Incremental development is part of what makes Spotfire S anexcellent prototyping tool. You can create an empty shell of a function,add features as desired, and relatively quickly create a workingversion of virtually any application. You can then evaluate yourprototype to see if portions of the application might be moreefficiently coded in C or Fortran, and if so, easily incorporate thatcompiled code into your finished Spotfire S application.The disadvantage of interpreted languages is the overhead of theinterpreter. Compiled code runs faster and requires less memory thaninterpreted code, in part because the compiler can look at the entireprogram and optimize the machine code to perform the requiredsteps in the most efficient manner. Because there is no need for aninterpreter, more computer resources can be devoted to the al computer programming, as the very name implies, dealswith programs, which are sequences of instructions that tell thecomputer what to do. In the sense that a computer language is alanguage, programs (in Spotfire S , functions) are verbs.Object-oriented programming, by contrast, deals largely with nouns,namely, the data objects that traditional programs manipulate. Inobject-oriented programming, you start thinking about a type ofobject and try to imagine all the actions you might want to perform3

Chapter 1 The S-PLUS Languageon objects of that type. You then define the actions specifically for thattype of object. Typically, the first such action is to create instances ofthe type.Suppose, for example, that you start thinking about some graphicalobjects, more specifically, circles on the computer screen. You want tobe able to create circles, but you also want to be able to draw them,redraw them, move them, and so on.Using the object-oriented approach to programming, you woulddefine a class of objects called circle, then define a function forgenerating circles. (Such functions are called generator functions.) Whatabout drawing, redrawing, and moving? All of these are actions thatmay be performed on a wide variety of objects, but may well need tobe implemented differently for each. An object-oriented approach,therefore, defines the actions generically, with generic functions calleddraw, redraw, move, and so on.The actual implementation of the action for a specific class is called amethod. For example, for our class circle we might define classspecific methods for the functions draw, redraw, and move. Spotfire S includes a mechanism for determining whether a function is generic,and if so, determining the class of its arguments and calling theappropriate method, so that, for example, if draw is generic and orb isan object of class circle, the call draw(orb) would automatically callthe draw method for class circle, and draw orb.We will take up object-oriented programming in detail in Chapter 12,Object-Oriented Programming in Spotfire S .Versions of theS LanguageThere are currently two distinct versions of the S language incommon use: the S Version 3 language that underlies S-PLUS 2000for Windows (and all earlier versions of S-PLUS for Windows, as well as UNIX versions of S-PLUS from 3.0 to 3.4) and the S Version4 language that underlies S-PLUS 5.0 and later on UNIX and SPLUS 6 for Windows and later.The S Version 3 language (referred to in this document as SV3)introduced the modeling language that is the foundation for mostSpotfire S statistical and analytic functionality. It had a simpleobject-oriented structure with a dispatch mechanism built on namingconventions. It did not apply any class structure to existing S-PLUSobjects such as vectors and matrices.4

Introduction to Spotfire S The S Version 4 language (referred to in this document as SV4)introduced a strongly-typed object-oriented structure similar to that inC ; in SV4, all objects are assigned classes, the dispatch mechanismfor methods is much more sophisticated, and there are far strictercontrols over inheritance. In particular, multiple inheritance is nolonger supported. If you are new to Spotfire S , you will be usingSV4 from the start and you will find the instructions in this manualaccurate. If you have been working with Spotfire S a while, you mayfind that certain S expressions you may have used in the past yielddifferent answers under SV4. We have tried to cover most of theserious differences in output between SV3 and SV4 in the appendixon migrating your code to the SV4 version of S-PLUS (6.0 andhigher) in the User’s Guide.ProgrammingTools inSpotfire S In the Microsoft Windows GUI, there are two main tools fordeveloping Spotfire S programs: the Commands window andScript windows. The Commands window will be familiar to all usersof S-PLUS prior to version 4. Only one Commands window can beopen, and the easiest way to do this is simply click on its Standardtoolbar button.Figure 1.1: The Commands window button, found on the Standard toolbar.The prompt in the Commands window indicates Spotfire S isready for your input. You can now type expressions for Spotfire S tointerpret. Throughout this book, we show typed commands precededby the Spotfire S prompt, as in the following example, because thisrepresentation matches what you see in the Commands window: plot(corn.rain)If you type in examples from the text, or cut and paste examples fromthe on-line manuals, be sure to omit the prompt character. To exit theCommands window, simply use the close window tool on the topright of the window. The command q()will close down Spotfire S altogether.5

Chapter 1 The S-PLUS LanguageThe fix function is available from the Commands window to let youedit a function within a text editor.In the Microsoft Windows GUI Script windows, on the other hand,do not execute each statement as it is typed in, nor is there a promptcharacter. They are for developing longer Spotfire S programs, andfor building programs from a variety of sources, such as the Historylog.For your first sessions programming in Spotfire S , we recommendyou use the Commands window.6

Syntax of S-PLUS ExpressionsSYNTAX OF S-PLUS EXPRESSIONSYou interact with Spotfire S by typing expressions, which the SpotfireS interpreter evaluates and executes. Spotfire S recognizes a widevariety of expressions, but in interactive use the most common arenames, which return the current definition of the named data object,and function calls, which carry out a specified computation. Typing thename of a built-in S-PLUS function, for example, shows the currentdefinition of the function: sqrtfunction(x).Call("S c use method", "sqrt")A name is any combination of letters, numerals, and periods ( .) thatdoes not begin with a numeral.NoteThis definition applies to syntactic names, that is, names recognized by the Spotfire S interpreter as names. Spotfire S provides a mechanism by which virtually any character string,including non-syntactic names, can be supplied as the name of the data object. This mechanismis described in Chapter 2, Data Management.Spotfire S is case sensitive, so that x and X are different names. Afunction call is usually typed as a function name followed by anargument list (which may be empty) enclosed in parentheses: plot(corn.rain) mean(corn.rain)[1] 10.78421All S-PLUS expressions return a value, which may be NULL.Normally, this return value is automatically printed. Some functions, however, such as graphsheet (in Microsoft Windows ) or motif (inUNIX), plot, and q are called primarily for their side effects, such asstarting or closing a graphics device, plotting points, or ending aSpotfire S session. Such functions frequently have the automaticprinting of their values suppressed.7

Chapter 1 The S-PLUS LanguageIf you type an incomplete expression (for example, by omitting theclosing parenthesis in a function call), Spotfire S provides acontinuation prompt ( , by default) to indicate that more input isrequired to complete the expression.Infix operators are functions with two arguments that have the specialcalling syntax arg1 op arg2. For example, consider the familiarmathematical operators: 2 7[1] 9 12.4 / 3[1] 4.133333Names andAssignmentOne of the most frequently used infix operators is the assignmentoperator - (and its equivalents, the equal sign, , and theunderscore, ) used to associate names and values. For example, theexpression aba - 7associates the value 7 with the name aba. The value of an assignmentexpression is the assigned value, that is, the value on the right side ofthe assignment arrow. Assignment suppresses automatic printing, butyou can use the print function to force Spotfire S to print theexpression’s value as follows: print(aba - 7)[1] 7If we now type the name aba, we see the stored value: aba[1] 7The value on the right of the assignment arrow can be any S-PLUSexpression; the left side can be any syntactic name or character string.1There are a few reserved names, such as if and function.Assignments typed at the Spotfire S prompt are permanent; objectscreated in this way endure from session to session, until removed.1.8The complete list is as follows: if, is, else, for, while, repeat,next, break, in, function, return, TRUE, T, FALSE, F, NULL, NA,Inf, NaN.

Syntax of S-PLUS ExpressionsAssignments within functions, however, are local to the function; theyendure only as long as the call to the function in which they occur.For a complete discussion of assignment, see Chapter 2, DataManagement.Object names must begin with a letter or period, and may include anycombination of upper and lower case letters, numbers and periods("."). For example, mydata, my.data and my.data.1 are all legalnames. Note the use of the period to enhance readability. With SPLUS 5.x and later, another naming convention arose, where wordspreviously separated by periods were simply concatenated, with thesecond and subsequent words having initial caps, as in the following:exportData, getCurrDirectory, findClassObjects.SubscriptingAnother common operator is the subscript operator [, used to extractsubsets of a S-PLUS data object. The syntax for subscripting isobject [subscript ]Here object can be any S-PLUS object and subscript typically takes oneof the following forms: Positive integers corresponding to the position in the dataobject of the desired subset. For example, the letters data setconsists of the 26 lowercase letters. We can pick the thirdletter using a positive integer subscript as follows: letters[3][1] "c" Negative integers corresponding to the position in the dataobject of points to be excluded: letters[-3][1] "a" "b" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m" "n"[14] "o" "p" "q" "r" "s" "t" "u" "v" "w" "x" "y" "z" Logical values; true values correspond to the points in thedesired subset, false values correspond to excluded points:9

Chapter 1 The S-PLUS Language i - 1:26 i[1] 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17[18] 18 19 20 21 22 23 24 25 26 i 13[1] T T T T T T T T T T T T F F F F F F F F F F F F F F letters[ i 13][1] "a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l"Subscripting is extremely important in making efficient use of SpotfireS because it emphasizes treating data objects as whole entities,rather than as collections of individual observations. This point ofview is central to Spotfire S utility as a data analysis computingenvironment. For a full discussion of subscripting, see the Operatingon Subsets of Data on page 172.10

Data ClassesDATA CLASSESEverything in S-PLUS is an object. All objects have a class. A S-PLUSexpression (itself an object) is interpreted by the Spotfire S evaluatorand returns a value, another object that can be assigned a name. Anobject’s class determines the representation of the object, that is, whattypes of information can be found within the object, and where thatinformation can be found. Most information about an object iscontained within specialized structures called slots.The simplest data objects are one-dimensional arrays called vectors,consisting of any number of elements corresponding to individual datapoints. The simplest elements are literal expressions that, either singlyor matched like-with-like, produce the following classes: logical:The values T (or TRUE) and F (or FALSE). integer:Integer values such as 3 or -4. numeric: Floating-point real numbers (double-precision bydefault). Numerical values can be written as whole numbers(for example, 3., -4.), decimal fractions (4.52, -6.003), or inscientific notation (6.02e23, 8e-47). complex: Complex numbers of the form a bi, where ab are integers or numeric (for example, 3 1.23i). character:andcharacter strings enclosed by matching doublequotes (") or apostrophes ( ’), for example, "Alabama",’idea’.These simple element classes are listed in order from leastinformative (logical) to most informative (character); this order isimportant when considering data objects formed by combiningelements from different classes.The number of elements in a data object determines the object’slength. A vector of length 1 can be created simply by typing a literaland pressing ENTER: 7.4[1] 7.4 "hello"[1] "hello"11

Chapter 1 The S-PLUS LanguageTo combine multiple elements into a vector, use the c function: c(T,F,T)[1] T F T c(8.3, 9.2, 11)[1] 8.3 9.2 11.0If you try to combine elements of different classes into a single vector,1Spotfire S coerces all the elements to the most informative class : c(T, 8.3, 5)[1] 1.0 8.3 5.0 c(8.3, 9 6i)[1] 8.3 0i 9.0 6i c(T, 8.3, "hello")[1] "TRUE" "8.3" "hello"You can obtain the class and length of any data object using the classand length functions, respectively: class(c(T, 8.3, 5.0))[1] "numeric" length(c(T, 8.3, "hello"))[1] 3The most generally useful of the recursive data types is the listfunction, which can be used to combine arbitrary collections of SPLUS data objects into a single object. For example, suppose youhave a vector x of character data, a matrix y of logical data, and atime series z as shown below: x - c("Tom", "Dick", "Harry") y - matrix(c(T, F, T, F), ncol 2) z - ts(sin(1:36), start 1989)You can combine these into a single S-PLUS data object (of class"list") using the list function:1.12This statement about coercion applies strictly only to the five simpleclasses described on page 11. These simple classes correspondroughly to what S version 3 and earlier referred to as modes.(Although objects of class "integer" have mode "numeric".) Theconcept of modes persists in S version 4, but it has been almostentirely superseded by the new class mechanism.

Data Classes mylist - list(x x, y y, z z) mylist x:[1] "Tom" "Dick" "Harry" y:[,1] [,2]TTFF[1,][2,] 0.991778853The list class is an extremely powerful tool in Spotfire S , and weshall use it extensively throughout this book.13

Chapter 1 The S-PLUS LanguageTHE SPOTFIRE S PROGRAMMING ENVIRONMENT Spotfire S uses tools available in the Microsoft Windowsenvironment. Some of these tools are built into Spotfire S asfunctions—for example, the edit function (Windows) and vi function (UNIX ), which allows you to edit with the Windows Notepad inWindows and vi editor in UNIX, respectively. Windows software,including spreadsheets such as Microsoft Excel and word processorssuch as Microsoft Word, can be called from Spotfire S using the dosand system functions. UNIX system functions, such as ls and awk,can be called via the unix function.In this section, we give a brief introduction to the most common toolsfor writing, editing, and testing your S-PLUS functions, as well

Are a new Spotfire S user and need how to use Spotfire S , primarily through the GUI. User's Guide Are familiar with the S language and Spotfire S , and you want to use the Spotfire S plug-in, or customization, of the Eclipse Integrated Development Environment (IDE). Spotfire S Workbench User's Guide Have used the S language and Spotfire .