Skip to content

setup

Jump to bottom
Christian Sieben edited this page Aug 11, 2018 · 16 revisions

Install Spartan

The installation of Spartan consists of downloading the source code and creating/appending to a startup.m file so that MATLAB knows where to find Spartan automatically.

  1. Download and unpack the source code, making note of the root Spartan folder.

  2. Add the following lines to a file named startup.m and place it in MATLAB's startup folder on your system. On Linux, startup.m files are often placed in /home/USER/Documents/MATLAB, but you may need to verify this for your own particular machine. (See https://ch.mathworks.com/help/matlab/matlab_env/add-folders-to-matlab-search-path-at-startup.html#btpajlr for more information.)

%% User configuration
%
spartanPath = fullfile('/', 'path', 'to', 'spartan');
srcPath = fullfile(spartanPath, 'functions');

addpath(spartanPath);
addpath(srcPath);

%% Initialize the environment
% 
env = utils.SpartanEnv.getEnvironment();

env.spartanPath = spartanPath;
                                 
clear

  1. Replace the spartanPath variable with the path to the Spartan root directory. You can either write it as an absolute string or use the fullfile method as show above.

  2. Save the file and restart MATLAB.

  3. In the command window, type env = utils.SpartanEnv.getEnvironment();. This returns a structure containing the information you just specified and assigns it to env. You can display this information by typing env in the command window to print the data to the screen. Importantly, the data stored inside this environment variable should persist, even if env is deleted. If you change the values of the structure's fields, the changes will remain until MATLAB is closed and restarted.

  4. Type SPR_head and open the main Spartan GUI window.

  1. Dependencies

Our software depends on a number of external codes, which are together with their respective licenses provided in the SPARTAN folder functions/dependencies.

  1. To detect the beads within Calculate_AffineT_from_Beads.m, we use parts of the MATLAB Particle Tracking Code repository.

  2. For DBSCAN, within particle_filter.m, we use an implementation from Michael Daszykowski.

  3. Within particle_filter.m, during the calculation of the shape descriptors, we use the script fit_ellipse.m.

  4. We use the MATLAB code provided by Nieuwenhuizen et al (Nat Methods 10, 557–562 (2013)) to calculate the resolution using Fourier Ring correlation.

  5. The 2D alignment code was developed by Xiaoyu Shi and Bo Huang and provided to us for use and incorporation into our software. The code is part of the Supplementary Software package and will also be available via the GitHub repository upon acceptance of the manuscript.

  6. The cspline fitter was developed by the Ries lab and is available on GitHub.

  7. The RCC drift correction was developed by the Huang lab and is available via their lab website.

Install Scipion (optional)

This package provides a small MATLAB interface to reconstruction routines provided by Scipion. The purpose of this interface is to conveniently setup and run single and multiparticle reconstruction workflows that are known to work for super-resolution microscopy. There are two options available in this interface. One uses an installation of Scipion that you have already installed yourself; the second uses Docker to download and launch a prebuilt version from DockerHub. If you already have Docker installed, then this will likely be the easiest approach.

Option 1: Native Scipion installation (requires Linux)

  1. You will need to follow the instructions to download and install Scipion 1.2 as detailed at https://github.com/I2PC/scipion/wiki/How-to-Install. Note that, at the time of this writing in April, 2018, Windows was not a supported operating system for Scipion.

  2. Navigate to the root Scipion folder and install the necessary EM packages using this command:

./scipion install \
    chimera \
    ctffind \
    ctffind4 \
    eman \
    frealign \
    relion \
    spider
  1. Once installed, append the following code to your startup.m file. This step assumes you already have a startup.m file for Spartan as described above:
%% Scipion configuration
%
env = utils.SpartanEnv.getEnvironment();

% The Scipion root folder
scipionPath = fullfile('/', 'path', 'to', 'scipion', 'source');
env.scipionPath = scipionPath;

% Path to the ScipionUserData folder.
userData = fullfile('/', 'path', 'to', 'ScipionUserData');
env.scipionUserDataPath = userData;

% Project template saved as part of Spartan
env.scipionSingleTemplate = fullfile(srcPath, '+em', ...
                                     'scipion_single_workflow.json');
env.scipionPairedTemplate = fullfile(env.spartanPath, 'functions', '+em', ...
                                     'scipion_paired_workflow.json');

clear

  1. Edit the line defining the scipionPath variable to point to the root directory for Scipion, respectively.

  2. Save the file.

  3. Restart MATLAB for the changes to take effect.

  4. In the command window, type env = utils.SpartanEnv.getEnvironment();. This returns a structure containing the information you just specified and assigns it to env. You can display this information by typing env in the command window to print the data to the screen. Importantly, the data stored inside this environment variable should persist, even if env is deleted. If you change the values of the structure's fields, the changes will remain until MATLAB is closed and restarted.

