NAME

Astro::Catalog - A generic API for stellar catalogs

SYNOPSIS

$catalog = new Astro::Catalog(Stars => \@array);
$catalog = new Astro::Catalog(Format => 'Cluster', File => $file_name);
$catalog = new Astro::Catalog(Format => 'JCMT', Data => $scalar);
$catalog = new Astro::Catalog(Format => 'Simple', Data => \*STDIN);
$catalog = new Astro::Catalog(Format => 'VOTable', Data => \@lines);

DESCRIPTION

Stores generic meta-data about an astronomical catalog. Takes a hash with an array reference as an argument. The array should contain a list of Astro::Catalog::Item objects. Alternatively it takes a catalog format and either the name of a catalog file or a reference to a scalar, glob or array.

FORMATS

For input the Astro::Catalog module understands Cluster, Simple, JCMT, TST, STL, GaiaPick, the UKIRT internal Bright Star catalog format and (a very simple parsing) of VOTable.

The module can output all of these formats except TST (which is input only).

METHODS

Constructor

new

Create a new instance from a hash of options

$catalog = new Astro::Catalog(Stars  => \@array);
$catalog = new Astro::Catalog(Format => 'Cluster', File => $file_name);
$catalog = new Astro::Catalog(Format => 'JCMT', Data => $scalar);

returns a reference to an Astro::Catalog object. See the configure method for a list of allowed arguments.

Output Methods

write_catalog

Will serialise the catalog object in a variety of file formats using pluggable IO, see the Astro::Catalog::IO classes

$catalog->write_catalog(
    File => $file_name, Format => $file_type, [%opts])
or die $catalog->errstr;

returns true on sucess and false if the write failed (the reason can be obtained using the errstr method). The %opts are optional arguments and are dependent on the output format chosen. Current valid output formats are 'Simple', 'Cluster', 'JCMT' and 'VOTable'.

The File argument can refer to a file name on disk (simple scalar), a glob (eg \*STDOUT), an IO::Handle object (for example something returned by the File::Temp constructor) a reference to a scalar (\$content) or reference to an array. For the last two options, the contents of the catalog file are stored in the scalar or in the array (a line per array entry with no new lines).

Accessor Methods

origin

Return (or set) the origin of the data. For example, USNOA2, GSC for catalog queries, or 'JCMT' for the JCMT pointing catalog. No constraint is placed on the content of this parameter.

$catalog->origin('JCMT');
$origin = $catalog->origin();

errstr

Error string associated with any error. Can only be trusted immediately after a call that sets it (eg write_catalog).

preferred_magnitude_type

Set or return the preferred magnitude type to be returned from the Astro::Catalog::Item->get_magnitude() method.

my $type = $catalog->preferred_magnitude_type;
$catalog->preferred_magnitude_type('MAG_ISO');

sizeof

Return the number of stars in the catalog (post filter).

$num = $catalog->sizeof();

sizeoffull

Returns the total number of stars in the catalog without filtering.

pushstar

Push a new star (or stars) onto the end of the Astro::Catalog object

$catalog->pushstar(@stars);

returns the number of stars now in the Catalog object (even if no arguments were supplied). The method guarantees that the stars are pushed onto the internal original list and the filtered/sorted version.

Currently no check is made to make sure that the star is already on one of the two lists.

popstar

Pop a star from the end of the Astro::Catalog object. This forces a copy of the array if one has not already been made (ie the original version is unchanged).

$star = $catalog->popstar();

the method deletes the star and returns the deleted Astro::Catalog::Item object.

popstarbyid

Return Astro::Catalog::Item objects that have the given ID. This forces a copy of the array if one has not already been made (ie the original version is unchanged).

@stars = $catalog->popstarbyid( $id );

The method deletes the stars and returns the deleted Astro::Catalog::Item objects. If no star exists with the given ID, the method returns an empty list.

If called in scalar context this method returns an array reference, and if called in list context returns an array of Astro::Catalog::Item objects.

This is effectively an inverse filter (see filter_by_id for complementary method).

allstars

Return all the stars in the catalog in their original ordering and without filtering.

