0
EMBL Hamburg Biological
Small Angle Scattering
BioSAXS

SHANUM manual

shanum

Written by P.V. Konarev & D. I. Svergun.
Post all your questions about SHANUM to the ATSAS Forum.

© ATSAS Team, 2015-2017

Table of Contents

Manual

The following sections describe the method implemented in SHANUM, how to run SHANUM on the supported platforms and the required input and the generated output files.

If you use results from SHANUM in your publication, please cite:

P.V. Konarev and D. I. Svergun. (2015) A posteriori determination of the useful data range for small-angle scattering experiments on dilute monodisperse systems. IUCr Journal, 2, 352-360.

Introduction

The program SHANUM employs Shannon sampling formalism to demonstrate that the useful experimental data range is defined by the number of meaningful Shannon channels that can be determined from the data set. The algorithm to determine this number and thus the data range is implemented in the program SHANUM and tested on a number of simulated data sets with various noise levels and with different degree of oversampling, corresponding to typical SAXS/SANS experiments. The method can be also applied to analyse experimental solution scattering data recorded in various conditions.

Running SHANUM

Command-Line Arguments and Options

The program SHANUM can be started in the batch mode when arguments are given:

$ shanum DATAFILE <Dmax> [OPTIONS]

SHANUM accepts the following command line arguments:

ArgumentDescription
DATAFILE A relative or absolute path to a data file that should contain s-vector and intensity columns (obligatory) and errors of intensities (optional)
<DMAX> Dmax (the value of the maximum particle size) can be provided by the user in the command line after the DATAFILE (optionally), if it is not provided SHANUM will estimate it automatically using Autorg and AutoGNOM.

SHANUM recognizes the following command-line options.

OptionDescription
-f <FIT_FILE> Prefix to store the best Shannon fit file and the target function f(M).
-d <DEBUG_MODE> Prefix to store all Shannon fit files and p(r) files estimated by the program as well as the target function f(M).
-h Print a summary of arguments and options and exit.

Runtime Output

On runtime, the following lines of output will be generated:

   Optimization of angular data range
        Datafile=ell_15_15_1_err20.dat
        Dmax=   30.000000000000000
        Smax=   4.0011000000000001
        Nsh=    38.207690568298950
        Nopt=          38
        Sopt=   3.9793506945470711

The fields can be interpreted as follows, from top to the bottom

Field Description
Datafile Input data file in ASCII format with 2 or 3 columns
Dmax The maximum size of the particle, estimated by SHANUM or provided by the user
Smax The actual maximum value of S-vector in the input data file
Nsh The actual number of Shannon channels in the input data file
Nopt The optimal number of Shannon channels estimated by SHANUM that corresponds to the useful angular data range in the input data file.
Sopt The optimal value of S-vector that determined the useful angular data for the input data file and is determined by Dmax and Nopt values.

shanum Input Files

SHANUM reads the data file in ASCII format that contains 2 or 3 columns, the columns are (S-vector,Intensity) or (S-vector, Intensity, Errors).

shanum Output Files

SHANUM always displays Dmax, Smax, Nsh, Nopt and Smax values on the screen. SHANUM outputs the best Shannon fit and the target function f(M) if '-f' prefix has been used. SHANUM stores all Shannon fits and the restored p(r) functions together with the target function f(M) if '-d' prefix was used.

Examples

The following examples show how to do shape reconstruction using SHANUM given the input data file 'datfile.dat'.

Running in batch mode

Run SHANUM and get online help.

$ shanum -h

Run SHANUM on the input data file 'datfile.dat' using default values for all parameters. Dmax value will be automatically estimated by autorg and autognom.

$ shanum datfile.dat

Run SHANUM on the input data file 'datfile.dat' defining the maximum size of the particle Dmax (it should be in the same units as the angular axis).

$ shanum datfile.dat 30

Run SHANUM on the input data file 'datfile.dat' using default values for all parameters. Dmax value will be automatically estimated by autorg and autognom. The best Shannon fit and the target function will be saved.

$ shanum datfile.dat -f

Run SHANUM on the input data file 'datfile.dat' using default values for all parameters. Dmax value will be automatically estimated by autorg and autognom. All Shannon fits and restored p(r) functions as wella as the target function will be saved.

$ shanum datfile.dat -d

  Last modified: July 22, 2015

© BioSAXS group 2015