Vex
===

.. py:class:: pride.io.Vex(file: str | pathlib.Path)

   Interface to VEX files.


   .. py:method:: load_observation_modes() -> dict[str, pride.types.ObservationMode]

      Load observation modes from the VEX file

      An observation mode is a configuration for the experiment, and it
      specifies the frequency band in which each of the antennas will operate.
      The VEX file can contain multiple observation modes.

      This function reads information about the observation modes from the VEX
      into ObservationMode objects, and returns a dictionary in which each of
      these objects is indexed by the mode ID.

      :return: Dictionary of observation modes



   .. py:method:: load_clock_parameters() -> dict[str, tuple[datetime.datetime, float, float]]

      Load clock offsets from $CLOCK section

      [From VEX documentation]
      The $CLOCK section contains the necessary clock parameters for proper
      correlation of the data. Normally, this information will be taken from
      the station logs, transcribed manually or, as a last resort, determined
      from a fringe search at the correlator.
      [END]
      The returned dictionary has the ID of a station as key, and a tuple with
      the following items as value:
      - Epoch of origin for the clock model
      - Clock offset with respect to UTC [s]
      - Clock rate [s/s]

      :return clock_parameters: Dictionary with clock parameters for each station.



   .. py:method:: load_station_ids_and_names(ignored_stations: list[str] | None = None) -> dict[str, str]

      Load information from the $STATION section

      Parses the STATION section of the VEX file to identify all the observatories
      potentially involved in the experiment. Checks the names of the antennas
      against a station catalog, normalizes them to ensure that they match the
      one used in the external data files of the delay and displacement models,
      and ensures that all of the IDs and names are unique.

      :param ignored_stations: List with IDs of stations to ignore
      :return stations: Dictionary with the station IDs as keys, and their
      normalized names as values.



   .. py:method:: load_source_data(source_name: str) -> SourceData

      Load information about a source

      Loads the type information and, for calibrators, the observed
      coordinates from the VEX file. The function ensures that type information
      is present, that the source type is valid, and that the coordinates are
      specified in the J2000 reference frame. The information is loaded into
      a SourceData data structure.

      :param source_name: Name of the source to load
      :return source_data: Data structure with information about the source



   .. py:method:: load_single_scan_data(scan_id: str, experiment_target: str) -> ScanData

      Return data about a single scan

      Returns a ScanData object with the following information:
      - Source type
      - Source name: Uses `experiment_target` for `source_type` = "target"
      - Observation mode
      - Initial epoch for all stations
      - Initial and final time offsets for each station involved

      :param scan_id: ID of the scan to load
      :param experiment_target: Name of the target for the experiment
      :return scan_data: Data structure with information about the scan