jscatter’s documentation

The aim of jscatter is handling of experimental data and models:

Jscatter Logo
  • Reading and analyzing experimental data with associated attributes as temperature, wavevector, comment, ….
  • Multidimensional fitting taking the attributes (as fixed parameters) into account.
  • Providing useful models (mainly for neutron and xray scattering), but there is no limitation.
  • Simplified plotting with paper ready quality (preferred in xmgrace).
  • Easy model building for non programmers.
  • Python scripts to document data evaluation and modelling.

Main concept

Link data from experiment, analytical theory or simulation with attributes as .temperature, .wavevector, .pressure,….
Methods for fitting, filter, merging,… using attributes by name.
An extensible library with common theories for fitting.
  1. Data organisation
Multiple measurements are stored in a dataList (subclass of list) containing dataArray ´s.
dataArray is a subclass of numpy ndarray but with attributes and more.
Full numpy ndarray functionality is preserved.
Special attributes are .X,.Y,.eY…- for convenience and easy reading.
Thus dataList represents e.g. a temperature series (as dataList) with measurements (dataArray) as list elements.
  1. Read/Write data
The intention is to read everything in the file to use it later and not ignore it as in numpy.loadtxt.
Multiple measurement files can be read at once and then filtered according to attributes to get subsets.
An ASCII file may consist of multiple sets of data with optional attributes or comments.
Data are a matrix of values in a file. Attribute lines have a name in front.
Everything else is a comment.
Thus the first two words (separated by whitespace) decide about assignment of a line:

- string + value -> attribute with attribute name + list of values
- value + value -> data line as sequence of numbers
- string + string -> comment
- single words -> comment
- string+@unique_name-> link to other dataArray with a unique_name

Even complex ASCII files can be read with a few changes given as options.
The ASCII file is still human readable and can be edited.
Attributes can be generated from content of the comments (attributes which are text and not numbers).
  1. Fitting
Multidimensional attribute dependent fitting (least square Levenberg-Marquardt, differential evolution, …from scipy.optimize).
Attributes are used automatically as fixed fit parameters.
See fit() for detailed description.
Simulation with changed parameters (e.g. to observe change within error limits).
  1. Plotting
We use an adaption of xmgrace for 2D plots (a wrapper; see GracePlot) as it allows
interactive publication ready output in high quality for 2D plots.
The plot is stored as ASCII (.agr file) with original data and not as non-editable image as png or jpg.
This allows a later change of the plot layout without recalculation, because data are stored as data and not as image.
Imagine the boss/reviewer asking for a change of colors/symbol size.
Nevertheless a small matplotlib interface is there and matplotlib can be used as it is (e.g. for 3D plots).
  1. Models
A set of models/theories is included see module e.g. formel, formfactor (ff) and structurefactor (sf).
User defined models can be used (e.g. as lambda function) just within a script or in interactive session of (I)python.
By intention the user should write own models (to include e.g. a background, instrument resolution, …) or to add different contributions.
Contribution by new models is welcome (but not trivial ones). Please give a publication as reference as in the provided models.

some special functions:

scatteringLengthDensityCalc() -> electron density, coh and inc neutron scattering length, mass
waterdensity() -> temperature dependent density of water (H2O/D2O) with inorganic subtstances
sedimentationProfile() -> approximate solution to the Lamm equation of sedimenting particles
RMSA() -> rescaled MSA structure factor for dilute charged colloidal dispersions
hydrodynamicFunct() -> hydrodynamic function from hydrodynamic pair interaction
multiShellSphere() -> formfactor of multi shell spherical particles
multiShellCylinder() -> formfactor of multi shell cylinder particles with caps
orientedCloudScattering() -> 2D scattering of an oriented cloud of scatterers
finiteZimm() -> Zimm model with internal friction -> intermediate scattering function
diffusionHarmonicPotential() -> diffusion in harmonic potential-> intermediate scattering function
smear() -> smearing for SANS (Pedersen), SAXS (line collimation) or by explicit Gaussian
desmear() -> desmearing according to the Lake algorithm for the above
waterXrayScattering() -> Absolute scattering of water with components (salt, buffer)

