/ 
Astro-Catalog-4.22
River stage one • 2 direct dependents • 2 total dependents
/ Astro::Catalog::Item

NAME

Astro::Catalog::Item - A generic star object in a stellar catalogue.

SYNOPSIS

  $star = new Astro::Catalog::Item(
               ID	    => $id,
               Coords	    => new Astro::Coords(),
               Morphology   => new Astro::Catalog::Item::Morphology(),
               Fluxes	    => new Astro::Fluxes(),
	       Quality      => $quality_flag,
               Field	    => $field,
               GSC	    => $in_gsc,
               Distance     => $distance_to_centre,
               PosAngle     => $position_angle,
               X	    => $x_pixel_coord,
               Y	    => $y_pixel_coord,
               WCS	    => new Starlink::AST(),
               Comment      => $comment_string
	       SpecType     => $spectral_type,
	       StarType     => $star_type,
	       LongStarType => $long_star_type,
	       MoreInfo     => $url,
               InsertDate   => new Time::Piece(),
               Misc  => $hash_ref,
				  );

DESCRIPTION

Stores generic meta-data about an individual stellar object from a catalogue.

If the catalogue has a field center the Distance and Position Angle properties should be used to store the direction to the field center, e.g. a star from the USNO-A2 catalogue retrieived from the ESO/ST-ECF Archive will have these properties.

REVISION

$Id: Item.pm,v 1.13 2007/09/25 23:23:43 cavanagh Exp $

METHODS

Constructor

new

Create a new instance from a hash of options

  $star = new Astro::Catalog::Item(
               ID           => $id,
               Coords	    => new Astro::Coords(),
               Morphology   => new Astro::Catalog::Item::Morphology(),
               Fluxes	    => new Astro::Fluxes(),
               Quality      => $quality_flag,
               Field	    => $field,
               GSC	    => $in_gsc,
               Distance     => $distance_to_centre,
               PosAngle     => $position_angle,
               X	    => $x_pixel_coord,
               Y	    => $y_pixel_coord,
               Comment      => $comment_string
	       SpecType     => $spectral_type,
	       StarType     => $star_type,
	       LongStarType => $long_star_type,
	       MoreInfo     => $url,
               InsertDate   => new Time::Piece(),
               Misc   => $misc,
				  );

returns a reference to an Astro::Catalog::Item object.

The coordinates can also be specified as individual RA and Dec values (sexagesimal format) if they are known to be J2000.

Accessor Methods

id

Return (or set) the ID of the star

$id = $star->id();
$star->id( $id );

If an Astro::Coords object is associated with the Star, the name field is set in the underlying Astro::Coords object as well as in the current Star object.

coords

Return or set the coordinates of the star as an Astro::Coords object.

$c = $star->coords();
$star->coords( $c );

The object returned by this method is the actual object stored inside this Star object and not a clone. If the coordinates are changed through this object the coordinate of the star is also changed.

Currently, if you modify the RA or Dec through the ra() or dec() methods of Star, the internal object associated with the Star will change.

Returns undef if the coordinates have never been specified.

If the name() field is defined in the Astro::Coords object the id() field is set in the current Star object. Similarly for the comment field.

ra

Return (or set) the current object R.A. (J2000).

$ra = $star->ra();

If the Star is associated with a moving object such as a planet, comet or asteroid this method will return the J2000 RA associated with the time and observer position associated with the coordinate object itself (by default current time, longitude of 0 degrees). Returns undef if no coordinate has been associated with this star.

$star->ra( $ra );

The RA can be changed using this method but only if the coordinate object is associated with a fixed position. Attempting to change the J2000 RA of a moving object will fail. If an attempt is made to change the RA when no coordinate is associated with this object then a new Astro::Coords object will be created (with a Dec of 0.0).

RA accepted by this method must be in sexagesimal format, space or colon-separated. Returns a space-separated sexagesimal number.

dec

Return (or set) the current object Dec (J2000).

$dec = $star->dec();

If the Star is associated with a moving object such as a planet, comet or asteroid this method will return the J2000 Dec associated with the time and observer position associated with the coordinate object itself (by default current time, longitude of 0 degrees). Returns undef if no coordinate has been associated with this star.

$star->dec( $dec );

The Dec can be changed using this method but only if the coordinate object is associated with a fixed position. Attempting to change the J2000 Dec of a moving object will fail. If an attempt is made to change the Dec when no coordinate is associated with this object then a new Astro::Coords object will be created (with a Dec of 0.0).

Dec accepted by this method must be in sexagesimal format, space or colon-separated. Returns a space-separated sexagesimal number with a leading sign.

fluxes

Return or set the flux measurements of the star as an Astro::Fluxes object.

$f = $star->fluxes();
$star->fluxes( $f );

$star->fluxes( $f, 1 );  # will replace instead of appending

The object returned by this method is the actual object stored inside this Item object and not a clone. If the flux values are changed through this object the flu values of the star is also changed.

If an optional flag is passed as set to the routine it will replace instead of appending (default action) to an existing fluxes object in the catalogue.

Returns undef if the fluxes have never been specified.

what_filters

Returns a list of the wavebands for which the object has defined values.

@filters = $star->what_filters();
$num = $star->what_filters();

if called in a scalar context it will return the number of filters which have defined magnitudes in the object. It will included 'derived' values, see Astro::Flux for details.

what_colours

Returns a list of the colours for which the object has defined values.

@colours = $star->what_colours();
$num = $star->what_colours();

if called in a scalar context it will return the number of colours which have defined values in the object.

