Release Notes for S-PLUS 6.2 for UNIX/Linux
(January 2004)

These release notes are current as of December 15, 2003. For updates to the release notes that are made after this date as well as other useful information, please see the Web site

www.insightful.com/support/splus62unix

This file contains the following information:

About this Release

What's New in S-PLUS 6.2

Bugs Fixed in S-PLUS 6.2

Supported Platforms and System Requirements

Installing S-PLUS

Using S-PLUS for UNIX from a Windows Desktop

Running S-PLUS

Getting Help in S-PLUS

Contact Information for Feedback

Notes and Known Issues

 

ABOUT THIS RELEASE

S-PLUS 6.2 for UNIX/Linux includes an optional Java-based graphical user interface (GUI). Information on starting S-PLUS with the GUI enabled is in the section 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 remote display (a different machine than the one S-PLUS on which is installed). For example, the display may be less than optimal in environments using an X-Windows emulator on a personal computer. 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 by the use of remote displays.

The new features in S-PLUS 6.2 for UNIX/Linux improve upon S-PLUS 6.1 in three main areas: native drivers, verbose logging, and XML generation and reporting. There are also a number of enhancements to existing functions.

Technical papers on the native drivers, verbose logging, XML generation, and XML reporting are available through the $SHOME/doc/tech_papers directory.

 

WHAT'S NEW IN S-PLUS 6.2

S-PLUS 6.2 includes a variety of new features to add to or extend S-PLUS capabilities. Major additions include:

In addition, existing functionality has been enhanced in the following areas:

This section briefly describes these additions and enhancements.

Native Drivers

S-PLUS now includes access to the following databases via direct database drivers:

Exporting to databases now allows existing tables to be either replaced or appended to.

Direct database access is accomplished by using driver components which must be separately installed on the system that is running S-PLUS. These driver components are provided by the database vendor, and usually consist of components that can be called directly by S-PLUS to send and receive database information in the native format that the database supports.

This functionality is described in more detail in the Native Drivers technical paper available by navigating to $SHOME/doc/tech_papers.

Verbose Logging

Batch processing support to run S-PLUS scripts non-interactively has been a key feature of S-PLUS for a number of releases. Often, this is performed to execute S-PLUS scripts as part of a production process.

For example, in the medical and pharmaceutical industries, it is vital that data management and statistical tasks be validated and documented. All steps involved in experimentation and validation must be documented and preserved in order to demonstrate to oversight bodies that the results are complete, accurate, valid, and reproducible. In addition to source files and generated output, log files are typically retained for these purposes, and they include the following:

This functionality is described in more detail in the Verbose Logging technical paper available by navigating to $SHOME/doc/tech_papers.

XML Generation and Reporting

Extensible Markup Language (XML) provides a powerful mechanism for both storing and exchanging information between applications. S-PLUS includes two libraries of functions for working with XML:

SPXML library (Insightful) Introduces a rich report generation system for creating custom reports in a wide array of document formats. It uses the Extensible Stylesheet Language (XSL) to create HTML, PDF, Postscript, or RTF reports from an XML description of an S-PLUS object.

Included in the SPXML library are functions to read and write XML using S-PLUS-specific XML tags and then convert between these tags and the tags used by other applications. They allow S-PLUS objects to be created from any XML file, with their creation specified using XSL.

XML library (Bell Laboratories) Introduces a set of S-PLUS classes representing XML objects, such as XMLNode and XMLComment. A Document Object Model (DOM) parser is used to create an S-PLUS object from the information in an XML file. This object can be traversed using S-PLUS subscripting, manipulated using S-PLUS functions, and written back to a file if desired.

This functionality is described in more detail in the XML Generation and XML Reporting technical papers available by navigating to $SHOME/doc/tech_papers.

DOX Library

S-PLUS 6.2 now includes the DOX library for the design and graphical analysis of industrial experiments, generically called "design of experiments." This was previously available as a separate S-PLUS module.

Information on the functionality of this library is available through the help system. An on-line manual in PDF format will be included in the final release in $SHOME/library/dox.

New User-Contributed Libraries

The user-contributed libraries class, design, hmisc, MASS, nnet, and spatial have been part of the Windows libraries in the past, and are now in UNIX as well. Contributors to these libraries include Bill Venables, Brian Ripley, and Frank Harrell.

Graphlet Enhancements

There are several new features in S-PLUS Graphlets, specifically with respect to the java.identify function:

In addition, a new spjgraph.jar file is included, containing updated java code. This should be used for viewing any Graphlets.

Out-of-memory problems that occur when zooming the Graphlet image too much have been fixed, as well as problems with passing NAs to java.identify with the winspj library. For more information, see the java.identify help file.

