create_visibility

ska_sdp_datamodels.visibility.create_visibility(config: Configuration, times: ndarray[Any, dtype[_ScalarType_co]], frequency: ndarray[Any, dtype[_ScalarType_co]], phasecentre: SkyCoord, channel_bandwidth: ndarray[Any, dtype[_ScalarType_co]], weight: float = 1.0, polarisation_frame: PolarisationFrame | None = None, integration_time: float = 1.0, zerow: bool = False, elevation_limit: float | None = 0.2617993877991494, source: str = 'unknown', scan_id: int = 0, scan_intent: str = 'none', execblock_id: int = 0, meta: dict | None = None, utc_time: Time | None = None, times_are_ha: bool = True) → Visibility[source]

Create a Visibility object with its main data array filled with complex double-precision zeros, and its axes and other attributes adequately initialised. What ‘adequately initialised’ means is explained at length in the notes section below, as are several important caveats.

This function caters specifically to visibility simulation purposes. In particular it computes approximate (u, v, w) coordinates from scratch rather than taking them as an externally precalculated input. See notes.

Parameters:

  • config (Configuration) – Configuration object describing the interferometer array with which the output Visibilities are assumed to have been observed. This is used to calculate (u, v, w) coordinates.

  • times (ndarray) – One-dimensional numpy array of floating point numbers representing hour angles in radians. Specifically, the hour angles under which the phase centre is seen from the centre of the interferometer. These get converted to a timestamp stored in the output Visibility, via a process explained in the notes. NOTE: how the data are interpreted is controlled by the times_are_ha parameter. times_are_ha=True by default and you should always use this. If times_are_ha=False, the data are also interpreted as radians and then scaled by a factor SIDEREAL_DAY_SECONDS / SOLAR_DAY_SECONDS. That code branch is not understood and likely an incorrect remnant of the past. Do NOT use it. TODO: parameter should be renamed hour_angles, and the times_are_ha=False branch should be removed.

  • frequency (ndarray) – One-dimensional numpy array containing channel centre frequencies in Hz.

  • phasecentre (astropy.coordinates.SkyCoord) – Phase centre coordinates as a SkyCoord object.

  • channel_bandwidth (ndarray) – One-dimensional numpy array containing channel bandwidths in Hz. Must have the same length as frequency.

  • weight (float, optional) – Default weight for valid data: data associated with autocorrelation baselines (ant1 == ant2) are zero-weighted, the rest are weighted by this value. TODO: some processing code might be designed around the assumption that weights should be in [0, 1]. If so, default weight should be 1.0, and this parameter should be removed.

  • polarisation_frame (PolarisationFrame or None, optional) – Polarisation frame of the output Visibility. If None, select the PolarisationFrame that corresponds to the ReceptorFrame of the array, which is specified inside ‘config’.

  • integration_time (float, optional) – Only used in the specific case where times only has one element. In this case, this will be the integration time associated to this unique time sample in the output Visibility, in seconds.

  • zerow (bool, optional) – If True, forcibly set the output Visibility “w” coordinate to zero at the end of the initialisation process.

  • elevation_limit (float or None, optional) – Elevation limit in radians. When creating the output Visibility, discard any time samples such that the phase centre would appear to be below elevation_limit when observed from the centre of the array. If None, no discarding is performed.

  • source (str, optional) – Source name carried in the attrs of the output Visibility.

  • scan_id (int, optional) – Scan number ID

  • scan_intent (str, optional) – Intent for the scan

  • execblock_id (int, optional) – Execution block ID

  • meta (dict or None, optional) – Optional user-defined metadata that gets stored inside the attrs of the output Visibility.

  • utc_time (astropy.time.Time or None, optional) – Used to convert input hour angles to actual timestamps in the output Visibility. How this is done is described in the notes. If None, this parameter is taken to be 2000-01-01T00:00:00. Default is leaving this to None. The alternative code path is untested.

  • times_are_ha (bool, optional) – Whether to interpret times as hour angles. Leave this to default of True, code path for False suspected incorrect (see times above). TODO: parameter should be removed.

Returns:

Visibility object with its main data array filled with complex double-precision zeros. What its other axes / attributes contain depends on the options provided (see notes below).

Return type:

Visibility

Notes

Input hour angles are converted to a time close to utc_time, the latter being 2000-01-01T00:00:00 by default. First, the code first finds the date of the transit of phasecentre that occurs nearest to utc_time; from there, it finds the times nearest to this transit time such that the phasecentre was seen under the input hour angles from the centre of the interferometer array. These are the timestamps of the output visibilities. Why things have been implemented that way is likely because it makes calculating accurate (u, v, w) easier. Setting the date to 1 Jan 2000 avoids discrepancies between apparent and mean coordinates, since that makes effects from the Earth’s precession/nutation negligible. See: https://en.wikipedia.org/wiki/Apparent_place

The output Visibility contains at most one time sample per entry in the times array. It may contain fewer time samples if elevation_limit was specified.

Integration times in the output Visibility are set to the difference between the consecutive timestamps of each visibility time sample, except when there is only one time sample in the output; in this case the value of integration_time is used.

Data corresponding to autocorrelation baselines (ant1 == ant2) are both flagged and zero-weighted in the output Visibility.