MID REST API

These docs are generated from the OpenAPI specification for the application. There is an issue with the RTD plugin which means the response types are not rendered. To see the API response bodies for the status codes listed below see the Swagger UI: https://k8s.stfc.skao.int/integration-ska-ost-senscalc-ui/senscalc/api/v<MAJOR_VERSION>/mid/ui/

GET /subarrays

Returns the array configurations available

Status Codes:

200 OK – Successful response with the list of array configurations.

GET /continuum/calculate

Calculates an integration time in seconds given a target sensitivity (or vice-versa) for the continuum mode. The result contains a continuum calculation for the full window, a spectral line calculation, weighting parameters for the continuum and line spectral modes and weighted results.

Query Parameters:

rx_band (string) – Enumeration of the receiver bands available for MID. Band 5a and 5b are not available for subarrays that include 13.5-m antennas (n_meer > 0). (Required)
subarray_configuration (string) – The enumerated option for the array configuration to use to perform the calculation. To define a custom configuration, set n_ska and n_meer and do not set this parameter.
n_ska (integer) – Number of 15-m antennas in the custom subarray. If set, n_meer must also be set and subarray_configuration should not be set.
n_meer (integer) – Number of 13.5-m antennas in the custom subarray. If set, n_ska must also be set and subarray_configuration should not be set.
integration_time_s (number) – The integration time of the observation in seconds. Should only be specified when calculating sensitivity and sensitivity parameter is not specified.
supplied_sensitivity (number) – The sensitivity of the observation. Should only be specified when calculating integration time and integration_time_s parameter is not specified.
sensitivity_unit (string) – The sensitivity unit in Jy/beam or K. Should only be specified when supplied sensitivity is specified.
pointing_centre (string) – Pointing centre in HH:MM:SS[.ss] [+|-]DD:MM:SS[.ss] (Required)
freq_centre_hz (number) – Central frequency in Hz. Combined with the bandwidth_mhz, it must define a spectral window that is contained within the rx_band. (Required)
bandwidth_hz (number) – Bandwidth for the continuum observation in Hz. Combined with the freq_centre_hz, it must define a spectral window that is contained within the rx_band. (Required)
spectral_averaging_factor (number) – Factor by which the spectral resolution should be averaged to calculate the effective resolution which is used in the calculation. The allowed values correspond to those offered by the Mid correlator.
n_subbands (integer) – If this parameter is provided, the ‘subbands’ field in the response body will contain a sensitivity result for each sub-band, which is calculated by dividing the bandwidth in N sub-bands. If the value is given as 1 then this is equal to the main sensitivity calculation so no ‘subbands’ are returned in the response. Note: if calculating integration time, subband_supplied_sensitivities must also be set. If subband_supplied_sensitivities is not supplied and this parameter is set and > 1, then subband_supplied_sensitivities is automatically calculated for the range of .n_subbands specified
subband_freq_centres_hz (array) – Central frequency of each sub-band in Hz. Providing sub-band frequencies enables the provision of additional weighting outputs.
subband_supplied_sensitivities (array) – Ordered array of the (thermal) sensitivity (Jy or K) for each sub-band, used when calculating integration time (n_subbands must be set as well and have the same number of elements if this is specified).
weighting_mode (string) – Enumeration of the weighting strategy used. (Required)
robustness (number) – Robust parameter. Only required and considered if the weighting is set to robust.
taper (number) – Gaussian taper (specified as arcseconds in image plane). No taper applied if left empty.
pwv (number) – Precipitable water vapour in mm.
el (number) – Elevation of the target that the observation will be performed at.
eta_system (number) – System efficiency. If provided, will be used instead of calculating it from eta_pointing, eta_coherence, eta_digitisation, eta_bandpass and eta_correlation
eta_pointing (number) – Pointing efficiency
eta_coherence (number) – Coherence efficiency
eta_digitisation (number) – Digitisation efficiency
eta_correlation (number) – Correlation efficiency
eta_bandpass (number) – Bandpass efficiency
t_sys_ska (number) – System Temperature of the 15-m antennas (K)
t_rx_ska (number) – Receiver Temperature of the 15-m antennas (K)
t_spl_ska (number) – Spillover Temperature of the 15-m antennas (K)
t_sys_meer (number) – System Temperature of the 13.5-m antennas (K)
t_rx_meer (number) – Receiver Temperature of the 13.5-m antennas (K)
t_spl_meer (number) – Spillover Temperature of the 13.5-m antennas (K)
t_sky_ska (number) – Sky temperature for 15-m antennas (K)
t_sky_meer (number) – Sky temperature for 13.5-m antennas (K)
t_gal_ska (number) – Galactic temperature for 15-m antennas (K)
t_gal_meer (number) – Galactic temperature for 13.5-m antennas (K)
alpha (number) – Spectral index of Galactic emission
eta_meer (number) – Dish efficiency for 13.5-m antennas
eta_ska (number) – Dish efficiency for 15-m antennas

