Matlab

From VISTA LAB WIKI

Jump to: navigation, search

This page is intended to be a resource for new users to get Matlab installed and working with the VISTA Lab software, VISTASOFT. Please take some time and read through this page to make sure that your setup is congruent with these recommendations.

Contents

[edit] Usage and Version Notes


Matlab is an essential tool for the work that we do in our lab. While the VISTA code has been used in conjunction with many versions of MATLAB, the version which has been most thoroughly used and debugged is version r2012b. These days essentially all of the debugging is now taking place in Matlab 2012b.

Some of the platform-specific problems, such as the MEX issues described in Troubleshooting, appear to be specific to some versions of MATLAB.

Earlier MATLAB versions will generally run the code, although some parts of the code utilize some MATLAB functions that are specific to newer versions.

[edit] Matlab on Linux

Running MATLAB from one of the lab linux boxes is a relatively smooth and gentle process. If you want to run MATLAB from an linux box that is not on the white network the only thing that will change will be the installation of MATLAB and the path to SPM8 and Java. Read on to learn more.

[edit] Install Matlab

Users who wish to run MATLAB on their own (NON VISTA LAB) Linux machines will have to acquire a version of MATLAB and install it locally.
If you're using one of the lab Linux boxes you need not worry about installing MATLAB. You can evoke any of a number of versions of MATLAB by simply typing the name of the version at the prompt, like so:

 $ matlab

That's it, now you're running MATLAB with one of the licenses on white.

VISTA LAB: Things should be done in this order:

  1. Download the Vistasoft GIT repository
  2. Set your paths for Vistasoft, SPM and JAVA


Non VISTA LAB: Things should be done in this order:

  1. Attain and install a version of MATLAB on your local machine
  2. Download the Vistasoft Git repository
  3. Download a copy of SPM8
  4. Set your paths for Vistasoft and SPM


[edit] Software

The following summarizes the software needed to run mrVista on Linux. People using the mrVista software tools divide into those who use and modify the software and those who use the software but do not modify it. If you simply wish to download a copy of mrVista you get get the zip file, as well as various other components, from the Software Page. People who are familiar with our methods may download the software as zip files from that site. We have never been funded to support the software. Consequently, we can not provide a full manual page or classes. If from reading our papers you feel that portions of our software would be beneficial to your research, please contact us. We have often helped colleagues get started. If we can spare the resources, and you can accommodate to our timing, we will be glad to help you.

[edit] Directory Structure

    To keep things organized we recommend that your directory structure look something like this:
    • /home/YourUserName/matlab/git/ <----- Do your GIT clone here.
    • /home/YourUserName/matlab/git/vistasoft/
    • /home/YourUserName/matlab/spm8/

[edit] GIT

We now use GitHub and GIT to manage our code repositories. Please visit the GIT page for more information regarding setting up and using GIT.


[edit] Vistasoft

    VISTASOFT is the main repository for the tools used in the VISTA Lab. The software includes methods for processing anatomical, functional, and diffusion tensor imaging data. The software is written mainly in Matlab. There are some additional utilities written in C++/VTK. All of the software runs on Linux (Red Hat). Most of the software also runs on Apple computers. The package contains: Download Options
      GIT
      Recommended for local users and those who want to contribute code or simply keep their software up to date. If you need help getting started using Git, have a look at the GIT page. # Repo URL: http://github.com/vistalab
      # Linux Checkout Command: git clone http://github.com/vistalab/vistasoft.git DOWNLOAD ZIP
      For those users who would like to quickly download a current version of the software. Clicking HERE will download a zip-file containing a current snapshot of the entire VISTASOFT repository.

[edit] Statistical Parametric Mapping (SPM)

    Everyone who uses VISTASOFT will need SPM8 functions because they are called by the mrVista code to do such things as compute transforms.
    • Information regarding downloading SPM8 and adding it to your path can be found on the SPM page.

[edit] JAVA

    MATLAB requires JAVA functionality to work properly. To add this functionality you need to add a line to your .bashrc file. If you don't know what that is, don't worry, it is just a file that specifies certain properties for your terminal sessions. Paths etc. What you need to do is add a line that points to Java. If you're non VISTA LAB you need to download and install Java and point to the downloaded version. For VISTA LAB members you need only to add the following line to your .bashrc file. cd /home/YourUserName/ gedit .bashrc add the following line anywhere in the file: export MATLAB_JAVA=/usr/local/java/jre1.6.0_07_a64 Save and restart your terminal. That's it.

[edit] Paths

Once you have the necessary software you need to point MATLAB to the software. This is done by creating a startup file which MATLAB will run each time it starts. This file will include commands to generate paths to where you have stored the software.

  • The startup.m file will go in /user/YourUserName/matlab

We have an example for you to take look at to help you create your Startup.m file. You can copy and paste startup.m a new matlab file and modify it to suit your setup (e.g., change the paths, write commands that add paths to other software that you would like in your path). Just make sure you save it as startup.m.

  • Save the modified file in your matlab directory (usually this is /user/YourUserName/matlab/). MATLAB knows to automatically execute startup.m if it finds a file with this name. All the necessary paths will be added whenever you fire up MATLAB. Note that the startup.m Linux example has commands that add the SPM8 tools to the path.

