Release Notes for S-PLUS 6.1 Release 2 for UNIX/Linux (June 2002) These release notes are current as of June 20, 2002. For updates to the release notes that are made after this date as well as other useful information, please see the Web site http://www.insightful.com/support/splus61unix This file contains the following information: About this Release What's New in S-PLUS 6.1 Release 2 Bugs Fixed in S-PLUS 6.1 Release 2 Supported Platforms and System Requirements Installation Instructions Running S-PLUS Getting Help in S-PLUS Contact Information for Feedback Notes and Known Issues ABOUT THIS RELEASE S-PLUS 6.1 Release 2 for UNIX/Linux includes an optional Java-based graphical user interface (GUI). Information on starting S-PLUS with the GUI enabled is in Running S-PLUS below. Due to limitations in the underlying Java implementation, performance of the GUI may be poor if you are displaying the S-PLUS GUI on a display that is remote from the machine where S-PLUS runs. This is common in environments using X Windows, for example. Actual performance depends on the bandwidth of the local network as well as the X Windows implementation. For best results, display the GUI on the same machine where S-PLUS runs. The performance of the underlying S-PLUS engine is not affected on remote displays. The new features in S-PLUS 6.1 Release 2 for UNIX/Linux improve upon S-PLUS 6.0 in two main areas: C++ connectivity and globalization. WHAT'S NEW IN S-PLUS 6.1 Release 2 S-PLUS 6.1 Release 2 includes specific features to add or extend S-PLUS capabilities in the following areas: 1. C++ connectivity 2. Globalization 3. Oracle connectivity (Solaris only) 4. User-defined help files 5. The Missing Data library 6. The Robust library 7. Survival analysis 8. Mixed effects models 9. New binary operator %in% 10. New error functions erf and erfc This section briefly describes these additions and enhancements. 1. C++ Connectivity CONNECT/C++ is now available with S-PLUS for UNIX/Linux. Previously, this feature was available only in S-PLUS for Windows. You can use CONNECT/C++ to create C++ applications that access S-PLUS functionality as well as C++ functions that are called from S-PLUS via the .Call interface. S-PLUS 6.1 Release 2 includes a C++ class library you can use to create and manipulate S-PLUS functions, parse and evaluate S-PLUS expressions, and return messages when objects have changed or databases have been attached or detached. The CONNECT/C++ library can be found in $SHOME/newfun/lib, source code can be found in $SHOME/sconnect, and examples can be found in $SHOME/sconnect/samples. In addition, an HTML document describing the library can be found in $SHOME/sconnect/help. Here, $SHOME is the home directory for your installation of S-PLUS 6. You can see this directory path by typing either getenv("SHOME") at the command prompt in S-PLUS or Splus SHOME from the UNIX prompt, where Splus is the script you use to launch S-PLUS 6.1 Release 2. The CHAPTER script has been updated with new command line switches to support CONNECT/C++: * -sconnectlib creates a chapter to build a shared library that uses CONNECT/C++, and * -sconnectapp creates a chapter to build an application that uses CONNECT/C++. See the "S-PLUS 6.1 for UNIX/Linux Supplement" for complete details on using CONNECT/C++. 2. Globalization Aspects of S-PLUS have been significantly enhanced to support globalization and locales. The concept of a locale is akin to Regional Settings in Microsoft Windows; setting a locale is a way of specifying which character sets, number formats, and collation sequences to use. This allows S-PLUS to support Western European character sets (ISO 8859-1) as well as 8-bit ASCII characters (ASCII codes 128-255) in character data and the names of objects. Globalization also permits you to import, export, and display numbers written with decimal separators other than the period, and thousands separators other than the comma. S-PLUS 6.1 Release 2 fully supports French and German locales. For complete details on the changes made to support global installation and use, see the "S-PLUS 6.1 for UNIX/Linux Supplement." The implementation of locales within S-PLUS does not apply to date formats because they are handled through a separate mechanism in the timeDate set of functions. Also, it does not apply to messaging; all messages in S-PLUS are in the English language. 3. Oracle Connectivity (Solaris Only) S-PLUS 6.1 Release 2 expands connectivity with Oracle database clients. This allows you to read data from an Oracle table, insert data into a table, and run arbitrary SQL queries, all from the S-PLUS command line. For complete details and examples, see the "S-PLUS 6.1 for UNIX/Linux Supplement." This feature is available on Solaris installations of S-PLUS 6.1 Release 2 only; Linux installations do not support this. 4. User-Defined Help Files In S-PLUS 6.1 Release 2, the process for creating and distributing custom S-PLUS help files has been greatly streamlined and documented better. For complete details, see the "S-PLUS 6.1 for UNIX/Linux Supplement." S-PLUS 6.1 Release 2 includes a set of tools in $SHOME/help/BuildHelpFiles which enable you to convert old-style help files to the format used in S-PLUS 6. In particular, you can use doc_to_S.cyg to convert old-style help files and you can use build_helpchm.cyg to create compiled help files for distribution. 5. The Missing Data Library The default version of of anyMissing now uses which.na instead of just stopping, if called for an object with slots that does not have its own method for anyMissing. The preGauss function now gives warnings when non-numeric variables are deleted, and suggests using preCgm (conditional Gaussian model) instead. In addition, preGauss evaluates a subset expression (if given) before non-numeric variables are deleted. If you call any of the following in S-PLUS 6.1 Release 2, the return value is an object of class "miVariable", without call and seed attributes: impGauss(..., return.type="matrix") impCgm(..., return.type="matrix") impLoglin(..., return.type="matrix") You cannot add attributes to an object with a new-style class like "miVariable" without losing the class and component names, which makes the object no longer work with the rest of the library code. 6. The Robust Library The choice of the robust covariance estimator used in covRob (the estim argument) is now set directly as an argument to covRob, not through the control argument. An example command from previous versions of the Robust library is: covRob(stack.dat, control = covRob.control(estim="M")) In S-PLUS 6.1 Release 2, this command becomes: covRob(stack.dat, estim = "M") The function covRob.control now returns only the control parameters required for the selected estimator. Truncated mean estimators have been added to gammaRob and weibullRob and are now the default. The fit.models function has been modified to support user-defined fit.models methods. The summary method for robust linear models now includes an option for obtaining bootstrap coefficient standard error estimates. 7. Survival Analysis The survival analysis library of functions from Terry Therneau has been updated in S-PLUS 6.1 Release 2. There is now a new function aareg for fitting Aalen's additive regression model for censored data. The Aalen model assumes the cumulative hazard H(t) for a subject can be expressed as a(t) + X B(t), where a(t) is a time-dependent intercept term, X is the vector of covariates for the subject (possibly time-dependent), and B(t) is a time-dependent matrix of coefficients. The estimates are inheritly non-parametric; a fit of the model will normally be followed by one or more plots of the estimates. The estimates may become unstable near the tail of a data set, since the increment to B at time t is based on the subjects still at risk at time t. The aareg function produces objects of class "aareg". Methods for this new class include print, summary, plot, and lines. New functions dsurvReg, psurvReg, and qsurvReg compute the density, cumulative probability, and quantiles, respectively, for the set of distributions supported by the survReg function. The survfit function can now handle general censoring of all types (left, right, and interval as well as counting process data). 8. Mixed Effects Models The set of S-PLUS functions for mixed effects models has been updated to the NLME 3.3.2 library from Jose Pinheiro and Douglas Bates. See the readme.txt file in $SHOME/library/nlme3 for complete details. 9. New Binary Operator %in% S-PLUS 6.1 Release 2 includes the new binary operator %in% that is a synonym to the is.element function. This operator is not related to the %in% formula syntax; see the is.element help file for details. 10. New Error Functions erf and erfc New functions erf and erfc have been added to the S-PLUS engine. These functions use pnorm to calculate estimates of the error function. SUPPORTED PLATFORMS AND SYSTEM REQUIREMENTS S-PLUS 6.1 Release 2 for UNIX/Linux is supported on the following: * 32-bit Solaris, Solaris 2.6, 7, or 8 * Red Hat Linux 6.1, 6.2, 7.0, 7.2 Minimum Recommended System Configuration Before installing S-PLUS, review the minimum system configuration information in the table below. To determine the required RAM, sum the base RAM and the per-user RAM multiplied by the number of simultaneous users. For example, a single-user Linux system should have at least 64 + 32*1 = 96MB of RAM. Platform Operating System Disk Space Base RAM Per-User RAM Sun SPARC Solaris 2.6, 7, 8 225 MB 64 MB 40 MB Intel x86 Red Hat 6.1, 6.2, 225 MB 64 MB 32 MB 7.0, or 7.2 The base RAM and per-user RAM listings can also be used to calculate minimum swap space requirements. In general, the minimum swap space required is twice the sum of the base RAM and the per-user RAM multiplied by the number of simultaneous users. For example, on a Solaris system with 3 simultaneous S-PLUS users, the minimum swap space is 2*(64+(40*3)) = 368MB. Note that these values are minima; if you work with moderate sized data sets, these numbers may be insufficient for your needs. Note also that they are computed for simple command-line S-PLUS; if you intend to run the Java GUI, you should add approximately 100MB RAM per user to the numbers shown in the table. For example, on Solaris, we recommend approximately 200MB RAM for one user running the Java GUI. Linux Platforms S-PLUS 6.1 Release 2 was developed under Red Hat 6.1 and tested/supported on Red Hat 6.2, 7.0, and 7.2. These releases contain the kernels and compilers listed in the table below. Other Linux distributions, such as SuSE, are not officially supported or tested. However, if do you wish to use another Linux distribution, you should use one that has similar versions of the kernels and compilers (e.g., SuSE 6.4, 7.0, or 7.2). For more information on various Linux distributions, see http://www.distrowatch.com. If you have difficulty running S-PLUS 6.1 Release 2 on Red Hat Linux 7.x, see the Notes and Known Issues below for a possible workaround. Red Hat OS 7.2 7.0 6.2 6.1 Kernel 2.4.7 2.2.16 2.2.14 2.2.12 GCC 2.96 2.96 2.91.66 2.91.66 glibc 2.2.4 2.1.92 2.1.3 2.1.2 Java Runtime Environment (JRE) The Java runtime environment (JRE) version 1.3 is included in S-PLUS 6.1 Release 2. Your operating system must support JRE 1.3 in order to run the Java-enabled version of S-PLUS. Note that the JRE provided by S-PLUS is installed as part of the S-PLUS distribution, and under normal circumstances, it is used only by S-PLUS. If you have a different version of the JRE on your system, the JRE used by S-PLUS should not interfere with your other JRE applications, which will continue to use the version you've previously installed. Solaris requirements for the JRE are available from http://java.sun.com/j2se/1.3/README.sparc These release notes indicate the Java 2 SDK Standard Edition v1.3.0 is supported on Solaris 2.6, Solaris 7, and Solaris 8 operating environments. In addition, Solaris requires various patches from Sun to run Java 1.3. Solaris users should check the list of recommended and required patches at the Web site http://java.sun.com/j2se/1.3/install-solaris-patches.html. Linux requirements for the JRE are available from http://java.sun.com/j2se/1.3/README-linux.html. These release notes indicate: "This version of the Java 2 SDK is supported on Intel Pentium platform running the Linux kernel v 2.2.12 and glibc v 2.1.2. A minimum of 32 megabytes RAM are required. Recommended: 48 megabytes of RAM, 16-bit color mode, KDE and KWM window managers. Sun Microsystems, Inc. has tested this release using Red Hat Linux 6.1." INSTALLING S-PLUS For complete installation instructions, please see the plain text file INSTALL.TXT located at the top level of your S-PLUS 6.1 Release 2 CD-ROM. For instructions on installing S-PLUS modules with this release of S-PLUS, see the document $SHOME/doc/modinst_unix.pdf. During installation, you are prompted for your S-PLUS serial number. Note that the serial number format has changed dramatically in S-PLUS 6.1 Release 2; you can find your new serial number on the S-PLUS 6.1 Release 2 CD-ROM jewel case. The serial number you enter during installation is recorded and you can retrieve it later by typing Splus SERIAL at the UNIX prompt on your system. Do NOT install this release over any existing version of S-PLUS. Instead, designate a clean installation directory for S-PLUS 6.1 Release 2 and proceed with the installation as described in INSTALL.TXT. RUNNING S-PLUS Before starting S-PLUS, you must do the following: 1. Set your DISPLAY environment variable to your local machine, if necessary. 2. Create an S-PLUS chapter to hold your work. To use the Java related features of S-PLUS, you must be able to connect to your local X window server. Thus, you must have the environmental variable DISPLAY set and the X window server on your local machine must allow the S-PLUS server to create windows on your machine; see the UNIX programs xauth or xhost. Typically, if you can run xclock on your machine, then S-PLUS should also be able to access the X server. To set your display from a C-like shell (csh, tcsh, etc.), use the setenv command: % setenv DISPLAY where is the name of your local machine. From the Bourne- and Korn-like shells (including sh, ksh, bash, etc.), use the following commands: % DISPLAY=;export DISPLAY You do not need to do this if your DISPLAY variable is set already; check the output from echo $DISPLAY to be sure. Creating an S-PLUS chapter is necessary for storing the data objects and external files you create in S-PLUS. The following commands create an S-PLUS chapter named mysplus for you to work in (be sure you don't have a mysplus directory in your home directory before typing these commands). % cd % mkdir mysplus % cd mysplus % Splus CHAPTER If you do not create a chapter, S-PLUS automatically creates one for you named MySwork the first time you start S-PLUS. You are now ready to start S-PLUS. S-PLUS may be launched in a variety of modes. The following lists each mode and the corresponding UNIX command-line expression for launching it. In all of the commands below, Splus refers to the script you use to launch S-PLUS 6.1 Release 2 on your system. * S-PLUS command line without Java % Splus * S-PLUS command line supporting Java calls, Java graphics, and the Java help interface % Splus -j * S-PLUS graphical user interface % Splus -g or % Splus -g & The second command using the ampersand "&" puts the GUI process into the background, freeing your xterm for other uses. The -e flag may be added to either of the first two modes to enable command-line editing. The Commands window in the graphical user interface always allows basic editing. S-PLUS 6.1 Release 2 includes two additional flags, -jit and -helpoff: * The -jit flag works with the -g, -j, and -userapp flags and allows you to turn on the Java just-in-time compiler. This makes the graphical user interface and help system run faster but introduces instabilities that often lead to crashes. In particular, the just-in-time compiler often crashes while repainting graphical user interface elements such as the JavaHelp window and the Data window. * The -helpoff flag is useful only with the -g flag. It turns off the automatic invisible startup of the help system. The invisible startup improves initial responsiveness of the help system but adds a significant memory footprint to the current session. If you wish to optimize your available memory, this flag may prove useful. GETTING HELP IN S-PLUS S-PLUS 6.1 Release 2 for UNIX/Linux uses JavaHelp 1.1.2 as its main help system. You can use the help.start and help.off functions to turn the help system on and off, respectively, throughout your S-PLUS session. To obtain help on a particular function, use the help or ? functions. The help system contains online help files for all the S-PLUS libraries that are attached at startup; help files for other libraries are available once the libraries are attached. To obtain help on the functionality of a particular dialog, click the Help button in that dialog. For replacement functions such as "dim<-", look for help on the corresponding regular function, such as dim. Look up Arithmetic, Assignment, and Comparison, respectively, for arithmetic, assignment, and comparison operators. In addition to this text file, an HTML version of these release notes is included in $SHOME/doc/relnotes.html. The installation notes are available in $SHOME/INSTALL.TXT and installation instructions for S-PLUS modules are located in $SHOME/doc/modinst_unix.pdf. A list of bugs fixed in this release is included in $SHOME/doc/FIXEDBUG.TXT. S-PLUS 6 has seven printed manuals which are also available as Adobe Acrobat PDF files in $SHOME/doc: S-PLUS 6.1 for UNIX/Linux Supplement unixsupp61.pdf Installation and Maintenance Guide instman.pdf Getting Started with S-PLUS 6.0 getstart.pdf S-PLUS 6 User's Guide unixug.pdf S-PLUS 6 Guide to Statistics, Volume 1 statman1.pdf S-PLUS 6 Guide to Statistics, Volume 2 statman2.pdf S-PLUS 6 Programmer's Guide pguide.pdf CONTACT INFORMATION FOR FEEDBACK Please feel free to contact us with questions or feedback about this release. Send all technical support queries and general comments to one of the locations listed below. North, Central, and South America Contact Technical Support at Insightful Corporation: Telephone: 206.283.8802 or 1.800.569.0123, ext. 235 Monday-Friday, 6:00 a.m. PST (9:00 a.m. EST) to 5:00 p.m. PST (8:00 p.m. EST) Fax: 206.283.8691 E-mail: support@insightful.com Web: www.insightful.com/support All Other Locations Contact the European Headquarters of Insightful Corporation: Christoph Merian-Ring 11, 4153 Reinach, Switzerland Telephone: +41 61 717 9340 Fax: +41 61 717 9341 E-mail: info@ch.insightful.com We are very interested in receiving information on possible bugs and usability enhancements from all users. Bug reports can be sent to the following e-mail address: bugs@insightful.com General information about this release of S-PLUS is available at: http://www.insightful.com/support/splus61unix The list of S-PLUS Frequently Asked Questions is available from: http://www.insightful.com/support/faq.htm NOTES AND KNOWN ISSUES These notes detail some characteristics and issues known to exists in this release. Our intent is to continue to resolve both known and newly discovered problems rapidly and to make improvements available to users through regular service releases. S-PLUS 6.1 Release 2 uses the latest Java code from Sun Microsystems (or the appropriate hardware vendor) as well as Sun's emerging JavaHelp system. Some instability in our product may be linked to issues with these Java technologies. The Graphical User Interface * If you see a message that contains "Can't connect to X11 window server using ...as the value of the DISPLAY variable" when attempting to start S-PLUS, this most likely means you forgot to set your DISPLAY environment variable. See Running S-PLUS for details. If you see messages about a connection to your display being refused by server, you may need to use the UNIX xhost command to allow access to your X server from the S-PLUS server. * The Data Set lists in dialogs display the names of data frames in your working directory. To see built-in example data sets as well, assign them to your working directory by typing commands similar to the following in the Commands window: fuel.frame <- fuel.frame catalyst <- catalyst environmental <- environmental Alternatively, you can simply type the name of a built-in example data set into a Data Set text field. * The Java menus and dialogs are equipped with keyboard shortcuts that allow you to use your keyboard instead of the mouse to navigate the GUI. The keyboard shortcuts are indicated by underscores in menu and field names; combine these with the ALT key or its equivalent to navigate the main menu. For example, ALT-F opens the File menu, and once that menu is displayed, pressing E brings up the Export Data dialog. Similarly, ALT-G will opens the Graph menu and then pressing S brings up the Scatter Plot dialog. Within dialogs, use the ALT key together with the indicated keyboard shortcuts to navigate to a desired field. For example, in the Scatter Plot dialog, use ALT-F to navigate to the x Axis Value field. Interfacing to Java Use the .JavaMethod function to call a static Java method from S-PLUS. For example, you can raise 2 to the power 10 and return the value as a double using .JavaMethod("java/lang/Math", "pow", "(DD)D", 2, 10) For more information, see the chapter "Interfacing with Java" in the Programmer's Guide. Cutting, Pasting, and Interrupting The Commands window in the graphical user interface uses the X-selection protocol for cutting and pasting; much of the rest of the GUI (including JavaHelp) uses the GUI-standard CTRL-C/CTRL-V for cutting and pasting. Thus, to paste an example from a JavaHelp help file window into the GUI Commands window, you need to select the example in JavaHelp, press CTRL-C, wait a moment to allow S-PLUS to copy the Java selection into the standard X clipboard buffer, then paste the example into the Commands window using your standard X paste command (typically a middle-click). Because CTRL-C can be interpreted as a cut command, the GUI version of S-PLUS uses ESC as its interrupt key. On some X displays, you may need to double-middle-click to execute a paste in the Commands window. European Keyboards A bug in version 1.3 of Sun's JRE causes some keys on European keyboards to be ignored in the S-PLUS Java GUI. For example, the ~ and # keys are ignored on British keyboards and the <>, [], and {} keys are ignored on Spanish keyboards. This bug is visible in Linux versions of S-PLUS but is not present in Solaris versions. It may be possible to work around this bug by using an alternate version of the JRE, like IBM JRE, or by installing JDK 1.4. If you are interested in either of these possibilities, please contact Technical Support. Java Display Issues To run the Java GUI on a remote display, you must have a display that supports the X Window System. This may be either a UNIX display or a PC running an X server such as X-Win32 or Reflection X. A text-only connection such as telnet does not support graphical applications. Java has a number of known problems displaying on a remote display using the X Window System. For this reason, we suggest (if possible) that you limit your use of the Java-based GUI in this release to the console of the machine on which S-PLUS is installed. That is, treat this release of the Java-based GUI as a workstation release, rather than as a network client/server release. Known problems with remote display include the following: * If the graphical user interface does not start on Solaris, you may need to patch your operating system. See Supported Platforms and System Requirements above. * Font substitutions produce awkward-looking fonts in menus and dialogs. * Dialogs tend to refresh slowly. A dialog may display initially with a gray background and take five or six seconds to refresh completely. * When using a remote display, Java renders the display on the server and then sends a bitmap of the application region to the remote display. The amount of information sent scales with the color depth of the display. With a Windows display, set the display to 256 colors for best performance. When running S-PLUS on Solaris and displaying on Linux, the Java virtual machine will not work properly with a 16 bit color display. Set your display to another color level to run Java properly. Our experience to date suggests that Java on Linux is more reliable than Java on Solaris for remote displays. Java on Solaris appears to have some implementation issues that hinder proper display on non-Solaris displays. Red Hat Linux 7.x If you have difficulty starting S-PLUS 6.1 Release 2 on Red Hat Linux 7.x, you may be encountering a bug in the current version of S-PLUS that causes a Java hang under certain conditions. To work around this, add the following lines to the top of the script you use to start S-PLUS: LD_ASSUME_KERNEL="2.2.5" export LD_ASSUME_KERNEL These commands will work if your system runs Bourne- and Korn-like shells. If your system runs C-like shells instead, add the following command to the top of your S-PLUS script: setenv LD_ASSUME_KERNEL 2.2.5 Your S-PLUS script is stored in two locations: $SHOME/cmd and a system-wide directory such as /usr/local/bin; both copies of the script should be modified. The name of the script is whatever you type at the UNIX prompt to start S-PLUS 6.1 Release 2. Dynamic Memory Issues The amount of memory available to a particular user in UNIX is controlled by various limits. To see them, type % limit at the UNIX prompt on your system. The defaults returned may be too small for S-PLUS. On one machine at Insightful Corporation, for example % limit datasize is 131072 kbytes by default. This can lead to S-PLUS running out of dynamic memory sooner than it otherwise should. The fix is to increase the limit, as in the following command: % limit datasize unlimited Some user limits are constrained by system limits that must be set by the superuser. If you maximize your user settings but still have dynamic memory problems, you may need to contact your system administrator to raise the system limits. Shared Libraries If you compile C or Fortran code for use with S-PLUS 6, note that 32-bit and 64-bit versions of S-PLUS 6 both produce makefiles that create shared libraries named S.so by default. These libraries are incompatible between versions and must be compiled for either 32-bit or 64-bit versions of S-PLUS. We recommend creating shared libraries with different names for each platform (such as S_64.so and S_32.so). You can then use dyn.open to open these libraries, if desired. Other Known Issues * When starting S-PLUS on a display for a machine that has a different operating system than the machine on which S-PLUS is running, you may receive a large number of warnings with a message such as "Font specified in font.properties not found [fontname]." * Error boxes from modeling dialogs do not have "always on top" status. They may become hidden behind the dialog box where they can't be seen. * On some remote displays, menu selections are not recognized if any part of a menu falls outside the application region. If dialogs fail to appear, increase the size of the application region to assure it contains the full menu. * Dialogs do not always recognize the ENTER key as equivalent to pressing the OK button. In particular, if the focus is on a combination box, the ENTER key is not recognized as the equivalent to the OK button. A workaround is to either press OK using the mouse or use the TAB key to move the focus to a field that is not a combination box and then press ENTER. * The approx function has been upgraded to use double-precision calculations in S-PLUS 6.1 Release 2. This means the results may be slightly different in some cases than they were in S-PLUS 6.0. In particular, you may get NAs for some endpoints of xout that were not NAs in 6.0. * CONNECT/C++ applications that use stdio may shutdown with a bad address signal. A possible fix is to rebuild libsconnect.so using the following steps: % cd $SHOME/sconnect % Splus MAKE libsconnect % cp libsconnect.so $SHOME/newfun/lib After this is done, rebuild the CONNECT/C++ application. Permissions for the sconnect and lib directories and the files within them must be such that the user has access to read and write files.