view release on metacpan or  search on metacpan

lib/Astro/Catalog.pm  view on Meta::CPAN

        $self->{AUTO_OBSERVE} = shift;
    }
    return $self->{AUTO_OBSERVE};
}

=item B<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.

=cut

sub misc {
    my $self = shift;
    if (@_) {
        $self->{'MISC'} = shift;
    }
    return $self->{'MISC'};
}

=back

=head2 General Methods

=over 4

=item B<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).

=cut

sub configure {
    my $self = shift;

    # return unless we have arguments
    return $self unless @_;

    # grab the argument list
    my %args = @_;

    # Go through hash and downcase all keys
    %args = _normalize_hash(%args);

    # Check for deprecation
    if (exists $args{cluster}) {
        warnings::warnif("deprecated",
                "Cluster option now deprecated. Use Format => 'Cluster', File => file instead");
        $args{file} = $args{cluster};
        $args{format} = 'Cluster';
    }

    # Define the actual catalog

    # Stars has priority
    if (defined $args{stars}) {
        # grab the array reference and stuff it into the object
        $self->pushstar( @{ $args{stars} } );

        # Make sure we do not loop over this later
        delete( $args{stars} );

    }
    elsif (defined $args{format}) {
        # Need to read the IO class
        my $ioclass = _load_io_plugin($args{format});
        return unless defined $ioclass;

        # Now read the catalog (overwriting $self)
        print "# READING CATALOG $ioclass \n" if $DEBUG;
        $self = $ioclass->read_catalog(
            File => $args{file},
            Data => $args{data},
            ReadOpt => $args{readopt});

        croak "Error reading catalog of class $ioclass\n"
            unless defined $self;

        # Remove used args
        delete $args{format};
        delete $args{file};
        delete $args{data};
        delete $args{readopt};
    }

    # Define the field centre if provided
    $self->fieldcentre(%args);

lib/Astro/Catalog.pm  view on Meta::CPAN

=cut

sub filter_by_observability {
    my $self = shift;

    $self->force_ref_time;
    my $ref = $self->stars;

    # For each star, extract the coordinate object and, if defined
    # check for observability
    @$ref = grep {$_->coords->isObservable} grep {$_->coords;} @$ref;
    return $self->stars if wantarray;
}

=item B<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 C<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 C<popstarbyid> for a similar method that returns stars
that are an exact match to ID and removes them from the current
list.

=cut

sub filter_by_id {
    my $self = shift;
    my $id = shift;

    # Convert to regex if required
    unless (ref $id) {
        $id = quotemeta($id);
        $id = qr/$id/i;
    }

    return $self->filter_by_cb(sub {$_[0]->id =~ $id;});
}

=item B<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 C<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)

=cut

sub filter_by_distance {
    my $self = shift;
    croak "Must be at least one argument"
        unless scalar(@_) > 0;

    # Read the arguments
    my $radius = shift;
    my $refpos = shift;
    $refpos = $self->reference unless defined $refpos;

    croak "Reference position not defined"
        unless defined $refpos;

    croak "Reference must be an Astro::Coords object"
        unless UNIVERSAL::isa($refpos, "Astro::Coords");

    # Calculate distance and throw away outliers
    return $self->filter_by_cb(sub {
        my $star = shift;
        my $c = $star->coords;
        return if not defined $c;
        my $dist = $refpos->distance($c);
        return if not defined $dist;
        return $dist < $radius;
    });
}

=item B<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/;});

=cut

sub filter_by_cb {
    my $self = shift;
    my $cb = shift;

    croak "Callback has to be a reference to a subroutine"
        unless ref($cb) eq "CODE";

    # Get reference to array (force copy)
    my $ref = $self->stars;

    @$ref = grep {$cb->($_);} @$ref;
    return $self->stars;
}

=back