Small Angle Scattering ToolBox

The Small Angle Scattering ToolBox (SASTBX): an open-source software for biomolecular small-angle scattering.

Webserver is back online

http://liulab.csrc.ac.cn/sastbx

Document: http://sastbx-document.rtfd.io

What can SASTBX do for you

Analysis SAS data.

  • Data reduction

Obtain one-dimensional scattering curves of intensity versus scattering vector (I-q curves).

  • PDDF

The intensity profile can be transformed to the pair distance distribution function.

  • Shape retrieval

Find plausible low resolution models that fit the experimental data.

  • Superpose Model

Superpose models at low resolutions.

Download

  • command line version: Using SASTBX under command line.
  • complete GUI version: friendly graphical user interface with no installation process, just download and use it.
  • light GUI version: The graphical user interface for the machines which has installed command line version.

Latest Version 1.0.0

64-bit Linux:

MacOS

Manually building from sources under Ubuntu

Attention:
These instructions are for developers!

Download Source Code Here: Download source code for Ubuntu

In the flowing procedure, the lines that are in the block are what you will type in command line.

* step 1: Unpack the compressed SASTBX file.

    tar -xjvf source_code_ubuntu.tar.gz
You will get a directory named modules.

* step2 configure the environment variables' The installation procedure should be executed in another directory, so make an empty directory to execute the installation.

cd SASTBX_PATH/
mkdir build

Recommend you organize the directory like this:

SASTBX_PATH(the directory saved source code and executed space)
       * build
       * modules

Attention :

SASTBX_PATH

is the path where the sastbx file exit, change it to your own path

example:

cd /usr/test/Documents/software/sastbx/build
/usr/test/Documents/software/sastbx is the SASTBX_PATH in the example

Then generate the environment variables

/your/choice/bin/python ../modules/libtbx/configure.py sastbx	
Lots of files will generate in build directory Then configure the environment variables
source setpaths_all.sh

To compile enter:

make
This will actually run the libtbx.scons command using all available CPUs. You can also manually specify the number of CPUs to use, for example:
make -j 4

* step3: vertify

Type

sastbx.python
in the command line, if you can enter the python process, the installation is success.

Manually building from sources under MacOS

Attention:
These instructions are for developers!

Download Source Code Here: Download source code for MacOS

In the flowing procedure, the lines that are in the block are what you will type in command line.

* step 1: Unpack the compressed SASTBX file.

    tar -xjvf source_code_macos.tar.gz
You will get a directory named modules.

* step2 configure the environment variables' The installation procedure should be executed in another directory, so make an empty directory to execute the installation.

cd SASTBX_PATH/
mkdir build

Recommend you organize the directory like this:

SASTBX_PATH(the directory saved source code and executed space)
       * build
       * modules

Attention :

SASTBX_PATH

is the path where the sastbx file exit, change it to your own path

example:

cd /usr/test/Documents/software/sastbx/build
/usr/test/Documents/software/sastbx is the SASTBX_PATH in the example

Then generate the environment variables

/your/choice/bin/python ../modules/cctbx_project/libtbx/configure.py sastbx	
Lots of files will generate in build directory Then configure the environment variables
source setpaths_all.sh

To compile enter:

make
This will actually run the libtbx.scons command using all available CPUs. You can also manually specify the number of CPUs to use, for example:
make -j 4

* step3: vertify

Type

sastbx.python
in the command line, if you can enter the python process, the installation succeeded.

Usage of command line

All the sastbx functions all listed in the table:

sastbx.build_db sastbx.buildmap sastbx.pregxs
sastbx.python sastbx.shapeup sastbx.refine_pr
sastbx.refine_rb sastbx.she sastbx.show_build_path
sastbx.show_dist_paths sastbx.superpose

Type one of these commands in the command line, you will find the usage of this command.

example:

sastbx.she
Usuage:
sastbx.she model=mymodel structure=mystructure.pdb

experimental_data=myexperimentaldata.qis 
pdblist=pdblist.txt  q_start=q_start q_stop=q_stop n_step=n_step output=outputfile
Required arguments:
    mystructure             the PDB file to be evaluated (must be provided)
 Optional arguments:
    mymodel             the model type to be used, it should be either debye or she (default is she)
    myexperimentaldata.qis  the sas profile, columns are q, I(q), and std
    q_start, q_stop         defines the range of q
    outputfile             the file used to store computed sas profile, default is output.iq (could be overwritten)
 