[edit] Linux Paths

To set up your shell environment you should edit your .bashrc file - which lives in your home directory in linux.


[edit] Matlab on Windows

Our lab does not develop code on or for Windows, nor do we test or debug on Windows. We recommend you move to Ubuntu Linux. However, if windows is your thing then pelase read on.
Running Matlab on Windows in such a way that everything works is a delicate process that requires Buddhist-like patience and strength of mind. That being said you should read through this section if you run MATLAB on Windows to ensure that you have a stress-free experience running VISTASOFT on your Windows machine.

[edit] Install Matlab

Users who wish to run MATLAB on their Windows machines will have to acquire a version of MATLAB and install it locally.
Things should be done in this order:

  1. Attain and install a version of MATLAB on your local machine
  2. Install GIT
  3. Download the Vistasoft Git repository
  4. Download a copy of SPM8
  5. Set your paths
  6. Install the Necessary Libraries (mrvInstall)


[edit] Software

The following summarizes the software needed to run mrVista on Windows. People using the mrVista software tools divide into those who use and modify the software and those who use the software but do not modify it. If you simply wish to download a copy of mrVista you get get the zip file, as well as various other components, from the Software Page. People who are familiar with our methods may download the software as zip files from that site. We have never been funded to support the software. Consequently, we can not provide a full manual page or classes. If from reading our papers you feel that portions of our software would be beneficial to your research, please contact us. We have often helped colleagues get started. If we can spare the resources, and you can accommodate to our timing, we will be glad to help you.

[edit] Directory Structure

To keep things organized we recommend that your directory structure look something like this:

    • C:\users\yourUserName\matlab\SPM8\
    • C:\users\yourUserName\matlab\vistasoft\ <----- Do your GIT Clone here.
You should create a directory structure that looks like the one above.

[edit] GIT

We now use GitHub and GIT to manage our code repositories. Please visit the GIT page for more information regarding setting up and using GIT.

[edit] Vistasoft

    VISTASOFT is the main repository for the tools used in the VISTA Lab. The software includes methods for processing anatomical, functional, and diffusion tensor imaging data. The software is written mainly in Matlab. There are some additional utilities written in C++/VTK. All of the software runs on Windows/XP and on Linux (Red Hat). Most of the software runs on Apple computers. The package contains: Download Options
      GIT
      Recommended for local users and those who want to contribute code or simply keep their software up to date. If you need help getting started using Git, have a look at the GIT page. # Repo URL: http://github.com/vistalab
      # Linux Checkout Command: git clone http://github.com/vistalab/vistasoft.git DOWNLOAD ZIP
      For those users who would like to quickly download a current version of the software. Clicking HERE will download a zip-file containing a current snapshot of the entire VISTASOFT repository.

[edit] Statistical Parametric Mapping (SPM)

    Everyone who uses VISTASOFT will need SPM8 functions because they are called by the mrVista code to do such things as compute transforms.
    • Information regarding downloading SPM8 and adding it to your path can be found on the SPM page.

[edit] Paths

Once you have the necessary software you need to point MATLAB to the software. This is done by creating a startup file which MATLAB will run each time it starts. This file will include commands to generate paths to where you have stored the software.

  • The startup.m file will go in C:/ProgramFiles/MATLAB/yourMatlabVersion/work

We have one sample for you to take look at to help you create your Startup.m file. You can copy and paste startup.m and vistaPath.m into new matlab files and modify each to suit your setup (e.g., change the paths, write commands that add paths to other software that you would like in your path). Just make sure you save them as startup.m and vistaPath.m respectively.

  • Save the modified files in MATLAB's work directory (usually this is C:\Program Files\MATLAB\R2007a\work). MATLAB knows to automatically execute startup.m if it finds a file with this name in its work directory, and because your startup.m calls the function vistaPath, all the necessary paths will be added whenever you fire up MATLAB. The startup.m example has commands that add the spm tools to the path.


[edit] Installing Necessary Libraries

This step is vital to ensuring the .mex files will work on your Windows MATLAB install.

If you already have the Vistasoft GIT repository (which you should by this step) then you have an easy way to install the necessary libraries. Simply start MATLAB and run:

    >> mrvInstall

Matlab requires Windows machines to have Visual Studio 2005 libraries installed to run mex-files that are compile on other systems. You must make sure that your machine has these libraries installed. The problem caused by not having these libraries, as well as the resolution, is described in a Mathworks page that illustrates the error and describes the solution.

If mrvInstall does not work for you... you can try the following:

  • Run the executable:
