Manipulating and extracting data from SQW files and objects

cut_sqw

There are various different forms of input for this function, the purpose of which is to take data from an SQW file and turn it into a n-dimensional cut which can be plotted, manipulated, etc. The "compulsory" inputs are given as follows:

my_cut = cut_sqw (data_source, proj, p1_bin, p2_bin, p3_bin)

data_source is a string giving the full filename (including path) of the input SQW file.

Projection axes

This defines the coordinate system you will use to view the data.

proj is a Matlab structure array containing information about the axes you wish to use to view the data. Because each point in the SQW file is labelled with h, k, and l (the reciprocal lattice vectors), and energy, it is possible, if you wish, to redefine the co-ordinate system with one of your choosing. For example you may wish to view the data in terms of (h,h,0)/(h,-h,0)/(0,0,l). This is distinct from the vectors u and v that are specified in gen_sqw, which describe how the crystal is oriented with respect to the spectrometer and are determined by the physical orientation of your sample.

Orthogonal axes case

The proj structure has several fields.

• proj.u is a 3-component vector of the form (h,k,l) which specifies the first viewing axis.
• proj.v is another 3-component vector of the same type which determines the second viewing axis: it is constructed to be in the plane of proj.u and proj.v and perpendicular to proj.u.

The program then automatically calculates the third viewing axes to be the cross product of the first two. The 4th axis is always energy and need not be specified. An offset for all cuts can be provided in the field proj.uoffset, which is a 4-component vector. For example you may wish to make the origin of all your plots (2,1,0), in which case proj.uoffset=[2,1,0,0] would be written. Finally you can specify proj.type, which is a string denoting whether each of the 3 Q-axes should be displayed in inverse Angstroms or in r.l.u. For example, if we wanted the first two Q-components to be in r.l.u. and the third to be in inverse Angstroms we would have proj.type='rra'. You can optionally supply names for the various axes by specifying proj.lab1='labelname' and so on.

Non-orthogonal axes case

In the case when the crystal lattice is not orthogonal there are two options for viewing the data. In the default case the proj is specified in the same way as above, however proj.v defines a vector in the orthonormal plane u,v. So if proj.u = (1,0,0) and proj.v=(0,1,0), but (1,0,0) and (0,1,0) are not orthongonal in reciprocal space, the second viewing axes will actually be the vector orthogonal to proj.u in the plane of proj.u and proj.v. The third axis is then the cross product as before.

You may optionally choose to use non-orthogonal axes, as in the following example. Specify proj.u = (1,0,0), proj.v=(0,1,0), proj.nonorthogonal = true (and optionally proj.w=[0,0,1]). This forces the axes to be the ones you define, even if they are not orthogonal. Beware the plots that are produced do have orthogonal axes (because of a limitation of Matlab) so any features may be skewed.

The inputs p1_bin etc. can have 3 different forms. If a single number (scalar) is given then that axis will be a plot axis and the bin width will be the number you specify, and the lower and upper limits will be determined by the extent of the data. If you specify a vector with 3 components then that axis will be a plot axis with the first and last components specifying the lower and upper limits of data to be cut, and the middle component specifies the bin width. If you specify a vector with 2 components then the signal will be integrated over that axis between limits specified by the two components of the vector.

Optional arguments are provided as follows:

my_cut = cut_sqw (data_source, proj, p1_bin, p2_bin, p3_bin, p4_bin, '-nopix', filename)

p4_bin specifies the binning / integration along the energy axis. In addition to the forms listed above for Q-axes, it is also possible to specify a binning of 0 for the energy axis only. In this case the energy binning that was specified when the raw data were converted into SPE format by Homer is used. The option '-nopix' means that the individual pixel information contributing to the resulting data is NOT retained (at present the default is to retain it, resulting in an output that is an sqw object, whereas using '-nopix' gives a dnd output). The filename optional argument is a string specifying a full filename (including path) for the data to be stored, in addition to being stored in the Matlab workspace.

cut

This is a specific case of cut_sqw, and can be used to take cuts from objects that are already in memory, rather than on disk in the SQW file.

To take a cut from an existing sqw or dnd object, retaining the existing projection axes and binning:

w1=cut(w,[],[lo1,hi1],[lo2,hi2],...)

Note that the number of binning arguments need only match the dimensionality of the object w, so can be fewer than 4. Note also that you cannot change the binning in a dnd object, i.e. you can only set the integration ranges and have to use [] for the plot axis.

To take a cut from an existing sqw object and change the binning along one or more of the plot axes:

w1=cut(w,[lo,step,hi],[lo1,hi1],....)

To take a cut from an existing sqw object and change the plot axes (i.e. use a new set of projections):

w1=cut(w,proj,[lo1,step1,hi1],[lo2,step2,hi2],[lo3,step3,hi3],[lo4,step4,hi4])

This is essentially the same syntax as cut_sqw, but with an sqw object rather than an SQW file as the first input.

This is a function to give the header information in an SQW file or file to which an sqw object has been saved, whose full filename is given by the argument filename. If the option '-full' is used then a fuller seat of header information, rather than just the principal header, is returned.

This is a function to give the header information in file to which a dnd object has been saved, whose full filename is given by the argument filename.

This is a function to give the header information in an SQW file or file to which an sqw object or dnd object has been saved, and whose full filename is given by the argument filename. If the option '-full' is used then a fuller seat of header information, rather than just the principal header, is returned. The purpose of this function is to read the contents regardless of your knowledge of whether or not it contains an sqw object or a dnd object.

This is a function to read sqw data from a file. Note that in this context we mean an n-dimensional dataset, which includes pixel information, that has been saved to file. This could be either a full SQW file, or an sqw dataset that has been saved to file. The object output will be an sqw object.

Exactly the same as above, but reads dnd data saved to file. If the file contains full sqw dataset, then it will be read as if it contained just a dnd dataset.

As above, but the output object is determined by the file contents. If the file contains a full sqw dataset, the output is an sqw object; if the file contains a dnd dataset, the output is the corresponding d01, d1d, ...d4d object.

save

save(object,filename)

Saves the sqw object or dnd object object from the Matlab workspace into the file specified by filename.

save_xye

Save data in an sqw or dnd dataset to an ascii file.

filename='C:\mprogs\my_ascii_file.txt';
save_xye(w_in,filename);

The format of the ascii file for an n-dimensional dataset is n columns of co-ordinates along each of the axes, plus one column of signal and another column of error (standard deviation).

xye

Extract the bin centres, intensity and standard errors from an sqw or dnd object.

S=xye(w);

The output is a structure with fields S.x (bin centres if a 1D object, or cell array of vectors containing the bin centres along each axis if 2D, 3D or 4D object), S.y (array of intensities), S.e (array of estimated error on the intensities).

hkle

Obtain the reciprocal space coordinate [h,k,l,e] for points in the coordinates of the display axes for an sqw object from a single spe file

[qe1,qe2] = hkle(w,x)

The inputs take the form:

w - sqw object x - Vector of coordinates in the display axes of an sqw object. The number of coordinates must match the dimensionality of the object. e.g. for a 2D sqw object, x=[x1,x2], where x1, x2 are column vectors. More than one point can be provided by giving more rows e.g. [1.2,4.3; 1.1,5.4; 1.32, 6.7] for 3 points from a 2D object. Generally, an (n x nd) array, where n is the number of points, and nd the dimensionality of the object.

The outputs take the form:

qe1 - Components of momentum (in rlu) and energy for each bin in the dataset. Generally, will be (n x 4) array, where n is the number of points

qe2 - For the second root