
Meme Maps

The accurate description of keywords and other memes often involves
mappings of one kind or another.  The simplest is the keyword which
is canonically a numeric value, yet is expressed in FITS headers
from certain control systems as a string;  but there are more
complex mappings.

The types of mapping we can express in the Memes schema are:

	Format conversion
		and/or
	Value conversion by table lookup
	Value conversion by function call
	Value conversion by paramaterized formula

We express these maps by manipulation of the ISA MID field
and the MapMID field in the Memes tables, and by ancillary data
in the Mbundles and Mmaps tables.  Here are some examples to
help you keep the concepts clearly in mind when designing
memes:

			FORMAT CONVERSION

HIRES1 AIRMASS is a character string:  FORTRAN format A5,
Sybase format char(5).  It has both an ISA mid and a Map mid.
The ISA mid points to Meme 470, KECK1DCS AIRMASS, which is
a float (F12.8).  The Map mid points to Meme 1229, whose
context is MapTypes.  Its name is F5_2 and its FORTRAN format
is F5.2.  It exists only to show that a floating point number
was formatted as F5.2, which is how HIRES AIRMASS got to be
an A5.

The Mmaps and Mbundles table play no part in the AIRMASS story.


			LIST OF LEGIT VALUES

RADECSYS is a good example of a keyword which has no numeric
internal representation requiring conversion, but which can
only assume one of a short list of legitimate values.  In this
case, there is no ISA or Map relationship, but the Mmaps table
nevertheless contains records for this keyword.

When we examine the Mmaps records for RADECSYS, we find four
legitimate values in ResVal.  ParMid and ParVal are null.  The
Comment field explicates the cryptic mnemonic strings which
are RADECSYS's possible values.


		MAPPING OF VALUES by TABLE LOOKUP

The keyword DCSSTAT is found in the contexts KECK1DCS and 
KECK1DCS.bin.  In the internal or binary (.bin) context its
units field is 'bitmask' and its sybase type is a int, 
indicating that the internal representation of this value is a 
4-byte bitmask.  The external (not .bin) keyword DCSSTAT has
an ISA mid of 1743 (the internal DCSSTAT) with a Map mid of
1745 (TableLook).

The fact that the map type is TableLook means that we know
(a) that there are records in Mmaps for DCSSTAT, and (b) how
to interpret them.  The object of the Mmaps records is to 
show the values which DCSSTAT takes on externally as a result 
of the internal values (and vice versa).  The Res Mid in Mmaps 
will therefore be the DCSSTAT external mid, and the Res Vals will 
be its values.  The Par MID is left NULL, since it's implicitly 
the same as the parent meme's (DCSSTAT external) ISA mid, in this 
case DCSSTAT internal.

Looking at the Mmaps data for DCSSTAT, therefore, we are not 
surprised to see that the Par Val field holds values like
1, 2, 4, 8, and so on (because we knew that the binary or
internal DCSSTAT units field was 'bitmask').  We see that
an internal value of 8 corresponds to the string 'running'.

For added value, we've stored the names of the KTL C source
symbols for DCSSTAT in the Comments field.  This is purely
documentary, at this release of the schema.

Note that this kind of lookup can be used for both operational and
documentary purposes.  For the case of the DCSSTAT table we are
merely describing how KTL may already have done the translations
for us.  But the one-to-one lookup can also describe the
mappings from xxxxxNAM to xxxxxORD and from xxxxxORD to xxxxxRAW.
In these cases we can use the database tables to generate the
configuration files that the stages will read at startup.
Also, the database contains all the information necessary for
a GUI application to perform the same mappings.


	MAPPING OF VALUES by FUNCTION CALL

We don't really know how to do this yet.  However, the UnitConv
map meme is a 'generic' function of sorts.  It will be found 
in use with the infamous PARANG keyword, as follows:

KECK1DCS PARANG is a float (F13.8) in degrees.  It ISA
KECK1DCS.bin PARANG, which is a float (F13.8) in radians.
The Map Mid for the conversion is 1747, or UnitConv.

The semantics of UnitConv say, basically, 'Do the obvious
unit conversion.'  In other words, you know you have to get
from radians to degrees, which is trivial, so we don't bother
to specify algorithms or specific function names. 

We could imagine that UnitConv is actually called Rad2Deg,
and has a large family of siblings called Deg2Rad, Deg2Hrs,
Pix2Rad, etc.  Alternatively...

One could envision an ancillary table called Mconvert which
consisted of three fields:  FromUnits, ToUnits, FunctionName.
Anyone setting up a Memes-based application could supply their
own favourite function names for documentary or code-generation
purposes.  We haven't taken it that far yet.  Stay tuned.


	MAPPING OF VALUES by PARAMETERS and ALGORITHM

Some mappings require a mathematical operation to convert units
between internal and one or more external representations.  We've
set up a prototype 'fake' example of this for your reference.

The fake keyword is KWCONV in the contexts DEMO and DEMO.bin.
KWCONV's binary representation is in floating point millimetres, 
but its external representation is in integer microfortnights
(we wouldn't want you to mistake this for a real keyword).
KWCONV (in DEMO) ISA 1748 (that's KWCONV in DEMO.bin).  Its
Map mid is 1742, which is DemoMap. 

If we look at DemoMap, and bring up its Bundles, we find that it
has 4 records in Mbundles.  They are (in order) the memes
BIAS1, BIAS2, SCALE, and UNITS.  These memes come from the context
MapParams, and it's understood that they will be used in the
configuration or construction of code that will do the unit
conversion for us.  We assume that we can define a set of 
algorithms (like polynomials) which require certain coefficients,
and that we can provide these coefficients (or parameters)
in an ordered list.  The Mbundles records for the map are
that ordered list.

Now we know that the type of algorithm used for this conversion
is a DemoMap and that it has these 4 parameters, we expect to
find values for these 4 parameters in Mmaps for KWCONV.

In Mmaps for KWCONV we find that Res Val fields are empty, but
Par MID fields are not.  The Par MID fields contain the mids
of the MapParam memes BIAS1, BIAS2, SCALE, and UNITS.  The
Par Vals fields contain values for these 4 parameters.

The parameters values for the algorithm will be written in the
order specified by Mbundles to a configuration file that
the stage will read at startup.  The MapType combined with the
parameters should describe mappings like xxxxxVAL to xxxxxRAW.  
Note, however, that the actual calculation requires 
knowledge that is not in the database.  All we know are the parameters
of some arithmetic formulae which correspond to different MapTypes.
That correspondence is not encoded in the database at this time.

