Observing
=========================

This chapter describes how to start and manage observations.

Starting an observation
-------------------------

To observe with a station, you must construct the observation's specifications, and hand it to the ``DeviceProxy("STAT/ObservationControl/1")`` device to start::

  observation_spec = {
    "observation_id": 12345,
    "start_time": "2106-02-07T00:00:00",
    "stop_time": "2106-02-07T01:00:00",
    "antenna_field": "HBA",
    "antenna_set": "ALL",
    "filter": "HBA_210_250",
    "dithering": {
      "enabled": true,
      "power": -4.0,
      "frequency": 102000000
    },
    "SAPs": [{
          "subbands": [10, 20, 30],
          "pointing": { "angle1": 1.0, "angle2": 0, "direction_type": "J2000" }
    }, {
          "subbands": [40, 50, 60],
          "pointing": { "angle1": 2.0, "angle2": 0, "direction_type": "J2000" }
    }],
    "HBA": {
      "DAB_filter": true,
      "tile_beam": { "angle1": 1.5, "angle2": 0, "direction_type": "J2000" }
    }
  }

  import json
  obs_control = DeviceProxy("STAT/ObservationControl/1")
  obs_control.add_observation(json.dumps(observation_spec))

The above specification contains the following parameters:

+-------------------------+-----------------------------------------------------------------------------------------+
| Parameter               | Description                                                                             |
+=========================+=========================================================================================+
| ``observation_id``      | User-specified unique reference to this observation.                                    |
+-------------------------+-----------------------------------------------------------------------------------------+
| ``start_time``          | automatically start observing when this timestamp is reached. (optional)                |
+-------------------------+-----------------------------------------------------------------------------------------+
| ``stop_time``           | automatically stop observing when this timestamp is reached.                            |
+-------------------------+-----------------------------------------------------------------------------------------+
| ``antenna_field``       | Which antenna field to use (LBA, HBA, HBA0, HBA1).                                      |
+-------------------------+-----------------------------------------------------------------------------------------+
| ``antenna_set``         | Which subset of antennas to use (ALL, INNER, OUTER, EVEN, ODD).                         |
+-------------------------+-----------------------------------------------------------------------------------------+
| ``filter``              | Which band filter to use (LBA_10_90, LBA_30_70, HBA_110_190, HBA_170_230, HBA_210_250). |
+-------------------------+-----------------------------------------------------------------------------------------+
| ``dithering.enabled``   | Whether to add analog dithering noise to increase linearity. (optional)                 |
+-------------------------+-----------------------------------------------------------------------------------------+
| ``dithering.power``     | Power (in dB) to apply for dithering (-4.0 to -25.0). (optional)                        |
+-------------------------+-----------------------------------------------------------------------------------------+
| ``dithering.frequency`` | Dithering frequency (in Hz). (optional)                                                 |
+-------------------------+-----------------------------------------------------------------------------------------+
| ``SAPs``                | List of pointings and frequencies (subbands) to track and beam form.                    |
+-------------------------+-----------------------------------------------------------------------------------------+
| ``HBA.DAB_filter``      | Enable the analog filter on the RCUs for DAB radio frequencies. (optional)              |
+-------------------------+-----------------------------------------------------------------------------------------+
| ``HBA.tile_beam``       | Pointing to track with the HBA tiles (optional). (specify for HBA)                      |
+-------------------------+-----------------------------------------------------------------------------------------+

This will configure the specified antenna field (f.e. ``HBA``) as follows:

* ``STAT/DigitalBeam/HBA`` is configured to beam form the antennas in the specified ``antenna_set``, track all pointings given in ``SAPs[x].pointing``, and produce beamlets for all subbands in ``SAPs[x].subbands``. The beamlets mirror the subbands in the order in which they are specified,
* The ``observation_id`` is used to annotate the beamlet data produced by this observation,
* ``STAT/AFH/HBA`` is configured to use the specified ``filter`` for the RCUs,
* ``STAT/TileBeam/HBA`` is configured to beam form all HBA tiles, tracking the given ``tile_beam`` pointing.

Observation Output
````````````````````````

The effect of the observations can be observed through the following means, all of which are managed independently from the observation:

* The beamlets streaming out of the station towards the processing cluster. The ``Beamlet`` device is responsible for managing and monitoring this data flow,
* The statistics streaming out of the station towards the control softwate. The ``XST/SST/BST`` devices are responsible, and allow inspection of this data flow,
* The various input signal monitoring points available in the ``SDP`` device, such as ``FPGA_input_signal_mean_RW``.

Life cycle
````````````````````````

The ObservationControl device will start each Observation when its start time is reached or past, and will stop it at the specified stop time. You can also force this to happen::

  obs_control = DeviceProxy("STAT/ObservationControl/1")
  obs_control.start_observation_now(12345) # starts observation 12345 now, regardless of its specified start time
  obs_control.stop_observation_now(12345)  # stops observation 12345 now, regardless of its specified stop time

Managing observation(s)
-------------------------

To manage running observations, we can interact with ObservationControl::


  >>> # Check which observations are known (running or yet to run)
  >>> obs_control.observations_R
  array([12345])

  >>> # Check which observations are running
  >>> obs_control.running_observations_R
  array([12345])

  >>> # Stop a running observation
  >>> obs_control.stop_observation_now(12345)

  >>> # Stop all running observations
  >>> obs_control.stop_all_observations_now()

Alternatively, we can inspect a running observation more closely. Each observation is represented by its own device: ``STAT/Observation/$id``, so if observation 12345 has been started, we can do the following::

  observation = DeviceProxy("STAT/Observation/12345")

This device exposes its settings as individual attributes, as well as:

:alive_R: Ever-increasing value as long as the observation is running. Allows one to check whether monitoring has become stale.

  :type: ``int``

:observation_settings_RW: JSON string of the specifications of this observation. NB: This attribute cannot be written once the observation has started.

  :type: ``str``

:observation_id_R: (et al) Each specification parameter can be retrieved individually.

  :type: (depends on specification parameter)