.\" @(#)vosloanspec.1 1.0 Feb-2013 MJF
.TH VOSLOANSPEC 1 "Feb 2013" "VOClient Package"
.SH NAME
vosloanspec \- Query for SDSS spectra

.SH SYNOPSIS
\fBvosloanspec\fP [<opts>] <obj> | {<ra> <dec>} | {<ra> <dec> <radius>}

.SH OPTIONS
The \fIvosloanspec\fP application accepts the following options:
.TP 8
.B \-h, --help
Print a help summary to the terminal and exit.  No processing is done 
following this flag.

.TP 6
.B \-P \fIRA\fP,\fIDEC\fP, --pos=\fIRA\fP,\fIDEC\fP
Set the query position (dec degrees).
.TP 6
.B \-R \fIREL\fP, --release=\fIREL\fP
Data release to query, allowed values are 'dr8' or 'dr9', the default is
to use whatever version is defined by the service as 'current'.
.TP 6
.B \-s \fIRADIUS\fP, --size=\fIRADIUS\fP
Set query radius (dec degrees).  The service imposes a max query radius of 10
degrees.
.TP 6
.B \-t \fITYPE\fP, --type=\fITYPE\fP
Object type constraint.  If not specified then all available spectra will
be returned, allowed values for the constraint are 'galaxy', 'qso' and 'star'.
.TP 6
.B \-z \fIZRANGE\fP, --redshift=\fIZRANGE\fP
Select by redshift range string(s).  A range is specified as two values
separated by a hyphen character (e.g. "0.1-0.3"), multiple ranges may be 
specified in a comma-delimited list (e.g. "0.1-0.3,1.0-1.5").

.TP 6
.B \-c, --count
Return only count of results available.
.TP 6
.B \-m, --meta
Print result position metadata.
.TP 6
.B \-D, --delete
Delete spectra after printing metadata.  In order to obtain the metadata, the
data are actually downloaded and then read, this option will delete these
files once the task exits.
.TP 6
.B \-l \fIN\fP, --limit=\fIN\fP
Limit to top \fIN\fP results.
.TP 6
.B \-u, --urls
Get urls to spectra only.

.TP 6
.B \-S, --samp
Broadcase urls as a SAMP spectrum message.
.TP 6
.B \-T, --table
Broadcase urls as SAMP load VOTable message.
.TP 6
.B \-N \fIN\fP, --num=\fIN\fP
Number of download threads to run in parallel (default: 12).

.TP 6
.B \-f \fIFILE\fP, --file=\fIFILE\fP
Input file of positions.
.TP 6
.B \-b \fIFILE\fP, --base=\fIFILE\fP
Base filename of downloaded files.
.TP 6
.B \-O \fIFILE\fP, --output=\fIFILE\fP
Output file for results.
.TP 6
.B \-o \fIOBJ\fP, --object=\fIOBJ\fP
Object name to resolve to query position.

.SH DESCRIPTION
The \fIvosloanspec\fP task provides access to Data Release 9 of 
the SDSS III Spectral Data.  This dataset contains over 1.5 million galaxies,
230,000 quasars, and 670,000 stars covering 14,500 square degrees of the sky.
.PP
Queries by position may be done using either a resolvable object name or an
explicit (RA,Dec) position given in ICRS decimal degrees.  The \fI-P\fP flag
can be used to specify the position as a single argument.  The default query
size is 0.25 degrees and may be changed using the \fI-s\fP flag.  If the 
DR8 release of the dataset is desired the \fI-R dr8\fP option may be used, 
by default the task will use whichever data release is deemed 'current' y
the service (DR9 as of this writing).  Spectra may be limited to a selection
of just 'galaxy', 'qso' or 'star' objects using the \fI-t\fP option.  The
\fI-z\fP option may be used to constrain the search by range of redshift
values.
.PP
Unless otherwise modified, the task will automatically download FITS spectra
for all objects within the query region.  The \fI-m\fP flag will print the 
positions of each object found (e.g. for marking an overlay), the \fI-u\fP
flag will print the access URLs for the spectra.  In the case of position
metadata the FITS files must actually be downloaded to the local machine
since the service doesn't provide this in a query return, the \fI-D\fP
flag will delete these images after the information is obtained.
.PP
To broadcast the spectra to SAMP-enabled applications using the
\fIspectrum\.load\.ssa-generic\fP message type, the \fI-S\fP option may be used.
The spectrum may be broadcast as a \fItable.load.FITS\fP message by specifying
the \fI-T\fP flag.

.SH REFERENCES
This task is based on the API available from

.nf
      http://api.sdss3.org/
.fi
See the documentation at this site for additional information about 
parameters.  The \fIvosloanspec\fP task attempts to provide a useful data
client using a non-VO interface and will eventually be replaced by a 
task with similar functionality using standard SSA services.

.SH RETURN STATUS
On exit the \fBvotcnv\fP task will return a zero indicating success, or a
one indicating an error.

.SH EXAMPLES
.TP 4
1)  Download all galaxy spectra w/in 0.1 deg of the Hubble Ultra Deep Field:

.nf
  % vosloanspec -s 0.1 -t galaxy HUDF
  % vosloanspec --size=0.1 --type=galaxy HUDF
.fi
.TP 4
2)  Get only the positions of the SDSS spectra around a point:

.nf
  % vosloanspec -m -D m51
  % vosloanspec --meta --delete m51
.fi
.TP 4
3)  Broadcast 5 spectra around 3c273 to SAMP-enabled apps:

.nf
  % vosloanspec -l 5 --samp 3c273     # as a spectrum msg
  % vosloanspec -l 5 --samp --table 3c273     # as a table msg
.fi
.TP 4
4)  Get all QSO spectra with a redshift > 0.3 (Note an upper range must be specified for the redshift range for a valid query):

.nf
  % vosloanspec --redshift=0.3-1.0
.fi

.SH BUGS
No known bugs with this release.
.SH Revision History
Feb 2013 - First public release
.SH Author
Michael Fitzpatrick (fitz@noao.edu), Feb 2013
.SH "SEE ALSO"
vodata, vospectra, voregistry, votopic