Option 2: Docker image (Linux and Mac)

  1. Install Docker for your system by following the instructions here. On Linux, ensure that your user account has access to the Docker daemon by adding it to the docker group as described here.

  2. Create a directory for Scipion user data if it doesn't already exist and add these lines to your startup.m file.

% Path to the ScipionUserData folder.
userData = fullfile('/', 'path', 'to', 'ScipionUserData');
env.scipionUserDataPath = userData;

% Project template saved as part of Spartan
env.scipionSingleTemplate = fullfile(srcPath, '+em', ...
                                     'scipion_single_workflow.json');
env.scipionPairedTemplate = fullfile(env.spartanPath, 'functions', '+em', ...
                                     'scipion_paired_workflow.json');

%% Docker environment variables

dockerPath = fullfile('/', 'usr', 'bin', 'docker');
env.dockerPath = dockerPath;

dockerDisplayServer = '$DISPLAY';
env.dockerDisplayServer = dockerDisplayServer;

clear

The ScipionUserData folder will live on your host file system so that the data is accessible even when the Docker Scipion container is not running. If you already added this variable to startup.m for a native Scipion install as described above, then you do not need to repeat this step.

  1. Docker should automatically download and launch the Scipion container the next time you launch a Docker-based Scipion workflow. Once downloaded, you will not need to download the image again unless you delete it from your saved Docker images.

Running Docker in Mac OS X (tested with 10.12.6)

The following steps where found in a blog post.

  • Install brew for mac

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

  • Install socat, a tool that creates a bridge between docker and the mac X window system

brew install socat socat TCP-LISTEN:6000,reuseaddr,fork UNIX-CLIENT:\"$DISPLAY\"

  • Open a new terminal tab. Install and open the Xquartz window system.

brew install xquartz open -a Xquartz

  • In the Xquartz > Preferences > Security tab, allow external network access.

  • Find your IP address and use it as a display variable for docker

ifconfig en0 docker run -e DISPLAY=XXX.XXX.XXX.XXX:0 -it --rm --name test epflbiophys/scipion:1.2

What is Scipion?

According to the Scipion website:

Scipion is an image processing framework to obtain 3D models of macromolecular complexes using Electron Microscopy.

Install Chimera (optional)

  1. Download and install Chimera by following the instructions here: https://www.cgl.ucsf.edu/chimera/download.html. Make note of the installation directory.

  2. Add the following lines to your startup.m file (assuming you already created one and configured Spartan with it as described above):

%% Chimera environment variables

chimeraPath = fullfile('path', 'to', 'chimera', 'installation', 'directory);
env.chimeraPath = chimeraPath;

chimeraScriptsPath = fullfile(spartanPath, 'files', 'python');
env.chimeraScriptsDir = chimeraScriptsPath;

Example of a complete startup.m file

%% User configuration
% This would occur in the GUI or an init script and contains the minimum
% amount of information required to run Scipion inside Spartan.

spartanPath = fullfile('/', 'path', 'to', 'Spartan');
srcPath = fullfile(spartanPath, 'functions');

addpath(spartanPath);
addpath(srcPath);

%% Initialize the environment
% Spartan only environment variables are specified here.

env = utils.SpartanEnv.getEnvironment();
env.spartanPath = spartanPath;

%% Scipion environment variables
scipionPath = fullfile('/', 'path', 'to', 'scipion');
env.scipionPath = scipionPath;

userData = fullfile('/', 'path', 'to', 'ScipionUserData');
env.scipionUserDataPath = userData;
env.scipionSingleTemplate = fullfile(srcPath, '+em', ...
                                     'scipion_single_workflow.json');
env.scipionPairedTemplate = fullfile(srcPath, '+em', ...
                                     'scipion_paired_workflow.json');
                                 
%% Chimera environment variables

chimeraPath = fullfile('/', 'usr', 'local', 'Chimera64-1.12');
env.chimeraPath = chimeraPath;

chimeraScriptsPath = fullfile(spartanPath, 'files', 'python');
env.chimeraScriptsDir = chimeraScriptsPath;

%% Docker environment variables

dockerPath = fullfile('/', 'usr', 'bin', 'docker');
env.dockerPath = dockerPath;

dockerDisplayServer = '$DISPLAY';
env.dockerDisplayServer = dockerDisplayServer;

clear

Localize/Register

Particles

Volume

SMLM Simulator

Help

Clone this wiki locally