not logged in  
login | register  

Docs:

Documentation
Web Services
FAQs
Downloads
Contact
References

Spectra module

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.

  1. WebService functions
    1. The WebServiceId (UserGUID)
    2. Data structures
    3. Spectrum Admin service functions
    4. Spectrum Search service functions
    5. Spectrum Utility service functions
  2. Database schema
    1. Database tables  
    2. Database functions
    3. Sample SQL queries
  3. Revision history

1. WebService functions

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

WSDL:

search_votable.asmx?WSDL

Admin service

admin.asmx

WSDL:

admin.asmx?WSDL

Utility service:

util.asmx

WSDL:

util.asmx?WSDL

1.1. The WebServiceId (UserGUID)

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.

1.2. Data structures

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

Description

string

Long description of the spectrum

Ucd

string

Universal Content Descriptor

Ra

double (8)

Right ascenation of the object in J2000

Dec

double (8)

Declination of the object in J2000

Cx

double (8)

 

Cy

double (8)

 

Cz

double (8)

 

HtmId

long (8)

HTM ID of the object

Synthetic

bool

Flag for synthetic or composite spectra

Z

float (4)

Redshift of the spectrum

ZError

float (4)

Error of redshift of the spectrum

ZStatus

enum

Status of the redshift value following the conventions

ZWarning

enum

Warning flags about the redshift following the conventions used in SDSS

ZCofidence

float (4)

Confidence of Z value

Class

enum

Class of the spatial object

SurveyID

long (8)

Identifies the large sky surveys

ObjectID

long (8)

Original ID of the spatial object in the survey's catalog

DateMeasured

datetime

Date of exposition of the spectrum

DateCreated

datetime

Date of registration into the database, read-only

DateModified

datetime

Date of the last modification, read-only

WavelengthMin

double (8)

Minimum of the wavelength interval, read-only, calculated by the service

WavelengthMax

double (8)

Maximum of the wavelength interval, read-only, calculated by the service

WavelengthScale

enum

Wavelenght scale
0: Linear
1: Logarithmic
2: Other

ValueUnitId

int (4)

Unit of the values of the spectrum
1: Jy (10e-17 ergs/s/cm^2/A)
2: counts (uncalibrated)

Public

bool

Determines whether the spectrum is accessible by other users than the one who added the spectrum to the database

UserFolder

int (4)

ID of your 'My Spectra' folder.

Keys

array

An array of Key object containing custom data fields

Points

array

An array of Point objects to store wavelength-value pairs

1.2.2. Key SOAP object

Member name

Data type

Description

Name

string

A name identifying the custom field

Value

string

The value, which can be either numeric or string

1.2.3. Point SOAP object

Member name

Data type

Description

Wavelength

float (4)

The wavelength in Angstroms

Value

float (4)

The value associated with the wavelength

Error

float (4)

Error of the value

Mask

enum

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.

Member name

Data type

Description

width

int (4)

Width of the image in pixels

height

int (4)

Height of the image in pixels

wavelengthMin

float (4)

Minimum value on the x-axis

wavelengthMax

float (4)

Maximum value on the x-axis

valueMin

float (4)

Minimum value on the y-axis

valueMax

float (4)

Maximum value on the y-axis

wavelengthLogBase

float (4)

Log base on the x-axis

valueLogBase

float (4)

Log base on the y-axis

titles

bool

Displays title on the graph if true

normalize

bool

Normalizes spectrum to 1 at peak if true

autoLoad

bool

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

float[]

see above

normalizePower

float

Parameter for the normalizer, varies upon object class

normalizeFactor

float

Parameter for the normalizer, varies upon object class

restframe

bool

Plots spectra in restframe

emLines

bool

Displays emission lines

1.3. Spectrum Admin service functions

SpectrumAdmin Service is for registered users and the functions can be accessed only with a WebServiceId recieved at registration.

Functions

Function name

Parameters

Description

CreateSpectrum

Records a new spectrum header to the database

 

string UserGUID

Your WebServiceId

 

string name

Name of the spectrum

 

string description

Long description of the spectrum

 

string ucd

Universal Content Descriptor

 

double ra

Right ascenation of the object in J2000

 

double dec

Declination of the object in J2000

 

float z

Redshift of the spectrum

 

float zError

Error of redshift of the spectrum

 

enum spectrumClass

Class of the spatial object

 

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.

string UserGUID

Your WebServiceId

 

object spectrum

Spectrum to record to the database

 

return value int

Returns the database ID of the new spectrum

ModifySpectrum

Modifies an existing spectrum header

 

int spectrumId

ID of the spectrum to modify

 

string UserGUID

Your WebServiceId

 

string name

