Close This Window

Please download official ILL logos here


For using on the web or on a screen

For printing in high resolution

White version, for dark backgrounds



Download PNG

Download TIF

Download white PNG

Download JPG

Download EPS

Download white EPS logo

Institut Laue-Langevin

The Computing for Science (CS) group supports ILL scientists, students and visitors in a number of activities including data analysis, instrument simulation and sample simulation.

Back to ILL Homepage
English French Deutsch 

All Software

Spec1d

A versatile set of tools to analyse 1d data sets in MATLAB


A collection of routines designed to facilitate the analysis of one dimensional (i.e. x, y, error) data sets from the command line in MATLAB. Data can be loaded into a structure, known as a spec1d object, and then processed with simple one-line commands. Liberal use is made of the operator overload feature of MATLAB5 so that operators such '+', '*' are redefined to work on 1d spectra, including the correct handling of error propogation. Using spec1d it is possible to perform complex data analysis, including non-linear least-squares fitting, in a very efficient manner. As it makes use of the load and function libraries from MFIT/MVIEW, it is completely general, and can be used to analyse data from more or less any source.

Requires MATLAB 5.1 or higher.

Version 2.0, February 2001
Des McMorrow and Henrik Rønnow
 

Summary

Introduction

Spec1d is presently built on the following class structure:

<tt>x-data      :     s.x</tt>
<tt>y-data      :     s.y</tt>
<tt>y error     :     s.e</tt>
<tt>x-label     :     s.x_label</tt>
<tt>y-label     :     s.y_label</tt>
<tt>datafile    :     s.datafile</tt>
<tt>y-fit       :     s.yfit</tt>

Spec1d objects can either be singular, or arrays. In this way it is possible to store and perform data analysis on many files (in fact whole data sets) using one line commands.

Note: The handling of errors in spec1d is designed  not to be restricted to the case where the errors are determined by counting statistics. You are advised, however, to check the routines to make sure that they are applicable to the problem you are trying to treat.

The easiest way to become familiar with spec1d is to study a number of examples.

Reading data files: use of the loads command

Example 1: Reading data stored in x, y, error format, and fitting it to a Gaussian peak
Example 2: Reading data from a formatted data file (ILL, SPEC, RISØ, etc)
Example 3: Reading multiple files, or multiple scans from the same file

Command summary

Command

Description

Examples

+

Addition of  the y values of spectra, or addition of constants to the x and y values.

Add together the y values in s1, s2, and s3:
<tt>>>stot=s1+s2+s3;</tt>
Add 10 to the y values in s8:
<tt>>>s9=s8+10;</tt>
Add 10 to the y values, and 2 to the x values:
<tt>>>s9=s8+[2 10;];</tt>

Note: The spectra to be added must have identical x axes; otherwise use combine.

-

Subtraction of the y values of two spectra, or subtraction of constants from the x and y values.

Subtract the y values in s2 from those in:
<tt>>>s3=s2-s1;</tt>
Subract 10 from the y value in s1:
<tt>>>s2=s1-10;</tt>
Subtract 20 from the x vaue in s10:
<tt>>>s11=s10-[20 0];</tt>

Note: Can only subtract spectra if they have identical x axes.

*

Multiplication of the y values of two  spectra,  or multiply the x or y values by a constant

Multiply the y values of  s2 and s1:
<tt>>>s3=s2*s1;</tt>
Multiply the y value in s1 by 10:
<tt>>>s2=s1*10;</tt>
Multiply the x value in s5 by 2 and the y value by 3.5: 
<tt>>>s7=s5*[2 3.5];</tt>

Note: When multiplying spectra, they must have identical x axes.

/

Division of  the spectra of the y values of two spectra, or divide the x or y values by a constant

Divide  the y values of  s2 by those in s1:
<tt>>>s3=s2/s1;</tt>
Divide the y values in s1 by 10:
<tt>>>s2=s1/10;</tt>
Divide the x values in s5 by 2 and the y value by 3.5: 
<tt>>>s7=s5/[2 3.5];</tt>

Note: When dividing two spectra, they must have identical x axes.

combine

Combine avearges the y values in  two or more spectra. The x tolerance and combination method are optional. The default method assumes that errors are determined by counting statistics. 

Average s1, s2 and s3 if the x points are closer than 0.01:
<tt>>>s4=combine(0.01,s1,s2,s3);</tt>
Average all of the spectra in the array of spec1d objects stotal. No tolerance is specified; the default value is eps:
<tt>>>sc=combine(stotal);</tt>

cut

Remove data over specified range(s) in x

Cut s1 outside of the range 101 to 102  in x
<tt>>>r=cut(s1,[101 102]);</tt>
Cut s1 in the x range 101-102 and 109-110 
<tt>>>r=cut(s1,[102 101],[110 109]);</tt>

display

Display the x, y and error values in a spectra

Print the x, y and error values of s2 in the Matlab command window
<tt>>>disp(s2);</tt>

dxdy

Differentiate a spectra

Differentiate spectra s4:
<tt>>>sd=dxdy(s4);</tt>

extract

Extract the x, y, and error values to arrays 

Extract the data from s10 to arrays x, y, error:
<tt>>>[x,y,e]=extract(s10);</tt>

fits

Perform a non-linear least-squares fit on of a specified model to the data in a spectra

