GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Astro::Catalog(3) User Contributed Perl Documentation Astro::Catalog(3)

Astro::Catalog - A generic API for stellar catalogues

    $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);

Stores generic meta-data about an astronomical catalogue. 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 catalogue format and either the name of a catalogue file or a reference to a scalar, glob or array.

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

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

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.

write_catalog
Will serialise the catalogue 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 catalogue file are stored in the scalar or in the array (a line per array entry with no new lines).

origin
Return (or set) the origin of the data. For example, USNOA2, GSC for catalogue queries, or 'JCMT' for the JCMT pointing catalogue. 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 catalogue (post filter).

    $num = $catalog->sizeof();
    
sizeoffull
Returns the total number of stars in the catalogue 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 catalogue (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 catalogue field centre in sexagesimal, space-separated format. Returns undef if no coordinate supplied.

    $ra = $catalog->get_ra();
    
get_dec
Return the Dec of the catalogue field centre in sexagesimal space-separated format with leading sign.

    $dec = $catalog->get_dec();
    
get_radius
Return the radius of the catalogue 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.

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 catalogue, 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 catalogue 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 catalogue) 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 catalogue 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 catalogue 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.

All these filters work on a copy of the full star list. The filters are cumulative.
filter_by_observability
Generate a filtered catalogue 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/;});
    

The following routines are available for sorting the star catalogue. 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 catalogue 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 (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.

Alasdair Allan <aa@astro.ex.ac.uk>, Tim Jenness <tjenness@cpan.org> Tim Lister <tlister@lcogt.net>
2022-05-14 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.