Release Notes for S-PLUS 6 Professional Edition for Windows, Release 2 (September 2001)

These Release Notes are current as of August 29, 2001. For updates to the Release Notes that are made after this date, please see the Web site www.insightful.com/support/spluslatest.html.

This service release of S-PLUS 6 Professional Edition for Windows addresses some problems and concerns that were identified or corrected since Release 1. In particular, numerous issues were addressed regarding the design and organization of the S-PLUS 6 help system, including the following:

For a complete list of bugs fixed in this release, see the Fixed Bugs document.

This service release also includes the following new features:

  1. The Export Graph dialog now contains an All Pages check box. By selecting this box, you can export all pages of a multi-page Graph sheet to any of the supported graphics formats. Selecting the All Pages check box disables the File name field and inserts a pound sign # before the last period in the file name. When you click OK, the pages in your Graph sheet are exported individually to the file format you choose; the names of the created graphics files are based on the file name, where the # character is replaced by the page number in the Graph sheet. For example, if the File name is GS1_Page.jpg and you check the All Pages box, S-PLUS creates the files GS1_Page1.jpg, GS1_Page2.jpg, GS1_Page3.jpg, etc. To choose a file name that is different from the default, modify the File name field before selecting the All Pages check box.

    2.  
  2. The Curve Fitting Plot dialog now contains a Precision property on the Results page, which controls the precision used when inserting an equation via the Insert > Curve Fit Equation menu item. The valid range for Precision is 1 through 15, representing the number of decimal places to appear in each of numeric values that make up an equation. Values outside this range cause S-PLUS to set Precision to 4; this is equivalent to the Auto option. If you modify Precision after inserting an equation into your curve fit plot, you must re-insert the equation for the change to appear.
For completeness, the Release Notes for S-PLUS 6 Release 1 are included below. These Release Notes are identical to those included in S-PLUS 6 Release 1, with the two execeptions Improved Project Management and Getting Help on S-PLUS. Changes were made to these two sections to clarify the design of S-PLUS 6 projects and the S-PLUS 6 help system.
 
 

Release Notes for S-PLUS 6 Professional Edition for Windows (July 2001)

This file contains the following information:

About this Release
Overview of S-PLUS for Windows Version 6.0

What's New in S-PLUS 6.0

Contact Information for Feedback

Supported Platforms and System Requirements

Installation Instructions

Running S-PLUS

Backward Compatibility Issues
 

Using Data Objects from S-PLUS 2000 and Earlier

Object-Oriented Programming

Interfacing with C and Fortran Code

Changes to Pattern-Matching Functions

Other Known Backward Compatibility Issues

  Getting Help in S-PLUS

Compilers/Linkers

ABOUT THIS RELEASE

This release of S-PLUS 6.0 for Windows is a full 32-bit Windows application with an Office 97/2000-compatible graphical user interface. Before you get started, you should notice that the working data in this version of S-PLUS is stored in a .Data directory, rather than the _Data directory used in earlier versions. Similarly, the audit file is now named .Audit instead of _Audit, and the preferences directory is now named .Prefs instead of _Prefs.

The help system in S-PLUS 6.0 uses Microsoft’s current help standard, HTML Help, and contains help for both the graphical user interface and the S-PLUS engine.

For a complete tutorial of this release, see the guide Getting Starting with S-PLUS 6 for Windows. You can access this document by selecting Help > Online Manuals > Getting Started Guide from the main S-PLUS menu.

OVERVIEW OF S-PLUS FOR WINDOWS VERSION 6.0

This release of S-PLUS for Windows incorporates the S Version 4 engine used in S-PLUS 5 and later for UNIX. This engine includes specific features to add or extend S-PLUS capabilities in the following areas:

  1. Performance improvements and large data sets.
  2. Object-oriented programming model.
  3. Faster response from the graphical user interface.
  4. Loading C and Fortran code into S-PLUS, and using that code to manipulate S-PLUS objects.
  5. New CONNECT/C++ Foundation Library of C++ classes.
  6. System tracking functions.
  7. Support for dates, times, and time series data.
  8. New CHAPTER mechanism.
  9. Support for connections and raw data.
This Overview briefly discusses these additions and extensions.

1. Performance Improvements and Large Data Sets

S-PLUS 6 is much more careful than S-PLUS 2000 about reclaiming memory as it evaluates, particularly during loops and when processing source files. Many loops in S-PLUS 2000 required increasing amounts of memory as the loop progressed; in S-PLUS 6, such loops can run with a fixed amount of memory. This allows many problems to be solved in S-PLUS 6 that simply weren't possible to complete in S-PLUS 2000.

Passing an object as an argument to a function no longer requires copying the object until it is modified in the function body. This means that large objects can be passed into functions and subfunctions without consuming the time and memory required to copy the object. This makes many programs run faster, especially when dealing with large objects. This benefit arises because S-PLUS 6 objects are reference-counted, meaning that identical versions of objects across evaluation frames require only one physical copy in memory. Other than providing speed and memory improvements, reference counting does not change the fundamental way functions and objects behave.