Fit a Gaussian to s1, with automatic estimation of start values of parameters. All parameters are allowed to vary, and the default values for the fit control parameters are used:
<tt>>>[sfit,fitpars]=fits(s1,'gauss');</tt>
Same as above, but with initial parameters specified and background (parameter 4) fixed:
<tt>>>[sfit,fitpars]=fits(s1,'gauss',[0.9 0.1 0.2 0.1],[1 1 1 0]);</tt>
As above, but with the fit control parameters specified:
<tt>>>[sfit,fitpars]=fits(s1,'gauss',[0.9 0.1 0.2 0.1],[1 1 1 0],[0.001 20 0.01]);</tt>

getfield

Get the values of  specified fields

Obtain the x values from d24:
<tt>>>x=getfield(d24,'x');</tt>
Obtain the x and y  values from d24:
<tt>>>[x,y]=getfield(d24,'x');</tt>
Obtain the x values and the x_label from d24:
<tt>>>[x,xlab]=getfield(d24,'x','x_label');</tt>

Note: the number of output variables must equal the number of fields requested.

horzcat

Create an array of spectra

Form an array of the spec1d the objects s4, s5, s6:
<tt>>>sout=[s4 s5 s6];</tt>

interpolate

Interpolate a spectrum to new x vales

Interpolate s10 to the x values specified in the array xnew:
<tt>>>snew=interpolate(s10,xnew);</tt>

loads

Load data from a file into a spectra

Load scan number 14 from the SPEC file ce2.dat:
<tt>>>s1=loads('specbatch', 'ce2.dat, X=Theta,Y=Exp_Hutch,M=Mon,S=14');</tt>
Load and combine scans 14 to 20:
<tt>>>s1=loads('specbatch', 'ce2.dat, X=Theta,Y=Exp_Hutch,M=Mon,S=[14++20]');</tt>
Load scans 14 to 20 into  an array:
<tt>>>s1=loads('specbatch', 'ce2.dat, X=Theta,Y=Exp_Hutch,M=Mon,S=[14:20]');</tt>

Load data from the ILL file ho001.dat:
<tt>>>s1=loads('illbatch', 'ho001.dat, X=OM,Y=I1,M=Mon');</tt>
Load  and combine ho001.dat to ho009.dat:
<tt>>>s1=loads('illbatch', 'ho00[1++9].dat, X=OM,Y=I1,M=Mon');</tt>
Load ho001.dat to ho009.dat into an array:
<tt>>>s1=loads('illbatch', 'ho00[1:9].dat, X=OM,Y=I1,M=Mon');</tt>

mapplot

Make a 2D plot of the data in an array of spectra.
Note: this is a visualisation tool, and not for data analysis.

Plot  array stot  (21 spectra):
<tt>>>mapplot(stot);</tt>
Plot and smooth using a Gaussian convolution of width 0.1;
<tt>>>mapplot(stot,[1:21],0.1);</tt>

normalise


Normalise the y data in a spectra to a specified value

Normalise y data in s2 to 10.5
<tt>>>s5=normalise(s2,10.5);</tt>

peakm

Calculate peak properties using the method of moments

Perform a peak analysis on s2:
<tt>>>stats=peakm(s2);</tt>
Perform peak analysis on array sall:
<tt>>>stats=peakm(sall);</tt>

peakt

Calculate the integrated intensity (and its error) using trapezoidal integration

Trapezoidal integration of peak in s3:
<tt>>>stats=peakt(s3);</tt>
Trapezoidal integration of array stot:
<tt>>>stats=peakt(stot);</tt>

plot

Basic plotting routine for displaying the contents of one or several spectra

Plot s3:
<tt>>>plot(s3);</tt>
Overlay s1, s2 and s3:
<tt>>>plot(s1 s2 s3);</tt>
Overlay s1, s2 and s3 on a loglog plot:
<tt>>>plot(s1 s2 s3,'loglog');</tt>
Overlay s1, s2 and s3 on a semilogy plot:
<tt>>>plot(s1 s2 s3,'loglog');</tt>

Overlay spectra in array st:
<tt>>>plot(st);</tt>
 

rebin

Rebin the data in a spectra to a new x axis


 

setfield

Set the values of specific fields

Set the x values in d24 to array xn:
<tt>>>d24=setfield(d24,'x',xn);</tt>
Set the datafile variable (i.e. title of graph)
<tt>>>d24=setfield(d24,'datafile','Great data');</tt>
 

smooth

Smooth the data using a 1D Gaussian convolution

Convolute s with a Gaussian of variance 0.2:
<tt>>>s=smooth(s,0.2)</tt>
 

spec1d

Create a new spec1d object

For a structure r 
<tt>>>r=spec1d(r)</tt>
converts r to a spec1d object

vertcat

Append the data from several spectra into one

Create a single spec1d object from s1, s2 and s3:
<tt>>>snew=[s1; s2; s3];</tt>
 

Installation

To use spec1d you need to:

You should create a directory called 'spec1d' in a directory which should be entered in your matlab path. Below this directory create
another directory called @spec1d. Place the files formatpars.m, loads.m, specdfdp.m, and speclsqr.m in the spec1d directory, and
all other files in @spec1d. Obtaining latest Matlab stuff (MFit/MView/Rescal/SSym/load/funcs/nllsq) from http://www.ill.fr/computing/cs-software/all-softwares/matlab-ill/#c4703

Case Studies

The examples here are designed to illustrate the versatility of spec1d in attackng complex data analysis problems in a flexible and transparent way.

Case Study 1: Fitting the order parameter of the magnetic transition in MnPS3