Installing Probability Tools

Option 1: Executable with Graphical Interface

There are two options for installing the wavelet probability analysis toolkit: command-line Matlab scripts, or a standalone executable which includes a graphical user interface (GUI). The current version of the GUI is labeled version “0.3”, which addresses some issues with inputting reference datasets.


Executables are located here:


  1. - WPAnalysisv0p3_Mac32_pkg.zip:  distribution for Macintosh 32-bit systems

   WPAnalysisv0p3_Mac_64bit_pkg.zip: distribution for Macintosh 64-bit systems


  1. - WPAnalysisv0.1_WinXP_pkg.exe: distribution for Windows XP (note: Windows packages are executables, unlike Mac packages)


  1. - WPAnalysisv0p3_Unix_pkg.zip: distribution for Unix/Linux


Scripts may be found here:


http://atoc.colorado.edu/~slsteven/wpitoolkit.tar

 



For ease of use, the scripts described below (see “Option 2”) have been compiled into a single stand-alone executable. The executable has all of the functionality of the command-line scripts; its major limitation is that custom formatting of plots (changing axis limits etc.) is not currently possible. However, the executable will allow the output of any calculation to be saved as a Matlab “.mat” file, so that custom plotting may be performed after the fact.


Installation is as follows. I also include an example of the actions required for each operating system.


Mac OS X


  1. 1.Download the appropriate distribution package for your operating system.


  1. 2.Unpack the file: on Mac, this may be done automatically.


  1. 3.Unpacking the file will create a directory called “WPAnalysisv1_Mac_[arch]”, where [arch] is either “32bit” or “64bit” depending on your machine.


    If you already have Matlab installed, skip to step 4. If you do not have Matlab installed on your machine, then you need to use the

    included disk image “MCRInstaller.dmg”, to install the “Matlab Compiler Runtime”, or MCR. This will allow the machine to execute

    Matlab scripts without a Matlab license.

   

    To mount the image, simply double-click on MCRInstaller.dmg; this will pop up a window labeled “MATLAB_Compiler_Runtime”,

    within which is an installation package called “MCRInstaller.pkg”. Double-click on this package and follow the installation

    instructions.


  1. 4. Once the MCR has been installed, you are now ready to run the analysis package.


    Mac OS X requires that several environment variables be properly set in order to run the package; an easy way to set these

    automatically is to use the shell script included with the WPAnalysis package.


    The shell script is found in the “WPAnalysis” directory mentioned above; in a terminal window, cd to that directory and issue the

    command “sh run_WPAnalysisv1_Mac.sh [Matlab directory]”.

    [Matlab directory] will be the location of the directory containing either your Matlab installation or the MCR.


    For example, on a Mac with a native Matlab installation, the Matlab directory will typically be /Applications/MATLAB_R2009b/,

    or MATLAB_[version] if you have a different version installed.

    If you have installed the MCR, your Matlab directory will be the installation location you gave your machine.


    For both Matlab and the MCR, note that the trailing slash should be left off to ensure proper functioning of the shell script.


    The “run_WPAnalysisv1_Mac” script will launch the GUI and you may proceed from there; see “Running the Toolkit” for more

    details on specific calculations.



    Example: Installing the 32-bit Mac GUI from a folder on your Desktop:

    - download the zip file from the Web

        on my laptop that is the 32-bit version WPAnalysisv1_Mac_32bit_pkg_feb11_2010.zip


    - unpack the zip file

       I downloaded to my Desktop folder; this makes a folder called WPAnalysisv1_Mac_32bit_pkg_feb11_2010 on the desktop.


    - since I already have Matlab installed, I don't need to install the MCR. So I open an X window:

        bash-3.2$  cd Desktop

        bash-3.2$  cd WPAnalysisv1_Mac_32bit_pkg_feb11_2010


        bash-3.2$ sh run_WPAnalysisv1_Mac_32bit.sh /Applications/MATLAB_R2009b.app


        In the X window is displayed:

        ------------------------------------------

        Setting up environment variables

        ---

        DYLD_LIBRARY_PATH is .:/Applications/MATLAB_R2009b.app/runtime/maci:/Applications/MATLAB_R2009b.app/bin/maci:/       

        Applications/MATLAB_R2009b.app/sys/os/maci:/System/Library/Frameworks/JavaVM.framework/JavaVM:/System/Library/

        Frameworks/JavaVM.framework/Libraries


        then the GUI pops up on my screen. Note that the GUI focus seems to be set such that the window appears behind existing

        windows on your screen, so you may want to move windows around to be sure that it has deployed successfully.





Windows


  1. 1.Download the appropriate distribution package for your operating system.


  1. 2.On Windows machines, the distribution package is actually itself an executable; double-click on the package to activate. What will happen is that a series of prompts will appear, giving you options for installation.


    The first thing to be installed is the Matlab Compiler Runtime (MCR), same as for Macs; this is required in order to run the

    main program.


    After installation of the MCR, the install wizard will create a .exe file called “WPAnalysisv1_WinXP” in your desired install location.

    This functions the same way as any other Windows application; just double-click to start the program. See “Running the Toolkit”

    for more details on specific calculations.


    Example: Installing the Windows XP GUI from a folder on your Desktop:


    - Download the .exe file from the Web: this should be WPAnalysisv1_WinXP_pkg.exe


    - Click on “My Computer” or otherwise open a file-browsing window. Click on the “Desktop” icon on the side to display the

       contents of the Desktop.


    - Double-click the icon for WPAnalysisv1_WinXP_pkg.exe. This will start the MCR Installer, as well as unpacking the rest of the

      package. Follow the prompts to complete installation of the MCR.


    - Now there should be an icon called simply “WPAnalysisv1_WinXP” on the Desktop. Double-click this to start the GUI.





