NRAO Home  >  Green Bank  |  Wiki Topic:    GB > Software > KaBandReceiver > ModificationRequest4C507

Changes | Index | Contents | Search | Statistics | Go

Indicate Subreflector Position in Data

Modification Request #4 (C5 2007)

• 1. Introduction
• 2. Background
• 3. Requirements
  • Assumptions
• 4. Design
• 5. Determining the state of the subreflector.
• 6. Deployment Checklist
• 7. Test Plan
  • 7.1 Internal Testing
  • 7.2 Sponsor Testing
  • 7.3 Integration/Regression Tests
• Signatures
• CCC Discussion Area

1. Introduction

The subreflector may be nodded during observations (see ModificationRequest2C407). In this observing mode, the subreflector is periodically moved between two positions, spending an equal amount of time in each position. In order to use this data it is necessary to tell what the subreflector was doing as each unit of data was collected (stationary at one position, moving, stationary at the other position).

2. Background

The existing switching state information (CAL and SIG) can not be used because the subreflector motion is not tied to either switching signal. In addition, the information that is needed has at least 3 values (position 1, moving, position 2) and the existing switching state information only has two values.

See ModificationRequest17C507 and ModificationRequest2C407 for related concepts. This MR is written to indicate the subreflector data correctly when subreflector nodding is done as described in those two MRs. Specifically, the SubNod building block described in ModificationRequest17C507 is assumed here and the new SUBMOTIN keyword in the GO FITS file will be examined to ensure that it has a value of "SubNod" before any attempt is made to determine the subreflector position during a scan.

3. Requirements

It is not necessary to record the actual position of the subreflector in the SDFITS table. Nor is it necessary to adjust the antenna pointing information in the SDFITS table to account for the subreflector motion. All that is necessary is that a value be added to the SDFITS table that records the state of the subreflector: position 1, moving, position 2. This new subreflector state value must be available in GBTIDL and it must be possible to do selections in GBTIDL based on that value. This information must also be available in the output of the sdfits produced for the Zpectrometer backend.

Assumptions

• The first subreflector position is position 1.
• The SubNod building block is used. SUBMOTIN = "SubNod" in the GO FITS file.

Note that the old test data will not be correctly marked after this MR has been implemented unless the accompanying GO FITS files are edited to provide the expected additional information.

4. Design

A short integer (I-type) column named SUBREF_STATE will be added to the output SDFITS table. That column will have 3 values: 1, 0, and -1. A value of 1 means that the subreflector is at the first position found in the Antenna file. A value of 0 means that the subreflector is moving between positions. A value of -1 means that the subreflector is at the second position found in the Antenna file. The details on how this state is determined from the Antenna FITS file is found in the next section. This column should also be added to the Zpectrometer sdfits output. That should be straightforward after the Zpectrometer code-merge has happened (see ModificationRequest15C507).

The requirement that this state value is available to data selection in GBTIDL means that it must be added to the index file used by GBTIDL. The index column will be named SUBREF. This is also true for the index used by the Zpectrometer i/o in GBTIDL.

The subreflector tilt is given by the SR_XT, SR_YT and SR_ZT columns in the Antenna FITS file. This information is used (as described in the next section) to determine the state of the subreflector (1,0,-1) for each row of the Antenna position table. The pointing direction for a single integration is an average over all rows in the Antenna position table that occur during that integration (described here). The states of the subreflector at each antenna position used in the average are examined. If any subreflector states during the integration are 0 (moving) then the entire SUBREF_STATE value for that integration will be 0. In all other cases, all subreflector states during the integration will be the same and that state (1 or -1) will be assigned to SUBREF_STATE for that integration.

The GO FITS file will contain additional keywords when the SubNod building block is used as described in ModificationRequest17C507. The presence of SUBMOTIN="SubNod" will be used to signall that the antenna tilt values need to be examined. When that keyword is not there or when it has some other value then SUBREF_STATE will be 1 for all rows in that scan. The additional SubNod keywords will be used as sanity checks against the values found by examining the tilt values as described in the next section.

