Util::GTIlist (version 1.1)

package Util::GTIlist;
##############################################################################
#
# DESCRIPTION: This class handles a list of GTI extensions. In particular 
# DESCRIPTION: it handles merging GTIs by "or-ing" them. 
#
# HISTORY: 0.0 -> 1.0 2004-05-04 
# HISTORY: Now write DATE-OBS and DATE-END in the post-y2k
# HISTORY: format when merging.
#
# HISTORY: 1.0 -> 1.1 2004-05-26
# HISTORY: Now merge_and_append_to and merge_and_extract methods take an optional
# HISTORY: "operation" argument which is passed to the merge method.
# HISTORY: Also, no longer attempts to set TSTART/TSTOP, etc. if a merged
# HISTORY: GTI is empty.
#
# VERSION: 1.1
#
##############################################################################

use Util::FITSlist;
use Util::Stool;
@ISA=("Util::FITSlist");

use strict;


############################
# constructor
############################
sub new { #(file1, file2 ...)
    my $self=shift;
   
    ###########################################
    # inherit the generic FITSlist constructor
    ###########################################
    $self=$self->SUPER::new(@_);

    $self->{MERGED_EXT}="GTI";

    return $self;

} # end of constructor

#################
# ACCESSORS:
#################

#############################################################################
# Return the EXTNAME for the file which has been (or would be) returned
# by the merge method. This is either the defualt extension name or
# the name of the extension in the existing file if thewre is only one file.
# If you give an argument, then the default extension name will be set to that.
#############################################################################
sub merged_ext {
    my $self = shift;
    my $default = shift;
    
    if($default) {$self->{MERGED_EXT}=$default }

    if($self->count() == 1) { return $self->get_extension(); }
    else                    { return $self->{MERGED_EXT}; }
}


#################
# METHODS:
#################

#############################################################################
# merge the GTIs by "or-ing" them with the mgtime FTOOL.
# If there is only one file, it returns that file
#############################################################################
sub merge {
    my $self=shift;
    my $merged_file=shift;
    my $operation = shift || "OR";

    #####################################
    # if there's just one file return it
    #####################################
    if($self->count() == 1 ) {
        return $self->file(0);

    } 

    ####################################################
    # multiple GTI extensions, so we need to merge them
    ####################################################
    unlink $merged_file;
    my $merger = Util::Ftool->new("mgtime")
                            ->params({ingtis   => $self->as_param(),
                                      outgti   => $merged_file,
                                      merge    => $operation,
                                      instarts => "START",
                                      instops  => "STOP",
                                      indates  =>  "MJDREF",
                                      intimes  =>" ",
                                      outstart => "START",
                                      outstop  => "STOP"})
                            ->run();

    if($merger->had_error()) { return undef; }

    ##############################################
    # set the EXTNAME to "GTI", since mgtime
    # sets it to STDGTI - as a holdover from ASCA
    ##############################################
    my $fits = Util::FITSfile->new($merged_file, 1);
    $fits->keyword("EXTNAME", $self->{MERGED_EXT});

    ################################################
    # set the start and stop time and date keywords
    # does mgtime not do this?
    ################################################
    my $last_row = $fits->nrows();
    
    if($last_row != 0 ) {

        my $tstart = $fits->cols("START")->rows(1        )->table();
        my $tstop  = $fits->cols("STOP" )->rows($last_row)->table();

        $fits->keyword("TSTART", $tstart);
        $fits->keyword("TSTOP" , $tstop );

        my $start_date = Util::Date->new($tstart);
        my  $stop_date = Util::Date->new($tstop);

        $fits->keyword("DATE-OBS", $start_date->date() .'T'. $start_date->time());
        $fits->keyword("DATE-END",  $stop_date->date() .'T'.  $stop_date->time());
    }

    return $fits->name();

} # end of merge method

#############################################################################
# merge the GTIs and then append the result to a given FITS file
#############################################################################
sub merge_and_append_to {
    my $self = shift;
    my $target = shift;
    my $operation = shift;

    ############################
    # merge the GTIs
    ############################
    my $tmp = "gti_list_$self->{TMP_FILE_SUFFIX}";
    my $merged = $self->merge($tmp, $operation);
    unless(defined $merged) { return; }

    ########################
    # append to the target
    ########################
    Util::FITSfile->new($merged, $self->merged_ext())
                  ->append_to($target);

    unlink $tmp;

} # end of marge_and_append_to

#############################################################################
# merge the GTIs, forcing a new file to always be created - unlike the
# merge method which will just return the original file if there is only
# one file in the list.
# The EXTNAME of the merged/extracted file will always be the default.
#############################################################################
sub merge_or_extract {
    my $self = shift;
    my $newfile = shift;
    my $operation = shift;

    ############################
    # merge the GTIs
    ############################
    my $merged = $self->merge($newfile, $operation);
    unless(defined $merged) { return; }

    ########################################
    # if a merger happended then we are done
    ########################################
    if($merged eq $newfile) { return; }


    #################################################
    # no merger, so we need to extract the extension
    #################################################
    Util::FITSfile->new($merged, $self->merged_ext() )
                  ->extract($newfile);

    ##############################################
    # ... and then set the EXTNAME to the default
    ##############################################
    Util::FITSfile->new($newfile, 1)
                  ->keyword("EXTNAME", $self->{MERGED_EXT});


} # end of marge_and_append_to



    

   

   




1;