expand Telescope-Instrument model

[pdowler]

From HST Archive coordination meeting: add a detector name.

[yeunga]

The following enhancement suggestion is an excerpt from opencadc/caom2tools#60 by dr-rodriguez:

"Some other wishlist items for CAOM v2.4 at the observation level:
An observation mode tag. While observation.type can get us some information about the type of observation, we sometimes need to provide more details and this observation.mode can be used to further refine that."

[pdowler]

There can be a (small) number of elements that make up the instrument, but in some cases different paths result in different planes or different artifacts or different parts. At some point this connects to the named bandpass (filter) which is currently specified in Chunk.energy and (summarised/aggregated) to Plane.energy.bandpassName... it seems worthwhile to revisit multiband data description and try to use a consistent pattern to describe multi-instrument-element

Although current multiband observations (eg. JCMT, MACHO) implement this as different files (artifacts) in different planes (thus with one bandpassName per plane), if someone were to store such data in a single file -> single artifact -> single plane with multiple bandpassName(s).

[pdowler]

CAOM currently has Telescope-Instrument with little more than names.

Interferometry looks more like Telescope-Collector-Instrument. Correlator info belongs in the provenance of the "raw" Plane.

Quick list of use cases:

1. DerivedObservation created by combining data from multiple telescopes and/or instruments (stack, mosaic, SED, time series, etc)
2. SimpleObservation created by combining data in real time from multiple telescopes (VLBI) -- multiple telescopes
3. SimpleObservation created by correlating data from multiple collectors in real time (interferometry) -- single telescope, multiple collectors
4. SimpleObservation created by passing signal through a combination of sub-components before recording it (filter, polarizer, grating, grism, beam splitter, ... detector) -- single instrument name but with different configurations that make it behave differently, so name is not very informative

The boundary between hardware and software in the "instrument" is intentionally vague.

Some long standing design principles/notes:
a. CAOM has never included collector size because the goal was always to be able to query on science rather than engineering metadata; collector size + exposure time is nominally related to depth/sensitivity but we always preferred to characterise this directly rather than have users do math to estimate it crudely.
b. pretty much every Telescope-Instrument in the world is bespoke so there is not a lot in common and a more detailed model probably has a very low value-to-complexity ratio

[pdowler]

On the line between hardware and software in the context of interferometry:

There is one instrument attached to each collector and the correlator is farther downstream so it is described by the provenance of the raw visibility data. Therefore:

• normally, the most raw plane (Plane.calibrationLevel = 0 or 1) does not have provenance because it is implicitly "from the instrument"; in principle such raw data could have provenance (eg describe the software/version used to format the data in FITS and store it) if that's considered worthwhile
• raw visibility data (Plane.calibrationLevel = 0) should have provenance information describing the correlator, eg:

Plane.provenance.name = {correlator name}
Plane.provenance.lastExecuted = {timestamp of data acquisition, probably start}
Plane.provenance.reference = {identifier for extra details about the named process}
Plane.provenance.version = {correlator software version(s)}
Pane.provenance.keywords = {additional adhoc metadata}

The other provenance fields look n/a and there would be no Plane.provenance.inputs (this is the first product stored).

---

If it makes sense that correlator is provenance and not instrument, then in the case of VLBI with between 2+ telescopes the observation does not have a common telescope or a common instrument and just has
provenance. It could be feasible/desirable to create something like:

data stream A: SimpleObservation, telescope A, plane X, no/minimal plane metadata, 
                           no artifact
data stream B: SimpleObservation, telescope B, Plane Y, no/minimal plane metadata, 
                           no artifact

and

correlated raw visibililty: DerivedObservation, 2 simple members above, no telescope, 
                                             raw plane w/ metadata and artifact(s)

because that's the first things stored. TBD