Despite these performance improvements, reference counting may cause some rapidly iterating loops (that do little more than call a single function to perform a mathematical computation on a small amount of data, for example) to run slower in S-PLUS 6 than in S-PLUS 2000. In this situation, S-PLUS spends more time setting up function calls at each iteration than doing the computations. Such loops are better handled with other techniques such as vector arithmetic and matrix algebra, where there are usually only one or two function calls.

The apply function has also been improved. It now runs faster and uses less memory when operating on matrix arguments. The benefits are most noticeable when dealing with large matrices.

Functions have been added that allow external data files to be imported in sequential blocks, so that all of the data are not in memory at the same time. This allows you to write algorithms that process data files in small "chunks", a useful technique for dealing with data files of size that greatly exceeds the available memory. See the online help for readNextDataRows for information.

 2. Object-Oriented Programming Model All objects now have a class, including atomic objects such as vectors and matrices.

The method-dispatching mechanism has been completely overhauled. 

New functions provide more extensive support for creating classes and methods.
 3. Faster Response from the Graphical User Interface The GUI is now more tightly integrated with the S-PLUS engine. The GUI no longer needs to make separate copies of each data set for its own use. 4. Loading C and Fortran Code into S-PLUS The new CHAPTER mechanism makes compiling and loading code much simpler than before.

It is possible to manipulate all S-PLUS classes from C code using the new .Call function.

 5. New CONNECT/C++ Foundation Library of C++ Classes C++ programmers can now use the CONNECT/C++ foundation class library to simplify the task of developing full-featured client applications that use the SV4 engine for computation. See the CONNECT/C++ Class Library help for more information.

CONNECT/C++ can also simplify the task of developing S-PLUS modules. C++ programmers can use CONNECT/C++ classes and methods to manipulate S objects passed from the .Call interface. CONNECT/C++ also provides tools for interfacing to the S interpreter from inside .Call.

The source code for this library is available in the \sconnect folder of your S-PLUS home directory.

 6. System Tracking Functions Useful S-PLUS resources for measuring speed and memory include:
  The sys.time function returns a vector of 2 timings expressed in seconds, cpu and elapsed times.

The memory.size function works the same way on NT, Windows 2000, and UNIX.

 7. Support for Dates, Times, and Time Series Data
8. New CHAPTER Mechanism
    C, C++, and Fortran code is now compiled using the CHAPTER mechanism described in Creating and Managing Chapters.

    You can create chapters from either the S-PLUS Commands window or in a DOS shell. You can also create chapters from within the Microsoft Visual Studio using special Chapter Wizards installed during S-PLUS setup. See the Creating and Managing Chapters help for more information.

9. Support for Connections and Raw Data

WHAT'S NEW IN S-PLUS 6.0

In addition to the SV4-specific features mentioned in the Overview, the following are new to S-PLUS 6.0 for Windows:

  1. Support for using Excel worksheets as Active Documents within S-PLUS.
  2. New java.graph graphics device for creating S-PLUS Graphlets.
  3. Improved PowerPoint Presentation Wizard.
  4. New options for preventing conversion of character data to factors in data frames.
  5. New Robust Statistics library.
  6. New Missing Data library.
  7. New built-in statistics functions.
  8. New and enhanced graphics functions.
  9. Extended import and export capabilities.
  10. New suite of rectangular functions.
  11. New functions for manipulating character strings.
  12. Updated postscript graphics device.
  13. New world databases for the maps library.
  14. Improved Object Explorer.
  15. Improved project management.
  16. New Update Versions tool.
  17. Enhanced Grid Editor.
  18. Usability enhancements in the S-PLUS GUI.
  19. Division of GUI options into User options and Project options.
  20. New configuration files.
  21. New executeSql function to send arbitrary SQL statements to a database.
  22. New recover.nonfiles function to reconstruct corrupt __nonfi files in working data directories.
This section briefly describes these additions and enhancements.
1. Support for Excel Worksheets as Active Documents in S-PLUS
You can now open, create, and save Excel worksheets directly from S-PLUS, and use the data in those worksheets for analysis and graphics. You do this by creating links from specific cell ranges in Excel to data frames in S-PLUS. See the User's Guide for a detailed tutorial. You can access this manual by selecting Help > Online Manuals > User's Guide from the main S-PLUS menu.
2. New java.graph Graphics Device
    The new java.graph graphics device creates bitmap graphics in the SPL format, which is used to create Java graphlets. Graphlets are S-PLUS plots embedded as interactive Java applets within Web pages. The new graphics device is based on one created in S-PLUS 6.0 for UNIX/Linux. Although the UNIX version of java.graph has extensive functionality, the Windows version is used only to create graphlets.
3. Improved PowerPoint Presentation Wizard.
The PowerPoint Presentation Wizard can now export multiple pages from a single graph sheet into PowerPoint. Thus, it is no longer necessary to save each page to disk before exporting them.
4. New Options for Character-to-Factor Conversions
You can now tell S-PLUS not to convert character data to factors when creating data frames. To do this, set the stringsAsFactors argument in the data.frame function to FALSE. Alternatively, you can set the global option stringsAsFactors to FALSE via the options function; this affects all character vectors and matrices created from the command line, as well as data frames.