Matlab makes it simple to install these libraries by providing an executable that is inside of the Matlab distribution. The executable is in the Matlab program subdirectory and called either vcredist_x86.exe (32-bit machine) or vcredist_x64.exe (64-bit machine).
The procedure is described on the MathWorks page and the key step is copied here:
    Microsoft supplies, with Visual Studio 2005, a self-extracting executable that installs the required libraries.Some versions of MATLAB contain a copy of this executable file. The first version this file was shipped with was MATLAB 7.2 (R2006a). In MATLAB for Windows (32-bit), the file is named vcredist_x86.exe and is located in the directory MATLAB\bin\win32. In MATLAB for Windows x64, the file :is named vcredist_x64.exe and is located in the directory MATLAB\bin\win64. In both cases, MATLAB\bin\vcredist* is in the MATLAB root directory, as returned by typing at the MATLAB command prompt:
    >> matlabroot
Navigate to matlabroot/bin/ and execute the vcredist_x64/86.exe
  • Install the necessary .dlls needed for mrMesh
In Windows, you may need a couple of extra .dlls, msvcr70.dll and MSVCP70.dll, to run mrMeshSrv.exe. If you get this error message when you double click mrMeshSrv.exe, go ahead and download those .dlls, unzip and then save them in C:\Windows\system32\ (if it asks you if you want to overwrite one or both click yes). Those .dll files should also be copied into C:\Windows\sysWOW64.


[edit] Compiling MEX Files

When setting up the VISTA toolbox, you will probably need to compile certain C functions (called MEX files) to work with your operating system and MATLAB version. We are currently implementing tools to do this automatically. See the Compiling MEX Files page for more details on these tools.

[edit] Troubleshooting

If after following the steps above you are having problems, you can check our troubleshooting page for help.

  • Mex Files - if you are having problems related to mex files and you're seeing errors that say 'invalid mex file' or something like it you need to follow the directions under the heading "Installing Necessary Libraries. If you have the VISTASOFT GIT repository then you probably already have the solution.
Run mrvInstall -- This script will search for and install missing libraries for you.
  • Installing a Compiler -- Certain functions may have to be compiled to work on your system. In order to compile these functions you need to install a compiler. The one we recommend is Visual Studio 2008.
Download Visual Studio
  • Re-compile Source Code -- Read the source code you are trying to compile (e.g., edit readFileNifti.c). Usually Bob or Tony will have described in the comments how to compile the code on different platforms.
  • What needs to be compiled? -- For mrDiffusion, there is a script called dtiCompileMex.m, which can be found in \VISTASOFT\mrDiffusion\src\. Running this script should compile all the necessary code for mrDiffusion to work, even on 64-bit Windows machines. For other mrVista software, you should ask someone like Bob or Rory which pieces of code should be recompiled, as there is no master script yet. pnet.c is needed, but has been recompiled to work on 64-bit windows already.
  • Building the VTK mex files -- Some of our mex files use the Visualization Tool Kit (VTK) to build (build_mesh) and manipulate (smooth_mesh, curvature) cortical surface manifolds. Compiling these functions takes a little more effort than simple mex files.
  • MESH -- Before using the mesh creation utilities you will need certain Windows libraries. These are often provided by .NET or Visual Studio.
  • SPM -- Re-compiled SPM functions.


[edit] Troubleshooting

  • Mex Files -- For 64-bit linux boxes, most MEX files have been recompiled to work (and have the extension .mexa64). However, if these functions are crashing, starting MATLAB with the -glnx86 flag will cause MATLAB to start in 32-bit mode, in which it will access the older, more compatible MEX files. (Performance may not be as good as in 64-bit mode, though.) Also note that some of our tools use parts of the SPM library. We use SPM8, but things should also work with SPM2. However, we've found that under 64-bit linux, you will probably need to recompile the SPM mex files for your platform.
  • Building the VTK mex files -- Our standard Linux platform is Ubuntu 12.04. To run our 3d visualization tools, you will need the VTK libraries installed as well as an older libstc++. Running (32-bit FC8):
  yum install vtk compat-libstdc++-33

or (64-bit FC9):

  yum install vtk compat-libstdc++-33.i386 glib2.i386 gtk2.i386 libXt.i386 mesa-libGLU.i386

should install the necessary packages.

  • Installing a Compiler -- Linux already has a compiler installed, you should be able to type mex filename to compile a file for Linux.


[edit] Running MATLAB Remotely

If you are a member of the VISTA Lab with an account on white you can run a copy of MATLAB remotely. This is a rather simple process. All you need is an X terminal and access to white.

  1. Start your X server
  2. SSH into one of the machines, e.g., Teal
    ssh -XY YourUserName@teal.stanford.edu
  3. Run a version of Matlab
    >> matlab

[edit] Accounts

You will need an account on the machine that you are trying to access remotely.

[edit] Troubleshooting

[edit] Java

If you have problems with dialog boxes opening off screen when tunneling into a Linux box from another computer, you can start MATLAB with this command: 'matlab -nojvm'. You will not be able to use the editor or debugger, but can still view GUIs and with fewer problems. The command 'matlab -nodesktop' will look the same to you, but will allow interaction with the editor/debugger, and will run more efficiently than 'matlab'.

Personal tools