Support VO simple spectral access capabilities.
Based on the Simple Spectral Access Protocol 1.04 Recommendation.
Retrieve a set of spectral data defined in the results of a query_data call.
url may either be a string containing a URL or a row from the vo.table array returned by query_data. If the latter, the actual URL used is grabbed from the column named ‘AcRef’. If such a column does not exist, a ValueError is raised.
pedantic has the same meaning as parse(). When pedantic is True, raise an error when the returned VOTable file violates the spec, otherwise issue a warning. Warnings may be controlled using the standard Python mechanisms. See the warnings module in the Python standard library for more information.
mimetype, if provided, will override the type returned from the server. Only use if you know what type of file you expect to be returned.
If the resulting file is:
- a fits file, a pyfits.hdulist object is returned
- a VOTABLE file, a VOTableFile object is returned
- otherwise, a read-only file-like object to the raw data is returned
Return the available simple spectral access catalogs as a list of strings. These can be used for the catalog_db argument to query_data().
Perform a Simple Spectral Access data query on a specified catalog. To get the data itself, use get_data.
catalog_db may be one of the following, in order from easiest to use to most control:
- None: A database of conesearch catalogs is downloaded from STScI. The first catalog in the database to successfully return a result is used.
- catalog name: A name in the database of conesearch catalogs at STScI is used. For a list of acceptable names, see list_catalogs().
- url: The prefix of a url to a IVOA Cone Search Service. Must end in either ? or &.
- A VOSCatalog instance: A specific catalog manually downloaded and selected from the database using the APIs in the vos_catalog module.
- Any of the above 3 options combined in a list, in which case they are tried in order.
pedantic has the same meaning as parse(). When pedantic is True, raise an error when the returned VOTable file violates the spec, otherwise issue a warning. Warnings may be controlled using the standard Python mechanisms. See the warnings module in the Python standard library for more information.
verbose, when True (default), will print information about the services being connected to.
pos: The center of the region of interest. The coordinate values may be specified either as a string or a 2-item sequence. If a string it is passed along to the service verbatim, and must be two numbers in list format (comma separated) with no embedded white space.
pos defaults to right-ascension and declination in decimal degrees in the ICRS coordinate system. A coordinate system reference frame may optionally be specified to specify a coordinate system other than ICRS. This may be the third element of a sequence, or if a string, separated from the two numbers by a semicolon.
size: The diameter of the search region specified in decimal degrees.
band: The spectral bandpass is given in `range-list-format`_, with each list element specified either numerically as a wavelength value or range, or textually as a spectral bandpass identifier, e.g., a filter or instrumental bandpass name. May be either a single value or (for numerical ranges) an open or closed range. Multiple element range-lists are supported by some services. If a single numerical value is specified as a range element it matches any spectrum for which the spectral coverage includes the specified value. If a two valued range is given, a dataset matches if any portion of it overlaps the given spectral region.
For a numerical bandpass, the units are wavelength in vacuum in units of meters. The spectral rest frame may be qualified as either source or observer, using either the last element of the sequence or separated by a semi-colon if given as a string:
band='1E-7/2E-6;source'
For most queries the precision with which the spectral bandpass is specified in the query probably does not matter very much. A rough bandpass broad enough to find all the interesting data will generally suffice; the more precise spectral bandpass specified in the query response for each spectrum can then be used to refine the query. In some cases, for example a cutout service operating upon high resolution spectra, support at the service level for specifying the spectral rest frame could be important. If the service does not support specification of the spectral frame the syntax should be permitted but may be ignored.
time: The time coverage (epoch) specified in `range-list-format`_, in ISO 8601. If the time system used is not specified, UTC is assumed. The value may be a single value or an open or closed range. If a single value is specified, it matches any spectrum for which the time coverage includes the specified value. If a two-valued range is given, a dataset matches if any portion of it overlaps the given temporal region.
Additional kwargs may be provided to pass along to the server. These arguments are specific to the particular catalog being queried. The standard set of optional arguments for SSA includes:
APERTURE, SPECRP, SPATRES, TIMERES, SNR, REDSHIFT, VARAMPL, TARGETNAME, TARGETCLASS, FLUXCALIB, WAVECALIB, PUBDID, CREATORID, COLLECTION, TOP, MAXREC, MTIME, COMPRESS, RUNID