web interface

Usage of GUI Version

Download the GUI Version

Open the Application,double click the icons:

Project Location

Set the project directory in the homepage:

All the result will located in the directory you selected, and for each function, there will generate a subdirectory with the same name of the project.

Preference

  • For light GUi version

Set SASTBX location, a directory contain module and build directory of SASTBX

Set the pymol location in the preference page

  • For complete GUI version

Set the pymol location in the preference page.

Note:

pymol path: The path of MacPymol application or the pymol executable file.

SASTBX path: The directory which contains the source code directory named “modules” and compile directory named “build”.

Here are some examples of pymol path:

/Applications/MacPymol.app

/usr/bin/pymol

The example of SASTBX path:

/Applications/sastbx/

Functions

  • Model Superposition

superpose models at low resolutions

The required inputs are 2 protein models or maps, all the other parameters are optional.

The the program can start with clicking 'run' button.

And the log can be seen in the widget.

The result can be seen in the result tab:

You can explore the content of each result file by seen the content or show in pymol

You can seen the superpose result by click “pymol” button in the toolbar.

Two protein are superposed.

  • Shape Search Engine

Fast retrieval 3D models for the given says experimental profile.

The instruction tab explain every parameters of the input tab.

Input the file and parameters:

The real time log file:

The result can be seen in the result tab:

These 10 maps are the best results that match the input SAXS file in the database.

You can explore the content of each result file by look through the content or show in pymol

You can seen the result by click “pymol” button in the toolbar.

Intensity Calculation

Compute theoretical scattering intensity curve for the given PDB models.

The instruction tab explain every parameters of the input tab.

Input the file and parameters:

The real time log file:

The intensity curve can be seen in the summary tab

P® Estimation

Using Parametic Formula to determinate the pair distance distribution function of saxs file.

The real time log file:

The pair distance curve can be seen in the summary tab

The original intensity curve of saxs file and the best intensity file curve:

Get Help

You can get help of the principle of each function and the tutorial of how to use the application whenever you click the help button:

And you can see:

The SASTBX Functions link:

shows the principle of each function.

The Tutorial and Examples link:

Development Documents

1.sastbx.she

Obtain one-dimensional scattering curves of intensity versus scattering vector (I-q curves).

Usage:

sastbx.she model=mymodel structure=mystructure.pdb 
experimental_data=myexperimentaldata.qis  pdblist=pdblist.txt  
q_start=q_start q_stop=q_stop n_step=n_step output=outputfile
 
Required arguments:
    mystructure             the PDB file to be evaluated (must be provided)
 Optional arguments:
    mymodel                   default she        
                              the model type to be used, it should be either debye or she 
    myexperimentaldata.qis    default None       
                              the sas profile, columns are q, I(q), and std
    q_start                   default 0          
                              start of Q array
    q_stop                    default 0.5        
                              end of Q arry
    n_step                    defalut 51         
                              Bin size 
    outputfile                default output.iq  
                              the file used to store computed sas profile and could be overwritten
examples:
sastbx.she structure=/usr/test/Documents/mystructure.pdb
sastbx.she structure=/usr/test/Documents/mystructure.pdb output=/usr/test/Documents/mystructure_she.iq
change the the file path /usr/test/Documents/mystructure.pdb to your own file path

returns

output.iq

You can open the iq file in the text editor.

2. saltbox.pregxs

Pair-distance distribution function determination

Usage:

 sastbx.pregxs data=data_file d_max=dmax scan=True/False output=output_prefix
parameters:
required arguments:
    data      q-intensity sigma
Optional arguments:
    d_max     default None                  Maximun distance in particle
    scan      default False                 When True, a dmax scan will be preformed
    output    default best.pr best.qii    
returns

.pr
.qii

You can open them in the text editor.

3. sastbx.superpose

Align models.

Usage:

sastbx.superpose fix=fixed_file typef=type [pdb | nlm | map ] mov=moving_file typem=type nmax=nmax
parameters:
required arguments:
  fix      default  None    pickle Cnlm coef of the fixed object
  mov      default  None    pickle Cnlm coef of the moving object
optional arguments:
 
 typef     default PDB      fixed model type: pdb or nlm or map
 
 typem     default PDB      moving model type: pdb or nlm or map 
 
 num_grid  default 41       number of point in each euler angle dimension
 rmax      default None     maxium radial distance to the C.o.M. (before the scaling)
 nmax      default 20       maximum order of zernike polynomial:fixed for the existing database
 topn      default 10       top N alignments will be further refined if required
 refine    default True     Refine the initial alignments or not
 write_map default False    write xplor map to file