Note that all of these enhancements are implemented when viewing Graphlets in a Web browser or viewing the java.graph window while S-PLUS is running.

Read and Write SAS 9 Files

SAS 9 files can now be imported and exported.

New Language Functions

The cummax() method returns a vector of non-decreasing (resp. non-increasing) numbers which are the cumulative maxima (resp. minima) of the values in x.

The file.realpath() function returns the absolute path name for a file.

substituteString() replaces parts of a string matching a regular expression.

Statistics

The control parameters (e.g., convergence threshold and maximum iteration count) used in GLM and GAM have been tightened. These algorithms may now perform more iterations before declaring convergence, but the extra computation time allows for more reliable parameter estimates in some situations (particularly when highly-correlated covariates are present).

 

BUGS FIXED IN S-PLUS 6.2

In this release, we have made a number of improvements to the quality of S-PLUS to make it a more reliable engine, especially for production purposes. Fixes were made in several areas:

Stability We have improved the overall stability of S-PLUS in several ways. Many reference counting errors and other internal engine errors have been fixed. Instabilities caused by working with large numbers of variables in statistics functions have also been addressed.

Statistics We improved many of the statistics functions to eliminate failures and correctly support options.

Accuracy We improved the accuracy of many of the probability distribution functions, especially for extreme parameter values. Some older single-precision functions have also been converted to double-precision.

Language Corrections were made to a number of core language functions, especially to deal with "corner cases" in a consistent fashion.

Data Access We improved the reliability of S-PLUS's data import and export functionality, to eliminate failures or data corruption which could occur with nonstandard file formats or import specifications.

GUI We have resolved a number of issues where dialogs or other elements of the GUI did not work as intended. We have also eliminated several crashes that could occur when working with the graphical user interface.

Graphics Errors in GUI graphics, command-line graphics (particularly for Trellis plots and timeDate charts), and Graphlets have been addressed.

Globalization We have addressed a few issues that arose when working with non-English characters in data, objects, and file names.

Performance The speed of some functions has been improved, and several memory leaks have been eliminated.

A complete list of Fixed Bugs in S-PLUS 6.2 is available.

SUPPORTED PLATFORMS AND SYSTEM REQUIREMENTS

S-PLUS 6.2 for UNIX/Linux is supported on the following:

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.8, 2.9

225 MB

64 MB

40 MB

Intel x86

Red Hat 8, 9

225 MB

64 MB

32 MB

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.2 was developed under Red Hat 8 and tested/supported on Red Hat 8 and 9. 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 www.distrowatch.com .

If you have difficulty running S-PLUS 6.2 on Red Hat Linux 8 or 9, see the Notes and Known Issues below for a possible workaround.

Red Hat OS

3 (Enterprise)

9

8

Kernel

2.4.21

2.4.20

2.2.18

GCC

3.2.3

3.2.2

3.2

glibc

2.3.2

2.3.2

2.2.93

Java Runtime Environment (JRE)

The Java runtime environment (JRE) version 1.4.0_01 is included in S-PLUS 6.2 .Your operating system must support JRE 1.4.0_01 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

java.sun.com/products/archive/j2se/1.4.0_01/jre/install-solaris.html

These release notes indicate the Java 2 SDK Standard Edition v1.4.0 is supported on Solaris 2.6, 7, 8, and 9 operating environments.

Linux requirements for the JRE are available from

java.sun.com/products/archive/j2se/1.4.0_01/install-linux.html

These release notes indicate the following:

"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-11. A minimum of 32 megabytes RAM are required. Recommended 48 megabytes of RAM, 16-bit color mode with KDE or the Gnome desktop and in conjunction with displays set to local hosts."

HP-UX requirements for the JRE are available from

www.hp.com/products1/unix/java/java2/sdkrte14/infolibrary/sdk_rnotes_1.4.0.01.html

These release notes provide the following recommendations:

"The HP-UX SDK for the Java(tm) 2 Platform version 1.4.0.01 provides the tools for developing and deploying Java applications on HP systems with HP-UX 11.0 and 11i PA-RISC.

"HP's SDK 1.4.0.01 includes Sun Microsystems' 1.4.0_01 build, all defects fixed in our SDK 1.3.1 and 1.4.0 releases, as well additional enhancements and defect fixes (described in the "Problems Fixed" section).

"The 1.4.0.01 SDK runs in 32-bit or 64-bit mode. It does not work with Itanium Processor Family (IPF) systems. Support for IPF systems will be provided in a separate release."

HP-UX requires or recommends various patches from HP in order to run Java 1.4. HP users should check the list of recommended and required patches at the following Web site:

www.hp.com/products1/unix/java/patches