@allstars = $catalog->allstars();
$ref = $catalog->allstars();

In list context returns all the stars, in scalar context returns a reference to the internal array. This allows the primary array to be modified in place so use this with care.

Addendum: This is pretty much for internal use only, but if you do this

$catalog->allstars(@stars);

you repalce the stars array with the array passed. Don't do this, it's bad!

stars

Return a list of all the Astro::Catalog::Item objects that are currently valid and in the current order. This method may well return different stars to the allstars method depending on the current sort in scope.

@stars = $catalog->stars();

in list context the copy of the array is returned, while in scalar context a reference to the array is return. In scalar context, the referenced array will always be that of the current list of valid stars. If the current list is empty the primary list will be copied into the current array so that it can be modified independently of the original list. This may cost you a lot of memory. Note that changes to the array ordering or content may be lost in this case whenever the reset_list method is used.

starbyindex

Return the Astro::Catalog::Item object at index $index

$star = $catalog->starbyindex($index);

the first star is at index 0 (not 1). Returns undef if no arguments are provided.

fieldcentre

Set the field centre and radius of the catalog (if appropriate)

$catalog->fieldcentre(
    RA     => $ra,
    Dec    => $dec,
    Radius => $radius,
    Coords => new Astro::Coords());

RA and Dec must be given together or as Coords. Coords (an Astro::Coords object) supercedes RA/Dec.

set_radius

Set the field centre radius. Must be in arcminutes.

$catalog->set_radius($radius);

set_coords

Set the field centre coordinates with an Astro::Coords object.

$catalog->set_coords($c);

get_coords

Return the Astro::Coords object associated with the field centre.

$c = $catalog->get_coords();

get_ra

Return the RA of the catalog field centre in sexagesimal, space-separated format. Returns undef if no coordinate supplied.

$ra = $catalog->get_ra();

get_dec

Return the Dec of the catalog field centre in sexagesimal space-separated format with leading sign.

$dec = $catalog->get_dec();

get_radius

Return the radius of the catalog from the field centre

$radius = $catalog->get_radius();

reference

If set this must contain an Astro::Coords object that can be used as a reference position. When a reference is supplied distances will be calculated from each catalog target to the reference. It will also be possible to sort by distance.

$ref = $catalog->reference;
$catalog->reference($c);

If a reference position is not specified explicitly the field centre will be used instead (if defined).

reftime

The reference time used for coordinate calculations. Extracted from the reference coordinate object if one exists and no override has been specified. If neither a default setting has been made and no reference exists the current time is returned.

$reftime = $src->reftime();

$src->reftime($newtime);

Time must be a Time::Piece object. This is only really important for moving objects such as planets or asteroids or for occasions when you are calcualting azimuth or elevation.

fielddate

The observation date/time of the field.

$fielddate = $src->fielddate;

$src->fielddate($date);

Date must be a Time::Piece object. This defaults to the current time when the Astro::Catalog object was instantiated.

auto_filter_observability

If this flag is true, a reset_list will automatically remove targets that are not observable (as determined by filter_by_observability which will be invoked).

Default is false.

misc

Method to contain information not handled by other methods. This is analogous to the Astro::Catalog::Item::misc method, and should also typically be used to store a hash reference.

General Methods

configure

Configures the object from multiple pieces of information.

$newcat = $catalog->configure(%options);

Takes a hash as argument with the list of keywords. Supported options are:

Format => Format of supplied catalog
File => File name for catalog on disk. Not used if 'Data' supplied.
Data => Contents of catalog, either as a scalar variable,
        reference to array of lines or reference to glob (file handle).
        This key is used in preference to 'File' if both are present

Stars => Array of Astro::Catalog::Item objects. Supercedes all other options.
ReadOpt => Reference to hash of options to be forwarded onto the
           format specific catalog reader. See the IO documentation
           for details.

If Format is supplied without any other options, a default file is requested from the class implementing the formatted read. If no default file is forthcoming the method croaks.

If no options are specified the method does nothing, assumes you will be supplying stars at a later time.

The options are case-insensitive.

Note that in some cases (when reading a catalog) this method will act as a constructor. In any case, always returns a catalog object (either the same one that went in or a modified one).

