Xpose

File Release Notes and Changelog

Release Name: Xpose 4 release 3

Notes:
Xpose 4.0 Release 3 (2008-10-24)
--------------------------------------------
by Andrew C. Hooker, Justin J. Wilkins, Mats O. Karlsson 
and E. Niclas Jonsson

http://xpose.sourceforge.net/

Introduction
------------
Xpose 4 is a ground-floor rewrite of Xpose 3.1. Chief amongst the enhancements
to be found in the new version will be its migration from S-PLUS to R, a free,
multi-platform statistical environment, the addition of direct access to Xpose
functions from the command line, and, through R, access to Xpose tools by
third-party applications.

R and required package installation
-----------------------------------
While Xpose 4 may well work using R under other operating systems, currently 
we only support Windows and Linux platforms. To install You will need:

* R version >=2.2.0
* the Hmisc package 
* the gam package

All of these are freely available from the Comprehensive R-Project
Archive Network (http://cran.r-project.org). To install Hmisc and gam,
you have a number of options.

  Option 1: The GUI (Windows) 
  ---------------------------
  Start the R GUI, and then select "Packages" -> "Install Package(s)..."
  from the menus at the top of the screen. You will be asked for a 
  mirror - select the one that seems closest to you, geographically,
  and click OK. Select "Hmisc" from the list, and click OK. Repeat all
  steps for "gam". 

  Option 2: The R console
  -----------------------
  Start R. Enter
  
  > install.packages("Hmisc")
  > install.packages("gam")

  and the Hmisc and gam packages will be downloaded and installed from the
  default mirror.

  Option 3: The hard way
  ----------------------
  Download the binary packages for Hmisc and gam from 
  http://cran.r-project.org/src/contrib/Descriptions/Hmisc.html and
  http://cran.r-project.org/src/contrib/Descriptions/gam.html,
  respectively. Start R. Enter (in Windows, for example)

  > install.packages(c("c:/temp/Hmisc_3.0-12.zip",
			"c:/temp/gam_0.97.zip"), 
                     repos=NULL)

  assuming you put your downloaded files in the directory "C:\temp". 

  Type ?install.packages in R for more details.
 

Xpose 4 Installation
--------------------
Download the correct archive for your operating system

  * For Windows users xpose4_VERSION.NUMBER_win32.zip
  * For Linux users xpose4_VERSION.NUMBER.tar.gz

where VERSION.NUMBER should be replaced by the most recent version of
xposed released. Once you have downloaded the archive, you will need to
install the Xpose package bundle. 

  Option 1: The GUI (Windows)
  ---------------------------
  Install from R, by using the GUI. Choose the menu item "Packages" ->
  "Install packages from local zip files..." and select the zip file
  you have downloaded (e.g. xpose4_4.0.1_win32.zip).

  Option 2: The R console (Linux & Windows)
  -----------------------------------------
  Start R. Enter
  
  > install.packages("C:/temp/xpose4_4.0.1_win32.zip",repos=NULL)

  if you are using Windows, or

  > install.packages("/tmp/xpose4_4.0.1.tar.gz",repos=NULL)

  if you are using Linux. Note that this assumes that you have stored
  your downloaded files in "C:\temp" or "/tmp/". Substitute as 
  needed.

NOTE: for windows, ensure you have downloaded the BINARY
distribution. If you have the source code release
(e.g. xpose4_4.0.1_src.zip), you will need to either (a) build the
packages from source code, as below, or download the correct file and
start again.  


Building Xpose 4 from source
----------------------------
For Windows users, you will need to download the source distribution
(e.g. xpose4_4.0.1_src.zip) from the website. In addition you will
need to download some package building toolsets from the web. We
direct you to this rather useful tutorial on building R packages under
Windows: 

http://www.maths.bris.ac.uk/~maman/computerstuff/Rhelp/Rpackages.html

This description is a bit outdated but useful as well

http://faculty.chicagogsb.edu/peter.rossi/research/bayes%20book/bayesm/Making%20R%20Packages%20Under%20Windows.pdf 

In addition the R help manuals give lots of information:

http://cran.r-project.org/doc/manuals/R-admin.html#The-Windows-toolset
http://cran.r-project.org/doc/manuals/R-exts.html

Your task under Linux should be much simpler. All the tools you need ought
to be available already in almost all distributions. Simply follow the
instructions (option 2) above.  The *.tar.gz release version of xpose
4 is a compressed source distribution that can be built using the
command above.  For more help on building R packages see:

http://cran.r-project.org/doc/manuals/R-exts.html


Running Xpose 4
---------------
* Start R
* At the R command prompt, type:
  
  library(xpose4) <ENTER>
  xpose4() <ENTER>

  and use the menu system!

Each function in the bundle is now independently available from the command
line, once libraries are loaded. For example, assuming your run is called
'run5.mod', you might do the following:

* Import data

  xpdb5 <- xpose.data(5)

* Display goodness-of-fit plots

  basic.gof(xpdb5)

More help is available in the online documentation, which can be found by
typing (for example) ?basic.gof at the R command line.  Using the GUI
(Windows): From the menu system in R choose 'Help' -> 'Html help' ->
'Search Engine & Keywords' and search for "xpose4".   


Don't Panic
-----------
Andrew Hooker (andrew.hooker@farmbio.uu.se)
should be able to get you a quick answer if you run into trouble.  The
website http://xpose.sf.net  should also be of help.


Release Schedule
----------------
Bugfix releases will be released regularly, fixing any problems that are
found. 


License
-------
Xpose 4 is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this program (available in \<RHOME>\share\licenses).  
If not, see <http://www.gnu.org/licenses/>.


Known Bugs
----------------------
* None at present, but there will certainly be a few




Changes:
Xpose 4 Changelog
-----------------
24-10-2008: Minor maintenance release
  * in compute.cwres() a debugging flag had been left in the file
    resulting in R going into debugging mode when this function was
    called. This has been fixed. 

04-10-2008: Maintenance release
  * Added ability to smooth the PI.ci "area" plots so that they match
    the "line" plots.  See 'PI.ci.area.smooth' in
    xpose.pandel.default()
  * Added 'logx' and 'logy' functionality to the PI plots.
  * Changed the par.summary and cov.summary routines and removed
    functions doing almost the same thing (adding that functionality
    to the current functions). 
  * fixed GAM plot problems in xp.plot() and added more support for
    GAM from the command line.
  * Fixed a problem with ind.plots() when the ID variable is not
    called ID.
  * Changed all functions in xpose4specific that began with "abs." to
    begin with "absval." to be consistant with the rules for generic
    function definitions in R.
  * Changed name of add.abs() to add.absval().
  * Changed name of par.summary() to parm.summary().   
  * Changed name of param.vs.cov() to parm.vs.cov().
  * Changed name of param.vs.param() to parm.vs.parm().


12-06-2008: Major release
  * Added functionality for visual predictive checks
  * Added functionality for numerical predictive checks

28-09-2006: Maintenance release
  * Added generic functions xpose.draw.table, xpose.draw.cell, xpose.get.c
      and xpose.get.r for drawing tables using the graphics device (JW)
  * Added specific function param.table to display parameter estimates 
      using the graphics device (e.g. in a PDF file) (JW)
  * Added additional specific functions for:
      - IWRES distribution (histogram) (iwres.dist.hist)
      - IWRES distribution (QQ) (iwres.dist.qq)
      - ETA distribution (histogram) (ranpar.dist.hist)
      - ETA scatterplot matrices (ranpar.splom)
      - ETAs vs covariates (ranpar.vs.cov)
      - Parameter tables on the graphics device (param.table)
  * Updated compute.cwres function so that it would work without xpose 4
      Just 'source' the file (compute.cwres.R) and it should work (AH)
  * fixed problems with the run summary function (AH)
  * added new general class of printing multiple plot objects on the
    same page (AH) 
  * Fixed bug with plotting results of GAM (AH)

21-08-2006: Maintenance release
  * Bugs in 'groups' argument fixed in xpose.plot.default,
      dv.vs.pred.ipred, dv.preds.vs.idv (multiple values of x or
      y not properly handled) (JW)
  * File devices (e.g. pdf, postscript, etc) now work correctly in
      all functions (JW)
  * Bug in multiple-page covariate plots fixed (only the first page 
      would display) (JW)
  * Bug in reading table files could sometimes leave file debris, 
      which could interfere with reading subsequent data - fixed (JW)
  * Bug in covariate checking could sometimes cause plot functions 
      to fail (e.g. abs.wres.vs.pred.by.cov) - fixed (JW)
  * Bug in the classic menu system prevented display of some plots -
      fixed (JW)
  * Bug in the classic menu system prevented display of some plots -
      fixed (JW)
  * Bug in CWRES calculation fixed (AH)
  * Bug in parameter histogram display fixed (JW)
  * Missing values (defaults to -99) now handled correctly (JW)
  * QQ plots no longer display categorical variables (JW)

24-07-2006: Maintenance release
  * Bug in 'subset' argument to individual plots corrected (JW)

21-07-2006: Maintenance release
  * Online documentation cleaned up (JW) 
  * Numerous small bugs fixed (JW)
  * *nix support added (JW)
  * Multipage plots now create stacks of display windows, rather than
      stacks of plots in a single window (JW)
  * Scatterplot matrices added (JW)
  * QQ plots for parameters and covariates added (JW)
  * Generic functions renamed for consistency (JW)
  
07-06-2006: Maintenance release
  * Bugs in CWRES application and documentation fixed (AH)
  * Bugs in histogram functions fixed
      - lack of defined covariates no longer causes crash
      - customization options now work

05-06-2006: Third release ("Midnight Sun")
  * GAM added (AH)
  * CWRES plots and functions added (AH)
  * gam package now required
  * Known bugs corrected

23-04-2006: Second release ("Easter Bunny")
  * SUBSET functionality fixed for all procedures
  * Preferences, summaries and data checkout implemented
  * Box and whisker plots now do what their preferences tell them to
  * 'label' function renamed to 'xlabel' for compatibility
  * Hmisc package now required
  * Many small additions and tweaks
  * R package functionality fixed

17-01-2006: Ind.plots.R updated (AH)

24-12-2005: Initial release ("Father Christmas")
  * Xpose 4 is a completely rewritten version of Xpose 3.1, and so
    everything has changed.