Units for the Y values (counts)

[Paolo Radaelli]

We need to store information on the units of the Y value.

These can be many differnt units e.g

• Dimensionless (i.e. no unit)
• Counts
• Counts/(whatever the X unit is)
• Counts/(solid angle)
• Counts/(solid angle)/(whatever the X unit is)
• etc

We need to

1. store these values
2. Force Algorithms to define the units of there output workspaces (they could of course be the same as the input).
3. Allow algoriths to define a Validator for there input workspaces to validate that the unit of the input workspace is acceptable
4. Carry the unit through to the user interface such that when plotting 1D data extracted from a workspace the unit is used for the Y axis.

[Nick Draper]

Notes from Paolo:

Regarding the Units for workspaces (I am talking about the unit for Y values, not for the axes), one idea is to implement a simple “unit algebra” that avoids the need to define all specific cases. Units are always of the type “n/cm²/sterad” or “barns” or “dimensionless”. Therefore, you need to build two “stacks”, one for the numerator (N) and one for the denominator (D), and implement simple combination rules. For example, let’s say you are writing a generic “divide” algorithm between W1 and W2, and the rule is N3=N1*D2, D3=D1*N2. Let’s say the unit of W1 are n/usec/sterad (a typical normalised detector), N1={[n]}, D1={[usec], [sterad]} and that of W2 are n/cm²/usec (perhaps resulting from a processed monitor), N2={[n]}, D2={[cm], [cm], [usec]} then the units of W3=W1/W2 will be N3={[n], [cm], [cm], [usec]}, D3={[usec],[sterad],[n]}, or, by removing the units that appear both in N3 and D3, N3={[cm], [cm]}, D3={[sterad]} i.e., cm²/sterad (a differential cross section). You can see that with this rule the algorithm will work regardless of the units of W1 and W2.

I think we should actively enforce units definition, because this will make people stop and think. For example, for a “+” or “-“ algorithm to work, the two input workspaces must have the same units, otherwise there is no way to define the output units.

The other advantage of units is that you can use them to deduce whether a workspace is a histogram or a distribution. Here is how you might do it. You need 3 “channels” or dimensions to define this property: “area”, “time” and “dispersion”, or ATD. In essence, you get more neutrons if you count over a bigger area, you count longer or count over a wider dispersive channel (e.g., more usec, more meV etc.). Each unit is therefore characterized by a 3-element array. For example, “counts” is characterized by the array (1,1,1) because is extensive in all three channels. “solid angle” (sterad) is characterized by (1,0,0) and so is “cm²â€ and “number of detectors”. “seconds of measurement”, “incident protons”, “frames” etc. is (0,1,0), whereas “usec”, “Angstrom”, “meV” etc. are (0,0,1). To get the ATD array of a generic unit you sum the numerator arrays and subtract the denominator arrays. In the example above, we have ATD(W1)=(1,1,1)-(0,0,1)-(1,0,0)=(0,1,0), ATD(W2)=ATD(W1), ATD(W3)=(0,0,0). Therefore, both W1 and W2 are extensive only in time – if we measured twice as long we would have twice the Y-values (within errors). W3 is completely intensive, it is a distribution in all “channels”. Knowing the ATD array allows you to decide whether rebinning, regrouping, summing values from different files etc. is allowed or whether you should do averaging instead.

[Russell Taylor]

(In [1647]) Added a text field to Workspace to hold the units of the data. The default is 'Counts', the YUnit() method returns 'Counts / XUnit' if the isDistribution() flag is true. Re #144.

[Russell Taylor]

(In [1649]) Added reading of workspace YUnit to qtiplot. Re #144.

[Russell Taylor]

(In [1650]) Doxygen update. Re #144.

[Russell Taylor]

(In [1706]) Set Y unit string correctly in this algorithm. Re #144.

[Stuart Campbell]

This ticket has been transferred to github issue ​992