To ensure similar conversions for data entered in the GUI, select Options > General Settings, click on the Data tab, and set the Default Text Col. to character. This GUI option affects new data entered into Data windows, and persists from session to session within a particular project.

To prevent S-PLUS from converting character data to factors upon import, set the stringsAsFactors argument in the importData function to FALSE. Alternatively, deselect the Strings as factors option in the Import From File dialog.

5. New Robust Statistics Library
S-PLUS 6.0 includes a new Robust Statistics library, which contains the following functionality: You can see full documentation for the library by selecting Help > Online Manuals > Robust Library. To begin using this library, either type the command library(robust, first=T) at the S-PLUS command line or choose File > Load Library from the S-PLUS menu.
6. New Missing Data Library
S-PLUS 6.0 also includes a new Missing Data library, which contains software for handling missing data in S-PLUS. The library uses a model-based approach, with models fit by EM and data augmentation (Gibbs sampler) algorithms. The data augmentation algorithms produce multiple imputations; users may also use their own routines for creating multiple imputations.

The Missing Data library includes capabilities for performing arbitrary analyses "in parallel" on multiple completed data sets. Numerical results can also be combined in ways that reflect the additional uncertainty due to missing data.

You can see full documentation for the library by selecting Help > Online Manuals > Missing Data Analysis Library. To begin using this library, either type the command library(missing, first=T) at the S-PLUS command line or choose File > Load Library from the S-PLUS menu.

7. New Statistics Functions.
S-PLUS 6.0 includes the following new statistics functions: In addition, the following new functions allow you to efficiently compute row-wise or column-wise descriptive statistics: colMeans, colSums, colVars, colStdevs, rowMeans, rowSums, rowVars.
8. New and Enhanced Graphics Functions.
S-PLUS 6.0 includes the following new graphics functions: New options have also been added to the Box Plot dialog. The Box Specs page of the dialog now includes options for controlling the direction, whisker style, and limit style of your box plots. As a result, you can create horizontal box plots from the GUI. To create a box plot, choose Graph > 2D Plot > Box Plot or Graph > 2D Plot > Horiz. Box Plot from the S-PLUS main menu. You can access both types of box plots via the 2DPlots palette.

Axes in GUI plots for date variables have been improved. They now choose calendar-based tick marks based on the days, weeks, months, quarter, or years spanned by the data. To use regularly-spaced tick marks as in S-PLUS 2000, open the Axis property dialog and modify any property in the Range page.

Minor tick marks are now included by default on x and y axes in GUI plots. This improves the appearance of date and log-scale axes, but decreases the data-to-ink ratio slightly. To remove minor tick marks, open the Axis property dialog and set the Minor Tick length to 0 on the Grids/Ticks page.

9. Extended Import/Export Capabilities.
The main functions for importing and exporting data from the command line are now called importData and exportData instead of import.data and export.data. The older functions remain in S-PLUS 6.0 for backward compatibility. The following file types are now supported: The new functions support importing and exporting data via ODBC using arguments similar to those in import.data and export.data (i.e., odbcConnection and odbcSqlQuery).
10. New Suite of Rectangular Functions.
The following functions are new in S-PLUS 6.0: as.rectangular, as.char.rect, is.rectangular, sub, numRows, numCols, rowIds, and colIds. This suite of functions allows you to access all rectangular data objects (matrices, data frames, and atomic vectors) in the same way. With these functions, specific class conversions between these types of data objects are no longer necessary.
11. New Functions for Manipulating Strings.
The new substring<- function can be used to replace portions of a character string.

The unpaste function splits a character string into a list of strings according to a given separator. For example, the command unpaste(getenv("SHOME"), sep=":") separates your SHOME variable by folder and drive letter.

12. Updated postscript Graphics Device
The postscript graphics device has changed significantly in this release. For details on the new arguments implemented, see the help file for postscript.
13. New World Databases for the maps Library
A low-resolution world database for the maps library, named world.thin, is included with S-PLUS 6. A high-resolution database named world is available with a Custom installation. These databases allow you to generate a map of any country in the world. For example, the command map("world.thin","canada") generates a map of Canada.
14. Improved Object Explorer
The Object Explorer has been enhanced in S-PLUS 6.0. It is now much faster and can deal with large numbers of displayed objects in a memory-efficient manner.

The Object Explorer toolbar button now toggles the default Object Explorer on and off instead of always creating a new Object Explorer. To create a new Object Explorer in S-PLUS 6.0, select File > New > Object Explorer from the main menu.

The Object Explorer now includes the SearchPath object by default. The SearchPath is expandable, allowing you to look into attached chapters and manipulate objects. You can copy objects between chapters via drag-and-drop and you can move objects from one chapter to another by cutting and pasting.