Name of the spectrum

 

string description

Long description of the spectrum

 

string ucd

Universal Content Descriptor

 

double ra

Right ascenation of the object in J2000

double dec

Declination of the object in J2000

float z

Redshift of the spectrum

float zError

Error of redshift of the spectrum

enum spectrumClass

Class of the spatial object

 

enum wavelengthScale

Linear = 0 or Logarithmic = 1 or Other = 2

 

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.

 

string UserGUID

Your WebServiceId

 

object spectrum

The spectrum to modify with the new data in a SOAP object. The object's SpectrumId must be specified.

 

return value bool

Returns true when the spectrum modified successfully, otherwise false

DeleteSpectrum

Deletes a spectrum from the database by it's ID

 

string UserGUID

Your WebServiceId

 

int id

ID of the spectrum to delete

 

return value bool

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

Your WebServiceId

 

object spectrum

The spectrum to delete in the form of a SOAP object. The object's SpectrumId must be specified.

 

return value bool

Returns true when the spectrum deleted successfully, otherwise false

AppendSpectrumPoint

Appends a wavelength-value pair to a spectrum specified by its Id

 

string UserGUID

Your WebServiceId

 

int spectrumId

Id of the spectrum which the new wavelength-value pair to attach

 

float wavelength

Wavelength in Angstroms

 

float response

Value

float error

Error of value

 

return value bool

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

 

string UserGUID

Your WebServiceId

 

int spectrumId

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.

 

return value bool

Returns true when the new wavelength-value pairs appended successfully, otherwise false

DeleteSpectrumPoints

Deletes all wavelength-value pairs associated with the spectrum

 

string UserGUID

Your WebServiceId

 

int spectrumId

Id of the spectrum whose wavelength-value pairs should be deleted

 

return value bool

Returns true when the points deleted succesfully, otherwise false

1.4 Spectrum Search service functions

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.

Functions

Function name

Parameters

Description

GetSpectrum
GetSpectrumAscii

Returns a Spectrum in different formats. The function can return the header only, or the values too.

int id

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

bool returnPoints

If true, function returns spectrum values too

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.

string name

LIKE query on the Name column.

string description

LIKE query on the Description column.

string ucd

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

 

enum spectrumClass

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

If specified, the column must be greater than this value.

string dateCreatedTo

If specified, the column must be less than this value.

string dateModifiedFrom

If specified, the column must be greater than this value.

string dateModifiedTo

If specified, the column must be less than this value.

double wavelengthMinFrom

If specified, the column must be greater than this value.

double wavelengthMinTo

If specified, the column must be less than this value.

double wavelengthMaxFrom

If specified, the column must be greater than this value.

double wavelengthMaxTo

If specified, the column must be less than this value.

enum wavelengthScale

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

bool returnPoints

If true, function returns spectrum values too

return value array

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

bool returnPoints

If true, function returns spectrum values too

return value array

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.

bool returnPoints

If true, function returns spectrum values too

return value array

Array of spectra matching the criteria

FindSpectraCone 

This functions returns spectra of spatial object within the specified cone

double ra

Right ascenation in J2000

 

double dec

Declination in J2000

 

double sr

Angle of the cone in arcmins

 

bool returnPoints

If true, function returns spectrum values too

 

return value array

Array of spectra matching the criteria

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.

 

float zFrom

Lower limit of redshift

 

float zTo

Upper limit of redshift

 

bool returnPoints

If true, function returns spectrum values too

 

return value array

Array of spectra matching the criteria

1.5 Spectrum Utility service functions

Function name

Parameters

Description

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.

return value array

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 spectra

Array of spectra to normalize in one turn

 

float[] limitsStart

Defines intervals for the spectrum normalizer function. Must be the same size as the normalizeLimitsEnd array.

 

float []limitsEnd

see above

 

float power

Parameter for the normalizer, varies upon object class

 

float factor

Parameter for the normalizer, varies upon object class

return value array

Array of the normalized spectra

RedshiftSpectra

Shifts passed spectra to the specified z

 

array spectra

Array of spectra to shift

 

float z

Shift spectra to a new z value. Specify 0 to put into restframe

return value array

Array of the shifted spectra

WeightSpectra

Weights the values with the following formula:

value = value * factor * wavelength ^ power;

 

array spectra

Array of spectra to weight.

 

float power

The power parameter of the formula

 

float factor

The factor parameter of the formula

return value array

Array of the weighted spectra

ComposeMedianSpectrum

Calculates the median of the passed spectra at all wavelength values in restframe. Returns the composite spectrum.

 

array spectra

Array of spectra to generate the composite from

 

enum scale

Linear = 0 or Logarithmic = 1, determines the new scale of the wavelength axis

 