Example see example_simple_diffusion.py and other Examples

# import jscatter and numpy
import numpy as np
import jscatter as js

# read the data (16 sets) with attributes as q, Dtrans .... into dataList
i5=js.dL(js.examples.datapath+'/iqt_1hho.dat')

# define a model for the fit
diffusion=lambda A,D,t,elastic,wavevector=0:A*np.exp(-wavevector**2*D*t)+elastic
# do the fit
i5.fit(model=diffusion,                     # the fit function
       freepar={'D':[0.08],'A':0.98},       # start parameters, "[]" -> independent fit
       fixpar={'elastic':0.0},              # fixed parameters
       mapNames={'t':'X','wavevector':'q'}) # map names from the model to names from the data
# single valued start parameters are the same for all dataArrays
# list start parameters indicate independent fitting for datasets
# the command line shows progress and the final result, which is found in .lastfit
i5.showlastErrPlot(yscale='l') # opens plot with residuals

# open a plot with fixed size and plot
p=js.grace(1.2,0.8)
# plot the data with Q values in legend as symbols
p.plot(i5,symbol=[-1,0.4,-1],legend='Q=$q')
# plot fit results in lastfit as lines without symbol or legend
p.plot(i5.lastfit,symbol=0,line=[1,1,-1])

# pretty up if needed
p.yaxis(min=0.02,max=1.1,scale='log',charsize=1.5,label='I(Q,t)/I(Q,0)')
p.xaxis(min=0,max=130,charsize=1.5,label='t / ns')
p.legend(x=110,y=0.9,charsize=1)
p.title('I(Q,t) as measured by Neutron Spinecho Spectroscopy',size=1.3)
p.text('for diffusion a single exp. decay',x=60,y=0.35,rot=360-20,color=4)
p.text(r'f(t)=A*e\S-Q\S2\N\SDt',x=100,y=0.025,rot=0,charsize=1.5)

if 0: # optional; save in different formats
    p.save('DiffusionFit.agr')
    p.save('DiffusionFit.jpg')
Picture about diffusion fit

Shortcuts:

import jscatter as js
js.showDoc()                  # Show html documentation in browser
exampledA=js.dA('test.dat')   # shortcut to create dataArray from file
exampledL=js.dL('test.dat')   # shortcut to create dataList from file
p=js.grace()                  # create plot
p.plot(exampledL)             # plot the read dataList

if not otherwise stated in the files:

written by Ralf Biehl at the Forschungszentrum Jülich ,
Jülich Center for Neutron Science 1 and Institute of Complex Systems 1
jscatter is a program to read, analyse and plot data
Copyright (C) 2015 Ralf Biehl

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.

jscatter package contents

Installation

Installation Instructions:

  • Dependencies

    numpy, scipy (automatically installed by pip)

    recommended:

    xmgrace for plotting in Linux (Ubuntu, Debian)

    sudo apt-get install grace
    

    xmgrace for plotting in MacOs

    #install XQuartz
    #install Homebrew or MacPorts
    # for Homebrew
    brew tap homebrew/x11
    brew install grace
    

    Anaconda is easier on MacOs

    Ipython for convenience

    matplotlib (needed for 3D plots):

    pip install ipython matplotlib
    
  • Installation (maybe use pip2 or pip3 dependent what you want to use)

    pip install jscatter
    

    as user in home directory:

    pip install jscatter --user
    

    from a local repository (development versions):

    pip install jscatter --user --upgrade --pre --find-links /where/the/file/is/saved
    
    options
    --user       : Install in user directory (folder defined by PYTHONUSERBASE or the default is used)
    --find-links : look in the given path for package links e.g development releases
    --upgrade    : to install upgrades
    --pre        : to install also development versions
    
  • CONTIN in DLS module

    See DLS module documentation for details how to get and compile the original fortran code. Only if needed.

Indices and tables