# Difference between revisions of "Manipulating and extracting data from SQW files and objects"

Toby Perring (Talk | contribs) |
Toby Perring (Talk | contribs) |
||

Line 17: | Line 17: | ||

'''Orthogonal axes case''' | '''Orthogonal axes case''' | ||

− | The <code>proj</code> structure has several fields | + | The <code>proj</code> structure has several fields: |

*<code>proj.u</code> is a 3-component vector of the form (h,k,l) which specifies the first viewing axis. | *<code>proj.u</code> is a 3-component vector of the form (h,k,l) which specifies the first viewing axis. | ||

*<code>proj.v</code> is another 3-component vector of the same type which determines the second viewing axis: it is constructed to be in the plane of <code>proj.u</code> and <code>proj.v</code> and perpendicular to <code>proj.u</code>. | *<code>proj.v</code> is another 3-component vector of the same type which determines the second viewing axis: it is constructed to be in the plane of <code>proj.u</code> and <code>proj.v</code> and perpendicular to <code>proj.u</code>. | ||

− | 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. | + | 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. |

+ | There are optional fields too: | ||

+ | *<code>proj.uoffset</code>, specifies an offset for all cuts, which is a 3-component vector in [h,k,l] or a 4-vector [h,k,l,e]. For example you may wish to make the origin of all your plots (2,1,0), in which case set <code>proj.uoffset=[2,1,0]</code>. | ||

+ | *<code>proj.type</code> specifies a three character string denoting the unit of measure along each of the three Q-axes, one character for each axis. If you want an axis to be displayed in inverse Angstroms, set the character to 'a'. For r.l.u. set the corresponding character to 'r' (which normalises so that the maximum of |h|,|k| and |l| is unity) or 'p' (which preserves the values of <code>proj.u</code> and <code>proj.v</code>. 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 <code>proj.type='rra'</code>. | ||

+ | *<code>proj.lab1='labelname'</code> supplies a label for the first projection axis, and <code>proj.lab2='labelname'</code> supplies a label for the second etc.s. | ||

'''Non-orthogonal axes case''' | '''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 <code>proj</code> is specified in the same way as above, however | + | In the case when the crystal lattice is not orthogonal there are two options for viewing the data. In the default case the <code>proj</code> is specified in the same way as above, however remember that, for example, 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), <code>proj.nonorthogonal = true</code> (and optionally <code>proj.w=[0,0,1]</code>). This forces the axes to be the ones you define, even if they are not orthogonal. Beware the plots that are produced | + | 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), <code>proj.nonorthogonal = true</code> (and optionally specify the third projection axis by setting <code>proj.w=[0,0,1]</code>). This forces the axes to be the ones you define, even if they are not orthogonal. Beware the plots that are produced plot them as orthogonal axes so any features may be skewed. However, it does make reading the location of a feature in a two-dimensional Q-Q plot straightforward, which is the main reason for doing this. |

+ | '''Binning arguments''' | ||

− | The inputs <code>p1_bin</code> 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 | + | The inputs <code>p1_bin</code> 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. The lower and upper limits will be determined by the extent of the data along that direction. | ||

+ | *If you specify a vector with three 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 two 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: | Optional arguments are provided as follows: |

## Revision as of 16:20, 16 January 2019

## Contents

## 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. There are optional fields too:

`proj.uoffset`

, specifies an offset for all cuts, which is a 3-component vector in [h,k,l] or a 4-vector [h,k,l,e]. For example you may wish to make the origin of all your plots (2,1,0), in which case set`proj.uoffset=[2,1,0]`

.`proj.type`

specifies a three character string denoting the unit of measure along each of the three Q-axes, one character for each axis. If you want an axis to be displayed in inverse Angstroms, set the character to 'a'. For r.l.u. set the corresponding character to 'r' (which normalises so that the maximum of |h|,|k| and |l| is unity) or 'p' (which preserves the values of`proj.u`

and`proj.v`

. 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'`

.`proj.lab1='labelname'`

supplies a label for the first projection axis, and`proj.lab2='labelname'`

supplies a label for the second etc.s.

**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 remember that, for example, 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 specify the third projection axis by setting `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 plot them as orthogonal axes so any features may be skewed. However, it does make reading the location of a feature in a two-dimensional Q-Q plot straightforward, which is the main reason for doing this.

**Binning arguments**

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. The lower and upper limits will be determined by the extent of the data along that direction.
- If you specify a vector with three 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 two 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.

## head_sqw

info=head_sqw(filename); info=head_sqw(filename,'-full')

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.

## head_dnd

info=head_dnd(filename);

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`

.

## head_horace

info=head_horace(filename); info=head_horace(filename,'-full')

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.

## read_sqw

output=read_sqw(filename);

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.

## read_dnd

output=read_dnd(filename);

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.

## read_horace

output=read_horace(filename);

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