jscatter’s documentation¶
The aim of Jscatter is treatment 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 for neutron and X-ray scattering form factors, structure factors and dynamic models (quasi elastic neutron scattering) and other topics.
- 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.
Provide an extensible library with common theories for fitting of physical models.
- Data organisation
Multiple measurements are stored in a
dataList
(subclass of list) containingdataArray
´s. dataArray is a subclass of numpy ndarray but with attributes and more.Special attributes are .X,.Y,.eY…- for convenience and easy reading. Full numpy ndarray functionality is preserved.
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 from a file to use it later if needed. Multiple measurement files can be read at once and then filtered according to attributes to get subsets.
A file may consist of multiple sets of data with optional attributes or comments in between. Data are a matrix like values in a file. Attribute lines have a name in front. Everything else is a comment and might be used later. 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. New attributes can be generated from content of the comments if not detected automatically.
- Fitting
Multidimensional attribute dependent fitting (least square Levenberg-Marquardt, differential evolution, …from scipy.optimize).
Attributes are used automatically as fixed fit parameters.
Simulation with changed parameters (e.g. to observe change within error limits).
See
fit()
for detailed description.
- 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 and is much faster than matplotlib.
The figure is stored as ASCII file (.agr) including data points and not as non-editable image as jpg/pdf… 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
By intention the user should write own models or modify existing ones to combine different contributions (to include e.g. a background, instrument resolution, …)
Models can be defined as lambda function or normal functions within a script or in interactive session of (I)python.
A set of models/theories is included, see e.g. formel, formfactor (ff) and structurefactor (sf). Models contain model parameters as attributes for later access.
Contribution by new models is welcome (please not trivial ones). Please give a documentation, reference to relevant publication and authorship as in the provided models.
Some special functions:
scatteringLengthDensityCalc()
-> electron density, coh and inc neutron scattering length, masswaterdensity()
-> density of water (H2O/D2O) with inorganic subtstancessedimentationProfile()
-> 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)
How to use Jscatter or see Examples and Beginners Guide / Help
# 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
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. Plotting in XmGrace
- 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 Sinusoidal 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. Multilamellar Vesicles
- 13.17. 2D oriented scattering
- 13.18. A nano cube build of different lattices
- 13.19. Using cloudscattering as fit model
- 14. Extending/Contributing/Fortran
- 15. Tips
- 16. Intention and Remarks
- 17. Installation
Installation¶
- Dependencies
- numpy, scipy -> Mandatory, automatically installed by pip
- Pillow -> Mandatory, for reading of SAXS images, automatic install by pip
- matplotlib -> Mandatory, for 3D plots and on Windows
- Ipython -> Optional, for convenience as a powerfull python shell
- gfortran -> Optional, without some functions dont work or use a slower python version
- xmgrace -> Optional, prefered plotting on Unix like (use matplotlib on Windows)
Installation may need root privileges. Use “sudo” on Linux and MacOS if needed.
Pip installation options (use pip2 or pip3 dependent if you use python2.7 or python3)
sudo pip install jscatter
As user in home directory (pip default is in ~/.local/). No sudo needed, only user privileges:
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 ~/.local) --find-links : look in the given path for package links e.g development releases --upgrade : to install upgrades --pre : to install also development versions
Ubuntu, all Debian related Linux
sudo apt-get install gfortran grace python-matplotlib # or python3-matplotlib sudo pip install ipython sudo pip install jscatter
CentOs, Suse, Fedora … do same as above but with yum/zypper…
MacOs, install Homebrew first as given on their web page (see Homebrew)
# install XQuartz from homebrew or from the AppStore sudo brew cask install xquartz # install xmgrace and gfortran sudo brew install grace gfortran matplotlib # then use pip sudo pip install ipython sudo pip install jscatter
Windows: Anaconda is a python distribution as alternative with numpy, scipy, matplotlib, Ipython preinstalled. Need of sudo depends on how Anaconda was installed (root or user). Maybee the matplotlib backend needs to be configured on Windows to work properly.
And there was more to adjust, when i stopped waisting my time. In my testcase it was a pain, but test and examples work (no Xmgrace, no fortran).
I strongly advise to use Linux in a VirtualMachine as it is easier to install and use.
# install jscatter on working anaconda environment pip install jscatter
Manjaro Linux (yaourt asks for permission as root or prepend sudo as above)
# install gfortran yaourt gcc-fortran # install xmgrace (only found in AUR), fonts are needed for the interface, fonts are loaded after restart yaourt xorg-fonts-75 xorg-fonts-100 grace-openmotif python-matplotlib pip install ipython pip install jscatter
CONTIN in DLS module (Only if needed).
See DLS module documentation for details how to get and compile the original fortran code.
Testing
You can test basic functionality of jscatter after installation:
import jscatter as js js.test.doTest() #basic graphics and fitting js.examples.runExample(7)
During development:
python setup.py test