Status Codes:

200 OK – Successful response with the results of the integration time or sensitivity calculation for continuum mode.
400 Bad Request – Request parameters failed validation, either against the OpenAPI spec or the domain specific validation,eg the spectral window not lying within the allowed range.
5XX – An error occurred making the calculation

GET /zoom/calculate

Calculates an integration time in seconds given a target sensitivity (or vice-versa) for the zoom mode. The result contains a spectral line sensitivity/integration time calculation, spectral (line) weighting parameters (e.g. beam-size and relative sensitivity), and weighted calculation (where applicable) for the given zoom window. Zoom modes are only available for the AA*, AA4 and custom subarrays (defined by n_ska and n_meer).

Query Parameters:

rx_band (string) – Enumeration of the receiver bands available for MID. Band 5a and 5b are not available for subarrays that include 13.5-m antennas (n_meer > 0). (Required)
subarray_configuration (string) – The enumerated option for the array configuration to use to perform the calculation. To define a custom configuration, set n_ska and n_meer and do not set this parameter.
n_ska (integer) – Number of 15-m antennas in the custom subarray. If set, n_meer must also be set and subarray_configuration should not be set.
n_meer (integer) – Number of 13.5-m antennas in the custom subarray. If set, n_ska must also be set and subarray_configuration should not be set.
integration_time_s (number) – The integration time of the observation in seconds. Should only be specified when calculating sensitivity and sensitivities parameter is not specified.
supplied_sensitivities (array) – Array of zoom sensitivities. This provides additional outputs for line observations (spectral_resolutions_hz and freq_centres_hz must be set as well and have the same number of elements). Should only be specified when calculating integration time and integration_time_s parameter is not specified.
sensitivity_unit (string) – The sensitivity unit in Jy/beam or K. Should only be specified when calculating integration time and supplied_sensitivities specified.
pointing_centre (string) – Pointing centre in HH:MM:SS[.ss] [+|-]DD:MM:SS[.ss] (Required)
freq_centres_hz (array) – Array of central frequency of zoom windows in Hz. Combined with the total_bandwidths_hz, each must define a spectral window that is contained within the rx_band. (Required)
spectral_resolutions_hz (array) – Array of zoom spectral resolutions. freq_centres_hz must be set as well and have the same number of elements. Validation only checks that the entered spectral resolution lies within the range defined by the narrowest and widest zoom windows, not that the entered spectral resolution corresponds to an actual zoom window. (Required)
total_bandwidths_hz (array) – Array of zoom total bandwidths for each zoom window. Combined with the freq_centre_hz, each must define a spectral window that is contained within the rx_band. Validation only checks that the entered bandwidth lies within the range defined by the narrowest and widest zoom windows, not that the entered bandwidth corresponds to an actual zoom window. (Required)
spectral_averaging_factor (number) – Factor by which the spectral resolution should be averaged to calculate the effective resolution which is used in the calculation. The allowed values correspond to those offered by the Mid correlator.
weighting_mode (string) – Enumeration of the weighting strategy used. (Required)
robustness (number) – Robust parameter. Only required and considered if the weighting is set to robust.
taper (number) – Gaussian taper (specified as arcseconds in image plane). No taper applied if left empty.
pwv (number) – Precipitable water vapour in mm.
el (number) – Elevation of the target that the observation will be performed at.
eta_system (number) – System efficiency. If provided, will be used instead of calculating it from eta_pointing, eta_coherence, eta_digitisation, eta_bandpass and eta_correlation
eta_pointing (number) – Pointing efficiency
eta_coherence (number) – Coherence efficiency
eta_digitisation (number) – Digitisation efficiency
eta_correlation (number) – Correlation efficiency
eta_bandpass (number) – Bandpass efficiency
t_sys_ska (number) – System Temperature of the 15-m antennas (K)
t_rx_ska (number) – Receiver Temperature of the 15-m antennas (K)
t_spl_ska (number) – Spillover Temperature of the 15-m antennas (K)
t_sys_meer (number) – System Temperature of the 13.5-m antennas (K)
t_rx_meer (number) – Receiver Temperature of the 13.5-m antennas (K)
t_spl_meer (number) – Spillover Temperature of the 13.5-m antennas (K)
t_sky_ska (number) – Sky temperature for 15-m antennas (K)
t_sky_meer (number) – Sky temperature for 13.5-m antennas (K)
t_gal_ska (number) – Galactic temperature for 15-m antennas (K)
t_gal_meer (number) – Galactic temperature for 13.5-m antennas (K)
alpha (number) – Spectral index of Galactic emission
eta_meer (number) – Dish efficiency for 13.5-m antennas
eta_ska (number) – Dish efficiency for 15-m antennas

