Simple Spectral Access (SSA) Service
Overview
The Simple Spectral Access (SSA) service provides a Virtual Observatory (VO) compliant standard interface to query and access spectroscopic data hosted at Data Central.
Queries may be submitted through an HTTP GET request to the service. Results of the query are returned in VOTABLE format that includes spectra metadata and links to spectra.
Access to the SSA service is provided via a synchronous web resource available from the following link:
- Interface to send queries: https://datacentral.org.au/vo/ssa/query
The implementation meets the requirements of the SSA Version 1.1 specifications.
The SSA Examples page contains details of more advanced usage of the SIA service (e.g. access from Python).
Workflow
The intended workflow of the SSA service is as follows:
- The user supplies an HTTP GET query to the query interface URL.
- A query is performed using the query parameters, producing a list of available spectra.
- If the POS parameter is specified, the results are ordered in increasing distance from the position
- A VOTABLE with the query results is returned with each row containing an access_url link.
- The access_url is a Datalink-enabled service that returns a spectrum (on request) for each result.
In many cases, the spectrum from access_url is actually a simplified 1D spectrum that is extracted from an original multi-extension file.
The original file may be retrieved using the url in the full_data_url column of the VOTABLE output.
Query Parameters
The following parameters are supported. The only required parameter is REQUEST, so each query requires REQUEST=queryData to be added to the URL. However, if you are using pyvo to access the SSA service, this is not required since this is handled internally.
This means that it is possible to submit queries that are not cone searches based on positions.
Unlike SIA, multiple values for each parameter are not permissible, however some parameters may allow lists of values to be specified.
Example values are listed below and usage is elaborated further below with example queries.
Having trouble viewing this table? It's best viewed in Firefox.
A PDF of the table is available to download here.
| Parameter | Description | Format | Units/Default value | Example values |
|---|---|---|---|---|
| REQUEST | The request or operation name | string | REQUEST=queryData is mandatory for all queries. | |
| POS | The centre of the region of interest specified as ra,dec in decimal degrees (ICRS 2000). Reference frame format modifier is not supported. | ra,dec | degrees | POS=52,-27.8 |
| SIZE | The diameter of the circular region of interest in decimal degrees. | double | degrees | SIZE=0.1 |
| BAND | A single wavelength or wavelength range of interest. Filter names are not supported (e.g. BAND=J), but see the FILTER parameter below (applicable to some spectra). Qualifiers of ;source or ;observer are not supported. | single value or range | metres | BAND in metres as either a single value (e.g. BAND=550e-9) or a range (e.g. BAND=1e-7/3e-6). The latter may also be specified as "/" (all wavelengths), "550e-9/" (wavelengths >= 550nm) or "/550e-9" (wavelengths <= 550 nm). |
| BANDREST | Same as BAND, but operates on the rest wavelength frame of the spectra. This only applies to spectra with defined redshifts. | single value or range | metres | BANDREST in metres as either a single value (e.g. BANDREST=550e-9) or a range (e.g. BANDREST=1e-7/3e-6). The latter may also be specified as "/" (all wavelengths), "550e-9/" (wavelengths >= 550nm) or "/550e-9" (wavelengths <= 550 nm). |
| TIME | A single time or time range of interest. | single value or range | A single time in format yyyy, yyyy-mm, yyyy-mm-dd or yyyy-mm-ddThh:mm:ss. May also be specified as a range, e.g. "/" (all time), "yyyy-mm-dd/yyyy-mm-dd (spectrum overlaps date range)", "yyyy-mm-dd/" (spectra taken >= yyyy-mm-dd) or "/yyyy-mm-dd" (spectra taken <= yyyy-mm-dd). | |
| TIMEMJD | The Modified Julian Date (MJD) in days. Can be used to filter using only MJD, rather than the date formats of the TIME parameter. | string | d | Can be either a single number (e.g. TIMEMJD=55063), matching spectra that overlaps the date, or as a range (e.g. TIMEMJD=55062.1/55064.3). The latter may also be specified as "/" (all time), "55062.1/" (MJD >= 55062.1) or "/55064.3" (MJD <= 55064.3). |
| FORMAT | Desired format of the retrieved data in a comma separated list. Supported values include application/x-votable+xml, application/fits, application/xml, votable, fits and metadata. | FORMAT=fits; FORMAT=FITS; FORMAT=application/fits; FORMAT=APPLICATION/FITS; FORMAT=votable; FORMAT=metadata; FORMAT=METADATA | ||
| SPECRP | The spectrum resolving power (Lambda/Delta Lambda). | double | Specified as a single number, e.g. SPECRP=12000, such that em_res_power >= 12000 or em_res_power_min >= 12000, where em_res_power and em_res_power_min are the relevant obscore parameters. | |
| SNR | The minimum signal-to-noise ratio. | double | Specified as a single number, e.g. SNR=20, such that em_snr > 20, where em_snr is the relevant obscore parameter. | |
| RV | The radial velocity. | double as a range | Specified as a range, e.g. "/" (all rvs), "100/" (rv >= 100 km/s) or "/50" (rv <= 50 km/s), where rv is the relevant custom obscore parameter. | |
| REDSHIFT | The redshift. | double as a range | Specified as a range, e.g. "/" (all redshifts), "1.2/" (redshift >= 1.2) or "/2" (redshift <= 2), where redshift is the relevant custom obscore parameter. | |
| TARGETNAME | The name of the target | string | Matches the obscore parameters target_name or alt_target_name. | |
| FLUXCALIB | Specifies the minimum level of flux calibration. | string | FLUXCALIB=absolute; FLUXCALIB=relative; FLUXCALIB=normalized; FLUXCALIB=any | |
| WAVECALIB | Specifies the minimum level of spectral coordinate calibration. | string | WAVECALIB=absolute; WAVECALIB=relative; WAVECALIB=any | |
| PUBDID | The IVOA publisher dataset identifier, assigned by the publisher of a dataset. | string | ||
| CREATORDID | The IVOA dataset identifier. | string | ||
| COLLECTION | The collection the spectra belong to. The format is the survey name, followed by "_" and the data release identifier. | string | COLLECTION=gama_dr2; COLLECTION=ozdes_dr2; COLLECTION=6dfgs_fdr; COLLECTION=galah_dr3; COLLECTION=2dfgs_fdr; COLLECTION=wigglez_final | |
| SUBCOLLECTION | The subcollection the spectra belong to. Added to allow differentiation between datasets belonging to an individual COLLECTION. | string | Mostly applicable if COLLECTION=gama_dr2, in which case: SUBCOLLECTION=2dfgrs;SUBCOLLECTION=2qz;SUBCOLLECTION=2slaq-lrg;SUBCOLLECTION=2slaq-qso;SUBCOLLECTION=6dfgs;SUBCOLLECTION=gama;SUBCOLLECTION=gama_lt;SUBCOLLECTION=mgc;SUBCOLLECTION=sdss;SUBCOLLECTION=wigglez | |
| TOP | Limits the number of returned records in the query response table to the specified number of top ranking ones. Since we order the output results by those nearest to the query position, we treat this parameter exactly like MAXREC (see below). | integer | TOP=50 | |
| MAXREC | The maximum number of records to be returned. | integer | MAXREC=100 | |
| CALIB | Calibration level of the data. Integer value of 0, 1, 2, 3 or 4. Briefly the calibration levels specify: internal format (0), standard format (1), science ready (2), enhanced science product (3) and analysis product (4). Most spectra belong to 2, but some stacked from multiple exposures are 3 (see also DPSUBTYPE below). | integer | CALIB=3 | |
| DPSUBTYPE | The dataproduct subtype of the spectrum. Either "science" or "combined" for stacked spectra. | string | DPSUBTYPE=science; DPSUBTYPE=combined | |
| EXPTIME | The minimum exposure time of the spectrum in seconds. Specified as a single number. | double | EXPTIME=1200, implies t_exptime >= 1200, where t_exptime is the relevant obscore parameter. | |
| FACILITY | The facility name used to take the spectrum. | string | FACILITY=AAT | |
| FILTER | Filter description for the spectrum. In some surveys this parameter denotes a shorthand to a filter that would describe the wavelength range of the spectrum (e.g. 6dfgs_fdr and galah_dr3). | string | For 6dfgs_fdr: FILTER=V; FILTER=R; FILTER=VR. For galah_dr3: FILTER=B; FILTER=V; FILTER=R; FILTER=I. | |
| FOV | The field-of-view (aperture size) in degrees used to obtain the spectrum, e.g. fibre diameter for MOS spectra or longslit width for longslit spectra, specified as a range. | string | degrees | e.g. FOV=/ (all sizes), FOV=a/ (s_fov >= a), FOV=/b (s_fov <= b), FOV=a/b (a <= s_fov <= b). Here s_fov is the obscore parameter of interest. |
| INSTRUMENT | The instrument name used to take the spectrum. | |||
| ISBEST | Boolean parameter whether the spectrum is the best available in a given COLLECTION. Acceptable values include 1, T, True or 0, F, False. | Boolean | ISBEST=T | |
| NEPOCHS | The minimum number of observations (epochs) for a spectrum. | integer | NEPOCHS=5 implies that t_xel >= 5, where t_xel is the relevant obscore parameter. | |
| PROPOSAL | Proposal code of the corresponding telescope proposal under which the spectra were taken. | string | ||
| RESOLUTION | The maximum resolution (full-width at half-maximum) of the spectrum in metres. | double | metres | e.g. a maximum resolution of 2.0 Angstrom (FWHM) would be RESOLUTION=2.0E-10, such that em_resolution <= 2.0E-10, where em_resolution is the relevant obscore parameter. |
| TIMERES | The minimum time resolution in seconds. | double | seconds | e.g. TIMERES=60 implies that t_resolution >= 60, where t_resolution is the relevant obscore parameter. |
| SEEING | The maximum seeing at the time of observation in arcsec. | double | arcsec | e.g. SEEING=1.5, implies that s_seeing <= 1.5, where s_seeing is our custom obscore parameter. |
Controlling the number of returned results
A default limit of 1000 results is in place to ensure results are returned in a timely manner.
Please note that this is a soft limit that can be superseded by specifying a higher number using the MAXREC or TOP parameters. To obtain results more quickly you can alternatively set MAXREC or TOP to a number less than 1000.
If the number passed using MAXREC or TOP exceeds the hard limit of 200000, then only 200000 results will be returned. A query of 200000 results will take around 12 minutes to complete.
A workaround to this limit is to perform multiple smaller SSA queries and combine the results together. The SSA Examples page contains some basic examples that combine separate target name or position queries together.
An important note about the two types of spectra available
The VOTable results include links to spectra either using the access_url or full_data_url.
Either may be used to access the spectrum of the object of interest.
Please note the following:
- The access_url links to a simplified one-dimensional spectrum that is readable by all clients.
- The full_data_url links to the original spectrum file that the access_url spectrum was extracted from.
Note that several surveys choose to store their data in formats that are either non-standard or peculiar in some way.
These formats may not be easily read by all clients (e.g. IRAF) and may consist of several fits extensions. These extensions often contain additional observations of an object such as a new observation taken at a later time or an observation covering a different wavelength range. In some cases these extensions may even include imaging data.
For these reasons, the spectra hosted by Data Central have been parsed using specialised loaders that form part of the specutils package. The access_url is then the result of converting these individually parsed spectra to a standard one-dimensional spectrum.
During this parsing process, the metadata relating to each spectrum is stored and returned in the various columns found in the VOTable results of the SSA query. Please note that as a result of this process each spectrum obtained from the access_url has a minimal fits header (see FITS FORMAT below for more details).
Should the user want to directly access additional information not contained in the metadata of the VOTable results, the original spectrum is accessible from the full_data_url. The user may then use other tools, e.g. the FV program or the specutils loaders to parse the original spectrum.
FITS FORMAT
&RESPONSEFORMAT=fits / FORMAT=fits
Please note that by default the default format of the access_url and full_data_url links are a VOTable.
(This was chosen to ensure spectra could be sent from TOPCAT to SPLAT: see the SSA Examples page for details).
This second VOTable contains the link to the FITS data in its access_url column.
In order to retrieve a FITS spectrum DIRECTLY from these links, you will need to do one of the following:
- Add the FORMAT=fits parameter to the SSA query URL (recommended). This adds &RESPONSEFORMAT=fits to each access_url or full_data_url
- Alternatively, append "&RESPONSEFORMAT=fits" manually to the access_url or full_data_url links.
The SSA Examples page contains many examples that demonstrate how to do option (2) from Python.
We recommend adding FORMAT=fits to the SSA query to retrieve spectra in FITS format.
FITS Header keywords added by Data Central
The one-dimensional spectra accessed via the access_url do not retain all the FITS header keywords from the original files (accessible from the full_data_url).
To remedy this we add the following FITS header keywords obtained from several obscore parameters (see Output VOTable Columns below for more details).
Note that the FITS header keyword comment for each parameter features " , added by DC".
| FITS Header Keyword | Obscore Parameter |
|---|---|
| RA | s_ra |
| DEC | s_dec |
| OBJECT | target_name |
| SURVEY | obs_collection |
| Z | redshift |
| RV | rv |
| TMIN | t_min |
| TMAX | t_max |
| TMID | t_midpoint |
| EXPTIME | t_exptime |
| TXEL | t_xel |
| BAND | band_name |
| SEEING | s_seeing |
| WMIN | em_min (converted to Angstrom) |
| WMAX | em_max (converted to Angstrom) |
| WMID | em_midpoint (converted to Angstrom) |
| WMINREST | em_min_rest (converted to Angstrom) |
| WMAXREST | em_max_rest (converted to Angstrom) |
| WMIDREST | em_midpoint_rest (converted to Angstrom) |
| FOV | s_fov (converted to arcsec) |
Unsupported Query Parameters
The following parameters are not currently supported by the SSA service.
| Parameter | Description |
|---|---|
| APERTURE | Aperture to extract (used by spectral extraction services only) |
| SPATRES | Spatial resolution (but see FOV parameter above) |
| VARAMPL | Variability Amplitude |
| TARGETCLASS | Class of target |
| MTIME | Modification time |
| COMPRESS | Return data in compressed form |
| RUNID | Request job identifier |
Output VOTable Columns
The VOTABLE includes tabular data in the TABLEDATA element. Each column represents a different ObsCore parameter, but there may be additional custom parameters.
A summary of the most important columns may be found below.
For all others please consult the ObsCore documentation.
Having trouble viewing this table? It's best viewed in Firefox.
A PDF of the table is available to download here.
| Parameter | Description | Units/Default value |
|---|---|---|
| score | Distance from the requested position in arcsec. Score used to sort query results in ascending order. | arcsec |
| dataproduct_type | The type of the dataproduct | |
| dataproduct_subtype | The subtype of the dataproduct | |
| calib_level | Calibration level of the dataproduct | |
| target_name | Target name | |
| alt_target_name | Alternative target name | |
| obs_id | Unique internal identifier | |
| obs_collection | Name of the data collection | |
| obs_subcollection | Sub group of the obs_collection | |
| obs_publisher_did | IVOA dataset identifier given by the creator | |
| access_url | URL to the requested spectrum | |
| access_format | Content format of the dataset | |
| access_estsize | Estimated size of dataset in kilobytes | kbyte |
| full_data_url | Link to full data file (e.g. original ingested spectrum) | |
| s_ra | Right ascension in decimal degrees | deg |
| s_dec | Declination in decimal degrees | deg |
| s_fov | Approximate diameter of region covered by data in decimal degrees | deg |
| s_region | Sky region covered by the data product | deg |
| s_resolution | Spatial resolution in arcsec (PSF FWHM) | arcsec |
| s_seeing | Average seeing in arcsec at the time of observation (FWHM) | arcsec |
| s_xel1 | Number of elements along the first coordinate of the spatial axis | |
| s_xel2 | Number of elements along the second coordinate of the spatial axis | |
| t_min | Start time of observation as Modified Julian Date (MJD) | d |
| t_max | End time of observations as Modified Julian Date (MJD) | d |
| t_midpoint | Midpoint of exposure in MJD | d |
| t_exptime | Exposure time in seconds | s |
| t_resolution | Time resolution in seconds (FWHM) | s |
| t_xel | Number of elements along the time axis | |
| em_min | Start wavelength of spectral coordinate in metres | m |
| em_max | End wavelength of spectral coordinate in metres | m |
| em_midpoint | Midpoint of spectral coordinate range | m |
| em_res_power | Spectral resolving power (R) | |
| em_res_power_min | Minimum spectral resolving power | |
| em_res_power_max | Maximum spectral resolving power | |
| em_xel | Number of elements along the spectral axis | |
| instrument_name | Instrument name | |
| facility_name | Facility name | |
| band_name | Name of the band or filter | |
| rv | The measured radial velocity | km/s |
| redshift | The measured heliocentric redshift | |
| em_min_rest | Start wavelength of spectral coordinate in metres in the rest frame | m |
| em_max_rest | End wavelength of spectral coordinate in metres in the rest frame | m |
| em_midpoint_rest | Midpoint of spectral coordinate range in the rest frame | m |
| is_best | Whether the spectrum is the best available or not | |
| em_snr | The measured signal to noise ratio of the spectrum | |
| o_ucd | Nature of the observable axis | |
| pol_xel | Number of elements along the polarization axis | |
| obs_title | Brief description of the dataset | |
| obs_creation_date | Date the dataset was created | |
| obs_creator_name | Name of the creator of the data | |
| obs_creator_did | IVOA dataset identifier given by the creator | |
| obs_release_date | Observation release date | |
| proposal_id | Identifier of proposal to which observation belongs | |
| publisher_id | IVOA dataset identifier for the publisher | |
| bib_reference | Service bibliographic reference | |
| data_rights | Public/Secure/Proprietary | |
| s_ucd | UCD for the nature of the spatial axis | |
| s_unit | Unit used for spatial axis | |
| s_resolution_min | Minimum spatial resolution in arcsec | arcsec |
| s_resolution_max | Maximum spatial resolution in arcsec | arcsec |
| s_calib_status | Type of calibration along the spatial axis | |
| s_stat_error | Astrometric precision along the spatial axis in arcsec | arcsec |
| s_pixel_scale | Sampling period in world coordinate units along the spatial axis in arcsec | arcsec |
| t_refpos | Time Axis Reference Position | |
| t_calib_status | Type of time coordinate calibration | |
| t_stat_error | Time coordinate statistical error in seconds | s |
| em_ucd | Nature of the spectral axis | |
| em_unit | Units along the spectral axis | |
| em_calib_status | Type of spectral coordinate calibration | |
| em_res_power_min | Minimum spectral resolving power | |
| em_res_power_max | Maximum spectral resolving power | |
| em_resolution | Spectral resolution in metres | m |
| em_stat_error | Spectral coordinate statistical error in metres | m |
| o_unit | Units used for the observable values | |
| o_calib_status | Type of calibration for the observable coordinate | |
| o_stat_error | Statistical error on the observable axis | o_unit |
| pol_states | List of polarization states present with a space between each state | |
| data_model | Datamodel name and version | |
| data_length | Number of points in spectrum | |
| sov_id | The DataCentral ID needed to access the object in the Single Object Viewer |
Some simple example queries
Query wigglez spectra above redshift=2.0 and only return 100 results:
Repeat the query requesting spectra in FITS format:
Query 6dFgs spectra only around RA=55 deg, DEC=-29.1 deg in a circle of 0.4 deg diameter and only the combined VR spectra:
https://datacentral.org.au/vo/ssa/query?POS=55,-29.1&SIZE=0.4&COLLECTION=6dfgs_fdr&FILTER=VR&REQUEST=queryData
Retrieve 100 results from the 6dF Galaxy Survey where the redshift is greater than 0.5:
Retrieve 100 results from the 6dF Galaxy Survey but only for the combined VR spectra:
https://datacentral.org.au/vo/ssa/query?MAXREC=100&COLLECTION=6dfgs_fdr&FILTER=VR&REQUEST=queryData
Retrieve Liverpool Telescope observations from GAMA DR2:
https://datacentral.org.au/vo/ssa/query?COLLECTION=gama_dr2&SUBCOLLECTION=gama_lt&REQUEST=queryData
Retrieve Wigglez spectra whose rest wavelength coverage includes 3000 A:
https://datacentral.org.au/vo/ssa/query?COLLECTION=wigglez_final&BANDREST=3000e-10&REQUEST=queryData
Retrieve combined (stacked) OzDES spectra whose rest wavelength coverage includes 3000 A:
Limitations of the current implementation
- There are some notable differences between the SSA service and the DataCentral SIA2 service. For example, the availability and capabilities endpoints are not defined for SSA, and submitting multiple values of SSA parameters are not permitted. These differences are mostly due to the specifications for SSA being older than SIA.
- We have given a preference to using the ObsCore data model over the Spectral data model when it comes to specifying data model element identifiers (utypes).
- The focus of this implementation is to provide plenty of parameters to filter query results. We have endeavoured to be compliant with the mandatory requirements of the SSA specifications, but there may be aspects that still need improvement.
- The default output of the SSA service is a VOTable and this may confuse users trying to access only FITS format data. See the section FITS FORMAT above for more details.
- We do not currently offer access to the ObsCore metadata (e.g. via an ObsTAP service). Implementing this is under investigation and may change in the future.
- We welcome constructive bug reports and feature suggestions on to improve this service.