Installation

Spring has been successfully run on Linux and MacOSX systems with the help of Conda that is a popular open source package management system for python packages. We base our most recent distribution of Spring for standard Linux and Mac systems on EMAN2 version2.91.

Prerequisites

Mac

  • Requirements: Xcode including Python with X11

MacOSX (10.8 - 10.15, 11)

  1. Xcode

  2. +command line tools

  3. X-Quartz

Launch the App Store and download Xcode. After it is installed, you need to install the Command Line Tools. This will install the default OS X Python binary.

  1. MacOSX 10.8: in Xcode’s preferences, go to the Downloads tab and install Command Line Tools.

  2. MacOSX 10.9 - 10.15, 11 (Big Sur):

% xcode-select --install

Wait until install completed. In order to activate Xcode developer tools, make sure to agree with the license:

% sudo xcodebuild -license

Acknowledge reading by typing agree after scrolling down.

Install the X11 window manager X-Qartz on your system.

Install by Conda

Due to the many python dependencies, we extended an EMAN2’s base conda environment (version 2.91) for SPRING.

Linux

Launch the install script below.

% wget https://spring.fz-juelich.de/_download/install_linux.sh
% sh install_linux.sh

#!/bin/sh
#author: Carsten Sachse
#date: 15-Mar-2021
#version: 0.4    
#usage: sh install_linux.sh
echo '================================================================================='
echo ' --------------------------- Running install_linux.sh ---------------------------'
echo 'This script will download and test Spring including required components on '
echo 'linux using Anaconda'
echo '================================================================================='
if [[ ${CONDA_PREFIX+x} ]]; then
  	echo 'Another version of conda is already active. Deactivate existing environment'
  	echo '   and re-run the installer.'
  	echo $'\nconda deactivate\n'
  	exit 0
fi
	
echo 'Specify installation directory of SPRING'
read INSTALLDIR

echo '---------------------------------------------------------------------------------'
echo '1. Install EMAN2 in specified directory.'
echo '---------------------------------------------------------------------------------'
STARTDIR=${PWD}
if [ -f ${STARTDIR}/eman2.91_sphire1.4_sparx_huge.linux64.sh ]; then
	echo found EMAN2 file.
else
	wget https://cryoem.bcm.edu/cryoem/static/software/release-2.91/eman2.91_sphire1.4_sparx_huge.linux64.sh
fi

sh eman2.91_sphire1.4_sparx_huge.linux64.sh << EOT
${INSTALLDIR}
y
EOT

echo '---------------------------------------------------------------------------------'
echo '2. Install additional python packages required for SPRING.'
echo '---------------------------------------------------------------------------------'
PKGEXT=package-extend.txt
cd ${INSTALLDIR}/bin
BINDIR=${PWD}
cd ${STARTDIR}
echo https://conda.anaconda.org/conda-forge/linux-64/mpi4py-3.0.1-py37hd955b32_0.tar.bz2#a8d6d7bbfc42b60c93055265d4df15a1 > $PKGEXT
echo https://repo.anaconda.com/pkgs/main/linux-64/tabulate-0.8.9-py37h06a4308_0.conda#c32cab843dc3438861fc2a57dec9504f >> $PKGEXT
echo https://repo.anaconda.com/pkgs/main/linux-64/sqlalchemy-1.3.23-py37h27cfd23_0.conda#2735db8ef0248df3e21603ae90840a43 >> $PKGEXT
echo https://repo.anaconda.com/pkgs/main/linux-64/vispy-0.5.3-py37hee6b756_0.conda#b59cd485c209f6de0a64b2c415cb7bd9 >> $PKGEXT
${BINDIR}/conda install --yes --file $PKGEXT 
rm -f $PKGEXT

echo '---------------------------------------------------------------------------------'
echo '3. Install CTFFIND binaries linux.'
echo '---------------------------------------------------------------------------------'
if [ -f ${STARTDIR}/ctffind-binaries-linux.tar.gz ]; then
	echo found ctffind binary files.
else
	wget https://spring.fz-juelich.de/_download/ctffind-binaries-linux.tar.gz
fi

