diff options
Diffstat (limited to 'vo/doc')
| -rw-r--r-- | vo/doc/datascope.hlp | 115 | ||||
| -rw-r--r-- | vo/doc/registry.hlp | 426 | ||||
| -rw-r--r-- | vo/doc/skybot.hlp | 0 | ||||
| -rw-r--r-- | vo/doc/sloanspec.hlp | 0 | ||||
| -rw-r--r-- | vo/doc/vizier.hlp | 87 |
5 files changed, 628 insertions, 0 deletions
diff --git a/vo/doc/datascope.hlp b/vo/doc/datascope.hlp new file mode 100644 index 00000000..4040ca02 --- /dev/null +++ b/vo/doc/datascope.hlp @@ -0,0 +1,115 @@ +.help datascope Aug06 nvo +.ih +NAME +datascope -- Toy "DataScope" application +.ih +USAGE +datascope what +.ih +PARAMETERS +.ls what +An image name, or the name of an object to be resolved into coordinates. +In the case of an image, the image is opened and if a valid WCS is +found the footprint of the image is used as the basis for the search. +In the case of an object name, the coordinates are resolved using the +\fBSESAME\fR service and a search of size \fBsr\fR degrees is performed. +The task will abort if the image doesn't contain a valid WCS. +.le +.ls service = "cone" +Type of service to query. \fBCone\fR or \fBsiap\fR are the only supported +services at the moment, "catalog" and "image" may be used as aliases +respectively. To query all supported services the value "all" may be used. +.le +.ls bandpass = "optical" +The bandpass of the service to be used (e.g. 'infrared', 'optical', +'x-ray', etc). Only those Registry resources listing this as part +of the spectral coverage field will be queried. +.le +.ls sr = "" +Search radius in decimal degrees. This parameter is only used when +resolving an object name. +.le +.ls filter = yes +Filter zero-valued or Error-returns +.le +.ls verbose = yes +Verbose output flag. +.le +.ls status = "" +Status return code of task (output). +.le + +.ih +DESCRIPTION + +The \fBDATASCOPE\fR task ...... + +.ih +EXAMPLES +1. Find IR catalogs that have data covered by the footprint +of the dev$wpix test image, filter results to exclude non-detections: + +.nf + cl> datascope dev$wpix service=cone bandpass=infrared filter+ + # + # Search Terms: RA=13:27:47.0 Dec=47:27:13.7 SR=0.109 + # Service Type: cone + # Total Querys: 22 + # + # + #Num ShortName Count IVO Identifier + #--- --------- ----- -------------- + 1 2MASS-PSC(CDS) 63 http://vizier.u-strasbg.fr/2MASS + 2 Simbad 10 ivo://CDS/simbad + 3 ADIL 1 ivo://adil.ncsa/targeted/conesearch + 4 NED(sources) 9 ivo://ned.ipac/Basic_Data_Near_Position + +.fi + +2. Find X-Ray image observations of M54: + +.nf + cl> datascope M54 service=siap bandpass=x-ray filter+ + # + # Search Terms: RA=18:55:03.3 Dec=-30:28:42.6 SR=0.250 + # Service Type: siap + # Total Querys: 14 + # + # + #Num ShortName Count IVO Identifier + #--- --------- ----- -------------- + 1 Chandra 2 http://cxc.harvard.edu/cda + 2 NED(images) 2 ivo://ned.ipac/Image + 3 RASS 3 ivo://nasa.heasarc/skyview/rass + # + # Zero Values: XMM-Newton,PSPC2,Granat/Sigma,HEAO1A,HRI,INTEGRALSPI_gc, + # PSPC1,RXTE, + # Err Returns: ROSAT/PSPC,SkyView,RASS3, + + + Now examine the Chandra images, since we match bandpass based on + the CoverageSpectral field of the resource we're not guaranteed that + the images being reported multiwavelength services are actually X-Ray. + + cl> sesame M54 + cl> siap regResolver ("Chandra","siap") sesame.ra sesame.dec 0.25 0.25 + ... to print the SIAP return table, + + To download the images directly.... + + cl> int siap, count, stat + cl> sesame M54 + cl> siap = dalSiapSvc(regResolver("Chandra","siap"),ses.ra,ses.dec,0.25) + cl> count = dalRecordCount(siap) + cl> for (i=0; i < count; i=i+1) { + >>> stat = dalGetData (siap, i, "chandra"//i//".fits") + >>> } +.fi + +.ih +REVISIONS +.le +.ih +SEE ALSO +voclient +.endhelp diff --git a/vo/doc/registry.hlp b/vo/doc/registry.hlp new file mode 100644 index 00000000..ce246b54 --- /dev/null +++ b/vo/doc/registry.hlp @@ -0,0 +1,426 @@ +.help registry Aug06 nvo +.ih +NAME +registry -- Browse the NVO Registry of data and services +.ih +USAGE +registry query +.ih +PARAMETERS +.ls query +A space separated list of keywords used to query the Registry. The query +requires that all keywords in the list be present in Title, Subject or +Description fields of the resource record. +.le +.ls svc_type = "" +Constrain the results to this particular service type. The value may +be any string (or substring) found in the 'ServiceType' field of a resource. +.le +.ls bandpass = "" +Constrain the results to this particular bandpass coverage. The value may +be any string (or substring) found in the 'CoverageSpectral' field of a +resource. +.le +.ls content = "" +Constrain the results to this particular content level description. The +value may be any string (or substring) found in the 'ContentLevel' field of a +resource. +.le +.ls sql = "" +An optional sql predicate string that will be combined with any keyword +query formed by the \fBquery\fR parameter. Defining this predicate allows +the user to constrain the results based on a specified field in the resource. +.le +.ls fields = "Title,Subject,CoverageSpectral" +The list of fields to be returned with all records in a verbose result. +.le +.ls header = yes +Print a header summarizing the query and constraints? +.le +.ls verbose = no +Print verbose output? In all cases each result will contain the record number, +the ShortName field, the ServiceType field and the Identifier field of the +resource record. If the verbose parameter is set, the fields listed by the +\fBfields\fR parameter will also be listed for each record. +.le +.ls interactive = no +Drop into an interactive command loop once the query has finished? This +command loop allows the user to repeatedly return to the result table, +browsing individual records in greater detail and summarizing the entire +result again before moving on. +.le +.ls record = -1 +Print the full resource record for this record number. If less than zero +the query is performed and all results are printed. If equal to zero, the +results obtained from the most recent query are printed using the result +handled saved int he \fBqres\fR parameter. Values greater than zero will +print the entire record for that resource. +.le +.ls metadata = no +If enabled, this will cause the task to list the metadata field available +in the Registry and quit. +.le + +.ls qres = 0 +The saved query response handle passed back by the VO Client from the most +recent query. Within a given CL-VOClient pairing this object should remain +valid and can be either passed to another application for use or will be +used internally when re-requesting a specific record from a new invocation +of the task. +.le +.ls qcount = 0 +The saved number of results from the query. +.le +.ls qstring = "" +The saved keyword query string. +.le +.ls qbandpass = "" +The saved spectral coverage constraint string. +.le +.ls qcontent = "" +The saved content level constraint string. +.le +.ls qsvc = "" +The saved service-type constraint string. +.le +.ls qsql = "" +The saved sql predicate constraint string. +.le +.ls status = "" +Status return code of the web service (output). +.le + +.ih +DESCRIPTION + +The \fBREGISTRY\fR task provides a simple command-line based browser of +the NVO Registry of data and services. It is a script task built around +new VO-CL builtin functions for doing simple Registry queries. + +The default query is based on a keyword search of the whitespace-delimited +words in the \fBquery\fR parameter. Results may be further constrained by +defining the \fBsvc_type\fR, \fBbandpass\fR, \fBcontent\fR and \fBsql\fR +parameters described above. If the \fBverbose\fR parameter is set the +the metadata fields listed in the \fBfields\fR parameter will follow the +one-line summary of each resource found. This summary contains a record +number, the 'ShortName', 'ServiceType', and 'Identifier' metadata fields +of each resource. + +Calling the task a second time with a null search term and the \fBrecord\fR +parameter will print all available information on that record. A record +number of zero will reprint the summary table of results. A list of the +available metadata fields is printed by setting the \fBmetadata\fR parameter. +If the \fBinteractiv\fR parameter is set the task will drop into a command +loop following the query, a summary of the available commands may be found +below. + +.ih +REGISTRY METADATA FIELDS + +The \fBREGISTRY\fR task is presently implemented such that it is somewhat +specific to the NVO Registry hosted at JHU/STScI +(http://nvo.stsci.edu/VORegistry/index.aspx or +http://voservices.net/registry/index.aspx) An upgrade to the standard +IVOA Registry interface is planned, however despite interface differences +the contents of the Registry will be largely the same. We mention this +since the metadata fields described here are likely to change in future +versions. + +The current Registry interface may be queried for the following columns +to be returned when part of the \fBfields\fR parameter: + +.nf + String-Valued Fields: + + Title Resource title (long version) + Name (alias for Title) + + Description Text description of resource + Facility Facility used to create the data + Identifier Standard ivo identifier of resource + ContentLevel Content Level (Research, educational, etc) + Contributor Entity responsible for creating service + CoverageSpatial Spatial coverage (STC) + CoverageSpectral Spectral coverage (csv list of bandpasses) + ContentLevel Content level (research, EPO, etc -- csv list) + CoverageTemporal Temporal coverage of data + Creator Entity responsible for creating the data + Instrument Instrument used to collect the data + ReferenceURL URL to reference about Resource + ResourceType Type of Service (Cone, Siap, etc) + ServiceType (alias for ResourceType) + ServiceURL Service URL (if appropriate) + ShortName Short name of Resource + Subject Subject keywords + Type Resource Type (catalog, survey, etc) + Version Data Version + + Real-Valued Fields: + + MaxSR Maximum search radius + + Integer-Valued Fields: + + MaxRecords Maximum records returned by the service +.fi + + +.ih +SQL PREDICATES + +The \fBsql\fR parameter may contain a valid sql predicate to be used as +part of the search. Unlike the \fBfields\fR parameter, this string is +specific to the Registry being queried and queries are formed using the +actual table column names and not the more abstract metadata fields described +above. + +A full list of the column names supported by the JHU/STScI Registry is +available at + +.nf + http://nvo.stsci.edu/voregistry/ListColumns.aspx +or http://voservices.net/Registry/ListColumns.aspx + +.fi + +Sql predicates can be used to search by columns not constrained by this +particular task interface, or to further constrain a search. For example, +to search for all resources who'd Creator is 'Smith' the task may be called +as + +.nf + cl> registry "" sql="CurationCreatorName like '%Smith%'" +.fi + +In this case we do not specify a keyword query and rely on the sql string +completely. The 'CurationCreatorName' is the column name we found from the +above URL, the '%' metacharacter matches all characters meaning we don't +need an explicit match. + + +.ih +COMMAND SUMMARY + +If the \fBinterfactive\fR parameter is enabled the task will perform the +requested query and then drop into a command loop supporting the following +keystroke commands: + +.nf + ? Print a usage summary + r Print detailed record (recnum will be prompted for) + s Print a summary list of results + v Enable the verbose flag + q Quit the command loop +.fi + +.ih +ALTERNATIVE CL REGISTRY ACCESS + +A programmatic interface to the Registry is also available in the CL +in the form of new builtin functions to the VO-CL. (The \fBREGISTRY\fR +task itself is a CL script using this interface.) + +The new functions will either directly return to the query result (high-level +access), or will return a "handle" that must be passed to other routines +to access that same result again in the VO Client (low-level access). In +some cases the functions are overloaded and will accept more than one form +of argument list (see below). + +.nf + + High-Level Registry Query: + + str = regResolver (idstring [, svctype [, attr [, index]]]) + N = regNResolved () + + Low-Level Registry Query: + + resource = regSearch (sql) + resource = regSearch (keywords, orValues) + resource = regSearch (sql, keywords, orValues) + + resource = regSvcSearch (svcType, searchTerm, orValues) + + count = regResCount (resource) + str = regValue (resource, attr_list, resIndex) +.fi + +.ls str = regResolver (idstring [, svctype [, attr [, index]]]) + +Resolve the given \fBidstring\fR to the attribute named by the \fBattr\fR +argument. The \fBidstring\fR may be either the ShortName or Identifier +field of a resource record and is not required to be an exact match. In +the case of multiple results, an exact match will be returned if found +otherwise the first match found in the record is used. + +The query may be refined further by defining a \fBsvctype\fR 2nd argument. +This argument is not required and is allowed to be a null string. + +Unless otherwise specified, the default \fBattr\fR attribute returned is +the ServiceURL. The \fBattr\fR may be a comma-delimited list of metadata +fields in which case the returned string will contain all requested attributes. + +If no \fBindex\fR is specified, the first matching record will be returned. +In the case of multiple results, the index may be used to loop through the +results but note that each time regResolver is called a new query is generated. +When looping through multiple results, use of the low-level interface is +preferred since the query will only be done once on the Registry, subsequent +calls are made only to the VO Client interface. A negative index will cause +the routine to return all matching records in the result string, one record +per line. +.le +.ls count = regNResolved () + +Return the number of records resolved by the last regResolver() query. Will +return -1 if an error occurred, 0 if no records found, 1 for a unique +resolution, otherwise >1 if multiple records were found. +.le + +.ls resource = regSearch (sql) + +Perform a registry query using the given sql predicate string. + +Return a \fBresource\fR handle needed by other routines for accessing the +query result. +.le +.ls resource = regSearch (keywords, orValues) + +Perform a registry query using a whitespace-delimited list of keywords. +The \fBorValues\fR boolean value is used to determine +whether all or only one of the given keywords are required for a match. + +Return a \fBresource\fR handle needed by other routines for accessing the +query result. +.le +.ls resource = regSearch (sql, keyword, orValues) + +Perform a registry query using an sql predicate string AND a + whitespace-delimited list of keywords. +The \fBorValues\fR boolean value is used to determine +whether all or only one of the given keywords are required for a match. + +Return a \fBresource\fR handle needed by other routines for accessing the +query result. +.le +.ls resource = regSvcSearch (svc, searchTerm, orValues) + +Do a Registry query constrained to the type of service defined by the +\fBsvc\fR argument (e.g. 'cone', 'siap', etc). The \fBsearchTerm\fR may be +either a whitespace-delimited list of keywords or an SQL predicate. In the +case of a keyword list the \fBorValues\fR boolean value is used to determine +whether all or only one of the given keywords are required for a match. + +Return a \fBresource\fR handle needed by other routines for accessing the +query result. +.le +.ls resource = regResCount (resource) + +Returns a count of the number of records in the \fBresource\fR handle. +.le +.ls str = regValue (resource, attr_list, resIndex) + +Return a string containing the requested metadata fields in the \fBattr_list\fR +argument from the query \fBresource\fR at record number \fBresIndex\fR (zero +indexed). A negative \fBresIndex\fR value will return all results, one per +line. +.le + +Examples using this interface are given below. + + +.ih +EXAMPLES +1. Find all Cone services registered as offering X-Ray catalogs, include +the Title and Subject of each resource printed: + +.nf + cl> registry "" svc=cone bandpass=x-ray verb+ +.fi + +Following the previous query: + +.nf + cl> registry rec=170 # details of record #170 + cl> registry rec=0 | page # to page the summary list + cl> registry rec=0 header- | sort col=2 # to sort by ShortName +.fi + + +2. Find all resources containing the object NGC188 in the resource entry: + +.nf + cl> registry "ngc 188" + cl> registry "ngc 188" svc=tabular # for VizieR tables only +.fi + +3. Find all resources about "active galaxies": + +.nf + cl> registry "active galaxies" # 186 results + cl> registry "active galaxy" # 55 results +.fi + +Note we get a different number of results depending on whether the plural is +used. Keyword queries are assumed to be substrings and so the phrase +"active galax" would match both 'galaxy' and 'galaxies' in the record. + + +4. Use the CL interface to find all GSC2.2 catalog services: + +.nf + cl> print (regResolver("GSC2.2","","ServiceType,Identifier",-1)) + CONE ivo://archive.stsci.edu/gsc/gsc2.2 + CONE http://vizier.u-strasbg.fr/GSC2 + + Since there is more than one cone service, call it by resolving the + identifier for the desired service on the fly: + + cl> cone regResolver("ivo://archive.stsci.edu/gsc/gsc2.2") \ + >>> 12:34:56.7 76:54:32.1 0.10 + + Because we resolved the identifier, we didn't need to further + constraint the query. The default gives us the ServiceURL we + wished to pass to the CONECALLER task. +.fi + + +5. Find all 2MASS catalog services currently registered: + +.nf + cl> registry 2mass + # + # Found 7 records + # + # Registry Query Constraints: + # Query Term: '2mass' + # ServiceType: cone + # + #No ShortName SvcType Identifier + #-- --------- ------- ---------- + # + 1 2MASS-PSC(CDS) CONE http://vizier.u-strasbg.fr/2MASS + 2 NOMAD CONE ivo://fs.usno/cat/nomad + 3 BMWHRICAT CONE ivo://nasa.heasarc/bmwhricat + 4 NED(sources) CONE ivo://ned.ipac/Basic_Data_Near_Pos... + 5 2MASS-XSC CONE ivo://irsa.ipac/2MASS-XSC + 6 2MASS-PSC CONE ivo://irsa.ipac/2MASS-PSC + 7 BHRFSCID CONE ivo://nasa.heasarc/bhrfscid +.fi + +Note that the ShortName is not guaranteed to be unique, here we have +'2MASS-PSC(CDS)' and '2MASS-PSC' as mirrors of the same data source. If +we use the regResolver() CL builtin to find the ServiceUrl using only the +string '2MASS-PSC' we would actually get the CDS service since it appears +first in the list. When a specific service is desired it is best to use +the Identifier string when resolving to a ServiceURL. One common use of +the REGISTRY task will be in quickly locating data of a particular type +(e.g. HST image services), and using the ShortName/Identifier to call the +data access services with a specific query. + +.ih +REVISIONS + +.ih +SEE ALSO +voclient, conecaller, siapcaller, vizier +.endhelp diff --git a/vo/doc/skybot.hlp b/vo/doc/skybot.hlp new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/vo/doc/skybot.hlp diff --git a/vo/doc/sloanspec.hlp b/vo/doc/sloanspec.hlp new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/vo/doc/sloanspec.hlp diff --git a/vo/doc/vizier.hlp b/vo/doc/vizier.hlp new file mode 100644 index 00000000..4cfe5146 --- /dev/null +++ b/vo/doc/vizier.hlp @@ -0,0 +1,87 @@ +.help vizier Aug06 nvo +.ih +NAME +vizier -- Download one or more VizieR tables +.ih +USAGE +vizier tab_id +.ih +PARAMETERS +.ls tab_id +A registry ShortName or Identifier string used to resolve to a specific +ServiceUrl for the table. +.le +.ls output = "STDOUT" +Output filename or STDOUT to print the table to the screen. +.le +.ls otype = "ascii" +Type of output table. The default return from a Cone service is a standard +VOTable (xml format). This table may be automatically converted to some +other format for use by other tasks by resetting this parameter. Allowed +output table types include: +.ls ascii +Simple space-separated ASCII file format. Note that string values in the +original VOTable will be quoted. +.le +.ls csv +Comma-Separated Value format. The first line is a header which contains +the column names. +.le +.ls fits +Convert VOTable to FITS binary table. Primary HDU is data-less, first +extension contains a FITS binary table. +.le +.ls votable +Do not process returned VOTable and output it directly. +.le + +For a full description of the supported STILTS output formats see +.nf + + http://www.star.bris.ac.uk/~mbt/stilts/sun256/outFormats.html +.fi +.le +.le +.ls all = yes +Download all matching tables? If enabled then each table matching the +given \fBtab_id\fR will be download and the \fBoutput\fR filename will +be the root filename and each table will be appended with a running number. + +A Registry ShortName typically refer to a single publication, while the +identifier refer to a specific table within that paper. To download all +tables in a given paper, run this task with the \fBtab_id\fR as the +Registry ShortName entry and the \fBall\fR parameter enabled. If you will +to download a specific table, call the task with the \fBIdentifier\fR field. +.le +.ls verbose = no +Verbose output flag. +.le +.ls status = "" +Status return code of task (output). +.le + +.ih +DESCRIPTION + +The \fBVIZIER\fR task ...... + +.ih +EXAMPLES +1. + +.nf +.fi + + +2. + +.nf +.fi + +.ih +REVISIONS +.le +.ih +SEE ALSO +voclient +.endhelp |