API Reference
SQWDndBase class
- sqw.@SQWDnDBase.IX_dataset_1d(w)
Convert 1D sqw object into IX_dataset_1d
>> wout = IX_dataset_1d (w)
- sqw.@SQWDnDBase.IX_dataset_2d(w)
Convert 2D sqw object into IX_dataset_2d
>> wout = IX_dataset_2d (w)
- sqw.@SQWDnDBase.IX_dataset_3d(w)
Convert 3D sqw object into IX_dataset_3d
>> wout = IX_dataset_3d (w)
- class sqw.@SQWDnDBase.SQWDnDBase
SQWDnDBase Abstract SQW/DnD object base class Abstract class defining common API and atrributes of the SQW and DnD objects
- sqw.@SQWDnDBase.acos(w1)
Implements acos(w1) for objects
>> w = acos(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.acosh(w1)
Implements acosh(w1) for objects
>> w = acosh(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.acot(w1)
Implements acot(w1) for objects
>> w = acot(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.acoth(w1)
Implements acoth(w1) for objects
>> w = acoth(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.acsc(w1)
Implements acsc(w1) for objects
>> w = acsc(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.acsch(w1)
Implements acsch(w1) for objects
>> w = acsch(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.asec(w1)
Implements asec(w1) for objects
>> w = asec(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.asech(w1)
Implements asech(w1) for objects
>> w = asech(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.asin(w1)
Implements asin(w1) for objects
>> w = asin(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.asinh(w1)
Implements asinh(w1) for objects
>> w = asinh(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.atan(w1)
Implements atan(w1) for objects
>> w = atan(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.atanh(w1)
Implements atanh(w1) for objects
>> w = atanh(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.binary_op_manager(w1, w2, binary_op)
Implements a binary operation for objects with a signal and a variance array.
>> w = binary_op_manager(w1, w2, binary_op)
All binary operations on Matlab double arrays are permitted (+, -, *, /, ) and are applied element by element to the signal and variance arrays.
Input:
- w1, w2 Objects on which the binary operation is to be performed.
One of these can be a Matlab double (i.e. double precision) array, in which case the variance array is taken to be zero.
If w1, w2 are scalar objects with the same signal array sizes: - The operation is performed element-by-element.
If one of w1 or w2 is a double array (and the other is a scalar object): - If a scalar, apply to each element of the object signal. - If it is an array of the same size as the object signal
array, apply the operation element by element.
If one or both of w1 and w2 are arrays of objects: - If objects have same array sizes, the binary operation is
applied object element-by-object element.
If one of the objects is scalar (i.e. only one object),
then it is applied by the binary operation to each object in the other array.
If one of w1, w2 is an array of objects and the other is a double array: - If the double is a scalar, it is applied to every object
in the array.
If the double is an array with the same size as the object
array, then each element is applied as a scalar to the corresponding object in the object array.
If the double is an array with larger size than the object
array, then the array is resolved into a stack of arrays, where the stack has the same size as the object array, and the each array in the stack is applied to the corresponding object in the object array. [Note that for this operation to be valid, each object must have the same signal array size.]
- binary_op Function handle to a binary operation. All binary operations
on Matlab double or single arrays are permitted (+, -, *, /, ).
Output:
w Output object or array of objects.
NOTES: This is a generic method - works for any class (including sigvar) so long as the methods below are defined on that class.
Requires that objects have the following methods to find the size of the public signal and variance arrays, create a sigvar object from those arrays, and set them from another sigvar object.
- >> sz = sigvar_size(obj) % Returns size of public signal and variance
% arrays
- >> w = sigvar(obj) % Create a sigvar object from the public
% signal and variance arrays
- >> obj = sigvar_set(obj,w) % Set signal and variance in an object from
% those in a sigvar object
- sqw.@SQWDnDBase.calculate_q_bins(win)
Calculate qh,qk,ql,en for the centres of the bins of an n-dimensional sqw or dnd dataset
>> [q,en]=calculate_q_bins(win)
Input:
win Input sqw/dnd object
Output:
- q Components of momentum (in rlu) for each bin in the dataset for a single energy bin
Arrays are packaged as cell array of column vectors for convenience with fitting routines etc.
i.e. q{1}=qh, q{2}=qk, q{3}=ql
- en Column vector of energy bin centres. If energy was an integration axis, then returns the
centre of the energy integration range
- sqw.@SQWDnDBase.calculate_qw_bins(win, optstr)
Calculate qh,qk,ql,en for the centres of the bins of an n-dimensional sqw or dnd dataset
>> qw=calculate_qw_bins(win) >> qw=calculate_qw_bins(win,’boundaries’) >> qw=calculate_qw_bins(win,’edges’)
Input:
win Input sqw or dnd object
Optional arguments: ‘boundaries’ Return qh,qk,ql,en at verticies of bins, not centres ‘edges’ Return qh,qk,ql,en at verticies of the hyper cuboid that
encloses the plot axes
Output:
- qw Components of momentum (in rlu) and energy for each bin in
the dataset Arrays are packaged as cell array of column vectors for convenience with fitting routines etc.
i.e. qw{1}=qh, qw{2}=qk, qw{3}=ql, qw{4}=en
Note that the centre of the integration range is used in
the calculation of qh,qk,ql,en even with the options ‘boundaries’ or ‘edges’
If one or both of the integration ranges is infinite, then
the value of the corresponding coordinate is taken as zero.
- sqw.@SQWDnDBase.change_crystal(varargin)
Change the crystal lattice and orientation of an sqw object or array of objects
- Most commonly:
>> wout = change_crystal (w, rlu_corr) % change lattice parameters and orientation
- OR
>> wout = change_crystal (w, alatt) % change just length of lattice vectors >> wout = change_crystal (w, alatt, angdeg) % change all lattice parameters >> wout = change_crystal (w, alatt, angdeg, rotmat) % change lattice parameters and orientation >> wout = change_crystal (w, alatt, angdeg, u, v) % change lattice parameters and redefine u, v
Input:
w Input sqw object
- rlu_corr Matrix to convert notional rlu in the current crystal lattice to
the rlu in the the new crystal lattice together with any re-orientation of the crystal. The matrix is defined by the matrix:
qhkl(i) = rlu_corr(i,j) * qhkl_0(j)
This matrix can be obtained from refining the lattice and
orientation with the function refine_crystal (type >> help refine_crystal for more details).
- OR
alatt New lattice parameters [a,b,c] (Angstroms) angdeg New lattice angles [alf,bet,gam] (degrees) rotmat Rotation matrix that relates crystal Cartesian coordinate frame of the new
lattice as a rotation of the current crystal frame. Orthonormal coordinates in the two frames are related by
v_new(i)= rotmat(i,j)*v_current(j)
- u, v Redefine the two vectors that were used to determine the scattering plane
These are the vectors at whatever disorientation angles dpsi, gl, gs (which cannot be changed).
Output:
wout Output sqw object with changed crystal lattice parameters and orientation
- NOTE
The input data set(s) can be reset to their original orientation by inverting the input data e.g.
call with inv(rlu_corr)
call with the original alatt, angdeg, u and v
- sqw.@SQWDnDBase.compact(win)
Squeezes the data range in an sqw or dnd object to eliminate empty bins
- Syntax:
>> wout = compact(win)
Input:
win Input object
Output:
- wout Output object, with length of axes reduced to yield the
smallest cuboid that contains the non-empty bins.
- sqw.@SQWDnDBase.convert_bins_for_shoelace(win, wref)
Converts data in the d2d object win into appropriate format for the shoelace rebinning function (i.e. bin corners rather than bin boundaries). The co-ordinate system is defined by the d2d object wref. If wref is empty then the co-ordinate system remains unchanged.
RAE 23/9/09
- sqw.@SQWDnDBase.cos(w1)
Implements cos(w1) for objects
>> w = cos(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.cosh(w1)
Implements cosh(w1) for objects
>> w = cosh(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.cot(w1)
Implements cot(w1) for objects
>> w = cot(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.coth(w1)
Implements coth(w1) for objects
>> w = coth(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.csc(w1)
Implements csc(w1) for objects
>> w = csc(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.csch(w1)
Implements csch(w1) for objects
>> w = csch(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.cut_dnd_calc_ubins(pbin, pin, nbin)
Create bin boundaries for integration and plot axes from requested limits and step sizes Uses knowledge of the range of the data and energy bins of the data to set values for those not provided.
- Syntax:
>> [iiax, ipax, p, noffset, nkeep, mess] = cut_dnd_calc_ubins (pbin, pin, nbin)
Input:
- pbin Cell array of requested limits and bins for plot axes:
pbin{1} Binning along first plot axis pbin{2} Binning along second plot axis
:
for as many axes as there are plot axes. For each binning entry:
[] or ‘’ Plot axis: use bin boundaries of input data
- [pstep] Plot axis: sets step size; plot limits taken from extent of the data
If pstep=0 then use current bin size and synchronise
the output bin boundaries with the current boundaries. The overall range is chosen to ensure that the range of the input data is contained within the bin boundaries.
- [plo, phi] Integration axis: range of integration - those bin centres that lie inside this range
are included.
- [plo, pstep, phi] Plot axis: minimum and maximum bin centres and step size
If pstep=0 then use current bin size and synchronise
the output bin boundaries with the current boundaries. The overall range is chosen to ensure that the range plo to phi is contained within the bin boundaries.
pin Cell array current bin boundaries on plot axes.
- nbin [2 x ndim] array containing the lower and upper indices of the
extremal elements along each axis
Output:
iax Index of integration axes into the incoming plot axes [row vector] iint Integration range for the new integration axes [(2 x length(iax)) vector] pax Index of plot axes into the incoming plot axes [row vector] p Call array containing bin boundaries along the remaining plot axes [column vectors]
i.e. data.p{1}, data.p{2} … (for as many plot axes as given by length of data.pax)
- noffset Offset along the remaining plot axes of the section from the input signal array (nkeep, below)
once the axes to be integrated over have been summed [row vector, length=no. elements of p]
nkeep Section of the input signal array to be retained: [2xndim], ndim=length(pin) mess Error message; empty if all was OK; non-empty otherwise (in which case all other output are empty)
Use this as the sole criterion of succesful operation because empty arrays for other outputs can be valid e.g. iax=[] and iint=[] if all axes are plot axes.
Notes
if the range of the data is zero along a plot axis, then the two bin boundaries
will both have the same value, even if a non-zero bin size was input.
- sqw.@SQWDnDBase.da(w, varargin)
Draw an area plot of a 2D sqw dataset or array of datasets
>> da(w) >> da(w,xlo,xhi) >> da(w,xlo,xhi,ylo,yhi) >> da(w,xlo,xhi,ylo,yhi,zlo,zhi)
- Advanced use:
>> da(w,…,’name’,fig_name) % Draw with name = fig_name
- >> da(w,…,’-noaspect’) % Do not change aspect ratio
% according to data axes unit lengths
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = da(w,…)
- sqw.@SQWDnDBase.dd(w, varargin)
Draws a plot of markers, error bars and lines of a 1D sqw object or array of objects
>> dd(w) >> dd(w,xlo,xhi) >> dd(w,xlo,xhi,ylo,yhi)
- Advanced use:
>> dd(w,…,’name’,fig_name) % draw with name = fig_name
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = dd(w,…)
- sqw.@SQWDnDBase.de(w, varargin)
Draws a plot of error bars of a 1D sqw object or array of objects
>> de(w) >> de(w,xlo,xhi) >> de(w,xlo,xhi,ylo,yhi)
- Advanced use:
>> de(w,…,’name’,fig_name) % draw with name = fig_name
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = de(w,…)
- sqw.@SQWDnDBase.dh(w, varargin)
Draws a histogram plot of a 1D sqw object or array of objects
>> dh(w) >> dh(w,xlo,xhi) >> dh(w,xlo,xhi,ylo,yhi)
- Advanced use:
>> dh(w,…,’name’,fig_name) % draw with name = fig_name
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = dh(w,…)
- sqw.@SQWDnDBase.dimensions(w)
Find number of dimensions and extent along each dimension of the signal arrays. - If 0D sqw object, nd=0, sz=zeros(1,0) (nb: []==zeros(0,0)) - if 1D sqw object, nd=1, sz=n1 - If 2D sqw object, nd=2, sz=[n1,n2] - If 3D sqw object, nd=3, sz=[n1,n2,n3] even if n3=1 - If 4D sqw object, nd=4, sz=[n1,n2,n3,n4] even if n4=1
The convention is that size(sz)=1 x ndim
>> [nd,sz]=dimensions(w)
- sqw.@SQWDnDBase.dimensions_match(w, nd_ref)
Check that the dimensions of an array of sqw objects are all the same
>> [ok,mess]=dimensions_match(w) >> [ok,mess]=dimensions_match(w,nref)
Input:
w sqw object or array of objects nd_ref [optional] If not given, check all sqw objects in the array
have the same dimensionality. If given, check that they match this dimensionality
Output:
ok True if all have the smae dimensionality (and match nref, if given) mess Empty if ok==true; error message if not nd Dimensionality
- sqw.@SQWDnDBase.disp2sqw_eval(win, dispreln, pars, fwhh, varargin)
Calculate sqw for a model scattering function
>> wout = disp2sqw_eval(win,dispreln,pars,fwhh,varargin)
Input:
- win Dataset, or array of datasets, that provides the axes and points
for the calculation
- dispreln Handle to function that calculates the dispersion relation w(Q) and
spectral weight, s(Q) Must have form:
[w,s] = dispreln (qh,qk,ql,p)
- where
- qh,qk,ql Arrays containing the coordinates of a set of points
in reciprocal lattice units
- p Vector of parameters needed by dispersion function
e.g. [A,js,gam] as intensity, exchange, lifetime
- w Array of corresponding energies, or, if more than
one dispersion relation, a cell array of arrays.
- s Array of spectral weights, or, if more than
one dispersion relation, a cell array of arrays.
- More general form is:
[w,s] = dispreln (qh,qk,ql,p,c1,c2,..)
- where
- p Typically a vector of parameters that we might want
to fit in a least-squares algorithm
- c1,c2,… Other constant parameters e.g. file name for look-up
table.
- pars Arguments needed by the function. Most commonly, a vector of parameter
values e.g. [A,js,gam] as intensity, exchange, lifetime. If a more general set of parameters is required by the function, then package these into a cell array and pass that as pars. In the example above then pars = {p, c1, c2, …}
- fwhh Parametrizes the resolution function. There are three
possible input values of fwhh:
- double A single FWHM value determines the FWHM of the
Gaussian resolution function
- function_handle A function that produces the FWHM value as a
function of energy transfer, it has to have the following simple header (where omega can be a row vector of energies:
dE = resfun(omega)
- function_handle A function handle of a function with two input
- parameters with the following header:
I = shapefun(Emat,omega)
where Emat is a matrix with dimensions of [nQ nE] and omega is a column vector with nQ elements. The shapefun produces a peakshape for every Q point centered at the given omega and normalized to one. The output I has the same dimensions as the input Emat.
Optional arguments: (varargin)
- ‘-al[l]’ Requests that the calculated sqw be returned over
the whole of the domain of the input dataset. If not given, then the function will be returned only at those points of the dataset that contain data. Applies only to input with no pixel information - it is ignored if full sqw object.
- ‘-av[erage]’ Requests that the calculated sqw be computed for the
average values of h,k,l of the pixels in a bin, not for each pixel individually. Reduces cost of expensive calculations.
Applies only to the case of sqw object with pixel information - it is
ignored if dnd type object.
Output:
wout Output dataset or array of datasets
- sqw.@SQWDnDBase.dispersion(win, dispreln, pars)
Calculate dispersion relation for dataset or array of datasets.
>> wdisp = dispersion (win, dispreln, p) % dispersion only >> [wdisp,weight] = dispersion (win, dispreln, p) % dispersion and spectral weight
The output dataset (or array of data sets), wdisp, will retain only the Q axes, and the signal array(s) will contain the values of energy along the Q axes. If the dispersion relation returns the spectral weight, this will be placed in the error array (actually the square of the spectral weight is put in the error array). In the case when the dispersion has been calculated on a plane in momentum (i.e. wdisp is IX_datset_2d) then the plot function ps2 (for plot_surface2)
>> ps2(wdisp)
will plot a surface with the z axis as energy and coloured according to the spectral weight.
The dispersion relation is calculated at the bin centres (that is, the individual pixel information in a sqw input object is not used).
If the function that calculates dispersion relations produces more than one branch, then in the case of a single input dataset the output will be an array of datasets, one for each branch. If the input is an array of datasets, then only the first dispersion branch will be returned, so there is one output dataset per input dataset.
Input:
- win Dataset that provides the axes and points for the calculation
If one of the plot axes is energy transfer, then the output dataset
will have dimensionality one less than the input dataset
- dispreln Handle to function that calculates the dispersion relation w(Q)
- Must have form:
[w,s] = dispreln (qh,qk,ql,p)
- where
- qh,qk,ql Arrays containing the coordinates of a set of points
in reciprocal lattice units
- p Vector of parameters needed by dispersion function
e.g. [A,js,gam] as intensity, exchange, lifetime
- w Array of corresponding energies, or, if more than
one dispersion relation, a cell array of arrays.
- s Array of spectral weights, or, if more than
one dispersion relation, a cell array of arrays.
- More general form is:
[w,s] = dispreln (qh,qk,ql,p,c1,c2,..)
- where
- p Typically a vector of parameters that we might want
to fit in a least-squares algorithm
- c1,c2,… Other constant parameters e.g. file name for look-up
table.
- p Arguments needed by the function. Most commonly, a vector of parameter
values e.g. [A,js,gam] as intensity, exchange, lifetime. If a more general set of parameters is required by the function, then package these into a cell array and pass that as pars. In the example above then pars = {p, c1, c2, …}
Output:
- wdisp Output dataset or array of datasets of the same type as the input argument.
The output dataset (or array of data sets) will retain only the Q axes, the
the signal array(s) will contain the values of energy along the Q axes, and the error array will contain the square of the spectral weight.
If the function that calculates dispersion relations produces more than one
branch, then in the case of a single input dataset the output will be an array of datasets, one for each branch. If the input is an array of datasets, then only the first dispersion branch will be returned, so there is one output dataset per input dataset.
- weight Mirror output: the signal is the spectral weight, and the error array
contains the square of the frequency.
- e.g. If win is a 2D dataset with Q and E axes, then wdisp is a 1D dataset
with just the Q axis
- sqw.@SQWDnDBase.dl(w, varargin)
Draws a line plot of a 1D sqw object or array of objects
>> dl(w) >> dl(w,xlo,xhi) >> dl(w,xlo,xhi,ylo,yhi)
- Advanced use:
>> dl(w,…,’name’,fig_name) % draw with name = fig_name
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = dl(w,…)
- sqw.@SQWDnDBase.dm(w, varargin)
Draws a marker plot of a 1D sqw object or array of objects
>> dm(w) >> dm(w,xlo,xhi) >> dm(w,xlo,xhi,ylo,yhi)
- Advanced use:
>> dm(w,…,’name’,fig_name) % draw with name = fig_name
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = dm(w,…)
- sqw.@SQWDnDBase.dp(w, varargin)
Draws a plot of markers and error bars for a 1D sqw object or array of objects
>> dp(w) >> dp(w,xlo,xhi) >> dp(w,xlo,xhi,ylo,yhi)
- Advanced use:
>> dp(w,…,’name’,fig_name) % draw with name = fig_name
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = dp(w,…)
- sqw.@SQWDnDBase.ds(w, varargin)
Draw a surface plot of a 2D sqw dataset or array of datasets
>> ds(w) >> ds(w,xlo,xhi) >> ds(w,xlo,xhi,ylo,yhi) >> ds(w,xlo,xhi,ylo,yhi,zlo,zhi)
- Advanced use:
>> ds(w,…,’name’,fig_name) % Draw with name = fig_name
- >> ds(w,…,’-noaspect’) % Do not change aspect ratio
% according to data axes unit lengths
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = ds(w,…)
- sqw.@SQWDnDBase.ds2(w, varargin)
Draw a surface plot of a 2D sqw dataset or array of datasets
>> ds2(w) % Use error bars to set colour scale >> ds2(w,wc) % Signal in wc sets colour scale
% wc can be any object with a signal array with same % size as w, e.g. sqw object, IX_dataset_2d object, or % a numeric array. % - If w is an array of objects, then wc must contain % the same number of objects. % - If wc is a numeric array then w must be a scalar % object.
>> ds2(…,xlo,xhi) >> ds2(…,xlo,xhi,ylo,yhi) >> ds2(…,xlo,xhi,ylo,yhi,zlo,zhi)
Differs from ds in that the signal sets the z axis, and the colouring is set by the error bars, or by another object. This enables two related functions to be plotted (e.g. dispersion relation where the ‘signal’ array holds the energy and the error array holds the spectral weight).
- Advanced use:
>> ds2(w,…,’name’,fig_name) % Draw with name = fig_name
- >> ds2(w,…,’-noaspect’) % Do not change aspect ratio
% according to data axes unit lengths
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = ds2(…)
- sqw.@SQWDnDBase.equal_to_tol(w1, w2, varargin)
Check if two sqw objects are equal to a given tolerance
>> ok = equal_to_tol (a, b) >> ok = equal_to_tol (a, b, tol) >> ok = equal_to_tol (…, keyword1, val1, keyword2, val2,…) >> [ok, mess] = equal_to_tol (…)
- Class specific version of the generic equal_to_tol that by default
assumes NaN are equivalent (see option ‘nan_equal’), and
ignores the order of pixels within a bin as the order is irrelevant (change the default with option ‘reorder’)
In addition, it is possible to check the contents of just a random fraction of non-empty bins (see option ‘fraction’) in order to speed up the comparison of large objects.
Input:
w1,w2 Test objects (scalar objects, or arrays of objects with same sizes)
- tol Tolerance criterion for numeric arrays (Default: [0,0] i.e. equality)
- It has the form: [abs_tol, rel_tol] where
abs_tol absolute tolerance (>=0; if =0 equality required) rel_tol relative tolerance (>=0; if =0 equality required)
If either criterion is satified then equality within tolerance is accepted.
- Examples:
[1e-4, 1e-6] absolute 1e-4 or relative 1e-6 required [1e-4, 0] absolute 1e-4 required [0, 1e-6] relative 1e-6 required [0, 0] equality required 0 equivalent to [0,0]
For backwards compatibility, a scalar tolerance can be given where the sign determines absolute or relative tolerance
+ve : absolute tolerance abserr = abs(a-b) -ve : relative tolerance relerr = abs(a-b)/max(abs(a),abs(b))
- Examples:
1e-4 absolute tolerance, equivalent to [1e-4, 0] -1e-6 relative tolerance, equivalent to [0, 1e-6]
- [To apply an absolute as well as a relative tolerance with a
scalar negative value, set the value of the legacy keyword
‘min_denominator’ (see below)]
- Valid keywords are:
‘nan_equal’ Treat NaNs as equal (true or false; default=true)
- ‘ignore_str’ Ignore the length and content of strings or cell arrays
of strings (true or false; default=false)
- ‘reorder’ Ignore the order of pixels within each bin
- (true or false; default=true)
Only applies if sqw-type object
- ‘fraction’ Compare pixels in only a fraction of the non-empty bins
- (0<= fracton <= 1; default=1 i.e. test all bins)
Only applies if sqw-type object
The reorder and fraction options are available because the order of the
pixels within the pix array for a given bin is unimportant. Reordering takes time, however, so the option to test on a few bins is given.
- sqw.@SQWDnDBase.exp(w1)
Implements exp(w1) for objects
>> w = exp(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.func_eval(win, func_handle, pars, varargin)
Evaluate a function at the plotting bin centres of sqw object or array of sqw object Syntax:
>> wout = func_eval (win, func_handle, pars) >> wout = func_eval (win, func_handle, pars, [‘all’]) >> wout = func_eval (win, func_handle, pars, ‘outfile’, ‘output.sqw’)
If function is called on sqw-type object (i.e. has pixels), the pixels’ signal is also modified and evaluated
Input:
- win Dataset or array of datasets; the function will be evaluated
at the bin centres along the plot axes
- func_handle Handle to the function to be evaluated at the bin centres
- Must have form:
y = my_function (x1,x2,… ,xn,pars)
- or, more generally:
y = my_function (x1,x2,… ,xn,pars,c1,c2,…)
x1,x2,.xn Arrays of x coordinates along each of the n dimensions
pars Parameters needed by the function
- c1,c2,… Any further arguments needed by the function e.g.
they could be the filenames of lookup tables for resolution effects)
- e.g. y=gauss2d(x1,x2,[ht,x0,sig])
y=gauss4d(x1,x2,x3,x4,[ht,x1_0,x2_0,x3_0,x4_0,sig1,sig2,sig3,sig4])
- pars Arguments needed by the function.
Most commonly just a numeric array of parameters
If a more general set of parameters is needed by the function, then wrap as a cell array {pars, c1, c2, …}
- keyword outfile If present, the output of func_eval will be written to the file:
of the given name/path. If numel(win) > 1, outfile must be omitted or a cell array of file paths with equal number of elements as win.
- Additional allowed options:
- ‘all’ Requests that the calculated function be returned over
the whole of the domain of the input dataset. If not given, then the function will be returned only at those points of the dataset that contain data.
Applies only to input with no pixel information - this option is ignored if
the input is a full sqw object.
Output:
wout Output objects or array of objects
- e.g.
>> wout = func_eval (w, @gauss4d, [ht,x1_0,x2_0,x3_0,x4_0,sig1,sig2,sig3,sig4])
- where the function gauss appears on the matlab path
function y = gauss4d (x1, x2, x3, x4, pars) y = (pars(1)/(sig*sqrt(2*pi))) * …
- sqw.@SQWDnDBase.get_proj_and_pbin(w)
Reverse engineer the projection and binning of an sqw object
>> [proj, pbin] = get_proj_and_pbin (w)
Input:
w sqw object
Output:
proj Projection as a projaxes object pbin Cell array, a row length 4, of the binning description of the
sqw object
- sqw.@SQWDnDBase.log(w1)
Implements log(w1) for objects
>> w = log(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.log10(w1)
Implements log10(w1) for objects
>> w = log10(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.mask(win, mask_array)
Remove the bins indicated by the mask array
>> wout = mask (win, mask_array)
Input:
win Input sqw object
- mask_array Array of 1 or 0 (or true or false) that indicate
- which points to retain (true to retain, false to ignore)
Numeric or logical array of same number of elements
- as the data_.
Note: mask will be applied to the stored data array
according as the projection axes, not the display axes. Thus permuting the display axes does not alter the effect of masking the data_.
Output:
wout Output dataset.
Original author: T.G.Perring
- sqw.@SQWDnDBase.mask_pixels(win, mask_array)
Remove the pixels indicated by the mask array
>> wout = mask_pixels (win, mask_array) % Mask array >> wout = mask_pixels (win, wmask) % Mask according to pixel array
% contents
Input:
win Input sqw object
- mask_array Array of 1 or 0 (or true or false) that indicate
- which pixels to retain (true to retain, false to ignore)
Numeric or logical array of same number of pixels
- as the data.
Note: mask will be applied to the stored data array
according as the projection axes, not the display axes. Thus permuting the display axes does not alter the effect of masking the data.
OR
- wmask sqw object in which the signal in individual pixels is
- interpreted as a mask array:
=1 (or true) to retain =0 (or false) to remove
wmask must have the same dimensionality, number of bins
along each dimension, and number of pixels in each bins as the array to be masked.
Output:
wout Output dataset.
- sqw.@SQWDnDBase.mask_points(win, varargin)
Determine the points to keep on the basis of ranges and mask array.
>> sel = mask_points (win, ‘keep’, xkeep, ‘remove’, xremove, ‘mask’, mask)
or any selection (in any order) of the keyword-argument pairs e.g.
>> sel = mask_points (win, ‘mask’, mask, ‘remove’, xremove)
Input:
win Input sqw object
- xkeep Ranges of display axes to retain for fitting. A range is specified by an array
of numbers which define a hypercube. For example in case of two dimensions:
[xlo, xhi, ylo, yhi]
- or in the case of n-dimensions:
[x1_lo, x1_hi, x2_lo, x2_hi,…, xn_lo, xn_hi]
- e.g. 1D: [50,70]
2D: [1,2,130,160]
- More than one range can be defined in rows,
[Range_1; Range_2; Range_3;…; Range_m]
where each of the ranges are given in the format above.
xremove Ranges of display axes to remove from fitting.
- mask Mask array of same number of elements as data array: 1 to keep, 0 to remove
Note: mask will be applied to the stored data array
according as the projection axes, not the display axes. Thus permuting the display axes does not alter the effect of masking the data_. The mask array works consistently with the input required by the mask method.
Output:
sel Mask array of same shape as data_. true for bins to keep, false to discard.
Advanced use: in addition the following two arguments, if present, suppress failure or the display of informational messges. Instead, the messages are returned to be used as desired.
ok =true if worked, =false if error
mess messages: if ok=true then informational or warning, if ok=false then the error message
- sqw.@SQWDnDBase.mask_random_fraction_pixels(win, npix)
reduce the number of pixels randomly in a sqw object
The function uses the mask_pixels() function to keep only a fixed fraction of pixels randomly chosen. Useful when doing numerically intensive simulations of sqw objects with sqw_eval or fit_sqw, to speed things up
wout = mask_random_fraction_pixels(win,npix_frac)
Input:
win Input sqw object
- npix_frac Fraction of pixels in win.data_.pix array to keep.
These are chosen at random. If win is an array then npix can either be a scalar, in which case all outputs will have the same number of retained pixels, or an array of the same size as win, in which case each mask is applied separately.
Output:
wout Output dataset.
- sqw.@SQWDnDBase.mask_random_pixels(win, npix)
reduce the number of pixels randomly in a sqw object
The function uses the mask_pixels() function to keep only a fixed amount of pixels randomly chosen. Useful when doing numerically intensive simulations of sqw objects with sqw_eval or fit_sqw, to speed things up
wout = mask_random_pixels(win,npix)
Input:
win Input sqw object
- npix Number of pixels in win.data_.pix array to keep.
These are chosen at random. If win is an array then npix can either be a scalar, in which case all outputs will have the same number of retained pixels, or an array of the same size as win, in which case each mask is applied separately.
Output:
wout Output dataset.
- sqw.@SQWDnDBase.minus(w1, w2)
Implements w1 - w2 for objects
>> w = w1 - w2
Input:
- w1, w2 Objects on which the binary operation is to be performed.
One of these can be a Matlab double (i.e. double precision) array, in which case the variance array is taken to be zero.
If w1, w2 are scalar objects with the same signal array sizes: - The operation is performed element-by-element.
If one of w1 or w2 is a double array (and the other is a scalar object): - If a scalar, apply to each element of the object signal. - If it is an array of the same size as the object signal
array, apply the operation element by element.
If one or both of w1 and w2 are arrays of objects: - If objects have same array sizes, the binary operation is
applied object element-by-object element.
If one of the objects is scalar (i.e. only one object),
then it is applied by the binary operation to each object in the other array.
If one of w1, w2 is an array of objects and the other is a double array: - If the double is a scalar, it is applied to every object
in the array.
If the double is an array with the same size as the object
array, then each element is applied as a scalar to the corresponding object in the object array.
If the double is an array with larger size than the object
array, then the array is resolved into a stack of arrays, where the stack has the same size as the object array, and the each array in the stack is applied to the corresponding object in the object array. [Note that for this operation to be valid, each object must have the same signal array size.]
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.mldivide(w1, w2)
Implements w1 w2 for objects
>> w = w1 w2
Input:
- w1, w2 Objects on which the binary operation is to be performed.
One of these can be a Matlab double (i.e. double precision) array, in which case the variance array is taken to be zero.
If w1, w2 are scalar objects with the same signal array sizes: - The operation is performed element-by-element.
If one of w1 or w2 is a double array (and the other is a scalar object): - If a scalar, apply to each element of the object signal. - If it is an array of the same size as the object signal
array, apply the operation element by element.
If one or both of w1 and w2 are arrays of objects: - If objects have same array sizes, the binary operation is
applied object element-by-object element.
If one of the objects is scalar (i.e. only one object),
then it is applied by the binary operation to each object in the other array.
If one of w1, w2 is an array of objects and the other is a double array: - If the double is a scalar, it is applied to every object
in the array.
If the double is an array with the same size as the object
array, then each element is applied as a scalar to the corresponding object in the object array.
If the double is an array with larger size than the object
array, then the array is resolved into a stack of arrays, where the stack has the same size as the object array, and the each array in the stack is applied to the corresponding object in the object array. [Note that for this operation to be valid, each object must have the same signal array size.]
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.mpower(w1, w2)
Implements w1 ^ w2 for objects
>> w = w1 ^ w2
Input:
- w1, w2 Objects on which the binary operation is to be performed.
One of these can be a Matlab double (i.e. double precision) array, in which case the variance array is taken to be zero.
If w1, w2 are scalar objects with the same signal array sizes: - The operation is performed element-by-element.
If one of w1 or w2 is a double array (and the other is a scalar object): - If a scalar, apply to each element of the object signal. - If it is an array of the same size as the object signal
array, apply the operation element by element.
If one or both of w1 and w2 are arrays of objects: - If objects have same array sizes, the binary operation is
applied object element-by-object element.
If one of the objects is scalar (i.e. only one object),
then it is applied by the binary operation to each object in the other array.
If one of w1, w2 is an array of objects and the other is a double array: - If the double is a scalar, it is applied to every object
in the array.
If the double is an array with the same size as the object
array, then each element is applied as a scalar to the corresponding object in the object array.
If the double is an array with larger size than the object
array, then the array is resolved into a stack of arrays, where the stack has the same size as the object array, and the each array in the stack is applied to the corresponding object in the object array. [Note that for this operation to be valid, each object must have the same signal array size.]
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.mrdivide(w1, w2)
Implements w1 / w2 for objects
>> w = w1 / w2
Input:
- w1, w2 Objects on which the binary operation is to be performed.
One of these can be a Matlab double (i.e. double precision) array, in which case the variance array is taken to be zero.
If w1, w2 are scalar objects with the same signal array sizes: - The operation is performed element-by-element.
If one of w1 or w2 is a double array (and the other is a scalar object): - If a scalar, apply to each element of the object signal. - If it is an array of the same size as the object signal
array, apply the operation element by element.
If one or both of w1 and w2 are arrays of objects: - If objects have same array sizes, the binary operation is
applied object element-by-object element.
If one of the objects is scalar (i.e. only one object),
then it is applied by the binary operation to each object in the other array.
If one of w1, w2 is an array of objects and the other is a double array: - If the double is a scalar, it is applied to every object
in the array.
If the double is an array with the same size as the object
array, then each element is applied as a scalar to the corresponding object in the object array.
If the double is an array with larger size than the object
array, then the array is resolved into a stack of arrays, where the stack has the same size as the object array, and the each array in the stack is applied to the corresponding object in the object array. [Note that for this operation to be valid, each object must have the same signal array size.]
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.mtimes(w1, w2)
Implements w1 * w2 for objects
>> w = w1 * w2
Input:
- w1, w2 Objects on which the binary operation is to be performed.
One of these can be a Matlab double (i.e. double precision) array, in which case the variance array is taken to be zero.
If w1, w2 are scalar objects with the same signal array sizes: - The operation is performed element-by-element.
If one of w1 or w2 is a double array (and the other is a scalar object): - If a scalar, apply to each element of the object signal. - If it is an array of the same size as the object signal
array, apply the operation element by element.
If one or both of w1 and w2 are arrays of objects: - If objects have same array sizes, the binary operation is
applied object element-by-object element.
If one of the objects is scalar (i.e. only one object),
then it is applied by the binary operation to each object in the other array.
If one of w1, w2 is an array of objects and the other is a double array: - If the double is a scalar, it is applied to every object
in the array.
If the double is an array with the same size as the object
array, then each element is applied as a scalar to the corresponding object in the object array.
If the double is an array with larger size than the object
array, then the array is resolved into a stack of arrays, where the stack has the same size as the object array, and the each array in the stack is applied to the corresponding object in the object array. [Note that for this operation to be valid, each object must have the same signal array size.]
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.multifit_func(varargin)
Simultaneously fit function(s) to one or more sqw objects
>> myobj = multifit_func (w1, w2, …) % w1, w2 objects or arrays of objects
This creates a fitting object of class mfclass_Horace with the provided data, which can then be manipulated to add further data, set the fitting functions, initial parameter values etc. and fit or simulate the data. For details about how to do this <a href=”matlab:help(‘mfclass_Horace’);”>Click here</a>
For example:
- >> myobj = multifit_func (w1, w2, …); % set the data
:
>> myobj = myobj.set_fun (@function_name, pars); % set forgraound function(s) >> myobj = myobj.set_bfun (@function_name, pars); % set background function(s)
:
>> myobj = myobj.set_free (pfree); % set which parameters are floating >> myobj = myobj.set_bfree (bpfree); % set which parameters are floating >> [wfit,fitpars] = myobj.fit; % perform fit
This method fits function(s) of the plot axes for both the foreground and the background function(s). The format of the fit functions depends on the number of plot axes for each sqw object. For examples see: <a href=”matlab:edit(‘example_1d_function’);”>example_1d_function</a> <a href=”matlab:edit(‘example_2d_function’);”>example_2d_function</a> <a href=”matlab:edit(‘example_3d_function’);”>example_3d_function</a>
See also multifit_sqw multifit_sqw_sqw
- [Help for legacy use (2017 and earlier):
If you are still using the legacy version then it is strongly recommended that you change to the new operation. Help for the legacy operation can be <a href=”matlab:help(‘sqw/multifit_legacy_func’);”>found here</a>]
- sqw.@SQWDnDBase.multifit_sqw(varargin)
Simultaneously fit function(s) of S(Q,w)to one or more sqw objects
>> myobj = multifit_sqw (w1, w2, …) % w1, w2 objects or arrays of objects
This creates a fitting object of class mfclass_Horace_sqw with the provided data, which can then be manipulated to add further data, set the fitting functions, initial parameter values etc. and fit or simulate the data. For details about how to do this <a href=”matlab:help(‘mfclass_Horace_sqw’);”>Click here</a>
For example:
- >> myobj = multifit_sqw (w1, w2, …); % set the data
:
>> myobj = myobj.set_fun (@function_name, pars); % set forgraound function(s) >> myobj = myobj.set_bfun (@function_name, pars); % set background function(s)
:
>> myobj = myobj.set_free (pfree); % set which parameters are floating >> myobj = myobj.set_bfree (bpfree); % set which parameters are floating >> [wfit,fitpars] = myobj.fit; % perform fit
This method fits model(s) for S(Q,w) as the foreground function(s), and function(s) of the plot axes for the background function(s)
For the format of foreground fit functions: <a href=”matlab:edit(‘example_sqw_spin_waves’);”>Damped spin waves</a> <a href=”matlab:edit(‘example_sqw_flat_mode’);”>Dispersionless excitations</a>
The format of the background fit functions depends on the number of plot axes for each sqw object. For examples see: <a href=”matlab:edit(‘example_1d_function’);”>example_1d_function</a> <a href=”matlab:edit(‘example_2d_function’);”>example_2d_function</a> <a href=”matlab:edit(‘example_3d_function’);”>example_3d_function</a>
See also multifit multifit_sqw_sqw
- [Help for legacy use (2017 and earlier):
If you are still using the legacy version then it is strongly recommended that you change to the new operation. Help for the legacy operation can be <a href=”matlab:help(‘sqw/multifit_legacy_sqw’);”>found here</a>]
- sqw.@SQWDnDBase.multifit_sqw_sqw(varargin)
Simultaneously fit function(s) of S(Q,w)to one or more sqw objects
>> myobj = multifit_sqw_sqw (w1, w2, …) % w1, w2 objects or arrays of objects
This creates a fitting object of class mfclass_Horace_sqw_sqw with the provided data, which can then be manipulated to add further data, set the fitting functions, initial parameter values etc. and fit or simulate the data. For details about how to do this <a href=”matlab:help(‘mfclass_Horace_sqw_sqw’);”>Click here</a>
For example:
- >> myobj = multifit_sqw_sqw (w1, w2, …); % set the data
:
>> myobj = myobj.set_fun (@function_name, pars); % set forgraound function(s) >> myobj = myobj.set_bfun (@function_name, pars); % set background function(s)
:
>> myobj = myobj.set_free (pfree); % set which parameters are floating >> myobj = myobj.set_bfree (bpfree); % set which parameters are floating >> [wfit,fitpars] = myobj.fit; % perform fit
This method fits function(s) of S(Q,w) as both the foreground and the background function(s). For the format of the fit functions: <a href=”matlab:edit(‘example_sqw_spin_waves’);”>Damped spin waves</a> <a href=”matlab:edit(‘example_sqw_flat_mode’);”>Dispersionless excitations</a>
See also multifit multifit_sqw
- [Help for legacy use (2017 and earlier):
If you are still using the legacy version then it is strongly recommended that you change to the new operation. Help for the legacy operation can be <a href=”matlab:help(‘sqw/multifit_legacy_sqw_sqw’);”>found here</a>]
- sqw.@SQWDnDBase.pa(w, varargin)
Overplot an area plot of a 2D sqw dataset or array of datasets
>> pa(w)
- Advanced use:
- >> pa(w,’name’,fig_name) % overplot on figure with name = fig_name
% or figure with given figure number or handle
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = pa(w,…)
- sqw.@SQWDnDBase.paoc(w)
Overplot an area plot of a 2D sqw dataset or array of datasets on the current figure
>> paoc(w)
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = paoc(w)
- sqw.@SQWDnDBase.pd(w, varargin)
Overplot markers, error bars and lines for a 1D sqw object or array of objects on an existing plot
>> pd(w)
- Advanced use:
- >> pd(w,’name’,fig_name) % overplot on figure with name = fig_name
% or figure with given figure number or handle
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = pd(w,…)
- sqw.@SQWDnDBase.pdoc(w)
Overplot markers, error bars and lines for a 1D sqw object or array of objects on the current plot
>> pdoc(w)
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = pdoc(w)
- sqw.@SQWDnDBase.pe(w, varargin)
Overplot error bars for a 1D sqw object or array of objects on an existing plot
>> pe(w)
- Advanced use:
- >> pe(w,’name’,fig_name) % overplot on figure with name = fig_name
% or figure with given figure number or handle
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = pe(w,…)
- sqw.@SQWDnDBase.peoc(w)
Overplot error bars for a 1D sqw object or array of objects on the current plot
>> peoc(w)
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = peoc(w)
- sqw.@SQWDnDBase.ph(w, varargin)
Overplot histogram for a 1D sqw object or array of objects on an existing plot
>> ph(w)
- Advanced use:
- >> ph(w,’name’,fig_name) % overplot on figure with name = fig_name
% or figure with given figure number or handle
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = ph(w,…)
- sqw.@SQWDnDBase.phoc(w)
Overplot histogram for a 1D sqw object or array of objects on the current plot
>> phoc(w)
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = phoc(w)
- sqw.@SQWDnDBase.pl(w, varargin)
Overplot line for a 1D sqw object or array of objects on an existing plot
>> pl(w)
- Advanced use:
- >> pl(w,’name’,fig_name) % overplot on figure with name = fig_name
% or figure with given figure number or handle
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = pl(w,…)
- sqw.@SQWDnDBase.ploc(w)
Overplot line for a 1D sqw object or array of objects on the current plot
>> ploc(w)
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = ploc(w)
- sqw.@SQWDnDBase.plot(w, varargin)
Plot 1D, 2D or 3D sqw object or array of objects
>> plot(w) >> plot(w,opt1,opt2,…) % plot with optional arguments
- Equivalent to:
>> dp(w) % 1D dataset >> dp(w,…)
>> da(w) % 2D dataset >> da(w,…)
>> sliceomatic(w) % 3D dataset >> sliceomatic(w,…)
For details of optional parameters type >> help sqw/dp, >> help sqw/da, or >> help sqw/sliceomatic as appropriate
- sqw.@SQWDnDBase.plotover(w, varargin)
Overplot 1D, 2D or 3D sqw object or array of objects
>> plotover(w) >> plotover(w,opt1,opt2,…) % plot with optional arguments
- Equivalent to:
>> pp(w) % 1D dataset >> pp(w,…)
>> pa(w) % 2D dataset >> pa(w,…)
For details of optional parameters type >> help sqw/pp, >> help sqw/pa, as appropriate
- sqw.@SQWDnDBase.plus(w1, w2)
Implements w1 + w2 for objects
>> w = w1 + w2
Input:
- w1, w2 Objects on which the binary operation is to be performed.
One of these can be a Matlab double (i.e. double precision) array, in which case the variance array is taken to be zero.
If w1, w2 are scalar objects with the same signal array sizes: - The operation is performed element-by-element.
If one of w1 or w2 is a double array (and the other is a scalar object): - If a scalar, apply to each element of the object signal. - If it is an array of the same size as the object signal
array, apply the operation element by element.
If one or both of w1 and w2 are arrays of objects: - If objects have same array sizes, the binary operation is
applied object element-by-object element.
If one of the objects is scalar (i.e. only one object),
then it is applied by the binary operation to each object in the other array.
If one of w1, w2 is an array of objects and the other is a double array: - If the double is a scalar, it is applied to every object
in the array.
If the double is an array with the same size as the object
array, then each element is applied as a scalar to the corresponding object in the object array.
If the double is an array with larger size than the object
array, then the array is resolved into a stack of arrays, where the stack has the same size as the object array, and the each array in the stack is applied to the corresponding object in the object array. [Note that for this operation to be valid, each object must have the same signal array size.]
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.pm(w, varargin)
Overplot markers for a 1D sqw object or array of objects on an existing plot
>> pm(w)
- Advanced use:
- >> pm(w,’name’,fig_name) % overplot on figure with name = fig_name
% or figure with given figure number or handle
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = pm(w,…)
- sqw.@SQWDnDBase.pmoc(w)
Overplot markers for a 1D sqw object or array of objects on the current plot
>> pmoc(w)
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = pmoc(w)
- sqw.@SQWDnDBase.pp(w, varargin)
Overplot markers and error bars for a 1D sqw object or array of objects on an existing plot
>> pp(w)
- Advanced use:
- >> pp(w,’name’,fig_name) % overplot on figure with name = fig_name
% or figure with given figure number or handle
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = pp(w,…)
- sqw.@SQWDnDBase.ppoc(w)
Overplot markers and error bars for a 1D sqw object or array of objects on the current plot
>> ppoc(w)
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = ppoc(w)
- sqw.@SQWDnDBase.ps(w, varargin)
Overplot a surface plot of a 2D sqw dataset or array of datasets
>> ps(w)
- Advanced use:
- >> ps(w,’name’,fig_name) % overplot on figure with name = fig_name
% or figure with given figure number or handle
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = ps(w,…)
- sqw.@SQWDnDBase.ps2(w, varargin)
Overplot a surface plot of a 2D sqw dataset or array of datasets
>> ps2(w) % Use error bars to set colour scale >> ps2(w,wc) % Signal in wc sets colour scale
% wc can be any object with a signal array with same % size as w, e.g. sqw object, IX_dataset_2d object, or % a numeric array. % - If w is an array of objects, then wc must contain % the same number of objects. % - If wc is a numeric array then w must be a scalar % object.
Differs from ds in that the signal sets the z axis, and the colouring is set by the error bars, or by another object. This enables two related functions to be plotted (e.g. dispersion relation where the ‘signal’ array holds the energy and the error array holds the spectral weight).
- Advanced use:
- >> ps(w,’name’,fig_name) % overplot on figure with name = fig_name
% or figure with given figure number or handle
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = ps2(w,…)
- sqw.@SQWDnDBase.ps2oc(w, varargin)
Overplot a surface plot of a 2D sqw dataset or array of datasets on the current figure The colour scale comes from a second source
>> ps2oc(w) % Use error bars to set colour scale >> ps2oc(w,wc) % Signal in wc sets colour scale
% wc can be any object with a signal array with same % size as w, e.g. sqw object, IX_dataset_2d object, or % a numeric array. % - If w is an array of objects, then wc must contain % the same number of objects. % - If wc is a numeric array then w must be a scalar % object.
Differs from ds in that the signal sets the z axis, and the colouring is set by the error bars, or by another object. This enables two related functions to be plotted (e.g. dispersion relation where the ‘signal’ array holds the energy and the error array holds the spectral weight).
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = ps2oc(w)
- sqw.@SQWDnDBase.psoc(w)
Overplot a surface plot of a 2D sqw dataset or array of datasets on the current figure
>> psoc(w)
- Return figure, axes and plot handles:
>> [fig_handle, axes_handle, plot_handle] = psoc(w)
- sqw.@SQWDnDBase.recompute_bin_data(w)
Given sqw_type object, recompute w.data.s and w.data.e from the contents of pix array
>> wout=recompute_bin_data(w)
- sqw.@SQWDnDBase.save(w, varargin)
Save a sqw object or array of sqw objects to file
>> save (w) % prompt for file >> save (w, file) % give file >> save (w, file,loader) % save file using specific data loader
(-update option, is provided, will be ignored)
- >> save (w, file,’-update’) % if the target file exist, update it to
latest format if this is possible. If update is possible, pixels in file will not be overwritten.
- Input:
w sqw object file [optional] File for output. if none given, then prompted for a file
Note that if w is an array of sqw objects then file must be a cell array of filenames of the same size.
Output:
- sqw.@SQWDnDBase.sec(w1)
Implements sec(w1) for objects
>> w = sec(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.sech(w1)
Implements sech(w1) for objects
>> w = sech(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.sigvar_get(w)
Get signal and variance from object, and a logical array of which values to ignore
>> [s,var,mask_null] = sigvar_get (w)
- sqw.@SQWDnDBase.sin(w1)
Implements sin(w1) for objects
>> w = sin(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.sinh(w1)
Implements sinh(w1) for objects
>> w = sinh(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.sliceomatic(w, varargin)
Plots 3D sqw object using sliceomatic
>> sliceomatic (w) >> sliceomatic (w, ‘isonormals’, true) % to enable isonormals
- >> sliceomatic (w,…,’-noaspect’) % Do not change aspect ratio
% according to data axes unit lengths
- To get handles to the graphics figure:
>> [figureHandle_, axesHandle_, plotHandle_] = sliceomatic(w,…)
NOTES:
- Ensure that the slice color plotting is in ‘texture’ mode -
On the ‘AllSlices’ menu click ‘Color Texture’. No indication will be made on this menu to show that it has been selected, but you can see the result if you right-click on an arrow indicating a slice on the graphics window.
- To set the default for future Sliceomatic sessions -
On the ‘Object_Defaults’ menu select ‘Slice Color Texture’
- sqw.@SQWDnDBase.sliceomatic_overview(w, varargin)
Plots 3D sqw object using sliceomatic with view straight down one of the axes
>> sliceomatic_overview (w) % down third (vertical) axis >> sliceomatic_overview (w, axis) % down axis of choice (axis=1,2 or 3)
>> sliceomatic_overview (w,… ‘isonormals’, true) % to enable isonormals
- >> sliceomatic_overview (w,…,’-noaspect’) % Do not change aspect ratio
% according to data axes unit lengths
- To get handles to the graphics figure:
>> [figureHandle_, axesHandle_, plotHandle_] = sliceomatic(w,…)
Do a sliceomatic plot, but set the axes so that we look straight down the chosen axis, so that when the slider is moved we get a series of what appear to be 2d slices.
NOTES:
- Ensure that the slice color plotting is in ‘texture’ mode -
On the ‘AllSlices’ menu click ‘Color Texture’. No indication will be made on this menu to show that it has been selected, but you can see the result if you right-click on an arrow indicating a slice on the graphics window.
- To set the default for future Sliceomatic sessions -
On the ‘Object_Defaults’ menu select ‘Slice Color Texture’
- sqw.@SQWDnDBase.smooth(win, varargin)
Smooth method - gataway to dnd object smoothing only.
- sqw.@SQWDnDBase.smooth_units(win, varargin)
Smooth method - gataway to dnd object smoothing only.
- sqw.@SQWDnDBase.sqrt(w1)
Implements sqrt(w1) for objects
>> w = sqrt(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.sqw_eval(win, sqwfunc, pars, varargin)
Calculate sqw for a model scattering function
>> wout = sqw_eval(win, sqwfunc, p) >> wout = sqw_eval(___, ‘-all’) >> wout = sqw_eval(___, ‘all’, true) >> wout = sqw_eval(___, ‘-average’) >> wout = sqw_eval(___, ‘average’, true) >> sqw_eval(___, ‘outfile’, outfile) >> wout = sqw_eval(___, ‘outfile’, outfile) >> sqw_eval(__, ‘outfile’, outfile, ‘filebacked’, true) >> wout = sqw_eval(__, ‘filebacked’, true)
- win Dataset (or array of datasets) that provides the axes and points
for the calculation
- sqwfunc Handle to function that calculates S(Q, w)
- Most commonly used form is:
weight = sqwfunc (qh, qk, ql, en, p)
- where
qh,qk,ql,en Arrays containing the coordinates of a set of points p Vector of parameters needed by dispersion function
e.g. [A, js, gam] as intensity, exchange, lifetime
weight Array containing calculated spectral weight
- More general form is:
weight = sqwfunc (qh, qk, ql, en, p, c1, c2, ..)
- where
- p Typically a vector of parameters that we might want
to fit in a least-squares algorithm
- c1, c2, … Other constant parameters e.g. file name for look-up
table
- pars Arguments needed by the function. Most commonly, a vector of parameter
values e.g. [A, js, gam] as intensity, exchange, lifetime. If a more general set of parameters is required by the function, then package these into a cell array and pass that as pars. In the example above then pars = {p, c1, c2, …}
- outfile If present, the outputs will be written to the file of the given
name/path. If numel(win) > 1, outfile must either be omitted or be a cell array of file paths with equal number of elements as win.
- all If true, requests that the calculated sqw be returned over
the whole of the domain of the input dataset. If false, then the function will be returned only at those points of the dataset that contain data_.
Applies only to input with no pixel information - it is ignored if
full sqw object. [default = false]
- average If true, requests that the calculated sqw be computed for the
average values of h, k, l of the pixels in a bin, not for each pixel individually. Reduces cost of expensive calculations. Applies only to the case of sqw object with pixel information - it is ignored if dnd type object. [default = false]
- filebacked If true, the result of the function will be saved to file and
the output will be a file path. If no outfile is specified, a unique path within tempdir() will be generated. Default is false.
- Note: all optional string input parameters can be truncated up to minimal
difference between them e.g. routine would accept ‘al’ and ‘av’, ‘ave’, ‘aver’ etc….
- wout If filebacked is false, an sqw object or array of sqw objects.
If filebacked is true, a file path or cell array of file paths. Output argument must be specified if outfile not given.
- sqw.@SQWDnDBase.sqw_eval_nopix_(obj, sqwfunc, all_bins, pars)
-
Helper function for sqw eval executed on a pixel-less object (i.e. DnD or SQW with no pixels Called by sqw_eval_ defined in sqw/DnDBase
- obj Dataset (or array of datasets) that provides the axes and points
for the calculation
sqwfunc Handle to function that calculates S(Q,w) all_bins Boolean flag wither to apply function to all bins or only those contaiing data pars Arguments needed by the function.
- sqw.@SQWDnDBase.tan(w1)
Implements tan(w1) for objects
>> w = tan(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.tanh(w1)
Implements tanh(w1) for objects
>> w = tanh(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.uminus(w1)
Implements uminus(w1) for objects
>> w = uminus(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.uplus(w1)
Implements uplus(w1) for objects
>> w = uplus(w1)
Input:
- w1 Input object or array of objects on which to apply the
unary operator.
Output:
w Output object or array of objects.
- sqw.@SQWDnDBase.xye(w, null_value)
Get the bin centres, intensity and error bar for a 1D, 2D, 3D or 4D dataset
>> S = xye(w) >> S = xye(w, null_value)
Input:
w sqw object or array of objects (1D, 2D, 3D or 4D) null_value Numeric value to substitute for the intensity in bins
with no data. Default: NaN
Output:
S Structure with the following fields:
- x If a 1D sqw object, a column vector with the bin centres
Otherwise, a cell array (row vector) of arrays, each array containing the bin centres for the plot axes. Each array of bin centres is a column vector.
- y n1 x n2 x… array of intensities, where n1 is the number of
bins along the first plot axis, n2 the number of bins along the second plot axis etc
- e n1 x n2 x… array of error bars, where n1 is the number of
bins along the first plot axis, n2 the number of bins along the second plot axis etc
Experiment class
- class sqw.@Experiment.Experiment(varargin)
EXPERIMENT Container object for all data describing the Experiment
- Experiment(varargin)
Create a new Experiment object.
obj = Experiment() obj = Experiment(detector_array[s], instrument[s], sample[s])
- Required:
detector_array Detector array (IX_detector_array objects) instrument Instrument (Concrete class inheriting IX_inst) sample Sample data (IX_sample object)
Each argument can be a single object or array of objects.
- instruments = None
Mirrors of private properties
- static loadobj(S)
Static method used my Matlab load function to support custom loading.
>> obj = loadobj(S)
Input:
- S Either (1) an object of the class, or (2) a structure
or structure array
Output:
- obj Either (1) the object passed without change, or (2) an
object (or object array) created from the input structure
or structure array)
PixelData class
- class sqw.PixelData.@PixelData.PixelData(arg, mem_alloc, upgrade)
PixelData Provides an interface for access to pixel data
This class provides getters and setters for each data column in an SQW pixel array. You can access the data using the attributes listed below, using the get_data() method (to retrieve column data) or using the get_pixels() method (retrieve row data).
Construct this class with an 9 x N array, a file path to an SQW object or an instance of sqw_binfile_common.
>> pix_data = PixelData(data); >> pix_data = PixelData(‘/path/to/sqw.sqw’); >> pix_data = PixelData(‘/path/to/sqw.sqw’, mem_alloc); >> pix_data = PixelData(faccess_obj); >> pix_data = PixelData(faccess_obj, mem_alloc);
Constructing via a file or sqw_binfile_common will create a file-backed data object. No pixel data will be loaded from the file on construction. Data will be loaded when a getter is called e.g. pix_data.signal. Data will be loaded in pages such that the data held in memory will not exceed the size (in bytes) specified by private attribute page_memory_size_ - this can be set on construction (see mem_alloc above).
The file-backed operations work by loading “pages” of data into memory as required. If editing pixels, to avoid losing changes, if a page has been edited and the next page is then loaded, the “dirty” page will be written to a tmp file. This class’s getters will then retrieve data from the tmp file if that data is requested from the “dirty” page. Note that “dirty” pages are written to tmp files as floats, but stored in memory as double. This means data is truncated when moving pages, hence pixel data should not be relied upon being accurate to double precision.
Usage:
>> pix_data = PixelData(data) >> signal = pix_data.signal;
or equivalently:
>> pix_data = PixelData(); >> pix_data.data = data; >> signal = pix_data.get_data(‘signal’);
To retrieve multiple fields of data, e.g. run_idx and energy_idx, for pixels 1 to 10:
>> pix_data = PixelData(data); >> signal = pix_data.get_data({‘run_idx’, ‘energy_idx’}, 1:10);
To retrieve data for pixels 1, 4 and 10 (returning another PixelData object):
>> pix_data = PixelData(data); >> pixel_subset = pix_data.get_pixels([1, 4, 10])
To sum the signal of a file-backed object where the page size is less than amount of data in the file:
>> pix = PixelData(‘my_data.sqw’) >> signal_sum = 0; >> while pix.has_more() >> signal_sum = signal_sum + pix.signal; >> pix.advance(); >> end
- Properties:
- u1, u2, u3 - The 1st, 2nd and 3rd dimensions of the Crystal
Cartesian coordinates in projection axes, units are per Angstrom (1 x n arrays)
dE - The energy transfer value for each pixel in meV (1 x n array) coordinates - The coords in projection axes of the pixel data [u1, u2, u3, dE] (4 x n array) q_coordinates - The spacial coords in projection axes of the pixel data [u1, u2, u3] (3 x n array) run_idx - The run index the pixel originated from (1 x n array) detector_idx - The detector group number in the detector listing for the pixels (1 x n array) energy_idx - The energy bin numbers (1 x n array) signal - The signal array (1 x n array). variance - The variance on the signal array (variance i.e. error bar squared) (1 x n array)
num_pixels - The number of pixels in the data block. pix_range - [2x4] array of the range of pixels coordinates in Crystal Cartesian coordinate system.
- data - The raw pixel data - usage of this attribute is discouraged, the structure
of the return value is not guaranteed.
page_size - The number of pixels in the currently loaded page.
- DATA_POINT_SIZE = '8'
num bytes in a double
- DEFAULT_PAGE_SIZE = 'realmax'
this gives no paging by default
- PixelData(arg, mem_alloc, upgrade)
- Construct a PixelData object from the given data. Default
construction initialises the underlying data as an empty (9 x 0) array.
>> obj = PixelData(ones(9, 200))
>> obj = PixelData(200) % initialise 200 pixels with underlying data set to zero
>> obj = PixelData(file_path) % initialise pixel data from an sqw file
>> obj = PixelData(faccess_reader) % initialise pixel data from an sqw file reader
>> obj = PixelData(faccess_reader, mem_alloc) % set maximum memory allocation
- >> obj = PixelData(__,false) – not upgrade class averages
(pix_range) for old file format, if these averages are not stored in the file. Default – true
- arg A 9 x n matrix, where each row corresponds to a pixel and
- the columns correspond to the following:
col 1: u1 col 2: u2 col 3: u3 col 4: dE col 5: run_idx col 6: detector_idx col 7: energy_idx col 8: signal col 9: variance
- arg An integer specifying the desired number of pixels. The underlying
data will be filled with zeros.
arg A path to an SQW file.
arg An instance of an sqw_binfile_common file reader.
- mem_alloc The maximum amount of memory allocated to hold pixel
data in bytes. If pixels cannot all be held in memory at one time, they will be loaded from the file (specified by ‘arg’) when they are required. This argument does nothing if the class is constructed with in-memory data. (Optional)
- advance(varargin)
Load the next page of pixel data from the file backing the object
This function will throw a PIXELDATA:advance error if attempting to advance past the final page of data in the file.
This function does nothing if the pixel data is not file-backed.
>> obj.advance() >> obj.advance(‘nosave’, true)
Inputs:
- nosave Keyword argument. Set to true to discard changes to cache.
(default: false)
Outputs:
current_page_number The new page and total number of pages advance will walk through to complete the algorithm
- base_page_size = None
The number of pixels that can fit in one page of data
- static cat(varargin)
Concatenate the given PixelData objects’ pixels. This function performs a straight-forward data concatenation.
>> joined_pix = PixelData.cat(pix_data1, pix_data2);
Input:
varargin A cell array of PixelData objects
Output:
- obj A PixelData object containing all the pixels in the inputted
PixelData objects
- coordinates = None
The coordinates of the pixels in the projection axes, i.e.: u1,
- copy()
Make an independent copy of this object This method simply constructs a new PixelData instance by calling the constructor with the input object as an argument. Because of this, any properties that need to be explicitly copied must be copied within this classes “copy-constructor”.
- dE = None
The array of energy deltas of the pixels (1 x n array) [meV]
- data = None
The full raw pixel data block. Usage of this attribute exposes
- delete()
Class destructor to delete any temporary files
- detector_idx = None
The detector group number in the detector listing for the pixels (1 x n array)
- energy_idx = None
The energy bin numbers (1 x n array)
- file_path = None
The file that the pixel data has been read from, empty if no file
- has_more()
Returns true if there are subsequent pixels stored in the file that are not held in the current page
>> has_more = pix.has_more();
- is_filebacked()
Return true if the pixel data is backed by a file or files. Returns false if all pixel data is held in memory
- isempty()
Return true if the PixelData object holds no pixel data
- static loadobj(S)
Load a PixelData object from a .mat file
- >> obj = PixelData.loadobj(S)
- S A data, produeced by saveobj operation and stored
in .mat file
obj An instance of PixelData object or array of objects
- move_to_first_page()
Reset the object to point to the first page of pixel data in the file and clear the current cache
This function does nothing if pixels are not file-backed.
- num_pixels = None
The number of pixels in the data block
- page_size = None
The number of pixels in the current page
- pix_range = None
The range of pixels coordinates in Crystal Cartesian
- q_coordinates = None
The spatial dimensions of the Crystal Cartesian
- run_idx = None
The run index the pixel originated from (1 x n array)
- set_range(pix_range)
Function allows to set the pixels range (min/max values of pixels coordinates)
Use with caution!!! No checks that the set range is the correct range for pixels, holded by the class are performed, while subsequent algorithms may rely on pix range to be correct. A out-of memory write can occur during rebinning if the range is smaller, then the actual range.
Necessary to set up the pixel range when filebased pixels are modified by algorithm and correct range calculations are expensive
- signal = None
The signal array (1 x n array)
- struct()
convert object into saveable and serializable structure
- u1 = None
The 1st dimension of the Crystal Cartesian orientation (1 x n array) [A^-1]
- u2 = None
The 2nd dimension of the Crystal Cartesian orientation (1 x n array) [A^-1]
- u3 = None
The 3rd dimension of the Crystal Cartesian orientation (1 x n array) [A^-1]
- variance = None
The variance on the signal array
- sqw.PixelData.@PixelData.append(obj, pix)
Join the pixels in the given PixelData object to the end of this object.
The pixels to append must all be in memory and you cannot append pixels if the inputted PixelData object has more pixels than are allowed in a single page.
Input
pix A PixelData object containing the pixels to append
- sqw.PixelData.@PixelData.compute_bin_data(obj, npix)
Compute the mean signal and variance given the number of contributing pixels for each bin Returns empty arrays if obj contains no pixels.
>> [mean_signal, mean_variance] = compute_bin_data(obj, npix)
Input
npix The number of contributing pixels to each bin of the plot axes
Output
- mean_signal The average signal for each plot axis bin.
size(mean_signal) = size(npix)
- mean_variance The average variance for each plot axis bin.
size(mean_variance) = size(npix)
- sqw.PixelData.@PixelData.do_binary_op(obj, operand, binary_op, varargin)
- DO_BINARY_OP perform a binary operation between this object and the given
operand
>> pix_diff = obj.do_binary_op(other_pix, @minus_single, ‘flip’, true)
>> pix_sum = obj.do_binary_op(signal_array, @plus_single, ‘npix’, npix)
>> pix_sum = obj.do_binary_op(signal_array, @plus_single, ‘npix’, npix, ‘flip’, true)
Input
- operand The second operand to use in the binary operation.
- The operand must have one of the following types:
scalar double
double array, the size of the array must be equal to obj.num_pixels
object with fields ‘s’ and ‘e’ (e.g. dnd or sigvar)
another PixelData object with obj.num_pixels equal
- binary_op Function handle pointing to the desired binary operation. The
function should take 2 objects with ‘.s’ and ‘.e’ attributes, e.g. a sigvar object
Named arguments
- flip Flip the order of the operands, e.g. perform “this - operand” if
flip is false, perform “operand - this” if flip is true.
- npix An array giving number of pixels in each bin. This argument should
have equal size to operand (assuming operand is numeric) and sum(npix, [], ‘all’) must be equal to obj.num_pixels
- sqw.PixelData.@PixelData.do_unary_op(obj, unary_op)
Perform a unary operation on this object’s signal and variance arrays
Input:
- unary_op Function handle pointing to the operation to perform. This
operation should take a sigvar object as an argument.
- sqw.PixelData.@PixelData.equal_to_tol(obj, other_pix, varargin)
EQUAL_TO_TOL Check if two PixelData objects are equal to a given tolerance
Input:
pix The first pixel data object to compare.
other_pix The second pixel data object to compare.
- tol Tolerance criterion for numeric arrays
(default = [0, 0] i.e. equality) It has the form: [abs_tol, rel_tol] where
abs_tol absolute tolerance (>=0; if =0 equality required) rel_tol relative tolerance (>=0; if =0 equality required)
If either criterion is satisfied then equality within tolerance is accepted.
- Examples:
[1e-4, 1e-6] absolute 1e-4 or relative 1e-6 required [1e-4, 0] absolute 1e-4 required [0, 1e-6] relative 1e-6 required [0, 0] equality required 0 equivalent to [0,0]
A scalar tolerance can be given where the sign determines if the tolerance is absolute or relative:
+ve : absolute tolerance abserr = abs(a-b) -ve : relative tolerance relerr = abs(a-b)/max(abs(a),abs(b))
- Examples:
1e-4 absolute tolerance, equivalent to [1e-4, 0] -1e-6 relative tolerance, equivalent to [0, 1e-6]
Keyword Input:
nan_equal Treat NaNs as equal (true or false; default=true).
- name_a Explicit name of variable a for use in messages
Usually not required, as the name of a variable will be discovered. However, if the input argument is an array element e.g. my_variable{3} then the name is not discoverable in Matlab, and default ‘input_1’ will be used unless a different value is given with the keyword ‘name_a’. (default = ‘input_1’).
- name_b Explicit name of variable b for use in messages.
The same comments apply as for ‘name_a’ except the default is ‘input_2’. (default = ‘input_2’).
- sqw.PixelData.@PixelData.get_data(obj, pix_fields, varargin)
GET_DATA Retrieve data for a field, or fields, for the given pixel indices in the full pixel block. If no pixel indices are given, the full range of pixels is returned.
This method provides a convenient way of retrieving multiple fields of data from the pixel block. When retrieving multiple fields, the columns of data will be ordered corresponding to the order the fields appear in the inputted cell array.
- >> sig_and_err = pix.get_data({‘signal’, ‘variance’})
retrieves the signal and variance over the whole range of pixels
- >> run_det_id_range = pix.get_data({‘run_idx’, ‘detector_idx’}, 15640:19244);
retrieves the run and detector IDs for pixels 15640 to 19244
Input:
pix_fields The name of a field, or a cell array of field names abs_pix_indices The pixel indices to retrieve, if not given, get full range.
The syntax for these indices attempts to replicate indexing into a regular Matlab array. You can use logical indices as well as normal indices, and you can index into the array “out-of-order”. However, you cannot use end, but it is possible to achieve the same effect using the num_pixels property.
- sqw.PixelData.@PixelData.get_pix_in_ranges(obj, abs_indices_starts, abs_indices_ends, recalculate_pix_range)
GET_PIX_IN_RANGES read pixels in the specified ranges Ranges are inclusive.
>> pix = get_pix_in_ranges([1, 12, 25], [6, 12, 27])
Input:
pix_starts Absolute indices of the starts of pixel ranges [Nx1 or 1xN array]. pix_ends Absolute indices of the ends of pixel ranges [Nx1 or 1xN array].
Output:
pix_out A PixelData object containing the pixels in the given ranges.
- sqw.PixelData.@PixelData.get_pixels(obj, abs_pix_indices, varargin)
Retrieve the pixels at the given indices in the full pixel block, return a new PixelData object.
>> pix_out = pix.get_pixels(15640:19244) % retrieve pixels at indices 15640 to 19244
>> pix_out = pix.get_pixels([1, 0, 1]) % retrieve pixels at indices 1 and 3
The function attempts to mimic the behaviour you would see when indexing into a Matlab array. The difference being the returned object is a PixelData object and not an array.
This function may be useful if you want to extract data for a particular image bin.
Input:
- abs_pix_indices A vector of positive integers or a vector of logicals.
The syntax for these indices attempts to replicate indexing into a regular Matlab array. You can use logical indices as well as normal indices, and you can index into the array “out-of-order”. However, you cannot use end, but it is possible to achieve the same effect using the num_pixels property.
Optional: ‘-ignore_range’ – if provided, new pix_object will not contain correct
pixel ranges
- sqw.PixelData.@PixelData.mask(obj, mask_array, varargin)
MASK remove the pixels specified by the input logical array
You must specify exactly one return argument when calling this function.
Input:
- mask_array A logical array specifying which pixels should be kept/removed
from the PixelData object. Must be of length equal to the number of pixels in ‘obj’ or equal in size to the ‘npix’ argument. A true/1 in the array indicates that the pixel at that index should be retained, a false/0 indicates the pixel should be removed.
- npix (Optional)
Array of integers that specify how many times each value in mask_array should be replicated. This is useful for when masking all pixels contributing to a bin. Size must be equal to that of ‘mask_array’. E.g.:
mask_array = [ 0, 1, 1, 0, 1] npix = [ 3, 2, 2, 1, 2] full_mask = [0, 0, 0, 1, 1, 1, 1, 0, 1, 1]
The npix array must account for all pixels in the PixelData object i.e. sum(npix, ‘all’) == obj.num_pixels. It must also be the same dimensions as ‘mask_array’ i.e. all(size(mask_array) == size(npix)).
Output:
pix_out A PixelData object containing only non-masked pixels.
- sqw.PixelData.@PixelData.move_to_page(obj, page_number, varargin)
- Set the object to point at the given page number
This function does nothing if the object is not file-backed or is already on the given page
Inputs: page_number – page number to move to
Returns: page_number – the page this routine moved to total_num_pages – total number of pages, present in the file
- sqw.PixelData.@PixelData.noisify(obj, varargin)
the noisify functionality to be applied on a per-page basis to the sqw object’s pixel data. See noisify(sqw_object,…) for details of the input and the Herbert noisify function for details of how the input is used. This noisify adds random noise to the object’s signal array, and a fixed error bar to the variance array, paging as required. The options in varargin specify how that is done; see the above functions for details. For options where the signal absolute maximum is used in the noise scaling, a paged pre-scan of the signal provides the maximum over all pages.
obj The PixelData instance. varargs Options for random number distribution and noise magnitude
scaling.
- pix_out If specified, returns a “noisified” copy of the input data
Otherwise it is a reference to the input object, which is “noisified” in place.
- sqw.PixelData.@PixelData.recalc_pix_range(obj)
Recalculate pixels range in the situations, where the range for some reason appeared to be missing (i.e. loading pixels from old style files) or changed through private interface (for efficiency) and the internal integrity of the object has been violated.
returns obj for compatibility with recalc_pix_range method of combine_pixel_info class, which may be used instead of PixelData for the same purpose. recalc_pix_range is a normal Matlab value object (not a handle object), returning its changes in LHS
- sqw.PixelData.@PixelData.set_data(obj, pix_fields, data, varargin)
SET_PIXELS Update the data on the given pixel data fields
The number of columns in ‘data’ must be equal to the number of fields in ‘pix_fields’. The number of rows in ‘data’ must be equal to the number of elements in ‘abs_pix_indices’.
Examples:
- Set the first 100 pixels’ signal and variance to zero
>> set_data({‘signal’, ‘variance’}, zeros(2, 100), 1:100);
Input:
pix_fields The name of a field, or a cell array of field names. data The data with which to set the given fields. abs_pix_indices The indices to set data on. If not specified all indices are
updated and ‘size(data, 2)’ must equal to obj.num_pixels.