jscatter’s documentation¶
The aim of jscatter is handling of experimental data and models:

- 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.
- 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.
- 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).
- 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).
- 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).
- 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, masswaterdensity()
-> temperature dependent density of water (H2O/D2O) with inorganic subtstancessedimentationProfile()
-> approximate solution to the Lamm equation of sedimenting particlesRMSA()
-> rescaled MSA structure factor for dilute charged colloidal dispersionshydrodynamicFunct()
-> hydrodynamic function from hydrodynamic pair interactionmultiShellSphere()
-> formfactor of multi shell spherical particlesmultiShellCylinder()
-> formfactor of multi shell cylinder particles with capsorientedCloudScattering()
-> 2D scattering of an oriented cloud of scatterersfiniteZimm()
-> Zimm model with internal friction -> intermediate scattering functiondiffusionHarmonicPotential()
-> diffusion in harmonic potential-> intermediate scattering functionsmear()
-> smearing for SANS (Pedersen), SAXS (line collimation) or by explicit Gaussiandesmear()
-> desmearing according to the Lake algorithm for the abovewaterXrayScattering()
-> 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')

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¶
- 1. Beginners Guide / Help
- 2. dataArray
- 3. dataList
- 4. formel
- 5. smallanglescattering (sas)
- 6. formfactor (ff)
- 7. structurefactor (sf)
- 8. dynamic
- 9. dls
- 10. parallel
- 11. graceplot
- 12. mpl
- 13. Examples
- 13.1. In a hurry and short
- 13.2. How to build simple models
- 13.3. How to build a more complex model
- 13.4. Some Sinusoidial fits with different kinds to use data atrributes
- 13.5. Simple diffusion fit of not so simple diffusion case
- 13.6. How to smooth Xray data and make an inset in the plot
- 13.7. How to fit SANS data including the resolution for different detector distances
- 13.8. Smearing and desmearing of SAX and SANS data
- 13.9. A long example for diffusion and how to analyze step by step
- 13.10. Sedimentation of two particle sizes and resulting scattering: a Simulation
- 13.11. Create a stacked chart of some curves
- 13.12. A comparison of different dynamic models in frequency domain
- 13.13. Protein incoherent scattering in frequency domain
- 13.14. Fitting a multiShellcylinder in various ways
- 13.15. Hydrodynamic function
- 13.16. 2D oriented scattering
- 13.17. Multilamellar Vesicles
- 14. Tips
- 15. Intention and Remarks
Installation¶
Installation Instructions:
- Dependencies
numpy, scipy (automatically installed by pip)
recommended:
xmgrace for plotting in Linux (Ubuntu, Debian)
sudo apt-get install gracexmgrace for plotting in MacOs
#install XQuartz #install Homebrew or MacPorts # for Homebrew brew tap homebrew/x11 brew install graceAnaconda is easier on MacOs
Ipython for convenience
matplotlib (needed for 3D plots):
pip install ipython matplotlibInstallation (maybe use pip2 or pip3 dependent what you want to use)
pip install jscatteras user in home directory:
pip install jscatter --userfrom 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 versionsCONTIN in DLS module
See DLS module documentation for details how to get and compile the original fortran code. Only if needed.