view release on metacpan or  search on metacpan

Flux.pm  view on Meta::CPAN

package Astro::Flux;

=head1 NAME

Astro::Flux - Class for handling astronomical flux quantities.

=head1 SYNOPSIS

  use Astro::Flux;

  $flux = new Astro::Flux( $quantity, $units, $waveband );

  $quantity = $flux->quantity('mag');

=head1 DESCRIPTION

Class for handling astronomical flux quantities. This class does
not currently support conversions from one flux type to another
(say, from magnitudes to Janskies) but may in the future.

=cut

use 5.006;
use strict;
use warnings;
use warnings::register;
use Carp;

use Number::Uncertainty;

our $VERSION = '0.01';

=head1 METHODS

=head2 Constructor

=over 4

=item B<new>

Create a new instance of an C<Astro::Flux> object.

  $flux = new Astro::Flux( $quantity, $type, $waveband );

The first three parameters must be defined. They are:

  quantity - numerical value for the flux, my be a primitive, or a
             C<Number::Uncertainty> object.
  type - type of flux. Can be any string.
  waveband - waveband for the given flux. Must be an C<Astro::WaveBand> object.

If any of the parameters are undefined, the constructor will throw
an error. If the waveband parameter is not an C<Astro::WaveBand> object,
the constructor will throw an error.

The type is case-insensitive for lookups using the C<quantity> method.

A fourth optional argument may be passed; this is a hash containing
the following optional keys:

  quality - an C<Misc::Quality> object denoting quality flags for the
    C<Astro::Flux> object.
  reference_waveband - an C<Astro::WaveBand> object denoting a reference
    waveband for the C<Astro::Flux> object. This is used for determining
    magnitudes when deriving them from C<Astro::FluxColor> objects. See
    C<Astro::Fluxes>.
  datetime - an C<DateTime> object which is the datetime of observation for the
    measurement in the C<Astro::Flux> object.
  obsid - An array reference to a list of observation identifiers. Can be
    used to identify the observation(s) from which this measurement was
    taken (e.g. from a filename).

=cut

sub new {
  my $proto = shift;
  my $class = ref( $proto ) || $proto;

  my $quantity = shift;
  my $type = shift;
  my $waveband = shift;

  my %args = @_;

  croak "Quantity must be defined"
    unless defined $quantity;

  unless ( UNIVERSAL::isa($quantity, "Number::Uncertainty" ) ) {
     $quantity = new Number::Uncertainty( Value => $quantity );
  }

  croak "Type must be defined"
    unless defined $type;

  croak "Waveband must be defined"
    unless defined $waveband;

  unless ( UNIVERSAL::isa($waveband, "Astro::WaveBand") ) {
     $waveband = new Astro::WaveBand( Filter => $waveband );
  }

  my $flux = {};

  $flux->{QUANTITY} = { uc($type) => $quantity };
  $flux->{WAVEBAND} = $waveband;
  $flux->{TYPE} = uc( $type );

  if( defined( $args{'quality'} ) &&
      UNIVERSAL::isa( $args{'quality'}, "Misc::Quality" ) ) {
    $flux->{QUALITY} = $args{'quality'};
  }
  if( defined( $args{'reference_waveband'} ) &&
      UNIVERSAL::isa( $args{'reference_waveband'}, "Astro::WaveBand" ) ) {
    $flux->{REFERENCE_WAVEBAND} = $args{'reference_waveband'};
  }

  if( defined( $args{'datetime'} ) &&
      UNIVERSAL::isa( $args{'datetime'}, "DateTime" ) ) {
    $flux->{TIME} = $args{'datetime'};
  }

  if( defined( $args{'obsid'} ) ) {
    $flux->{OBSID} = $args{'obsid'};
  }

  bless( $flux, $class );
  return $flux;

}

=back

=head2 Accessor Methods

=over 4

=item B<quantity>

Returns the quantity for a requested flux type.

  my $mag = $flux->quantity('mag');

No conversions are done between types. What you put in via the
constructor is all you can get out, so if you specify the type
to be 'magnitude' and you ask for a 'mag', this method will
throw an error.

The type is case-insensitive.