Status Codes:

200 OK – Successful response with the results of the integration time or sensitivity calculation for zoom mode.
400 Bad Request – Request parameters failed validation, either against the OpenAPI spec or the domain specific validation,eg the spectral window not lying within the allowed range.
5XX – An error occurred making the calculation

GET /pss/calculate

Calculates a target sensitivity for the PSS mode given an integration time in seconds.

Query Parameters:

rx_band (string) – Enumeration of the receiver bands available for MID. Band 5a and 5b are not available for subarrays that include 13.5-m antennas (n_meer > 0). (Required)
subarray_configuration (string) – The enumerated option for the array configuration to use to perform the calculation. To define a custom configuration, set n_ska and n_meer and do not set this parameter. (Required)
integration_time_s (number) – The integration time of the observation in seconds. Should only be specified when calculating sensitivity and sensitivity parameter is not specified.
pointing_centre (string) – Pointing centre in HH:MM:SS[.ss] [+|-]DD:MM:SS[.ss] (Required)
freq_centre_hz (number) – Central frequency in Hz. Combined with the bandwidth_hz, it must define a spectral window that is contained within the rx_band. (Required)
bandwidth_hz (number) – Bandwidth for the PSS observation in Hz. Combined with the freq_centre_hz, it must define a spectral window that is contained within the rx_band.
dm (number) – Dispersion Measure in pc/cm^3
intrinsic_pulse_width (number) – Intrinsic pulse width in milliseconds. If pulsar_mode is folded pulse, this must be less than the pulse period.
pulse_period (number) – Pulse period in milliseconds. This parameter is ignored if pulsar_mode is single_pulse.
pulsar_mode (string) – Sensitivity calculation type. Must be one of folded_pulse or single_pulse. (Required)
pwv (number) – Precipitable water vapour in mm.
el (number) – Elevation of the target that the observation will be performed at.
eta_system (number) – System efficiency. If provided, will be used instead of calculating it from eta_pointing, eta_coherence, eta_digitisation, eta_bandpass and eta_correlation
eta_pointing (number) – Pointing efficiency
eta_coherence (number) – Coherence efficiency
eta_digitisation (number) – Digitisation efficiency
eta_correlation (number) – Correlation efficiency
eta_bandpass (number) – Bandpass efficiency
t_sys_ska (number) – System Temperature of the 15-m antennas (K)
t_rx_ska (number) – Receiver Temperature of the 15-m antennas (K)
t_spl_ska (number) – Spillover Temperature of the 15-m antennas (K)
t_sys_meer (number) – System Temperature of the 13.5-m antennas (K)
t_rx_meer (number) – Receiver Temperature of the 13.5-m antennas (K)
t_spl_meer (number) – Spillover Temperature of the 13.5-m antennas (K)
t_sky_ska (number) – Sky temperature for 15-m antennas (K)
t_sky_meer (number) – Sky temperature for 13.5-m antennas (K)
t_gal_ska (number) – Galactic temperature for 15-m antennas (K)
t_gal_meer (number) – Galactic temperature for 13.5-m antennas (K)
alpha (number) – Spectral index of Galactic emission
eta_meer (number) – Dish efficiency for 13.5-m antennas
eta_ska (number) – Dish efficiency for 15-m antennas

Status Codes:

200 OK – Successful response with the results of the folded_pulse_sensitivity or single_pulse_sensitivity calculation for PSS mode.
400 Bad Request – Request parameters failed validation, either against the OpenAPI spec or the domain specific validation,eg the spectral window not lying within the allowed range.
5XX – An error occurred making the calculation