Add monitor star handling to proseco (new `mon_star` argument)

[taldcroft]

Add a new keyword argument to the get_aca_catalog function in order to support proseco handling of monitor window requests in the OR STAR=(RA, Dec, Mag) or scheduling of monitor windows in ERs.

Proseco will then handle all aspects of deciding what to do with the request, following the defined process below for ORs (for function=0 defined below).

If it is not initially selected, try selecting a catalog with the monitor star forced for inclusion as a guide star:

• If no new critical messages from sparkles appear relative to the initially-selected catalog, convert to guide (with 8x8 readout in slot 7)
• Else schedule the star as a monitor star.

This requires:

• New argument passed by ORviewer
• ORviewer needs to take the image readout size (6x6, 8x8) from the proseco catalog.
• Formal integration of sparkles into the star selection process. This is a conceptual barrier rather than technical, but not a problem.

See also https://occ-cfa.cfa.harvard.edu/browse/MATLAB-11472

Proseco API

One keyword argument monitors which can accept a list of lists (or 2-d array of floats) in the form:

[
 [coord0, coord1, coord_type, mag, function],  # Monitor window 1 (req'd)
 [coord0, coord1, coord_type, mag, function],  # Monitor windows 2, 3, ... N (optional)
 ..
]

If passed as a list of lists, the input will be converted to a numpy 2-d array (np.array(monitors)) which will have shape (N, 5) where N is the number of monitor windows.

• coord0: first coordinate (RA, row, or yag)
• coord1: second coordinate (Dec, col, or zag)
• coord_type: 0: RA/Dec (deg), 1: row/col (pixel), 2: yag/zag (arcsec)
• mag: star magnitude (only used for commanded MAXMAG for monitor window requests)
• function:
  • 0: Schedule as a guide star if it meets requirements and does not introduce critical warnings. Always using brightest star as designated track star.
  • 1: Schedule as a guide star if it is in the AGASC (raises an exception if not).
  • 2: Schedule as monitor window that tracks the brightest star
  • 3: Schedule as monitor window that is fixed (no tracking)

Use cases:

• OR-specified monitor target function=0
  • This is the most common configuration and let's proseco decide how to schedule the OR
  • Coordinates provided as RA, Dec
• OR-specified monitor target function=1
  • Force scheduling as a guide star in a case where proseco would normally schedule as a monitor window.
  • E.g. a star where the observer provides information on mag or variability that is different from the AGASC (it is currently brighter than in the AGASC)
• OR-specified monitor target function=2
  • Force scheduling as a monitor window in a case where proseco would normally schedule as a guide star.
  • E.g. a star where the observer provides information on mag or variability that is different from the AGASC (fainter or more variable).
• Fixed-location ER monitor window function=3
  • Used for engineering investigation, e.g. looking at a specific flickering pixel
  • coord0,1 as yag/zag or row/col, coord_type=1 or 2
  • Most commonly row/col, so we could just drop coord_type=2 for simplicity.

[jeanconn]

To do this completely, we'd also want to determine DTS and for a MON in proseco and make that available to ORViewer (which would need to get it and use it).

[taldcroft]

In addition to mon_star for science monitor windows, we also need a way of specifying an arbitrary number of monitor windows in an observation. The minimal set of information per monitor window is (yag, zag, track), where track is a bool that indicates if the monitor DTS will be assigned to the mon window slot (track = False) or the brightest scheduled guide star (track = True).

For API we could do mon_yags, mon_yags, and mon_tracks, where each is a value or list of values. The mon_tracks can be bool or int (0 or 1).

Note that the PEA monitor command is more flexible, and allows automatic convert to track at a mag threshold. We don't use this operationally. Likewise the designated track star is arbitrary, but we are agreed to always just use the brightest guide star. Thus neither of those capabilities in the PEA monitor command need support in the proseco API.

cc: @jeanconn @jskrist

[taldcroft]

To do this completely, we'd also want to determine DTS and for a MON in proseco and make that available to ORViewer (which would need to get it and use it).

AFAIK all the necessary columns are already in the ACATable, but the dim and res appear to be just stubbed with values that are not correct. But from the proseco interface perspective the information is already available to ORviewer, it just needs to use it. As a reminder, dim is used for DTS for a mon slot. I'm not sure offhand of what the meaning of the res flag is for MON, but that might be overlayed with convert-to-track.

<ACATable length=11>
 slot  idx      id    type  sz   p_acq    mag    maxmag   yang     zang    dim   res  halfw
