jscatter’s documentation — jscatter 0.6.6 documentation

# jscatter’s documentation

The aim of this package 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.

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.

2. 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).

3. 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).

4. 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).

5. 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')

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
  - 1.1. Reading ASCII files
  - 1.2. Creating from numpy arrays
  - 1.3. Fitting experimental data
  - 1.4. Plot experimental data and fit result
- 2. dataArray
  - 2.1. Attributes
  - 2.2. Fitting
  - 2.3. Housekeeping
  - 2.4. Convenience
- 3. dataList
  - 3.1. Attributes
  - 3.2. Fitting
  - 3.3. Housekeeping
- 4. formel
  - 4.1. Functions
  - 4.2. Quadrature
  - 4.3. Centrifugation
  - 4.4. NMR
  - 4.5. Material Data
  - 4.6. other Stuff
  - 4.7. Constants and Tables
- 5. Small angle scattering (sas)
  - 5.1. Smear/desmear
  - 5.2. Housekeeping
- 6. formfactor (ff)
  - 6.1. Form Factors
  - 6.2. addons
- 7. structurefactor (sf)
  - 7.1. Structure Factors
  - 7.2. Hydrodynamics
  - 7.3. Pair Correlation
- 8. dynamic
  - 8.1. Transfom between domains
  - 8.2. Time domain
  - 8.3. Frequency domain
- 9. DLS
- 10. parallel
- 11. GracePlot
  - 11.1. GracePlot
  - 11.2. GraceGraph
  - 11.3. other classes
- 12. mpl
  - 12.1. Plot
  - 12.2. Figures
  - 12.3. Axes
- 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

>     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

>       pip install jscatter

>   as user in home directory:

>       pip install jscatter --user
>       # from a local file
>       pip install jscatter --user --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 and Development versions:

>       option
>       --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

- Index
- Module Index
- Search Page