This averaging of antenna positions occurs in ScanData.getAntennaPositions and the antenna positions are read from disk in ScanData.gatherAntennaPositions. The raw subreflector tilt positions will be read in at the same time that the raw antenna positions are read in gatherAntennaPositions. The individual subreflector states will be determined (as described in the next session) using these tilt positions in gatherAntennaPositions (or a method called from there). The getAntennaPositions method will also examine the subreflector states and return the state value as part of the returned value. These subreflector integration states will be stored internally and a new method, ScanData.getAverageIntSubrefState will be added. There is no need to add a method to go along with getAverageScanMajor (and Minor) which return the average positions over an entire scan. Those methods are used in the obsolete "avg" mode of sdfits. This method will be used by the SDFITSWriter.getRow method to set the SUBREF_STATE value for that row.

Additional modifications needed:

• BinaryTableHDU.create: Add the descriptor for the new SUBREF_STATE column
• IndexWriter: new version, new column, new cell formatting, new field to translate in IndexWriter.translateInfo
• GBTIDL:
  • io classes - must read new field and write new field in binary table and index.
    • new field in data containers (data_container_struct) - common to both continuum and spectral-line data
    • add field to row in sdfits::define_sdfits_row
    • new FITSVER value in sdfits::create_sdfits_file
    • new code to read this field in io_sdfits_line and io_sdfits_cntm
    • new translation in io_sdfits_writer::spectrum_to_row
    • new index field in line_row_info and cntm_row_info structs
    • new index translation in line_index::spectrum_to_info
  • GUIDE layer
    • find_struct : add new index column name (also double check that previously added columns made it in here)

5. Determining the state of the subreflector.

The test data I used is scan 23 from TKA_07APR07. Note that in order for this algorithm to work with this test data after this MR has been implemented will require that the accompanying GO file be edited so that it has the expected value for SUBMOTIN and the expected SubNod keywords SUBNODL, SUBNUNIT, and the 6 SUBaTb keywords.

• Example subreflector position data (sqrt(SR_XT^2+SR_YT^2+SR_ZT^2)) for a few cycles:
  

The 3 states (1,0,-1) are obvious to the eye but it is tricky to identify those states using an algorithm. The following algorithm works on the test data. A few additional days could be devoted to trying out alternatives. This algorithm works without any additional information (e.g. the two positions that the subreflector is being tilted between or some information on how long the subreflector spends in each position). However, that information is available now and it should be used to refine this algorithm for both speed and robustness (the tilts described here may be superimposed on other subreflector motion, e.g. PTCS focus tracking).

• The 3 tilt values are combined to get a single tile value at each observed time: sqrt(SR_XT^2 + SR_YT^2 + SR_ZT^2). This means that the specific tilt direction could be changed without having to modify sdfits.
• A simple "derivative" is calculated by subtracting the immediately previous tilt from the current tilt (i.e. tilt_dot[i] = tilt_dot[i]-tilt_dot[i-1])
• The locations of the peaks are found in the derivative. This gives the number of samples between each state (and twice that is the total length of one cycle). All peak locations are used to get an average time between peaks over the entire scan.
• An average tilt position vector over one complete cycle (twice the average length between peaks) is made from all values in the vector of tilt values. This will consist of the average first tilt position (position 1) in most of the first half of the vector and the average second tilt position (position -1) in the second half of the vector. Each half is examined, starting from the middle of that half, to find all of the points within some factor of the RMS in that half (working away from the middle and refining the RMS as it goes). A factor of 4 seems to work well. It is assumed that the middle 3 points are all okay to use in starting off the mean and RMS calculation. The result is a set of points near position 1 and another set of points near position -1 and everything else is in the moving state. It is assumed that this repeats itself following the pattern found when the peaks were located. The Astrid script (ModificationRequest2C407) will ensure that the observations start in position 1. Users who write their own script and have the subreflector start in the other position will get incorrectly labeled data. These users are on their own although it should be straightforward to hack any data reduction scripts to reverse the meaning of position 1 and position -1 in the sdfits table.

This shows the same sample data with the 3 states over-plotted in different colors. The states were identified using the method described here.

• Example subreflector position showing different states (blue is 1, yellow is -1, and red is 0):
  