cd ${BINDIR}/..
tar -xvzf ${STARTDIR}/ctffind-binaries-linux.tar.gz 
cd ${STARTDIR}

echo '---------------------------------------------------------------------------------'
echo '4. Install SPRING.'
echo '---------------------------------------------------------------------------------'
wget https://files.pythonhosted.org/packages/c7/c0/881d59f0aaa676142fedea7fb789fe35f22bae3746497db04663b95f7686/emspring-0.87.1724.tar.gz
tar -xvzf emspring-0.87.1724.tar.gz
cd emspring-0.87.1724
${BINDIR}/python setup.py install
cd ${STARTDIR}
rm -rf emspring-0.87.1724 emspring-0.87.1724.tar.gz

echo '================================================================================='
echo "Install done. Spring was installed with EMAN2/SPHIRE in ${INSTALLDIR}" 
echo 'and the conda environment has been added to your startup shell script.'
echo '=======> For changes to take effect, close and re-open your current shell. <====='
echo '================================================================================='

exit 0

Mac

Launch the install script below.

% curl --remote-name https://spring.fz-juelich.de/_download/install_mac.sh
% sh install_mac.sh

#!/bin/sh
#author: Carsten Sachse
#date: 15-Mar-2021
#version: 0.4    
#usage: sh install_mac.sh
echo '================================================================================='
echo ' --------------------------- Running install_mac.sh -----------------------------'
echo 'This script will download and test Spring including required components on '
echo 'mac using Anaconda'
echo '================================================================================='
if [[ ${CONDA_PREFIX+x} ]]; then
  	echo 'Another version of conda is already active. Deactivate existing environment'
  	echo '   and re-run the installer.'
  	echo $'\nconda deactivate\n'
  	exit 0
fi
	
echo 'Specify installation directory of SPRING'
read INSTALLDIR
echo '---------------------------------------------------------------------------------'
echo '1. Install EMAN2 in specified directory.'
echo '---------------------------------------------------------------------------------'
STARTDIR=${PWD}
if [ -f ${STARTDIR}/eman2.91_sphire1.4_sparx_huge.MacOS.sh ]; then
	echo found EMAN2 file.
else
	curl --remote-name https://cryoem.bcm.edu/cryoem/static/software/release-2.91/eman2.91_sphire1.4_sparx_huge.MacOS.sh
fi

sh eman2.91_sphire1.4_sparx_huge.MacOS.sh << EOT
${INSTALLDIR}
y
EOT

echo '---------------------------------------------------------------------------------'
echo '2. Install additional python packages required for SPRING.'
echo '---------------------------------------------------------------------------------'
PKGEXT=package-extend.txt
cd ${INSTALLDIR}/bin
BINDIR=${PWD}
cd ${STARTDIR}
echo https://conda.anaconda.org/conda-forge/osx-64/mpi4py-3.0.1-py37h27a7d74_0.tar.bz2#161874d6435d21909ab8087d75519ae7 > $PKGEXT
echo https://conda.anaconda.org/conda-forge/noarch/tabulate-0.8.9-pyhd8ed1ab_0.tar.bz2#ee657dbe69e892aeccde7cabb4edf261 >> $PKGEXT
echo https://conda.anaconda.org/conda-forge/osx-64/sqlalchemy-1.3.23-py37h7585375_0.tar.bz2#0064112e193874f87c6156ebf7c735ed >> $PKGEXT
echo https://conda.anaconda.org/conda-forge/osx-64/vispy-0.6.6-py37h7d46f5f_0.tar.bz2#d50270dbe201b6f2aa621a353856e678 >> $PKGEXT
${BINDIR}/conda install --yes --file $PKGEXT 
rm -f $PKGEXT