You can also use the SearchPath object to manage the chapters in your search path. To attach a new chapter, right-click on the SearchPath object and select Attach Chapter from the context-sensitive menu. To detach or modify the read/write properties of a chapter, right-click on it and select the appropriate entry from the menu. These facilities are also available from the File > Chapters menu.

The Object Explorer now has the ability to display objects in different databases that share the same name. Objects that are masked by another object of the same name earlier in the search path are displayed with a red "X" over their icon. This gives you a visual alternative to the masked function.

By design, the components of some objects are hidden from view in the Object Explorer. For example, lm model objects appear only in the right pane of the Object Explorer. Thus, you cannot expand such objects in the left pane to access their individual components. Instead, you interact with them by right-clicking on the object and selecting the appropriate method from the menu (i.e., Plot, Summary, Predict, or Coefficients). This change was introduced in S-PLUS 2000 Release 3. S-PLUS 6 introduces a new feature to the context menu named Expand; by right-clicking on an object in the right pane of the Object Explorer and selecting Expand, you can move it to the left pane and expand its components as if it were an ordinary list. This new feature is available when you view objects in databases under the SearchPath, and is not available when you view them in regular project folders such as Data.

To make the Object Explorer easier to use, two redundant features have been removed. The Page selector at the top of the right pane is now gone; instead, use the scroll bar to page through a list of objects. The Match tool at the top of the left pane has also been removed; instead use the Find Objects button in the ObjectExplorer toolbar to search for objects that have names matching a specific pattern.

15. Improved Project Management
If enabled during installation, S-PLUS now prompts you for a project directory when it launches. The chosen project directory is used as the chapter attached in position 1 of your search path. This feature makes it unnecessary to explicitly set the environment variable S_PROJ. To enable this option while in S-PLUS, check the Prompt for project folder box in the Startup page of the Options > General Settings dialog.

Workspaces, which were introduced in S-PLUS 2000 as both a project management and a window management tool, have been replaced in S-PLUS 6 by the chapter tools found in the File > Chapters menu. To access objects from an S-PLUS 2000 workspace, use the File > Chapters > Attach/Create Chapter dialog, which adds the workspace folder to your search path. Alternatively, you can use the File > Chapters > New Working Chapter to replace the database in position 1 of your search path with a new or existing chapter; if you select an S-PLUS 2000 workspace folder, you are prompted to run it though the Migration Wizard first. See the Backward Compatibility section below for information on using old S-PLUS objects in a valid S-PLUS 6 chapter.

When attaching an S-PLUS 6 chapter, either with the Attach/Create Chapter dialog or the attach function, specify the chapter folder and not the .Data folder contained within it. However, to attach an S-PLUS 2000 database, specify the _Data folder for the database. Note that S-PLUS 2000 databases cannot be attached in position 1 of your search path. Be sure to read the section Using Data Objects From S-PLUS 2000 or Earlier below before attempting to access any of your S-PLUS 2000 databases in S-PLUS 6.

16. New Update Versions Tool
S-PLUS 6.0 includes an Update Versions tool, which checks the www.insightful.com Web site for new releases and allows you to download and install patches. Updates to this software will be released periodically; you should use the Update Versions tool to check for such updates. To use the Update Versions tool, choose Update S-PLUS from the Help menu while in S-PLUS, or choose Check for Updates in the S-PLUS program group.
17. Enhanced Grid Editor
The Grid Editor now supports a wider variety of object classes. In addition to the classes "vector", "matrix", "ts", "its", "cts", "rts", "data.frame", and "data.sheet", you can now view objects of class "array", "design", "timeSeries", "signalSeries", and "model.matrix".

In S-PLUS 6, only objects of class "vector", "matrix", and "data.frame" can be modified using the Grid Editor. S-PLUS opens all other classes (including "structure" and "named") in read-only mode, allowing you to view or graph the data; using the Data and Statistics dialogs with read-only objects is not allowed, however. You can easily convert read-only objects into editable data frames by using the Convert to Data Frame option in the Data menu or DataSet toolbar.

You can extend the capabilities of the Grid Editor to view in read-only mode objects of classes you create yourself. To do this, create appropriate methods for the generic functions getVectorNames and getVectorData.

The Grid Editor supports the new class "timeDate", which replaces the dates class from S-PLUS 2000 for date and time data. The Properties dialog for timeDate columns gives you a high level of control over display formats including the year, month, day, hour, minute, second, and time zone. The defaults for displaying and entering time and date data are automatically set from the Regional Options in the Windows Control Panel, but you can also control them from the Data and Startup pages of the Options > General Settings dialog.

When you change the name of a column in the Grid Editor to something that includes illegal characters (i.e., space or punctuation marks), S-PLUS replaces the characters with periods to form a legal column name. The original name you entered is placed in the Description field of the Properties dialog for the column (if no description is already present); it is also used as the axis label in any graphs you create.

