Calibration Database

From EOVSA Wiki
Revision as of 17:10, 20 September 2016 by Mlukicheva (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Description and Use of the EOVSA Calibration Database


We have created a general-purpose table in the SQL-Server database eOVSA06, named abin, which is used to hold binary calibration data in a general format given by an XML format string in the same table. The table is meant to be extendable to any calibration type, although it remains to be seen whether it is general enough to handle all use cases. This document describes the scheme, the format of the abin entries, and the list of currently defined binary types (this will have to be updated on a regular basis as new definitions are added).

Description of the General Scheme

The general idea is to create entries into the abin table that are self-describing and completely general.

The table columns are:

['Bin';, 'Timestamp', 'Version', 'Id', 'Description']

The Id number is auto-incremented to be unique to each record, and is never set by the user. Each type definition will appear in the table with an n.0 Version number (float), and whenever it is updated, a new n.0 record is written with the current Timestamp. This provides a history, with the corresponding Timestamp giving the start timerange of applicability (actually regretting that this key is called Version, since its purpose could more accurately be referred to as the calibration Type). To distinguish between this key and the true versions given within the type definition record, the latter is referred as the “internal version.” The Bin column contains an XML data description that is to be used to decode the data. The Version (type) number n will be unique for each calibration type, so that records with Version = 1.0, for example, will always contain the latest definition for a particular type of data defined as type 1 (the type of calibration data is further described in the Description column). The type definitions, as well as helper routines for creating, reading, and writing records is found in the Python module

The XML data itself, found in the Bin column of a Version n.0 record, contains an internal version variable that gives a further record of the version of the XML format. As a concrete example, the latest Version 4.0 (delay centers) calibration will contain an XML string that includes its own internal version variable, say its value is 2.1, that would distinguish it from an earlier type 4.0 version. This internal version number is used by the send_xml2sql() to determine whether a definition defined in has changed and needs to be written to the abin table.

After (never before) the defining n.0 record is written, subsequent records of that type can be written containing the binary calibration data, which will be decoded using the defining XML string. Thus, after writing the latest Version 4.0 format record, subsequent records with Version 4.1 (type 4, with internal version 1.0) can be written that will be decoded using that latest 4.0 XML string. Other versions, e.g. 4.2 (internal version 2.0) etc., could in principle be written, although it is not clear why that would be needed (perhaps an important change to the contents, but without a corresponding change to the format, could be indicated with a new 4.x version number). Thus, the latest delay_centers entry can be read with a query like:

SELECT TOP 1 * FROM abin WHERE Version > 4.0 AND Version < 5.0 ORDER BY Timestamp DESC

while the delay_centers entry for a given Timestamp tstamp can be read with a query like:

SELECT TOP 1 * FROM abin WHERE Version > 4.0 AND Version < 5.0 AND Timestamp <= tstamp ORDER BY Timestamp DESC

In testing this, it was discovered that binary records returned by such a query are limited in length to 4096. To get an arbitrarily long record, one must prepend the string “SET TEXTSIZE 2147483647” to the query. Note that such details are already handled by the helper routine read_cal() in As new calibration types are created, their definitions will be added to, both by updating the cal_types() routine to add the new type’s Version number and Description, and by adding a two writing routines—one called type>2xml() routine that returns the XML description of the data (later written into the database by send_xml2sql()), and one called <type>2sql() that converts the calibration data to a binary buffer and writes it into the database, where <ype> is a hopefully rational name for the new type. As new formats for an existing type are created, it should be fine to simply update the cal_types() routine to change the description (if needed) and update the format embodied in the <type>2xml() and <type>2sql() routines. It should not be necessary to keep the old format, since the database itself already forms a history. Of course, any previous versions of the file will also be kept in the github versioning system.

Currently-Defined Types

This section will hopefully be updated whenever new types are added, to provide a list of currently-defined calibration data types. However, it is probably wise to consult the file to verify the current definitions. Here is the verbatim return statement from cal_types():

return {1:['Total power calibration (output of SOLPNTCAL)','proto_tpcal2xml',1.0],

        2:['DCM master base attenuation table [units=dB]','dcm_master_table2xml',1.0],

        3:['DCM base attenuation table [units=dB]','dcm_table2xml',1.0],

        4:['Delay centers [units=ns]','dlacen2xml',1.0]}

To add a new type, simply add another entry to this dictionary, with a unique type number, and a three-element list whose first element is the Description string, second element is the string name of the routine to call to create the XML definition (returns a binary buffer ready for writing to the abin table), and third element is the version number. Then add the corresponding type>2xml() routine defining the format of the binary data, and the <type>2sql() routine that converts the calibration data to a corresponding binary buffer. The module includes a routine send_xml2sql(), which can be called at any time and checks the latest version of each calibration type in the abin table, and updates any that have changed (i.e. has a different version number than the latest one in the table). The return statement of each <type>2sql() routine should call write_cal() to actually write the binary buffer to the database, so that a single call to the routine does everything. It is anticipated that routines that create the calibration data will call the corresponding <type>2sql() routine directly.

To change an existing type, change the description in the cal_types() routine, if desired, and change the corresponding <type>2xml() and <type>2sql() routines to create the new definition. It should not be strictly necessary to increment the version number that will be written into the XML description, unless two active versions are needed at the same time. It is up to the programmer to decide whether to increment the version’s minor (fractional) or major (integer) part of the version number, since only its uniqueness is required.

Reading Back Data for a given Calibration Type

If the above scheme is followed, it should be possible to use a single, general routine to find and successfully read the binary calibration data for a given time. The read_cal() routine in the module does this, returning a Python dictionary and the binary buffer. The dictionary contains key, value pairs defining the variable names (keys) and the types and start location (values) in the binary buffer. To use these returned entities, one employs the extract() routine defined in the module, e.g. to read the total power (type 1) calibration factors for antenna 5 on April 3, 2016 as of 20:00 UT:

import stateframe, util

tp, buf = read_cal(1, t=util.Time(‘2016-04- 03 20:00’))

calfac = stateframe.extract(buf,tp[‘Antenna’][4][‘Calfac’])

Here the index for antenna 5 is 4, since it is a zero-based index. Note that to read the values for the current time, the input t can be omitted.