get_magnitude

Returns the magnitude for the supplied filter if available

$magnitude = $star->get_magnitude( 'B' );
get_flux_quantity

Returns the flux quantity for the given waveband and flux type.

my $flux = $star->get_flux_quantity( waveband => 'B',
                                     type => 'mag' );

The arguments are passed as a hash. The value for the waveband argument can be either a string describing a filter or an Astro::WaveBand object. The value for the flux type is case-insensitive.

Returns a scalar.

get_errors

Returns the error in the magnitude value for the supplied filter if available

$mag_errors = $star->get_errors( 'B' );
get_flux_error

Returns the flux error for the given waveband and flux type.

my $flux = $star->get_flux_error( waveband => 'B',
                                  type => 'mag' );

The arguments are passed as a hash. The value for the waveband argument can be either a string describing a filter or an Astro::WaveBand object. The value for the flux type is case-insensitive.

Returns a scalar.

get_colour

Returns the value of the supplied colour if available

$colour = $star->get_colour( 'B-V' );
get_colourerror

Returns the error in the colour value for the supplied colour if available

$col_errors = $star->get_colourerr( 'B-V' );
preferred_magnitude_type

Get or set the preferred magnitude type to be returned from the get_magnitude method.

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

Defaults to 'MAG'.

morphology

Get or set the morphology of the star as an Astro::Catalog::Item::Morphology object.

$star->morphology( $morphology );

The object returned by this method is the actual object stored inside this Star object and not a clone. If the morphology is changed through this object the morphology of the star is also changed.

quality

Return (or set) the quality flag of the star

$quality = $star->quailty();
$star->quality( 0 );

for example for the USNO-A2 catalogue, 0 denotes good quality, and 1 denotes a possible problem object. In the generic case any flag value, including a boolean, could be used.

These quality flags are standardised sybolically across catalogues and have the following definitions:

STARGOOD
STARBAD

TBD. Need to provide quality constants and mapping to and from these constants on catalog I/O.

field

Return (or set) the field parameter for the star

$field = $star->field();
$star->field( '0080' );
gsc

Return (or set) the GSC flag for the object

$gsc = $star->gsc();
$star->gsc( 'TRUE' );

the flag is TRUE if the object is known to be in the Guide Star Catalogue, and FALSE otherwise.

distance

Return (or set) the distance from the field centre

$distance = $star->distance();
$star->distance( '0.009' );

e.g. for the USNO-A2 catalogue.

posangle

Return (or set) the position angle from the field centre

$position_angle = $star->posangle();
$star->posangle( '50.761' );

e.g. for the USNO-A2 catalogue.

x

Return (or set) the X pixel co-ordinate of the star

$x = $star->x();
$star->id( $x );
y

Return (or set) the Y pixel co-ordinate of the star

$y = $star->y();
$star->id( $y );
wcs

Return (or set) the WCS associated with the star.

$wcs = $star->wcs;
$star->wcs( $wcs );

The WCS is a Starlink::AST object.

comment

Return (or set) a comment associated with the star

$comment = $star->comment();
$star->comment( $comment_string );

The comment is propogated to the underlying coordinate object (if one is present) if the comment is updated.

spectype

The spectral type of the Star.

$spec = $star->spectype;
startype

The type of star. Usually uses the Simbad abbreviation. eg. '*' for a star, 'rG' for a Radio Galaxy.

$type = $star->startype;

See also longstartype for the expanded version of this type.

longstartype

The full description of the type of star. Usually uses the Simbad text. If no text has been provided, a lookup will be performed using the abbreviated startype.

$long = $star->longstartype;
$star->longstartype( "A variable star" );

See also longstartype for the expanded version of this type.

moreinfo

A link (URL) to more information on the star in question. For example this might provide a direct link to the full Simbad description.

$url = $star->moreinfo;
insertdate

The time the information for the star in question was gathered. This is different from the time of observation of the star.

$insertdate = $star->insertdate;

This is a Time::Piece object.

fluxdatestamp

Apply a datestamp to all the Astro::Flux objects inside the Astro::Fluxes object contained within this object

$star->fluxdatestamp( new DateTime() )

this is different from the time for which the inormation about the star was gathered, see the insertdate() method call, and is the time of observation of the object.

distancetostar

The distance from another Item,

my $distance1 = $star->distancetostar( $star2 )

returns a tangent plane separation value in arcsec. Returns undef if the star is too far away.

within

Check if the passed star is within $distance_in_arcsec of the object.

my $status = $star->within( $star2, $distance_in_arcsec )

returns true if this is the case.

misc

A hold-all method to contain information not covered by other methods.

my $misc = $item->misc;
$item->misc( $misc );

This accessor can hold any type of variable, although it is recommended that a hash reference is used for easier lookups:

my $misc = $item->misc;
my $vrad = $misc->{'vrad'};
my $vopt = $misc->{'vopt'}

Obsolete Methods

Several methods were made obsolete with the introduction of V4 of the Astro::Catalog class. These were magnitudes(), magerr(), colours() and colerr(). The functionality these supported is now part of the addfluxes() method.

General Methods

configure

Configures the object from multiple pieces of information.

$star->configure( %options );

Takes a hash as argument with the list of keywords. The keys are not case-sensitive and map to accessor methods.

Note that RA and Dec keys are allowed. The values can be supplied in either sexagesimal or decimal degrees.

COPYRIGHT

Copyright (C) 2001 University of Exeter. All Rights Reserved. Some modification are 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>,