[LIBISIS-code-tickets] [LIBISIS] #151: Captioning and units of plots needs to be generalised

[LIBISIS Library and Applications]

#151: Captioning and units of plots needs to be generalised
--------------------------+-------------------------------------------------
 Reporter:  Toby Perring  |       Owner:  Dickon Champion
     Type:  enhancement   |      Status:  new            
 Priority:  critical      |   Milestone:                 
Component:  General       |    Keywords:                 
--------------------------+-------------------------------------------------
 About a year ago we agreed to use IXTunits to hold captioning information
 for the purpose of getting LIBISIS working.

 However, it is not a proper solution for generic plots: the quantity along
 an axis (e.g. temperature) is not the same as the units in which it is
 measured (e.g. Celsius, Kelvin, Fahrenheit...), and many quantities can
 have the same units e.g. scattering angle, two theta, azimuthal angle...
 are all in degrees - or radians. We need to allow the quantity and the
 units to be independently set, and Libisis to appropriately construct the
 caption at the time of plotting from the two.


 In the following, I consider a 1D dataset only, but expands obviously to
 an arbitrary dimensional dataset.

 Add extra fields to the object, s_label and x_label, so that no has

 base, title, signal, error, s_label, s_units, x, x_label, x_units,
 x_distribution

 x_label  (class char)      The quantity or caption along the x-axis
 x_unit (class IXTunit)     The units

 x_label  (class char)      The quantity or caption of the signal
 x_unit (class IXTunit)     The units of the signal

 The captions on the plot are constructed as follows (in Matlab syntax for
 character strings)

 signal axis:
 [s_label. '(',s_units.units,')']    if x_distribution=false
 [s_label. '(',s_units.units,') / ',x_units.units]    if
 x_distribution=true

 x-axis:
 [x_label, '(',x_units.units,')']

 In both cases, the obvious thing is done if x_units or s_units have not
 been filled. Also, in both cases several lines of caption must be
 acceptable, with the units string appended on to the last line e.g.
 x_label = {'Hello','sailor'} and x_units='meV'
  =>     'hello'
         'sailor (meV)'


 For example, we might have
 x_label = 'Time'
 x_units='second'        <== pseudocode, as this is actually an IXTunits
 object; this means the field 'units' of the IXTunits object is 'second'
 x_distribution=false

 s_label='Temperature'
 s_units='K'             <== pseudocode, as above

 in which case the caption are 'Temperature (K)'  and 'Time (second)'

 Or,
 x_label = 'Time'
 x_units='microsecond'
 x_distribution=true

 s_label='Counts'
 s_units=''

 in which case the caption are 'Counts / microsecond'  and 'Time
 (microsecond)'



 I've not addressed what changes might need to be made to the IXTunits
 class. There may need to be some. These are my thoughts:

 We want to be able to just set the units string, but not bother with a
 code, because we don't have any function that knows how to manipulate
 these units e.g.
         myunit = IXTunits('degrees')
         myunit = IXTunits('bushels')

 We want to be able to set a units object according to an already defined
 code:
         myunit = IXTunits('w')

 We want to be able to initialise the units string for a 'user' unit,
 because we will write some code elsewhere that handles units
 interconversion (or other manipulations) in a very specific way
         myunit=IXTunits('$bushel','bushel')

 But note that the units code for built-in units actually define the
 caption at present e.g. if units code is 'w' it should define the caption
 as 'Energy transfer (meV)' unless the IXdataset object has x_label
 defining it as something else. We should therefore have a thrid string for
 when a units code is defined, which is the default label
         myunit=IXTunits('$bushel','bushel','Fruit production')

 Another point to note is that the format
         myunit = IXTunits('degrees')
 is OK so long as the string 'degrees' does not conflict with a built-in
 unit. Somehow we have to check that. Alternatively, we might insist, as is
 the case at the moment, that we give a code to every unit string - but it
 is rather painful in that in the most common instance that one want to
 simply have a units string for the construction of the captions, one has
 to create a dummy code which will never be used anywhere. A check on pre-
 defined units already needs to be done so that they are not redefined, so
 it should be quite straightforward to extend the check.

-- 
Ticket URL: <http://trac.libisis.org/code/ticket/151>
LIBISIS Library and Applications <http://www.libisis.org/>
LIBISIS Library and Applications