int points

Number of points to resample to

 

float[] limitsStart

Defines intervals for the spectrum normalizer function. Must be the same size as the normalizeLimitsEnd array.

 

float []limitsEnd

see above

 

float power

Parameter for the normalizer, varies upon object class

 

float factor

Parameter for the normalizer, varies upon object class

return value object

The composite spectrum object

ComposeAverageSpectrum

Calculates the average of the passed spectra at all wavelength values in restframe. Returns the composite spectrum.

 

array spectra

Array of spectra to generate the composite from

 

enum scale

Linear = 0 or Logarithmic = 1, determines the new scale of the wavelength axis

 

int points

Number of points to resample to

 

float[] limitsStart

Defines intervals for the spectrum normalizer function. Must be the same size as the normalizeLimitsEnd array.

 

float []limitsEnd

see above

 

float power

Parameter for the normalizer, varies upon object class

 

float factor

Parameter for the normalizer, varies upon object class

return value object

The composite spectrum object

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.

 

array spectra

An array of spectrum objects to plot.

 

struct par

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.

2. Database schema

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!

2.1. Spectra table

This table contains spectrum header information

Column name

Data type

Description

ID

bigint (8)

Primary key of the Spectra table

Name

nvarchar (255)

Name of the spectrum

Description

ntext

Long description of the spectrum

UCD

nvarchar (255)

Universal Content Descriptor

Ra

float (8)

Right ascenation in J2000

Dec

float (8)

Declination in J2000

Cx

float (8)

 

Cy

float (8)

 

Cz

float (8)

 

HtmlID

bigint (8)

HTM id calculated from the coordinates

Synthetic

bit

 

Z

real (4)

Redshift of the object

ZError

real (4)

Absolute error of redshift of the object

ZStatus

smallint (2)

 

ZWarning

int (4)

 

ZConfidence

real (4)

 

Class

smallint (2)

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)

SurveyID

int (4)

ID of the survey from which the spectrum comes. Foreign key to the Surveys table.
1: SDSS DR1 (SDSS)
2: 2dF GRS (2DF) etc.

ObjectID

bigint (8)

ID of the object in the original survey catalog

DateMeasured

datetime (8)

Date of exposition

DateCreated

datetime (8)

Date of registration into the database

DateModified

datetime (8)

Date of last modification

WavelengthMin

float (8)

Minimum of the wavelength interval

WavelengthMax

float (8)

Maximum of the wavelength interval

WavelengthScale

int (4)

Wavelenght scale
0: Linear (LINEAR)
1: Logarithmic (LOGARITHMIC)
2: Other (OTHER)

ValueUnitID

int (4)

Unit of spectral data. Foreign key to the SpectrumValueUnits table
1: Jy (10e-17 erg/cm^2/s/A) - calibrated
2: counts - uncalibrated

Public

bit

 

UserFolder

int (4)

Indices on the Spectra table

Index name

Columns

Description

PK_Spectra

ID

Primary key, Unique

IX_Spectra_HtmID

HtmID

2.2. SpectrumKeys table

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.

Column name

Data type

Description

SpectrumID

bigint (8)

Foreign key to the Spectra table

NumValue

float (8)

Numeric data

StringValue

nvarchar (50)

Textual data, or storing unit if NumValue is not null

Indices on the SpectrumPoints table

Index name

Columns

Description

FK_SpectrumKeys_Spectra

SpectrumID -> ID

Foreign key

2.3. SpectrumPoints table

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.

Column name

Data type

Description

SpectrumID

bigint (8)

Foreign key to the Spectra table

Wavelength

real (4)

Wavelength in Angstroms

Value

real (4)

Spectrum value.
See notes above!

Error

real (4)

Error of value

Mask

int (4)

Gives extra information about the validity of value at the given wavelength, following the SDSS convetions.
*** more doc needed ***

Indices on the SpectrumPoints table

Index name

Columns

Description

FK_SpectrumPoints_Spectra

SpectrumID -> ID

Foreign key

2.4. SpectrumValueUnits table

The table contains the common spectrum value units.

Column name

Data type

Description

ID

int (4)

Primary key on the table

Text

nvarchar (50)

Written form of the unit

Calibrated

bit

Flag for calibrated values (can be used for magnitude calculation)

Indices on the SpectrumValueUnits table

Index name

Columns

Description

 

 

***

2.5. Surveys 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.

Column name

Data type

Description

ID

int (4)

Primary key on the table

Name

nvarchar (50)

Name of the survey

2.6. Database functions that can be used for advanced queries

Function name

Description

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.

2.7. Sample SQL queries

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

Description

 

 

 

 

3. Revision history