not logged in login | register
Docs:
Note! We changed the SOAP object model according to the preliminary IVOA SED Object Model described in the following proposal: http://hea-www.harvard.edu/~jcm/vo/docs/spec.html Further changes are possible. The documentation below is obsolete.
Using this website and web service, you can search and manage spectra of spatial objects from different survey catalogs. Version 1.x allows you to post your own spectra (after registration) and search the spectra in the database by several criteria.
The spectrum webservices use the SOAP standard to communicate with the clients. Some of the functions can be called via HTTP POST and HTTP GET as well. We provide several versions of each function to access our database in your favourite format. We support standard SOAP format, VOTable and ASCII.
To learn more about WebServices, visit the following sites: http://msdn.microsoft.com/webservices/ or http://java.sun.com/webservices/ Web service clients and VOTable parsers are also available in Perl, Python etc.
Search service (SOAP XML):
search.asmx
WSDL:
search.asmx?WSDL
Search service (VOTable):
search_votable.asmx
search_votable.asmx?WSDL
Admin service
admin.asmx
admin.asmx?WSDL
Utility service:
util.asmx
util.asmx?WSDL
Since every registered user of our system can post his/her spectra to the database, it is important to identify them not only with login name and password while using the web site, but somehow when accessing the administrative function via webservices. WebServiceId (named UserGUID in the functions) is a global unique identifier, a 36 char string (16 bytes in binary), which is used for this identification purpose.
You can post new spectra only with your WebServiceId, and you can modify or delete only those spectra which were posted by you.
Each spectrum consists of a header and an array of wavelength-value pairs.
1.2.1. Spectrum SOAP object
Implements the spectrum's header
Member name
Data type
Description
Id
int (4)
Database primary key of the spectrum. Set to 0, when you want to create a new spectrum, anyway set to the appropriate Id
Name
string
Name of the spectrum
Long description of the spectrum
Ucd
Universal Content Descriptor
Ra
double (8)
Right ascenation of the object in J2000
Dec
Declination of the object in J2000
Cx
Cy
Cz
HtmId
long (8)
HTM ID of the object
Synthetic
bool
Flag for synthetic or composite spectra
Z
float (4)
Redshift of the spectrum
ZError
Error of redshift of the spectrum
ZStatus
enum
Status of the redshift value following the conventions
ZWarning
Warning flags about the redshift following the conventions used in SDSS
ZCofidence
Confidence of Z value
Class
Class of the spatial object
SurveyID
Identifies the large sky surveys
ObjectID
Original ID of the spatial object in the survey's catalog
DateMeasured
datetime
Date of exposition of the spectrum
DateCreated
Date of registration into the database, read-only
DateModified
Date of the last modification, read-only
WavelengthMin
Minimum of the wavelength interval, read-only, calculated by the service
WavelengthMax
Maximum of the wavelength interval, read-only, calculated by the service
WavelengthScale
Wavelenght scale 0: Linear 1: Logarithmic 2: Other
ValueUnitId
Unit of the values of the spectrum 1: Jy (10e-17 ergs/s/cm^2/A) 2: counts (uncalibrated)
Public
Determines whether the spectrum is accessible by other users than the one who added the spectrum to the database
UserFolder
ID of your 'My Spectra' folder.
Keys
array
An array of Key object containing custom data fields
Points
An array of Point objects to store wavelength-value pairs
1.2.2. Key SOAP object
A name identifying the custom field
Value
The value, which can be either numeric or string
1.2.3. Point SOAP object
Wavelength
The wavelength in Angstroms
The value associated with the wavelength
Error
Error of the value
Mask
Gives extra information about the validity of value at the given wavelength, following the SDSS convetions.
1.2.3. SpectrumGraphParameters object
This object is used with the plot function. Initialize all values before calling the function. Set numeric values to -1 to use default.
width
Width of the image in pixels
height
Height of the image in pixels
wavelengthMin
Minimum value on the x-axis
wavelengthMax
Maximum value on the x-axis
valueMin
Minimum value on the y-axis
valueMax
Maximum value on the y-axis
wavelengthLogBase
Log base on the x-axis
valueLogBase
Log base on the y-axis
titles
Displays title on the graph if true
normalize
Normalizes spectrum to 1 at peak if true
autoLoad
If true, the service loads spectra automatically when a valid SpectrumID is set.
normalizeLimitsStart
float[]
Defines intervals for the spectrum normalizer function. Must be the same size as the normalizeLimitsEnd array.
normalizeLimitsEnd
see above
normalizePower
float
Parameter for the normalizer, varies upon object class
normalizeFactor
restframe
Plots spectra in restframe
emLines
Displays emission lines
SpectrumAdmin Service is for registered users and the functions can be accessed only with a WebServiceId recieved at registration.
Functions
Function name
Parameters
CreateSpectrum
Records a new spectrum header to the database
string UserGUID
Your WebServiceId
string name
string description
string ucd
double ra
double dec
float z
float zError
enum spectrumClass
enum wavelengthScale
Linear = 0 or Logarithmic = 1 or Other = 2
return value int
Returns the database ID of the new spectrum
CreateSpectrumIndirect
Records a new spectrum header to the database, but accepts a standard SOAP Spectrum object as an imput parameter. Can be used from SOAP client only. Also records the SpectrumPoint objects in one step.
object spectrum
Spectrum to record to the database
ModifySpectrum
Modifies an existing spectrum header
int spectrumId
ID of the spectrum to modify
return value bool
Returns true when the spectrum modified successfully, otherwise false
ModifySpectrumIndirect
Modifies an existing spectrum header record. Note! Since a SOAP spectrum object can contain spectrum points, and those can be sent to this method too, you should know that this function does not modify the wavelength-value pairs, only the header info. To modify points, delete them first using the DeleteSpectrumPoints method, and insert the new points with AppendSpectrumPointIndirect.
The spectrum to modify with the new data in a SOAP object. The object's SpectrumId must be specified.
DeleteSpectrum
Deletes a spectrum from the database by it's ID
int id
ID of the spectrum to delete
Returns true when the spectrum deleted successfully, otherwise false
DeleteSpectrumIndirect
Deletes a spectrum from the database by it's ID. Accepts a Spectrum SOAP object as input.
string userGUID
The spectrum to delete in the form of a SOAP object. The object's SpectrumId must be specified.
AppendSpectrumPoint
Appends a wavelength-value pair to a spectrum specified by its Id
Id of the spectrum which the new wavelength-value pair to attach
float wavelength
Wavelength in Angstroms
float response
float error
Error of value
Returns true when the new wavelength-value pair appended successfully, otherwise false
AppendSpectrumPointIndirect
Appends an array of wavelength-value pairs to a spectrum specified by its Id
Id of the spectrum which the new wavelength-response pairs to attach
array responses
An array of wavelength-value pairs in the form of a SOAP array.
Returns true when the new wavelength-value pairs appended successfully, otherwise false
DeleteSpectrumPoints
Deletes all wavelength-value pairs associated with the spectrum
Id of the spectrum whose wavelength-value pairs should be deleted
Returns true when the points deleted succesfully, otherwise false
The Spectrum Search service functions provide functionality to query the spectrum database. There are two versions of this service, one for returning SOAP XML and one for VOTable, which have exactly the same functions.
GetSpectrum GetSpectrumAscii
Returns a Spectrum in different formats. The function can return the header only, or the values too.
Id of the spectrum to return
bool returnPoints
If true, function returns spectrum values too
return value object
The spectrum in a SOAP XML object, VOTable or an ascii string
FindSpectraByKeyword
Performs a LIKE query on the spectra table and returns results as an array of spectra. The search is performed on the following columns of the Spectra table: Name, Description, UCD
return value array
The array of spectra matching the criterium
FindSpectraAdvanced
Returns spectra matching the advanced criteria. The different search conditions are connected with AND. Specify zero string ("") to omit condition with string data type, and -1 for numeric data types.
string keyword
LIKE query in the following columns of the Spectra table: Name, Description, UCD, Version.
LIKE query on the Name column.
LIKE query on the Description column.
LIKE query on the UCD column.
double raFrom
Minimum of ra in J2000
double raTo
Maximum of ra in J2000
double decFrom
Minimum of dec in J2000
double decTo
Maximum of dec in J2000
float zFrom
Minimum of redshift
float zTo
Maximum of redshift
float zErrorFrom
Minimum of error of redshift
float zErrorTo
Maximum of error of redshift
float zConfidenceFrom
Minimum of confidence of redshift
float zCondifdenceTo
Maximum of confidence of redshift
Class of spatial object
int surveyId
ID of the survey in which the spectrum was measured
string dateMeasuredFrom
If specified, the column must be greater than this value.
string dateMeasuredTo
If specified, the column must be less than this value.
string dateCreatedFrom
string dateCreatedTo
string dateModifiedFrom
string dateModifiedTo
double wavelengthMinFrom
double wavelengthMinTo
double wavelengthMaxFrom
double wavelengthMaxTo
Linear = 0 or Logarithmic = 1 or Other = 2 or Any = -1 Specify Any to omit this criterium
int valueUnitId
Restricts search to spectra with the specified flux unit
Array of spactra matching the criteria
FindSpectraAdvancedIndirect
Function works exacly as FindSpectraAdvanced, except it uses a structure as an input instead of the numerous parameters
struct par
Structure of parameters as describer above
Array of spectra matching the criteria
FindSpectraBySqlQuery
Function returns spectra matching the specified SQL query
string sql
A SQL WHERE and ORDER BY clause to run on the Spectra table.
FindSpectraCone
This functions returns spectra of spatial object within the specified cone
Right ascenation in J2000
Declination in J2000
double sr
Angle of the cone in arcmins
FindSpectraRedshift
This function returns spectra of spatial object with redshift in the specified range. Be careful, because a 0.1 interval contains more than 1000 spectra.
Lower limit of redshift
Upper limit of redshift
ResampleSpectra
Resamples the spectrum to a different wavelength interval and scale. The function uses nearest neighbour interpolation at the unknown wavelength values and set the no_data mask outside the measured interval. This operation is required before convolving with filters.
The formula to determine new wavelength values:
Linear resampling: wavelength = start + i * inc Logarithmic resampling: 10^(start + i * inc)
where i goes from 0 to points - 1
array spectra
The spectra objects with filled Points array
enum scale
Linear = 0 or Logarithmic = 1, determines the new scale of the wavelength axis
double start
The new minimum wavelength in the resampled spectrum.
double inc
Incrementum of the resampledspectrum, used in the formula above
int points
Number of points to resample to
double z
The function can redshift spectra to the passed z in one turn. Pass the Z field of the spectrum header to leave the spectrum in the measured redshift, or specify 0 to put into restframe.
Array of the resampled spectra
NormalizeSpectra
This function normalizes spectra in the following way: First step it puts the spectrum into restframe, weights the spectrum's values with a formula described at the WeightSpectra function, normalizes it taking samples from the specified intervals, then runs the Weight function with inverse values.
Array of spectra to normalize in one turn
float[] limitsStart
float []limitsEnd
float power
float factor
Array of the normalized spectra
RedshiftSpectra
Shifts passed spectra to the specified z
Array of spectra to shift
Shift spectra to a new z value. Specify 0 to put into restframe
Array of the shifted spectra
WeightSpectra
Weights the values with the following formula:
value = value * factor * wavelength ^ power;
Array of spectra to weight.
The power parameter of the formula
The factor parameter of the formula
Array of the weighted spectra
ComposeMedianSpectrum
Calculates the median of the passed spectra at all wavelength values in restframe. Returns the composite spectrum.
Array of spectra to generate the composite from
The composite spectrum object
ComposeAverageSpectrum
Calculates the average of the passed spectra at all wavelength values in restframe. Returns the composite spectrum.
PlotSpectraGraph
Generates a graph with the spectrum curves on it. The parameters should be passed in a SpectrumGraphParameters object. It is not nessesary to be the spectra in the database, you can plot your own spectra too. However, if you want to plot spectra that are already in the database, it's enough to post a spectrum header with the SpectrumID field specified and the Points array empty, the service will recognize them and load from the database automatically.
An array of spectrum objects to plot.
A SpectrumGraphParameters structure with the parameters of the graph.
return value bytes
A binary array containing the graph in GIF format. Save it to a file or send to the user interface from your service client application.
Since you can query the spectrum database using SQL query, you should get familiar with the database structure. Our database server uses the T-SQL 92 standard query language, so joins and aggregate function can be used. Text fields are stored in two-byte unicode.
Note! If you use the WebService to return data in a VOTable format, you are allowed to use SELECT [column[, column ...]] format to specify the columns to return. When using the web form or the webservice, but you want the results in a SOAP object format, you always have to use SELECT * (star) instead of a column list.
We implemented a SQL preparser to allow using predefined constants in queries. These constants are detailed at the description of each column in parentheses. All of these constants are upper case!
This table contains spectrum header information
Column name
ID
bigint (8)
Primary key of the Spectra table
nvarchar (255)
ntext
UCD
float (8)
HtmlID
HTM id calculated from the coordinates
bit
real (4)
Redshift of the object
Absolute error of redshift of the object
smallint (2)
ZConfidence
Class of the object 0: Unknown (UNKNOWN) 1: Star (STAR) 2: Galaxy (GALAXY) 3: Qso (QSO) 4: Hiz_Qso (HIZ_QSO) 5: Sky (SKY) 6: Star_Late (STAR_LATE) 7: Gal_Em (GAL_EM) 101: Merger (MERGER) 102: BrightStarHalo (BRIGHTSTARHALO)
ID of the survey from which the spectrum comes. Foreign key to the Surveys table. 1: SDSS DR1 (SDSS) 2: 2dF GRS (2DF) etc.
ID of the object in the original survey catalog
datetime (8)
Date of exposition
Date of registration into the database
Date of last modification
Minimum of the wavelength interval
Maximum of the wavelength interval
Wavelenght scale 0: Linear (LINEAR) 1: Logarithmic (LOGARITHMIC) 2: Other (OTHER)
ValueUnitID
Unit of spectral data. Foreign key to the SpectrumValueUnits table 1: Jy (10e-17 erg/cm^2/s/A) - calibrated 2: counts - uncalibrated
Indices on the Spectra table
Index name
Columns
PK_Spectra
Primary key, Unique
IX_Spectra_HtmID
HtmID
This table contains the spectra's custom key pairs. The SpectrumID column determines the corresponding row in the Spectra table and should be used for join queries. Since each value can be either numeric or textual, use the appropriate field when writing queries. The value type is recognized by the web service and stored in the NumValue or StringValue field, the other field is always NULL.
SpectrumID
Foreign key to the Spectra table
NumValue
Numeric data
StringValue
nvarchar (50)
Textual data, or storing unit if NumValue is not null
Indices on the SpectrumPoints table
FK_SpectrumKeys_Spectra
SpectrumID -> ID
Foreign key
This table contains the spectra's wavelength-value pairs. The SpectrumID column determines the corresponding row in the Spectra table and should be used for join queries. The unit of the values is determined by the ValueUnitID int the Spectra table. Since the database stores uncalibrated spectra too, be sure to use calibrated spectra only (ValueUnitID= 1, Jy) when calculating magnitudes.
Spectrum value. See notes above!
Gives extra information about the validity of value at the given wavelength, following the SDSS convetions. *** more doc needed ***
FK_SpectrumPoints_Spectra
The table contains the common spectrum value units.
Primary key on the table
Text
Written form of the unit
Calibrated
Flag for calibrated values (can be used for magnitude calculation)
Indices on the SpectrumValueUnits table
***
This table contains the name of different surveys from which we loaded spectral data. The table contains only surveys loaded at JHU, other users should use SurveyID = 0.
Name of the survey
fGetNearbyObjEq(@ra float, @dec float, @r float)
Returns SpectraIDs of the objects within an @r arcmin radius of the given point of the sky. ra and dec in J2000.
The following samples illustrate how to use the SQL query interface. You can execute each query by clicking on the execute link.
T-SQL command