returns

if fix and mov type is PDB:
fixed_file_za.pdb
moving_file_za.pdb

example:

sastbx.superpose fix=a.pdb mov=b.pdb
results:

a_za.pdb, b_za.pdb

4. sastbx.build_db

Creat database with a directory of PDB files.

Build your own database The default database used in the software is compiled using this script based on 10,733 models chosen from PISA

Usage:

libtbx.python build_db.py path=path nmax=nmax fix_dx=True/False
parameters:

path           default None       path of pdb files
nmax         default 20            maximum order of zernike expansion
fix_dx        default True         Whether keeping default dx=0.7A or not
np              default 50            number of point covering [0,1]
nprocess   default 4              number of processes
prefix        defualt myDB      the prefix of pickle file names
Attention:

The path should be a directory that contains only PDB files.

returns:

.codes
.nlm
.nn
.rmax

examples:

For example, if there is a directory named pdb_models which contains 3D models in pdb format, and now I want to generate a database for these models. If I want the data to be stored in the database directory ( suppose that both the directories are in /usr/test/Documents/) and nmax=30, then I will write a command like this:

sastbx.python path=/usr/test/Documents/pdb_models nmax=30
result:

myDB.codes myDB.nlm myDB.nn myDB.rmax

or

If I want to name the return files as “models”, then I will

libtbx.python build_db.py path=/usr/test/Documents/pdb_models prefix=/usr/test/Desktop/database/models
result:

models.codes models.nlm models.nn models.rmax
  • .codes file records the PDB file’s name used in the database genetation.
  • .nlm file records the Zernike moments coeffcients.
  • .nn fiel recoed the Hnn coeffcients.
  • .rmax file contains the largest radius of each structure.

Data stored in these files are all in list format, and information for a specific model can be accessed with the same index.

It is also easy to read the contents stored in these files with simple python codes (run sastbx.python and run the codes interactively):

from libtbx import easy_pickle
prefix="/usr/test/Documents/pdb_models"
codes=easy_pickle.load(prefix+".codes")
nlm_coefs=easy_pickle.load(prefix+".nlm")
nn_coefs=easy_pickle.load(prefix+".nn")
rmaxs=easy_pickle.load(prefix+".rmax")
 
#retrieval information for a specific model
code="model_of_interest" #suppose the name of the model is "model_of_interest"
indx=codes.index(code)
nlm_coef=nlm_coefs[indx]
nn_coef=nn_coefs[indx]
rmax=rmaxs[indx]
If I save the python script as get_data.py, then I can run the script by the command:

sastbx.python get_data.py
in the command line.

5. sastbx.shapeup

Fast Retrieve 3D models for the given saxs experimental profile within 1 minite.

Usage:

sastbx.shapeup target=target.iq  rmax=rmax nmax=nmax scan=True*/False
buildmap=True*/False pdb=pdbfile path=database_path

parameters:

required arguments:
    target    the intensity profile
optional arguments:
    rmax      default guessed from Rg    
              radius of the molecule (default: guessed from Rg)
    nmax      default 10                 
              maximum order of the zernike polynomial expansion (<=20 for precomputed database)
    qmax      default 0.20               
              maximum q value, beyond which the intensity profile will not be considered 
    path      default None               
              path to the database (this MUST be correct to execute the searching)
    buildmap  default True               
              build electron density map in xplor format, all the map will be aligned
    pdb       default None               
              any pdb model to be compared, and the maps will be aligned to the first pdb file
    prefix    the output prefix
 
returns:

The atomic models match the SAS profile (default 10 models in ccp4 format) You can observe the models in pymol

If you creat a database by using sastbx.build_db, you can search with the new database:

sastbx.shapeup target=myquery.dat rmax=estimated_rmax dbpath=path_of_database

More Details can be found in the reference.

Reference

Haiguang Liu, Alexander Hexemer & Peter H.Zwart The Small Angle Scattering ToolBox (SASTBX):an open-source software for biomolecular small-angle scattering

Richard Feynman

“everything that is living can be understood in terms of the jiggling and wiggling of atoms”.

and now, we want to watch atoms jiggling and wiggling.

X-rays, electrons, fluorescence light, the advances of photon sciences, together with computational modeling, are making this happen.