Again, this demonstrates that an algorithm exists that works with the test data. There may be better algorithms that could be used. Some development time will be set aside to explore other algorithms.

Modifications to this algorithm that should be explored during implementation include:

• Use the provided half-cycle time (SUBNODLN and SUBNUNIT) to check that the times between peaks in the derivative are consistent. A substantial difference here should result in a warning message.
• Use the provided subreflector tilts between the two beams (SUBaTb keywords) to derive an expected total difference between the two subreflector positions and compare it with that found in the algorithm. Note that these tilts are the commanded tilts and not the indicated tilts in the appropriate frame as recorded in the antenna FITS file. The indicated tilts are equal to the commanded tilts plus a constant tilt offset on each axis due to focus tracking where that constant may vary with each scan. The 3 focus tracking offsets for a given scan are given by these three equations where the FTRZ* and LFC* values are FITS keywords in the Antenna FITS file primary header (note that this means that any changes to these equations will need to be accompanied by changes to the sparrow code that processes those tilts for sdfits):
  • Xt_indicated = Xt_commanded + FTRKXTA + LFC_XT
  • Yt_indicated = Yt_commanded + FTRKYTA + LFC_YT (the focus tracking offset term in Ytilt here is usually zero)
  • Zt_indicated = Zt_commanded + FTRKZTA + LFC_ZT

6. Deployment Checklist

• Update the sdfits description documentation.
• Update relevent GBTIDL documentation. At this point, probably just note the additional selection field.

7. Test Plan

• Existing test data should be filled using sdfits to ensure:
  • That non-nodding data is handled correctly (SUBREF_STATE should be 1 for all integrations)
  • subreflector nodding is handled correctly (TKA_07APR07) after making a local copy and modifying the accompanying GO fits files.
• New test data taken (nodding and non-nodding) and SUBREF_STATE checked.
  • New test data should be taken using both ways to express the nodding half cycle time (SUBNUNIT of "integrations" and "seconds").
  • Some test data taken where the nodding half cycle time is not an integer number of integrations.
• GBTIDL used to read this test data. Ensure that SUBREF_STATE can be selected and that the value is preserved when written to disk by GBTIDL.

7.1 Internal Testing

• Unit tests
  • Existing unit test data can be used to ensure that SUBREF_STATE is 1 for all integrations (non-nodding)
  • A scan from TKA_07APR07 with modified GO FITS file should be added to the sdfits unit test data to verify that things work as expected there.
  • Filled sdfits file from that test scan of TKA_07APR07 should be added to the gbtidl test data and used by unit tests there (selection and i/o).
  • New test data as described above should be added to the data used in unit tests and unit tests written to use that data.

7.2 Sponsor Testing

This section is for the sponsor. What do you need to do in order to ensure that the MR is complete and correct? These tests are the prerequisite for sign off for the "accepted/delivered by sponsor" item in the "signatures" section.

7.3 Integration/Regression Tests

• Normal, non-nodding scans should be taken and all data should have SUBREF_STATE==1 in the sdfits file and as seen in GBTIDL.
• Nodding scans should be taken. That data should be processed using the GBTIDL scripts described in ModificationRequest5C507.

Signatures

APPROVED: I acknowledge that my request is fully contained in this MR, and if the SDD delivers exactly what I specified, I will be happy.

ACCEPTED: I acknowledge that I have validated the completed code according to the acceptance tests, and I am happy with the results.

Written	- BobGarwood - 27 Aug 2007
Checked	- JoeBrandt - 12 Sep 2007
Approved by Sponsor	- RonMaddalena - 24 Sep 2007
Approved by CCC	- RonMaddalena - 25 Sep 2007
Accepted/Delivered by Sponsor	- RonMaddalena - 31 Oct 2007

Symbols:

• Use %X% if MR is not complete (will display )
• Use %Y% if MR is complete (will display )

CCC Discussion Area

Attachment:	Action:	Size:	Date:	Who:	Comment:
example_data.jpg	action	21988	17 Jul 2007 - 16:46	BobGarwood	Example subref position data for a few cycles
example_marked.jpg	action	27725	17 Jul 2007 - 17:33	BobGarwood	Example subref pos showing different states