The Change Data Type dialog now keeps the factor labels when you convert a factor column to a numeric type such as "double" or "integer". This feature is helpful if your factor column has numeric labels. In previous versions of S-PLUS, the Change Data Type dialog always converted a factor column to its codes when a numeric type was chosen as the new type. To do this in S-PLUS 6.0, use the function codes in the Expression field of the Transform dialog.

The function Edit.data can be used to open a Grid Editor from the S-PLUS command line. The Grid Editor is opened in read-only mode for objects that require it.

The Paste Link feature of S-PLUS 2000 has been removed in favor of the new Excel integration capabilities.

18. Usability Enhancements in the S-PLUS GUI
New entries under the Options menu allow you to modify the background colors of the various S-PLUS window types, including scripts, reports, graph sheets, and the Object Explorer. To see the new entries, select Options > Document Background Colors. The Commands window, which already supported this feature in previous releases of S-PLUS, can be customized by selecting Options > Command Line.

The Report window is now editable. New options in the ReportWindow toolbar allow you to modify the size, font, and style of the text that appears in an S-PLUS report. Because of these changes, reports are now saved with a default extension of *.rtf instead of *.srp (the extension that was used in earlier versions of S-PLUS).

You can now search through and save the Commands window. To search the text in the Commands window, select Edit > Find or type Ctrl-F while the Commands window is active. To save the Commands window as a plain text file, select File > Save As.

By default, the width and length options are now set to the dimensions of the current output window, including Script and Report windows as well as the Commands window. You can use the options function to disable this behavior. For example, set options(length=100) or options(width=65) to change the length and width of your output in all windows, respectively. Alternatively, you can change the settings in the Computations page of the Options > General Settings dialog; the settings you choose here apply to all windows and persist between sessions of S-PLUS for the current project. To re-enable automatic updating of these options, call options(width="auto") or options(length="auto"). The resize("auto") command changes both the length and width options simultaneously so that they are again set to the dimensions of the current output window.

19. Division of GUI Options into Two Groups
Options listed in the Startup tab of the Options > General Settings dialog are now set as User options and recorded in the Windows registry. Therefore, these settings persist from session to session and from project to project. The custom background colors for windows (described above) are also stored as User options.

All other options specified by dialogs in the Options menu are set as Project options and stored in the .Prefs directory of your projects. If you use multiple projects, you can manipulate these options on a project-by-project basis.

