shanum

• Manual
  • Introduction
  • Running shanum
    • Command-Line Arguments and Options
    • Runtime Output
  • shanum Input Files
  • shanum Ouput Files
• Examples

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.

Introduction

The program SHANUM uses Shannon sampling principles to show that the range of useful experimental data is determined by the number of meaningful Shannon channels in the dataset. SHANUM includes an algorithm to calculate this number, which in turn defines the data range. This algorithm has been tested on several simulated datasets with varying noise levels and degrees of oversampling, similar to typical SAXS/SANS experiments. Additionally, this method can be applied to analyze experimental solution scattering data collected under various conditions.

Running SHANUM

Usage:

$ shanum [OPTIONS] <DATAFILE>

OPTIONS known by SHANUM are described in next section, the required argument DATAFILE, in the section on input files.

Command-Line Arguments and Options

SHANUM requires the following command line arguments:

Argument	Description
DATAFAILE	Exactly one experimental SAS data (.dat) or regularised SAS data (.out) file.

Absolute as well as relative path to data files are accepted.

SHANUM recognizes following command-line options:

Short option	Long option	Description
	--first <N>	Index of the first point to be used; default: 1
	--rg <VALUE>	Starting point for \(D_{max}\) search in the same units as the angular axis of the data; default: estimated from data
	--dmax <VALUE>	If specififed, this \(D_{max}\) is used, no optimization is done. The unit of \(D_{max}\) is assumed to be the same as the unit of the angular axis of the data.
	--fit <FILE>	Relative or absolute path to save the the final fit to the data. If not specified, the fit is not stored.
-v	--version	Print version information and exit.
-h	--help	Print a summary of arguments, options, and exit.

Runtime Output

On runtime, output similar to the lines below 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

Field	Description
Datafile	Name of the input data file
Dmax	The maximum size of the particle, estimated by SHANUM or provided by the user
Smax	The maximum value of tha angular vector in the input data file
Nsh	The total number of Shannon channels in the input data file
Nopt	The calculated optimal number of Shannon channels estimated by SHANUM that corresponds to the useful angular data range in the input data file
Sopt	The calculated optimal value of the angular vector that determined the useful angular data for the input data file as determined by Dmax and Nopt values.

shanum Input Files

SHANUM expects exactly one experimental SAS data (.dat) or regularised SAS data (.out) file.

shanum Output Files

By default, shanum does not write data to file, but can store the fit to the input data on request with the fit option.

Examples

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

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; the units of dmax must match the units of the angular axis.

$ shanum --dmax=30 datfile.dat

Run SHANUM on the input data file ‘datfile.dat’ using default values for all parameters. The \(D_{max}\) value will be automatically estimated by autorg and autognom. The best Shannon fit and the target function will be saved to the user-defined file name.

$ shanum --fit=datfile.fit datfile.dat