Additional patches are required to run S-PLUS and use the Connect/C++ features on HP-UX. These patches are listed in INSTALL.TXT.

 

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.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. You can find your new serial number on the S-PLUS 6.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.2 and proceed with the installation as described in INSTALL.TXT.

 

USING S-PLUS FOR UNIX FROM A WINDOWS DESKTOP

Solaris versions of S-PLUS may be accessed remotely from a Windows desktop using X-server software. S-PLUS has been testing with the following products:

Exceed (Hummingbird)

Reflection X (WRQ)

X-Win32 (StarNet)

The graphical user interface (GUI) performance of S-PLUS will depend upon the X-server software. The performance of the underlying S-PLUS engine is not affected.

The following notes describe configurations that have been found to produce the best results.

Exceed

Version 8.0.0 of Exceed was tested, and no significant performance problems were observed. When launching S-PLUS from an xterm, the xterm pops in front of the S-PLUS application when it first displays, and the S-PLUS application must be clicked with the mouse to recover desktop focus. Fonts were smaller than on other X-servers. Exceed seemed to have the best response time of any of the X-servers.

Reflection X

Version 10.0 of Reflection X was tested, and no performance problems were observed.

X-Win32

When using some versions of X-Win32 to start-up X-applications on your desktop, we have found that the "multiple windows" setting causes some latency in GUI response and some defects in displaying GUI elements. We recommend running in "single window" mode.

If you are connecting with XDMCP, then running in "single window" mode should present you with a default window manager from which you may run S-PLUS.

If you are connecting with rsh or rexec in "single window" mode, the application may be displayed in a "raw" X-session that lacks a window manager. We recommend that you start the Solaris default window manager (/usr/dt/bin/dtwm) using either the X-Win32 "Command" option, or from an xterm on the Solaris host. Once the window manager has been launched, the S-PLUS application should run and display successfully.

 

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 < display_name>

where <display_name > is the name of your local machine. From the Bourne- and Korn-like shells (including sh, ksh, bash, etc.), use the following commands:

% DISPLAY=< display_name>;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.2 on your system.

% Splus

% Splus -j

% 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.2 includes two additional flags, -jit and -helpoff:

 

GETTING HELP IN S-PLUS

S-PLUS 6.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 on-line 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 HTML file, a text version of these release notes is included in $SHOME/RELNOTES.TXT. 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.2 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

S-PLUS 6 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

In addition, new features to S-PLUS 6.2 are documented in four technical papers, located in $SHOME/doc/tech_papers:

Native Drivers

native_drivers.pdf

Verbose Logging

verbose_logging.pdf

XML Reporting

xml_reporting.pdf

XML Generation

xml_generation.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

Insightful Switzerland
Christoph Merian-Ring 11, 4153
Reinach, Switzerland
Tel: +41 61 717 9340 Fax: +41 61 717 9341
E-mail: info.ch@insightful.com

Insightful UK
5th Floor
Network House
Basing View
Basingstoke, Hampshire RG21 4HG
Tel: +44 (0) 1256 339800
Fax: +44 (0) 1256 339839
E-mail: info.uk@insightful.com

Insightful France
7, rue Auber
31000 Toulouse
France
Tel: +33 0 5 62 27 70 60
Fax: +33 0 5 62 27 70 61
E-mail: info.fr@insightful.com

Insightful France
67, avenue du Maréchal Joffre
92000 Nanterre
Tel: + 33 (0) 1 55 69 37 33
Fax: + 33 (0) 1 56 69 37 34
E-mail: info.fr@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

www.insightful.com/support/splus62unix

The list of S-PLUS Frequently Asked Questions is available from

www.insightful.com/support/faq.asp

 

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.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

"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 the server, you may need to use the UNIX xhost command to allow access to your X server from the S-PLUS server.

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.

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.

Database Access to Sybase

On Solaris, the current implementation of Sybase database access may fail within a Java application based on SplusUserApp with an error message:

Problem in openOrImportData(file, type, rowsToRead, ..:
Error -1 returned when opening data source '' for reading.
Internal error message was 'Error in dbopen DB-Library error:
Unable to connect: SQL Server is unavailable or does not exist.'.

If this occurs, here is a workaround:

If you wish to access the Sybase server "qaimage.insightful.com" within your SplusUserApp application, you must first execute the following Java code:

  SplusUserApp.eval("importData(type=\"directsybase\",
  server=\"qaimage.insightful.com\")\n");
  SybaseInit.initServer("qaimage.insightful.com");

This code must be called from the main Java thread. This can be done by performing these calls in the "main" function of the application, before any other threads are created.

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.

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:

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.

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.2 , 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

"Font specified in font.properties not found [fontname]."

In most cases, this and similar messages can be safely ignored.

% 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.