API uncertainty - in principal Data is not needed since File could be overloaded (in a similar way to write_catalog).

reset_list

Forces the star list to return to the original unsorted, unfiltered catalog list.

$catalog->reset_list();

If auto_filter_observability is true, the list will be immediately filtered for observability.

force_ref_time

Force the specified reference time into the coordinate object associated with each star (in the current list). This ensures that calculations on the catalog entries are all calculated for the same time.

$catalog->force_ref_time();

After this, the times in the coordinate objects will be set and will no longer reflect current time (if they had it originally).

calc_xy

Calculate the X and Y positions for every item in the catalog, if they have an RA and Dec.

$catalog->calc_xy($frameset);

The supplied argument must be a Starlink::AST::FrameSet.

Filters

All these filters work on a copy of the full star list. The filters are cumulative.

filter_by_observability

Generate a filtered catalog where only those targets that are observable are present (assumes that the current state of the coordinate objects is correct but will use the reference time returned by reftime). ie the object is returned to its original state and then immediately filtered by observability. Any stars without coordinates are also filtered. Starts from the current star list (which may already have been filtered).

@new = $catalog->filter_by_observability();

Returns the newly selected stars (as if the stars method was called immediately, unless called in a non-list context.

filter_by_id

Given a source name filter the source list such that the supplied ID is a substring of the star ID (case insensitive).

@stars = $catalog->filter_by_id("IRAS");

Would result in a catalog with all the stars with "IRAS" in their name. This is just a convenient alternative to filter_by_cb and is equivalent to

@stars = $catalog->filter_by_cb(sub {$_[0]->id =~ /IRAS/i;});

A regular expression can be supplied explicitly using qr//:

@stars = $catalog->filter_by_id(qr/^IRAS/i);

See popstarbyid for a similar method that returns stars that are an exact match to ID and removes them from the current list.

filter_by_distance

Retrieve all targets that are within the specified distance of the reference position.

@selected = $catalog->filter_by_distance( $radius, $refpos );

The radius is in radians. The reference position defaults to the value returned by the reference method if none supplied.

API uncertainty:

- Should the radius default to the get_radius() method?
- Should this method take hash arguments?
- Should there be a units argument? (radians, arcmin, arcsec, degrees)

filter_by_cb

Filter the star list using the given the supplied callback (reference to a subroutine). The callback should expect a star object and should return a boolean.

@selected = $catalog->filter_by_cb(sub {$_[0]->id == "HLTau"});
@selected = $catalog->filter_by_cb(sub {$_[0]->id =~ /^IRAS/;});

Sorting

The following routines are available for sorting the star catalog. The sort applies to the current source list and not the original source list. This is the case even if no filters have been applied (ie the original unsorted catalog is always available).

sort_catalog

Sort the catalog.

$catalog->sort_catalog($mode);

where mode can be one of

"unsorted"
"id"
"ra"
"dec"
"az"
"el"

and

"distance"
"distance_az"

if a reference position is available. "az" and "el" require that the star coordinates have an associated telescope and that the reference time is correct.

If mode is a code reference, that will be passed to the sort routine directly. Note that the callback must expect $a and $b to be set.

The method force_ref_time is invoked prior to sorting unless the mode is "id". "name" is a synonym for "id".

Currently the unsorted option simply forces a reset_list since there is currently no tracking of the applied filters. It should be possible to step through the original list and the current filtered list and end up with a filtered but unsorted list. This is not implemented.

Pre-canned sorts are optimized because the values are precalculated prior to doing the sort rather than calculated each time through the sort.

COPYRIGHT

Copyright (C) 2001-2002 University of Exeter. All Rights Reserved. Some modificiations Copyright (C) 2003 Particle Physics and Astronomy Research Council. All Rights Reserved.

This program was written as part of the eSTAR project and is free software; you can redistribute it and/or modify it under the terms of the GNU Public License.

AUTHORS

Alasdair Allan <aa@astro.ex.ac.uk>, Tim Jenness <tjenness@cpan.org> Tim Lister <tlister@lcogt.net>