|
Astro::SIMBAD::Client - Fetch astronomical data from SIMBAD 4. |
Astro::SIMBAD::Client - Fetch astronomical data from SIMBAD 4.
use Astro::SIMBAD::Client; my $simbad = Astro::SIMBAD::Client->new (); print $simbad->query (id => 'Arcturus');
This package implements the SOAP query interface to version 4 of the SIMBAD on-line astronomical catalog, as documented at http://simbad.u-strasbg.fr/simbad4.htx. This package will not work with SIMBAD version 3. Its primary purpose is to obtain SIMBAD data, though some rudimentary parsing functionality also exists.
There are three ways to access this data.
- URL queries are essentially page scrapers, but their use is
documented, and output is available as HTML, text, or VOTable. URL
queries are implemented by the url_query() method.
- Scripts may be submitted using the script() or script_file() methods.
The former takes as its argument the text of the script, the latter
takes a file name.
- Queries may be made using the web services (SOAP) interface. The
query() method implements this, and queryObjectByBib,
queryObjectByCoord, and queryObjectById have been provided as
convenience methods. The documentation speaks of this functionality as
under development. As of December 13 2006 'txt' queries work as
advertised, but 'vo' queries return empty VOTables. Caveat user.
Astro::SIMBAD::Client is object-oriented, with the object supplying not only the SIMBAD server name, but the default format and output type for URL and web service queries.
A simple command line client application is also provided, as are various examples in the eg directory.
The following methods should be considered public:
set() method once the object is instantiated.
A line consisting of exactly '---' separates objects.
Data appear on lines that look like
name: data
and are parsed into a hash keyed by the given name. If the line ends with a comma, it is assumed to contain multiple items, and the data portion of the line is split on the commas; the resultant hash value is a list reference.
The user would normally not call this directly, but specify it as the parser for 'txt'-type queries:
$simbad->set (parser => {txt => 'Parse_TXT_Simple'});
This is not a full-grown VOTable parser capable of handling the full spec (see http://www.ivoa.net/Documents/latest/VOT.html). It is oriented toward returning <TABLEDATA> contents, and the metadata that can reasonably be associated with those contents.
The return is a list of anonymous hashes, one per <TABLE>. Each hash contains two keys:
{data} is the data contained in the table, and
{meta} is the metadata for the table.
The {meta} element for the table is a reference to a list of data gathered from the <TABLE> tag. Element zero is the tag name ('TABLE'), and element 1 is a reference to a hash containing the attributes of the <TABLE> tag. Subsequent elements if any represent metadata tags in the order encountered in the parse.
The {data} contains an anonymous list, each element of which is a row of data from the <TABLEDATA> element of the <TABLE>, in the order encountered by the parse. Each row is a reference to a list of anonymous hashes, which represent the individual data of the row, in the order encountered by the parse. The data hashes contain two keys:
{value} is the value of the datum with undef for '~', and
{meta} is a reference to the metadata for the datum.
The {meta} element for a datum is a reference to the metadata tag that describes that datum. This will be an anonymous list, of which element 0 is the tag ('FIELD'), element 1 is a reference to a hash containing that tag's attributes, and subsequent elements will be the contents of the tag (typically including a reference to the list representing the <DESCRIPTION> tag for that FIELD).
All values are returned as provided by the XML parser; no further decoding is done. Specifically, the datatype and arraysize attributes are ignored.
This parser is based on XML::Parser if that is available. Otherwise it uses XML::Parser::Lite, which should be available since it comes with SOAP::Lite.
The user would normally not call this directly, but specify it as the parser for 'vo'-type queries:
$simbad->set (parser => {vo => 'Parse_VO_Table'});
bib => queryObjectByBib ($bibcode, $format, $type) coo => queryObjectByCoord ($coord, $radius, $format, $type) id => queryObjectById ($id, $format, $type)
where:
$bibcode is a SIMBAD bibliographic code $coord is a set of coordinates $radius is an angular radius around the coordinates $type is the type of data to be returned $format is a format appropriate to the data type.
The $type defaults to the value of the type attribute, and the $format defaults to the value of the format attribute for the given $type.
The return value depends on a number of factors:
If the query found nothing, you get undef in scalar context, and an empty list in list context.
If a parser is defined for the given type, the returned data will be fed to the parser, and the output of the parser will be returned. This is assumed to be a list, so a reference to the list will be used in scalar context. Parser exceptions are not trapped, so the caller will need to be prepared to deal with malformed data.
Otherwise, the result of the query is returned as-is.
Caveat: Chapter 1 of the SIMBAD 4 Users Guide at http://simbad.u-strasbg.fr/guide/ch01.htx speaks of the Web Services as 'to be developed'. They are documented in the help at http://simbad.u-strasbg.fr/simbad/sim-help, and this method implements that interface to the best of my ability. But 'vo' queries began returning empty VOTables on or about December 3 2006, and as of December 13 still behave this way. The 'txt' queries appear to work.
$value = $simbad->query (bib => $bibcode, $format, $type);
See the query() documentation for more information.
$value = $simbad->query (coo => $coord, $radius, $format, $type);
See the query() documentation for more information.
$value = $simbad->query (id => $id, $format, $type);
See the query() documentation for more information.
script_file() method.
If the verbatim attribute is false, the front matter of the result (up to and including the '::data:::::' line) is stripped. If there is no '::data:::::' line, the entire script output is raised as an exception.
If a 'script' parser was specified, the output of the script
(after stripping front matter if that was specified) is passed to it.
The parser is presumed to return a list, so if script() was called in
scalar context you get a reference to that list back.
If no 'script' parser is specified, the output of the script (after stripping front matter if that was specified) is simply returned to the caller.
id = query by identifier, coo = query by coordinates, ref = query by references, sam = query by criteria.
The arguments depend on on the type, and are documented at http://simbad.u-strasbg.fr/simbad/sim-help. They are specified as name => value. For example:
$simbad->url_query (id =>
Ident => 'Arcturus',
NbIdent => 1
);
Note that in an id query you must specify 'Ident' explicitly. This is true in general, because it is not always possible to derive the first argument name from the query type, and consistency was chosen over brevity.
The output.format argument can be defaulted based on the object's type setting as follows:
txt becomes 'ASCII', vo becomes 'VOTable'.
Any other value is passed verbatim.
If the query succeeds, the results will be passed to the appropriate parser if any. The reverse of the above translation is done to determine the appropriate parser, so the 'vo' parser (if any) is called if output.format is 'VOTable', and the 'txt' parser (if any) is called if output.format is 'ASCII'. If output.format is 'HTML', you will need to explicitly set up a parser for that.
The Astro::SIMBAD::Client attributes are documented below. The type of the attribute is given after the attribute name, in parentheses. The types are:
boolean - a true/false value (in the Perl sense); hash - a reference to one or more key/value pairs; integer - an integer; string - any characters.
Hash values may be specified either as hash references or as strings. When a hash value is set, the given value updates the hash rather than replacing it. For example, specifying
$simbad->set (format => {txt => '%MAIN_ID\n'});
does not affect the value of the vo format. If a key is set to the null value, it deletes the key. All keys in the hash can be deleted by setting key 'clear' to any true value.
When specifying a string for a hash-valued attribute, it must be of the form 'key=value'. For example,
$simbad->set (format => 'txt=%MAIN_ID\n');
does the same thing as the previous example. Specifying the key name without an = sign deletes the key (e.g. set (format => 'txt')).
The Astro::SIMBAD::Client class has the following attributes:
This attribute determines whether setting the parser should attempt to autoload its package.
The default is 1 (i.e. true).
The default value is 0.
query()
output type. See
http://simweb.u-strasbg.fr/simbad/sim-help for how
to specify formats for each output type. Output type 'script' is used to
specify a format for the script() method.
The format can be specified either literally, or as a subroutine name or code reference. A string is assumed to be a subroutine name if it looks like one (i.e. matches (\w+::)*\w+), and if the given subroutine is actually defined. If no namespace is specified, all namespaces in the call tree are checked. If a code reference or subroutine name is specified, that code is executed, and the result becomes the format.
The following formats are defined in this module:
FORMAT_TXT_SIMPLE_BASIC - a simple-to-parse text format providing basic information; FORMAT_TXT_YAML_BASIC - pseudo-YAML (parsable by YAML::Load) providing basic info; FORMAT_VO_BASIC - VOTable field names providing basic information.
The FORMAT_TXT_YAML_BASIC format attempts to provide data structured similarly to the output of the Astro::SIMBAD manpage, though Astro::SIMBAD::Client does not bless the output into any class.
A simple way to examine these formats is (e.g.)
use Astro::SIMBAD::Client; print Astro::SIMBAD::Client->FORMAT_TXT_YAML_BASIC;
Before a format is actually used it is preprocessed in a manner depending on its intended output type. For 'vo' formats, leading and trailing whitespace are stripped. For 'txt' and 'script' formats, line breaks are stripped.
The default specifies formats for output types 'txt' and 'vo'. The 'txt' default is FORMAT_TXT_YAML_BASIC; the 'vo' default is FORMAT_VO_BASIC.
The default format for 'script' is blank, under the assumption that the
script provides its own format. If you provide a 'script' format, it
must be a 'txt'-style format, and it will be prepended to the script you
pass to the script() method. There is no way to default the format for
the script_file() method.
Parsers may be specified by either a code reference, or by the text name of a subroutine. If specified as text and the name is not qualified by a package name, the calling package is assumed. The parser must be defined, and must take as its lone argument the text to be parsed.
If the parser for a given output type is defined, query results of that type will be passed to the parser, and the result returned. Otherwise the query results will be returned verbatim.
The output types are anything legal for the query() method (i.e. 'txt'
and 'vo' at the moment), plus 'script' for a script parser. All default
to '', meaning no parser is used.
The default is 'simbad.u-strasbg.fr'.
The default is 'txt'.
script() and script_file() are to strip
the front matter from the script output. If false, everything up to and
including the '::data:::::' line is removed before passing the output to
the parser or returning it to the user. If true, the script output is
passed to the parser or returned to the user unmodified.
The default is 0 (i.e. false)
Thomas R. Wyant, III (wyant at cpan dot org)
Copyright 2006 by Thomas R. Wyant, III (wyant at cpan dot org). All rights reserved.
This module is free software; you can use it, redistribute it and/or modify it under the same terms as Perl itself. Please see http://perldoc.perl.org/index-licence.html for the current licenses.
|
Astro::SIMBAD::Client - Fetch astronomical data from SIMBAD 4. |