Unix/Linux


The process for Unix/Linux is very similar to that for Mac. Instead of a self-extracting executable, as in the Windows case, the package must again be downloaded and installed manually.


  1. 1.Download the appropriate package for your operating system. The “WPAnalysisv1_Unix” package should run on most Unix and Linux systems; if this is not the case please contact Samantha Stevenson at samantha.stevenson@colorado.edu.


  1. 2.Unzip the package. Note that the file does not end in the standard .gz extension, but .zip; this may mean that you need to run “unzip” rather than “gunzip” on your system.

   

    Unzipping will extract the contents of the package to the local directory; you may want to create a directory to store the contents.


  1. 3.If Matlab is not installed on your machine, you will need to run the MCR installer, which is included with the package. The MCR installer is a Unix binary file, which can be executed on the command line. Some machines may require the ./ prefix; in other words you may need to type “./WPAnalysisv1_Unix.bin” rather than simply “WPAnalysisv1_Unix.bin”.


  1. 4.After the MCR has been installed, or if Matlab is already running on your system, use the included shell script to launch the GUI. This will be a file called “run_WPAnalysisv1_Unix.sh”. The syntax is the same as for the Mac installation; issue the command

    “sh run_WPAnalysisv1_Unix.sh [Matlab directory]”, where [Matlab directory] is the location either of Matlab or of the MCR.


    The directory syntax is similar to that for Mac OS X: after you have installed the MCR, give the installation location as the argument

    to run_WPAnalysisv1_Unix.sh. For example, if you have installed the MCR to a directory on your desktop called MCRdir, you will

    issue the command


    sh run_WPAnalysisv1_Unix.sh /Desktop/MCRdir/

    to run the GUI.


    Note that for systems running a native Matlab installation, the location required by the shell script is *not* the location of the Matlab

    binary file, but rather the location of the distribution. On most machines, this is typically something like /usr/local/matlab.

    To locate your native Matlab directory, use “which matlab”.


   Example: Installing the Unix GUI from a folder in your home directory:


    - Download the .zip file from the Web: this should be WPAnalysisv1_Unix_pkg.zip


    - Make a directory for the package contents:

        bash-3.2$ mkdir WPdir

        bash-3.2$ cd WPdir

        bash-3.2$ mv ../WPAnalysisv1_Unix_pkg.zip .


    - Extract the package:

       bash-3.2$ unzip WPAnalysisv1_Unix_pkg.zip


    - Run the MCR Installer if necessary:

        bash-3.2$ ./MCRInstaller.bin


    - Run shell script to execute the program: in this case I will use the local installation of Matlab.

        bash-3.2$ sh run_WPAnalysisv1_Unix.sh /usr/local/matlab

        This command should start up the GUI.






Option 2: Matlab Scripts




Codes for all calculations have been created in Matlab: for running the scripts on the command line, you may install the tarfile available at wpitoolkit.tar


The tar file contains the following Matlab scripts:


Calculation scripts

ciregress.m: regression of WPI confidence interval width vs. record length

emp_hyptest.m: empirical hypothesis testing procedure for WPI distributions

selfsim.m: self-overlap WPI distribution calculation

wpi.m: driver code to calculate the value of WPI

wpicomp.m: calculates comparison WPI distribution between two datasets


Wrapper (plotting) scripts

plot_emphyptest.m

plot_selfsim.m

plot_wpicomp.m


Datasets: in directory ExampleData

All datasets are monthly NINO3.4 time series

CCSMcontrol_CCSM3.5_T31x3_nino34monthly.txt:                             1200-year CCSM3.5 integration

RHLOW_CCSM3.5_T31x3_nino34monthly.txt:                                      600-year CCSM3.5 integration

COREhindcast_1949to2003_LargeandYeager_nino34monthly.txt:       55-year ocean hindcast of Large & Yeager (2004),

                                                                                                                covering 1949-2003


Examples: in directory ExampleCalculations

ar1vscore.m:      hypothesis testing on the CORE hindcast vs. CORE with AR(1) noise added

rhlowvscore.m: model validation of RHLOW vs. the CORE hindcast




Installation Procedure for Command-Line Package


Installing the command-line scripts should proceed the same way on all operating systems. To install the wavelet probability toolkit:


  1. 1.Download the tarfile containing Matlab scripts: http://atoc.colorado.edu/~slsteven/wpitoolkit.tar


  1. 2.Unpack the file, if this is not automatic on your system. This will result in the creation of a directory called “wpitoolbox”, with subdirectories “ExampleData” and “ExampleCalculations”.


  1. 3.Download and install the wavelet toolkit of Torrence & Compo:

    http://paos.colorado.edu/research/wavelets/software.html

    This need not be in the same directory as the wavelet probability toolkit.


  1. 4.Once inside Matlab, run the startup script found in the “wpitoolbox” directory. Script is called wpistartup.m, and will prompt you for the locations of both the Torrence & Compo toolkit and the wpitoolbox directory itself. These locations will be added to your Matlab path, which will then enable all the relevant tools to function without changing the directory from which Matlab is run.