int64 int64   int64   str3 str3 float64 float64 float64 float64  float64  int64 int64 int64
----- ----- --------- ---- ---- ------- ------- ------- -------- -------- ----- ----- -----
    0     1         2  FID  8x8   0.000    7.00    8.00  -773.20 -1742.03     1     1    25
    1     2         4  FID  8x8   0.000    7.00    8.00  2140.23   166.63     1     1    25
    2     3         5  FID  8x8   0.000    7.00    8.00 -1826.28   160.17     1     1    25
    3     4 395980320  BOT  6x6   0.979    8.36    9.86 -1082.69  -536.11    20     1   160
    4     5 395981608  BOT  6x6   0.974    8.96   10.46  1097.40  -672.89    20     1   160
    5     6 395981808  BOT  6x6   0.982    6.73    8.23  1189.28 -1067.77    20     1   160
    6     7 396109520  BOT  6x6   0.944    9.52   11.02   403.44   663.02    20     1   160
    7     8 396114080  BOT  6x6   0.963    9.25   10.75 -2319.27   785.98    20     1   160
    0     9 396112616  ACQ  6x6   0.766    9.81   11.20  1906.50  1979.73    20     1   160
    1    10 395980240  ACQ  6x6   0.654   10.14   11.20   429.24  -934.92    20     1    60
    2    11 396114440  ACQ  6x6   0.431   10.33   11.20  2369.37   337.60    20     1    60

[jeanconn]

Right, by "make available" I did mean actually get the values and put them in the data structure. It is a good point that the 'dim' and 'res' columns are already in the ACATable. A nit though, would there be value in renaming those to match backstop again (dimdts and restrk)? I think they were just chopped for space in starcheck.

And yes from the starcheck checks restrk == 1 is convert-to-track.

[taldcroft]

Renaming to match backstop is a good thing in principle, but then proseco won't match starcheck. I'm kind of inclined to say that the starcheck "API" wins at this point, but still open for discussion. I think diverging from starcheck (or renaming starcheck columns) is more likely to cause headaches.

[jskrist]

AFAIK all the necessary columns are already in the ACATable, but the dim and res appear to be just stubbed with values that are not correct. But from the proseco interface perspective the information is already available to ORviewer, it just needs to use it. As a reminder, dim is used for DTS for a mon slot. I'm not sure offhand of what the meaning of the res flag is for MON, but that might be overlayed with convert-to-track.

In ORViewer, the DTS for a monitor window is stored as the row index of the star catalog to be used. Is that similar to what the 'dim' column represents in the ACATable? For non-monitor windows the same property is used to store the search box size.

[taldcroft]

I updated the proposed API and put this into the initial issue description up top.

[jeanconn]

I've reviewed the update to the proposed API and it makes sense to me, though I still have questions about mag. With regard to mag, for science observations that start as

STAR=(255.842917,59.581667,8.400000,MON)

it still isn't clear to me if we want to do anything with that supplied mag. If the requested object exists in the star catalog, I assume we want to use the AGASC magnitude instead of the observer's supplied magnitude for evaluation. For commanding, I also figured for function = 0 (standard science monitor windows) that our MAXMAG in the proseco table would then either be

1) set to a reasonable value from AGASC mag if the row ends up being a guide star 2) set to whatever we use now for a very faint value if the row ends up a MON star

So I'm thinking mag would be ignored proseco side for function = 0. And that's fine, but I wanted to talk it out.

Also still need #304 .

[taldcroft]

For function = 0, the provided mag value would be used if there is no AGASC star within 2" of the provided STAR coordinates, in the same way as for functions 1 and 2. Specifically, set MAXMAG = mag + 1.5. This does not do anything in practice, but is consistent with general precedence.

[jeanconn]

Would it be reasonable to update this API to drop the MON request automatically if the resulting guide star catalog does not meet requirements?

[taldcroft]

Done (see description up top).

[jskrist]

I have been working the MATLAB side of this, and think I have a decent implementation, although I am not sure if the monitors keyword argument can be a list of numpy.float64 values, or if I will need to convert that to some other type before sending it into proseco. I cannot test this until there is something on the python side to handle the new parameter. currently I get the (expected) error: unexpected keyword argument "monitors"

if I pass this in to the current flight proseco.

[taldcroft]

monitors can be a 1-d or 2-d numpy array of float64. Probably from your code perspective it is easiest to just always make it 2-d, where for one monitor window the shape would be 1x5 shape=(1, 5), while for 2 mon windows the shape would be (2, 5).

[jskrist]

monitors can be a 1-d or 2-d numpy array of float64. Probably from your code perspective it is easiest to just always make it 2-d, where for one monitor window the shape would be 1x5 shape=(1, 5), while for 2 mon windows the shape would be (2, 5).

That's the way it is coded up for now. The monitors argument will always be an nx5 array (typically 1x5 or 2x5). I am hard-coding the last two elements to always be 0 at the moment, as it will always pass in the RA/Dec and I don't really understand the options for the function element (or how to present that to the user).

[jeanconn]

I don't recall what the intent of function == 2 is, now that I look over this again. Does 2: Schedule as monitor window that tracks the brightest star just mean force behavior as a "standard" monitor window (where the readout follows the motion of the DTS) but doesn't really "track" anything?

[taldcroft]

@jskrist @jeanconn - I updated the API section in the description to add an option and provide use-case examples. Let me know if this does not clear things up.

[taldcroft]

I also removed the option to pass a 1-d list for a single monitor window. This is not really helpful and possibly confusing. So it always has to be a 2-d array N x 5 where N is the number of monitor windows.