major_version=`sw_vers -productVersion | cut -d. -f1`
if [ $major_version -eq 11 ];then
	echo "---\nPatch vispy in Big Sur fixing ctype errors https://github.com/vispy/vispy/issues/1885#\n---"
	echo "--- lib/python3.7/site-packages/vispy/ext/cocoapy.py   2021-03-19 22:26:43.000000000 +0100
	+++ lib/python3.7/site-packages/vispy/ext/cocoapy.py     2021-01-13 04:16:41.000000000 +0100
	@@ -1120,7 +1120,7 @@
	 
	 # Even though we don't use this directly, it must be loaded so that
	 # we can find the NSApplication, NSWindow, and NSView classes.
	-appkit = cdll.LoadLibrary('/System/Library/Frameworks/AppKit.framework/Versions/Current/AppKit')
	+appkit = cdll.LoadLibrary(util.find_library('AppKit'))
	 
	 NSDefaultRunLoopMode = c_void_p.in_dll(appkit, 'NSDefaultRunLoopMode')
	 NSEventTrackingRunLoopMode = c_void_p.in_dll(" > cocoapy.patch
	 cd ${BINDIR}/..
	 patch -Ru lib/python3.7/site-packages/vispy/ext/cocoapy.py ${STARTDIR}/cocoapy.patch
	 cd ${STARTDIR}
	 rm -f cocoapy.patch
fi

echo '---------------------------------------------------------------------------------'
echo '3. Install CTFFIND binaries mac.'
echo '---------------------------------------------------------------------------------'
if [ -f ${STARTDIR}/ctffind-binaries-mac.tar.gz ]; then
	echo found ctffind binary files.
else
	curl --remote-name https://spring.fz-juelich.de/_download/ctffind-binaries-mac.tar.gz
fi

cd ${BINDIR}/..
tar -xvzf ${STARTDIR}/ctffind-binaries-mac.tar.gz 
cd ${STARTDIR}

echo '---------------------------------------------------------------------------------'
echo '4. Install SPRING.'
echo '---------------------------------------------------------------------------------'
curl --remote-name https://files.pythonhosted.org/packages/c7/c0/881d59f0aaa676142fedea7fb789fe35f22bae3746497db04663b95f7686/emspring-0.87.1724.tar.gz
tar -xvzf emspring-0.87.1724.tar.gz
cd emspring-0.87.1724
${BINDIR}/python setup.py install
cd ${STARTDIR}
rm -rf emspring-0.87.1724 emspring-0.87.1724.tar.gz

echo '================================================================================='
echo "Install done. Spring was installed with EMAN2/SPHIRE in ${INSTALLDIR}" 
echo 'and the conda environment has been added to your startup shell script.'
echo '=======> For changes to take effect, close and re-open your current shell. <====='
echo '================================================================================='

exit 0

Activation

The conda environment base has been added to your startup shell script. After re-launch of your shell, you can now execute any of the programs from the spring package by typing the program, e.g.:

% spring

Testing

Check functionality of installed code by running some tests.

from spring.tests.micprgs.test_micctfdetermine import TestMicCtfDetermineMpi
t = TestMicCtfDetermineMpi()
t.setup()
t.do_end_to_end_test_sa_inputfile_with_MPI()
t.do_end_to_end_test_sa_inputfile_no_CTFTILT_with_MPI()
t.teardown()

Changelog

0.87.1723 (2021-03-08)

0.86.1661 (2017-12-12)

  • MICHELIXTRACE: release of algorithm as published in Huber et al. 2017 including statistical thresholding, search for optimal parameter combination and persistence length pruning

  • Web-based Helical Diffraction Simulator on http://spring.embl.de based on SEGLAYER2LATTICE.

0.85.1617 (2017-07-12)

  • MICCTFDETERMINE: updated to work with ctffind4.

  • SEGCLASSRECONSTRUCT: updated to work with binning option.

  • SEGMENTCLASS: updates to work with larger datasets for classification to reduce memory issues.

  • SEGCLASSLAYER: addition of ‘B-factor’ option to adjust high-resolution layer-line contrast.

  • SEGREFINE3DINSPECT: Bfactor/Resolution cutoff option separated from long helix option.

  • MICHELIXTRACE: Algorithm update to increase robustness of filament tracing.

  • SEGREFINE3DGRID/SEGGRIDEXPLORE: Now with out-of-plane deviation parameter.

  • SEGMENTPLOT/SEGREFINE3DPLOT: Now plots quantities on micrograph if subset micrograph chosen.

  • Updated to work with SLURM cluster

0.84.1470 (2016-01-04)

General bugfixes and improvement in stability. Addition of explanatory tool tips.

  1. SEGCLASSEXAM

  • Multiple bugfixes including wrong computation of pixelsize.

  1. SEGMENTREFINE3D

  • Addition of new parameter “Choose out-of-plane tilt for amplitude correlation.”

  1. Installation procedures

  • Updated dependencies GCC, matplotlib, libpng including build procedures.

0.83.1449 (2015-1-26)

  • Fixes in SEGMENTREFINE3D procedure, now also works for non-zero out-of-plane tilts.

0.83.1432 (2014-12-30)

  • Fixes and improvements

  1. Installation procedures

  • Updated dependencies GCC, Numpy, Scipy, Openmpi including build procedures.

  1. SEGMENTREFINE3D

  • Computation of persistence length at the end of each refinement run. Can be used now as a selection criterion for discarding less straight helices in the next refinement run.

  • Selection criteria: Straight helices, Layer-line correlation and Projection matching cross-correlation are now selected in percent range of the distribution instead of cutoff values, e.g. upper 20 % –> 80 - 100 %.

  • ‘Continue refinement option’ - in case no reference structure is given a 3D reconstruction based on the provided parameters is now created for further refinement.

  • Improved segment-based motion correction, now accepts mrcs-stacks.

  • Computation of structure-masked FSC with mask deconvolution according to Ultramicroscopy Chen et al. 2013 (Scheres and Henderson) for resolutions better than 12 Angstrom.

  • Added error estimates for forward x-shift, forward out-of-plane tilt and in-plane rotation angles according to Sachse et al, 2007 J Mol Biol.

  • Overhaul in symmetrization of volumes to make them perfectly even.

  • Diagnostic power spectra are now always written out as EMAN2 image files in addition to diagnostic summary.

  1. High-performance computing cluster

  • Added support for SLURM.

  1. SEGMENTCLASS, SEGLAYERLATTICE

  • Many minor fixes.

Note: old refinement.dbs and grid.dbs need to be upgraded to be readable by the latest Spring version.

% spring -udb='grid.db' -inp grid.db -out grid_upd.db
% spring -udb=refinement.db -inp=refinement024.db -out=refinement024_up.db

0.82.1339 (2014-09-15)

  • Improved installation procedures including build and binary install scripts.

0.82.1339 (2014-04-25)

  • General fixes, optimizations and enhancements

  1. SEGMENTREFINE3D

  • Fixes for data sets with large number of asymmetric units

  • Fix/workaround for occasional database lock problems on cluster mounted nodes

  • Fix in ‘Absolute limit of x and y-shifts’ handling. Now properly respects this.

  • Declared some options as experimental: support remains limited.

  • Occasional over-estimation of FSC fixed due to densities at upper and lower ends of filament

  • Implementation of ‘independent half-set’ refinement (a.k.a. gold-standard refinement)

Note: the update will break reading your previous refinement.db files Database files can be updated as follows:

% spring -udb=refinement.db -inp=refinement024.db -out=refinement024_up.db

  1. SEGREFINE3DINSPECT

  • Additional option of signal-to-noise weighting using FSC file.

  1. SEGLAYER2LATTICE

  • Simulation of layer-line pattern takes rotational symmetry into account

0.81.1282 (2014-01-26)

  • Fixes, enhancements and optimization

  1. SEGMENTREFINE3D

  • Disk requirements for temporary directories revised.

  • Improved handling of selected segments. Spring processes helices as one entity and discards them later for 3D reconstruction.

  • FSC only computed with cylinder mask.

  • Improved experimental power spectra for high/maximum resolution analysis.

  1. SEGMENT

  • Fix in frame processing.

  • Rotated stack only written if requested.

  1. SEGMENTEXAM

  • Addition of selection options from spring.db.

  1. SEGCLASSEXAM

  • Addition of mpi option.

  1. SEGLAYER2LATTICE

  • Addition of tooltips of predicted Bessel orders.

  1. SEGCLASSLAYER

  • Accepts also power spectra as input.

  • Added tooltips on Bessel look up table.

  1. General

  • Parameter input from prompt now works using Tab auto completion including file search.