20. New Configuration Files
The startup sequence for the various initialization files has changed. The following functions and files are run in order (if they exist) when S-PLUS launches:
  • S-PLUS first runs the file SHOME\S.init, which contains the standard S-PLUS initialization instructions. DO NOT EDIT THIS FILE.
  • Local administrators can create and edit the file SHOME\local\S.init to specify particular actions to be performed at the start of S-PLUS sessions for all users at a particular site. This is evaluated prior to .First, so an individual may override the actions in SHOME\S.init and SHOME\local\S.init. The .First.local function, which a system administrator can create in the system database library\splus, provides another mechanism for this, although this is not recommended.
  • S-PLUS looks for the file SHOME\S.chapters, which is a text file containing paths to library sections or S-PLUS chapters. These chapters are attached to session search paths for all users at a particular site.
  • Next, S-PLUS looks for local copies of S.init and S.chapters in the current project directory. These files are analogous to the global files SHOME\S.init and SHOME\S.chapters, but they are evaluated only for a single project.
  • Finally, a user's .First function is called when S-PLUS is started. The S_FIRST environment variable, if it is set, replaces the .First function, if any.
    • 21. New executeSql Function
    S-PLUS 6 includes the new function executeSql, which can be used to send arbitrary SQL statements to a database via ODBC. For example, you can use the command executeSql("DSN=mydatabase", "INSERT into mytable values ('Hello')") to add a record to an existing table.
    22. New recover.nonfiles Function
      The new recover.nonfiles function was designed to reconstruct corrupt __nonfi files in working data directories. The only required argument is the corrupted database, specified by either its number in your search path or a character string. When called, recover.nonfiles searches the database for all files that do not have an __nonfi entry, then prompts you for names with which to restore the missing entries. As currently implemented, you must start S-PLUS and run recover.nonfiles from inside the Commands window.

    CONTACT INFORMATION FOR FEEDBACK

    North American users should send all technical support queries and general comments for this release by email to the following address:

         support@insightful.com

    In other countries, contact your local distributor for information on support options. For a list of distributors, see Insightful Corporation's Web site:

         www.insightful.com/info/distributorsmain.html

    Current information about this release is available at:

         www.insightful.com/support/spluslatest.html

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

         www.insightful.com/support/faq.html

    We are very interested in receiving information on possible bugs and usability enhancements from all users. Please send such bug reports to:

         bugs@insightful.com

    You can FAX your comments to S-PLUS Quality Assurance at the following number:

         (206) 283-8691

    Please feel free to contact us with questions or feedback. Be sure to read the section below on Backward Compatibility to see if you've encountered a known issue. A list of bugs reported against this release is available at www.insightful.com/support/spluslatest.html.

    SUPPORTED PLATFORMS AND SYSTEM REQUIREMENTS

    S-PLUS 6.0 for Windows is supported on the following:

    Windows 95, Windows 98, and Windows ME

    Windows NT 4.0 and Windows 2000 running on Intel platforms

     S-PLUS IS NOT SUPPORTED UNDER WIN32S (that is, Windows 3.1x), nor is it supported under Windows NT 3.51.

    The minimum recommended system configuration is Pentium II/233 with 96MB of RAM. You must have at least 175MB of free disk space for the typical installation (and, if not installing on Drive C:\, an additional 75MB free disk space on Drive C:\ to unpack the distribution). A complete installation requires 230MB of free disk space.

    If you have a Beta version or a Release Candidate of S-PLUS 6.0 installed on your computer, you must remove it before installing the version from this CD. To remove your existing version, run the S-PLUS Setup program as described below. If a dialog appears that displays the options Modify, Repair, and Remove, the Setup program has found an existing S-PLUS 6.0 installation. In this case, choose Remove and respond to the prompts to complete the removal of the application. To install this release, run the Setup program again and follow the instructions below.

    Do NOT install this release over any existing version of S-PLUS. Instead, designate a clean installation directory for S-PLUS 6.0 and proceed with the Setup program as described below.

    INSTALLING S-PLUS

    The S-PLUS Setup program offers a variety of options:
     
    Typical Installs all of the S-PLUS files in the selected directory, including the release notes (this document), program files, online help, sample files, development support files, and supported libraries.

    Recommended for most users.
    Compact Installs minimum files required by S-PLUS in the target directory you choose, including the release notes (this document) and the program files.
    Custom Installs only selected parts of S-PLUS. Choose whether to install the release notes (this document), program files, online help, sample files, development support files, and supported libraries.

    Any files you choose not to install can be installed later by selecting the icon for Add/Remove Programs in the Control Panel. See below for more details.

    Recommended for advanced users.

    Installing S-PLUS on Your Computer

    If the operating system of your machine is Windows NT or Windows 2000, you must have full Administrator priveleges to install S-PLUS. This is because the installation program must write to both the C:\WINNT\System folder and the registry, which is possible only if you have the correct privileges. This is a restriction imposed by InstallShield, the installation program that S-PLUS uses.

    Installing S-PLUS from the CD-ROM:

    1. Insert the CD-ROM into the CD-ROM drive.
    2. If your system has CD-ROM AutoPlay enabled, the S-PLUS Setup program starts automatically. Otherwise, click the Start button, then Run, then type x:\setup (where x is the drive letter of the CD-ROM). Alternatively, double-click the setup.exe file in the CD-ROM drive of Windows Explorer.
    3. The S-PLUS Setup window appears.
    4. Follow the Setup instructions on the screen. It is a good idea to turn off other applications while installing S-PLUS, in particular virus checkers and screen savers.
    Adding and removing components of S-PLUS: To add or remove parts of S-PLUS from your system, select the Add/Remove Programs icon in the Control Panel. Choose S-PLUS from the list of installed programs, and then click the Add/Remove button. Once in the S-PLUS Setup program, select the Modify option. Use the tree of components provided to add (select) or remove (deselect) parts of S-PLUS. Uninstalling S-PLUS from your computer: To uninstall S-PLUS, select the Add/Remove Programs icon in the Control Panel. Choose S-PLUS from the list of installed programs, and then click the Add/Remove button. Once in the S-PLUS Setup program, select the Remove option.

    RUNNING S-PLUS

    Options in the S-PLUS Program Group:

    In the S-PLUS program group, you can choose to start S-PLUS 6 (full GUI application) or the S-PLUS console (command line prompt). You can also view help on creating chapters and using the new CONNECT/C++ class library, in addition to viewing the Release Notes (this document).

    After installing S-PLUS, the S-PLUS program group appears as an option under Programs when you click the Start button.

     To start S-PLUS with the full graphical user interface:
    1. From the Start menu, choose Programs.
    2. Choose the S-PLUS program group.
    3. Choose S-PLUS 6.
    To start S-PLUS as a console application without the GUI:
    1. From the Start menu, choose Programs.
    2. Choose the S-PLUS program group.
    3. Choose S-PLUS Console.
    S-PLUS determines the location of SHOME based on the following rules: S-PLUS determines the location of S_PROJ based on following rules:

    BACKWARD COMPATIBILITY ISSUES

    S-PLUS 6.0 for Windows uses a completely reengineered implementation of the S language. OBJECTS CREATED WITH S-PLUS 6.0 CANNOT BE USED WITH EARLIER VERSIONS OF S-PLUS. You should always run S-PLUS 6.0 in an S-PLUS 6.0 chapter as described in the installation instructions; this ensures that your working directory contains only objects created in S-PLUS 6.0. You can use older objects in S-PLUS 6.0, but you should access them by attaching directories in a position other than 1 in the search list so that S-PLUS 6.0 does not accidentally write to them. If S-PLUS 6.0 does not write to an SV3 _Data directory, it can still be used by S-PLUS 2000 and earlier.

    Much of the graphical user interface, with the exception of the Object Explorer, is virtually identical to that of S-PLUS 2000. In particular, the GUI toolkit of guiXX functions is 100% compatible with S-PLUS 2000. Scripts using these functions should run with no modifications in S-PLUS 6.0.

    The class mechanism is completely different from that in earlier versions of S-PLUS, and there are many changes to many fundamental functions. Backward compatibility was a design consideration of paramount importance, so most examples from earlier books on S and S-PLUS should run without modification. However, data objects created with S-PLUS 6.0 are different from objects created with S-PLUS 2000 and earlier.

    Using Data Objects From S-PLUS 2000 and Earlier

    Do not run S-PLUS 6.0 using a data directory created by S-PLUS 3.x, 4.x, or 2000 as your working directory. If you have extensive collections of user-written S-PLUS functions, you should use the Migration Wizard to convert them to a form accepted by S-PLUS 6.0 for Windows. The S-PLUS Migration Wizard is designed to step you through the process of converting an older project for use in S-PLUS 6.0. The wizard converts an entire project when invoked, including any document objects such as graphs, scripts, and reports.

    You can start the Migration Wizard from either inside or outside of S-PLUS as follows:

    To convert an existing project folder for use with S-PLUS 6.0, follow the steps below. Each of these steps represents a screen shown by the wizard during the migration process.
    1. Start the Migration Wizard.

      2.  
    2. Specify the project folder you want to convert by typing its path name in the text box, or by clicking Browse and navigating to it.

      3.  
    3. Specify a new project folder to contain the migrated files by typing its path name in the text box, or by clicking Browse and navigating to it. If the folder you specify does not already exist, the wizard creates it and initializes it as a valid S-PLUS chapter. The new project folder must be a new or empty folder. If the folder you specify already contains files, the wizard does not continue.

      4.  
    4. Select the files in the old project folder that you want to migrate. By default, all files are selected. Special folders, such as the _Data object directory and the _Prefs preferences directory, are indicated by a small blue asterisk in the center of the folder’s icon. Individual files contained in a special folder are not selectable; if a special folder is selected, all the files in it are migrated. This screen also displays the total number of bytes required to migrate the selected items. As you select or deselect items for migration, this figure is immediately updated.

      5.  
    5. Specify where you want to save the migration log file by typing a path name in the text box, or by clicking Browse and navigating to the location. During the migration, the wizard saves useful status and error information in the log file. After the migration, you can examine this text file to see the progress made on individual items.

      6.  
    6. Before you click Finish to launch the migration, the wizard informs you what actions will be taken during the process. As the migration progresses, each source file/folder and its corresponding target file/folder are displayed. The progress indicator is updated after each item is migrated, so you can see how far along the migration is. The Migration results pane displays the same information that is stored in the log file. When the migration is complete, a final COMPLETED message appears in the Migration results pane, with the progress indicator at 100%. You can use the scroll bar to scroll through the Migration results pane to see each item and the result of migration.

      7.  
    7. Click Close to exit the wizard, or click Back to back up to a previous step and perform a different migration.
    There are two areas that are not handled by the Migration Wizard: multiple inheritance and local assignment before modification. Thus, if you need to access old objects that inherit from multiple classes, you must regenerate them in S-PLUS 6.0. An example of this is nlme objects; the Migration Wizard cannot convert old-style nlme objects into a version that is compatible with S-PLUS 6.0, so you must regenerate them. Likewise, if you have code that modifies built-in data sets, you must assign the objects locally before they can be modified in S-PLUS 6.0; see Object-Oriented Programming below.

    Object-Oriented Programming

    The object-oriented programming model has changed in this version of S-PLUS as well. Although the old model based on UseMethod still works for old-style classes, it does not work for new classes and old unclassed objects (which now have explicit classes). You cannot define old-style methods for new classes.

    S-PLUS 6.0 for Windows has a stronger functional programming model than before. To support this, several changes have been made in S-PLUS behavior:

    1. Objects must be assigned to the working data directory before they can be modified by replacement functions. Earlier versions of S-PLUS automatically assigned the modified object to the working data.

      2.  
    2. Generic functions, their methods, and their group generic must all have identical argument lists. This is not a problem for functions defined using the old class mechanism, where generic functions are defined in terms of the UseMethod function. However, methods defined for internal generics, such as the subscripting function "[", must obey this convention. They must also be defined somewhat differently to work properly in S-PLUS 6.0. If you have such methods for your own classes, use the new setMethod function to define that function as a method before attempting to use it in S-PLUS 6.0 for Windows. For example, the old-style method "[.data.frame" had a different default for its drop argument than the default internal method. To make this method work in S-PLUS 6.0, it was necessary to use setMethod as in the command below.

      3.   setMethod("[", "data.frame", where = ".", function(x, ..., drop = T)
      { if(missing(drop)) "[.data.frame"(x, ...) else "[.data.frame"(x, ..., drop = drop) }       )


      Failure to observe this rule will cause difficulties in substitute, sys.parent, nargs, sys.call, match.call, missing, and default argument evaluation, among others.

    Interfacing with C and Fortran Code

    Dynamic loading and static loading (the LOAD utility) are no longer supported. Compiled code is now added to S-PLUS by means of dynamic linking, using the CHAPTER mechanism described in the Programmer’s Guide.

    The pointers argument is now absent from .C. Compiled code that uses the pointers argument will crash S-PLUS. Much of the functionality that the pointers argument was intended to support is now supported by the new .Call function, which allows you to manipulate arbitrary S objects, including objects of user-defined classes.

    The file S.h has changed significantly in S-PLUS 6.0. In particular, constants such as TRUE, FALSE, DOUBLE, and INT have been renamed to avoid names that are commonly used in other software packages that S-PLUS must coexist with. For details, see the Programmer's Guide.

    C and Fortran code used with S-PLUS 2000 and earlier needs to be recompiled before it can be used with S-PLUS 6.0.

    Changes to Pattern-Matching Functions

    In previous versions of S-PLUS, a number of functions had pattern arguments specifying a pattern to be matched, with the pattern-matching semantics being platform dependent. In UNIX versions, the operating system's grep utility was used while in Windows versions, a close approximation of filename wildcard matching was used. In S-PLUS 6.0 for Windows, the behavior of the pattern argument for these functions is retained, and a regexpr.pattern argument has been added. Because they use the regexpr function (regular expression pattern matching), the pattern-matching semantics for the regexpr.pattern arguments are platform independent. These functions are: 

    again, find.objects, history, objects, objects.summary.
         To illustrate these changes, consider trying to find all objects with names ending in ".myobj". Using a UNIX version of S-PLUS, one command is: > objects(pattern="\\.myobj$") Using S-PLUS for Windows, a command is: > objects(pattern="*.myobj") The following command works in either version of S-PLUS: > objects(regexpr.pattern="\\.myobj$") To maintain backward compatibility in S-PLUS for Windows, the regexpr.pattern argument to the again and history functions may still be a logical value indicating whether the pattern argument is to have regexpr-style semantics. If not, or if only the pattern argument is specified, simple text-matching semantics (i.e., no wildcards) is used, as was the case in earlier Windows versions.

    In previous versions of S-PLUS, the grep function's pattern argument also had platform dependent semantics. In S-PLUS 6.0, the old behavior is retained in the function oldGrep, and the grep function now has platform independent behavior that uses regexpr. To illustrate these changes, consider trying to find the index in a character vector x of all elements that start with "my.". Using S-PLUS for UNIX, one command is:

    > oldGrep("^my\\.", x) Using S-PLUS for Windows, a command is: > oldGrep("my.*", x) The following version works in either version of S-PLUS: > grep("^my\\.", x) A new regexpr.replace function has also been added to S-PLUS 6.0, which replaces patterns matched within elements of a character vector. The pattern argument to the new function has the same semantics as that for the regexpr function. A future enhancement will allow portions of the matched pattern to be part of the replacement, as can be done with the "\1" construct of the UNIX sed utility; e.g. ‘s/my\(.*\)/your\1/g’.

    Other Known Backward Compatibility Issues

    Use data.dump(..., oldStyle=T) to dump compatible objects from S-PLUS 6.0 for use in S-PLUS 2000 and earlier. The data.dump function can now only dump from one database at a time, as specified by the new where argument. By default, where=1.

    GETTING HELP ON S-PLUS

    To obtain help on a particular function in this release, use the help or ? functions. 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 S-PLUS 6, the help files for GUI and command line functions are completely separate. To access all of the GUI help files, select Help > Available Help > S-PLUS Help; to access all of the command-line help files, select Help > Available Help > Language Reference. If you ask for help primarily by clicking on Help buttons in dialogs, you'll want to access S-PLUS Help on a regular basis for its Contents, Index, and Search tabs. Likewise, if you ask for help primarily through the help or ? functions, you'll want to access the Language Reference on a regular basis for the Contents, Index, and Search tabs available there.

    COMPILERS/LINKERS

    S-PLUS 6.0 is built with Microsoft VC++6.0 and Compaq/DEC Fortran 6.0. All samples shipped with S-PLUS 6.0 have been tested with VC++6.0 and Compaq/DEC Fortran 6.0. If you use Microsoft VC++6.0 and Compaq/DEC Fortran 6.0 in your projects that link to S-PLUS, use the import libraries in SHOME\lib. For example sqpe.lib is the import library for sqpe.dll containing the core S-PLUS interpreter, and sconnect.lib is the import library for sconnect.dll containing the CONNECT/C++ class library.

    File input and output is fully supported in C code called from S-PLUS, but input and output directed to the standard streams STDIN, STDOUT, and STDERR requires special handling. This special handling is provided by the header file newredef.h, which is included in S.h and sconnect.h. If you need to disable this behavior, define NO_NEWIO before S.h or sconnect.h. For example:

    #define NO_NEWIO
    #include "S.h"