#!/usr/bin/env perl

# this program has two jobs:
# 1: for the given exp_tag, generate the binned & mosaiced JPEG images
# 2: examine the collection of per-imfile statistics and reject.  At the moment, 
#    this program (and the database) only allows rejection at the exposure level,
#    not at the imfile level. 

use Carp;
use warnings;
use strict;

## report the program and machine
use Sys::Hostname;
my $host = hostname();
print "\n\n";
print "Starting script $0 on $host\n\n";

use vars qw( $VERSION );
$VERSION = '0.01';

use IPC::Cmd 0.36 qw( can_run run );             # tools to run UNIX programs with control over I/O
use PS::IPP::Metadata::Config;                   # tools to parse the psMetadataConfig files
use PS::IPP::Metadata::Stats;

use PS::IPP::Metadata::List qw( parse_md_list ); # tools to parse a metadata into a hash list
use Statistics::Descriptive;                     # tools for calculating basic statistical quantities
use File::Temp qw( tempfile );                   # tools to construct temp files

use PS::IPP::Config qw($PS_EXIT_SUCCESS          
		       $PS_EXIT_UNKNOWN_ERROR
		       $PS_EXIT_SYS_ERROR
		       $PS_EXIT_CONFIG_ERROR
		       $PS_EXIT_PROG_ERROR
		       $PS_EXIT_DATA_ERROR
		       $PS_EXIT_TIMEOUT_ERROR
		       caturi
		       );                        # tools to parse the IPP configuration information
my $ipprc = PS::IPP::Config->new(); # IPP configuration

use Getopt::Long qw( GetOptions :config auto_help auto_version gnu_getopt ); # option parsing
use Pod::Usage qw( pod2usage ); 

# parse the command-line options
my ( $det_id, $iter, $exp_id, $exp_tag, $det_type, $camera, $filter, $reject, $outroot, $dbname, $reduction,
     $verbose, $no_update, $no_op );
GetOptions(
	   'det_id|d=s'        => \$det_id,
	   'iteration=s'       => \$iter,
	   'exp_id|e=s'        => \$exp_id,
	   'exp_tag|=s'        => \$exp_tag,
	   'det_type|t=s'      => \$det_type,
	   'camera=s'          => \$camera,
	   'outroot|w=s'       => \$outroot,   # output file base name
	   'filter=s'          => \$filter,
	   'reject'            => \$reject,
	   'dbname|d=s'        => \$dbname, # Database name
	   'reduction|=s'      => \$reduction,
	   'verbose'           => \$verbose,   # Print to stdout
	   'no-update'         => \$no_update,
	   'no-op'             => \$no_op,
	   ) or pod2usage( 2 );

pod2usage( -msg => "Unknown option: @ARGV", -exitval => 2 ) if @ARGV;
pod2usage( -msg => "Required options: --det_id --iteration --exp_id --exp_tag --det_type --camera --outroot",
	   -exitval => 3) unless 
    defined $det_id   and 
    defined $iter     and 
    defined $exp_id   and 
    defined $exp_tag  and 
    defined $det_type and 
    defined $camera   and
    defined $outroot;

# load IPP config information for the specified camera
$ipprc->define_camera($camera);

# Recipes to use based on reduction class
$reduction = 'DETREND' unless defined $reduction;

my $recipe1 = $ipprc->reduction($reduction, 'JPEG_BIN1_RESID_' . uc($det_type)); # Recipe to use
&my_die("Unrecognised detrend type: $det_type", $det_id, $iter, $PS_EXIT_PROG_ERROR) unless defined $recipe1;

my $recipe2 = $ipprc->reduction($reduction, 'JPEG_BIN2_RESID_' . uc($det_type)); # Recipe to use
&my_die("Unrecognised detrend type: $det_type", $det_id, $iter, $PS_EXIT_PROG_ERROR) unless defined $recipe2;

# values to extract from output metadata and the stats to calculate
# XXX -bg_mean_stdev should take rms of bg_mean_stdev if bg_mean_stdev != 0 (A)
# XXX -bg_mean_stdev should take stdev of bg_mean if bg_mean_stdev == 0     (B)
# XXX  (A) if imfile.Ncomp > 1, (B) if imfile.Ncomp == 1
my $STATS = 
    [
	#          KEYWORD                 STATISTIC          CHIPTOOL FLAG
	{ name => "bg",             type => "mean",  flag => "-bg",            dtype => "float" },
	{ name => "bg_mean_stdev",  type => "stdev", flag => "-bg_mean_stdev", dtype => "float" },
	{ name => "bg_stdev",       type => "rms",   flag => "-bg_stdev",      dtype => "float" },  
	{ name => "bg_skewness",    type => "mean",  flag => "-bg_skewness",   dtype => "float" },  
	{ name => "bg_kurtosis",    type => "mean",  flag => "-bg_kurtosis",   dtype => "float" },  
	{ name => "bin_stdev",      type => "rms",   flag => "-bin_stdev",     dtype => "float" },
	{ name => "fringe_0",       type => "mean",  flag => "-fringe_0",      dtype => "float" },
	{ name => "fringe_1",       type => "rms",   flag => "-fringe_1",      dtype => "float" },
	{ name => "fringe_0",       type => "stdev", flag => "-fringe_2",      dtype => "float" },
	{ name => "user_1",         type => "mean",  flag => "-user_1",	       dtype => "float" }, # fringe residual
	{ name => "user_2",         type => "rms",   flag => "-user_2",	       dtype => "float" }, # fringe residual
	{ name => "user_1",         type => "stdev", flag => "-user_3",	       dtype => "float" }, # fringe residual
	];
my $stats = PS::IPP::Metadata::Stats->new($STATS); # Stats parser

# Look for programs we need
my $missing_tools;
my $dettool = can_run('dettool') or (warn "Can't find dettool" and $missing_tools = 1);
my $ppImage = can_run('ppImage') or (warn "Can't find ppImage" and $missing_tools = 1);
if ($missing_tools) { 
    warn("Can't find required tools.");
    exit($PS_EXIT_CONFIG_ERROR); 
}

# Get list of imfile files
my ($files, $command, $success, $error_code, $full_buf, $stdout_buf, $stderr_buf);
{
    # dettool command to select imfile data for this exp_id
    $command  = "$dettool -residimfile";
    $command .= " -det_id $det_id";
    $command .= " -iteration $iter";
    $command .= " -exp_id $exp_id";
    $command .= " -dbname $dbname" if defined $dbname;
    ( $success, $error_code, $full_buf, $stdout_buf, $stderr_buf ) =
	run(command => $command, verbose => $verbose);
    unless ($success) {
	$error_code = (($error_code >> 8) or $PS_EXIT_PROG_ERROR);
	warn("Unable to perform dettool -residimfile: $error_code\n");
	exit($error_code);
    }
    # XXX report an error message if stdout_buf is empty

    # Parse the stdout buffer into a metadata
    my $mdcParser = PS::IPP::Metadata::Config->new;	
    my $metadata = $mdcParser->parse(join "", @$stdout_buf) or
	&my_die("Unable to parse metadata config doc", $det_id, $iter, $exp_id, $PS_EXIT_PROG_ERROR);

    # parse the file info in the metadata
    $files = parse_md_list($metadata) or
	&my_die("Unable to parse metadata list", $det_id, $iter, $exp_id, $PS_EXIT_PROG_ERROR);

    # Parse the statistics on the residual image
    $stats->parse($metadata) or &my_die("Unable to find all values in statistics output.", $det_id, $iter, $exp_id, $PS_EXIT_PROG_ERROR);
}

# outroot examples (HOST components must be set)
# file://data/ipp004.0/gpc1/20080130
# neb:///ipp004-v1/gpc1/20080130
# neb:///*/gpc1/20080130 (volume not specified)

# check for existing directory, generate if needed
$ipprc->outroot_prepare($outroot);

my $jpeg1Name  = $ipprc->filename("PPIMAGE.JPEG1", $outroot); # Binned JPEG #1
my $jpeg2Name  = $ipprc->filename("PPIMAGE.JPEG2", $outroot); # Binned JPEG #2
my $logName    = $ipprc->filename("LOG.EXP",       $outroot); # Name for log

my $logFile;
unless ($no_op) {
    $logFile = $ipprc->file_create_append( $logName );
}

# XXX in debug mode, unlink = 0
my ($list1File, $list1Name) = tempfile( "$exp_tag.detresid.$det_id.$iter.b1.list.XXXX", UNLINK => 1 );
my ($list2File, $list2Name) = tempfile( "$exp_tag.detresid.$det_id.$iter.b2.list.XXXX", UNLINK => 1 );
foreach my $file (@$files) {
    print $list1File ($ipprc->filename( "PPIMAGE.BIN1", $file->{path_base}, $file->{class_id} ) . "\n");
    print $list2File ($ipprc->filename( "PPIMAGE.BIN2", $file->{path_base}, $file->{class_id} ) . "\n");
}
close $list1File;
close $list2File;


# build the JPEG images
unless ($no_op) {
    # Make the jpeg for binning 1
    $command = "$ppImage -list $list1Name $outroot -recipe PPIMAGE $recipe1"; # Command to run
    ( $success, $error_code, $full_buf, $stdout_buf, $stderr_buf ) =
	run(command => $command, verbose => $verbose);
    unless ($success) {
	$error_code = (($error_code >> 8) or $PS_EXIT_PROG_ERROR);
	&my_die("Unable to run ppImage: $error_code", $det_id, $iter, $exp_id, $error_code);
    }
    &my_die("Unable to find expected output file: $jpeg1Name", $det_id, $iter, $exp_id, $PS_EXIT_SYS_ERROR) unless -f $ipprc->file_resolve($jpeg1Name);
    
    # Make the jpeg for binning 2
    $command = "$ppImage -list $list2Name $outroot -recipe PPIMAGE $recipe2"; # Command to run
    ( $success, $error_code, $full_buf, $stdout_buf, $stderr_buf ) =
	run(command => $command, verbose => $verbose);
    unless ($success) {
	$error_code = (($error_code >> 8) or $PS_EXIT_PROG_ERROR);
	&my_die("Unable to run ppImage: $error_code", $det_id, $iter, $exp_id, $error_code);
    }
    &my_die("Unable to find expected output file: $jpeg2Name", $det_id, $iter, $exp_id, $PS_EXIT_SYS_ERROR) unless -f $ipprc->file_resolve($jpeg2Name);
}

#### measure stats and reject if needed ####

# Rejection thresholds & related data
my $expected                = rejection_limit( 'EXPECTED',         $det_type, $filter );
my $reject_imfile_mean      = rejection_limit( 'IMFILE.MEAN',      $det_type, $filter );
my $reject_imfile_flux      = rejection_limit( 'IMFILE.FLUX',      $det_type, $filter );
my $reject_imfile_stdev     = rejection_limit( 'IMFILE.STDEV',     $det_type, $filter );
my $reject_imfile_skewness  = rejection_limit( 'IMFILE.SKEWNESS',  $det_type, $filter );
my $reject_imfile_kurtosis  = rejection_limit( 'IMFILE.KURTOSIS',  $det_type, $filter );
my $reject_imfile_meanstdev = rejection_limit( 'IMFILE.MEANSTDEV', $det_type, $filter );
my $reject_imfile_snr       = rejection_limit( 'IMFILE.SNR',       $det_type, $filter );
my $reject_imfile_bin_stdev = rejection_limit( 'IMFILE.BIN.STDEV', $det_type, $filter );
my $reject_imfile_bin_snr   = rejection_limit( 'IMFILE.BIN.SNR',   $det_type, $filter );
my $reject_exp_mean         = rejection_limit( 'EXP.MEAN',         $det_type, $filter );
my $reject_exp_flux         = rejection_limit( 'EXP.FLUX',         $det_type, $filter );
my $reject_exp_stdev        = rejection_limit( 'EXP.STDEV',        $det_type, $filter );
my $reject_exp_meanstdev    = rejection_limit( 'EXP.MEANSTDEV',    $det_type, $filter );
my $reject_exp_snr          = rejection_limit( 'EXP.SNR',          $det_type, $filter );
my $reject_exp_bin_stdev    = rejection_limit( 'EXP.BIN.STDEV',    $det_type, $filter );
my $reject_exp_bin_snr      = rejection_limit( 'EXP.BIN.SNR',      $det_type, $filter );

# storage array
my @fluxes;

foreach my $file (@$files) {
    my $name      = $file->{class_id};
    my $mean      = $file->{bg};	# Mean for this imfile
    my $stdev     = $file->{bg_stdev}; # Stdev for this imfile
    my $skewness  = $file->{bg_skewness}; # Skewness for this imfile
    my $kurtosis  = $file->{bg_kurtosis}; # Kurtosis for this imfile
    my $meanStdev = $file->{bg_mean_stdev}; # Stdev of Means for this imfile
    my $binStdev  = $file->{bin_stdev}; # Binned Stdev for this imfile

    # calculate and save the fluxes
    my $flux;
    if ($file->{exp_time} == 0.0) {
	$flux = $mean;
    } else {
	$flux = $mean / $file->{exp_time};
    }
    push @fluxes, $flux;

    $mean -= $expected;

    last if $no_op;

    # reject exposure if, for any imfiles, the mean residual counts
    # deviate from the expected value by more than N sigma, (sigma =
    # total pixel variance).  this test is sensible for images which
    # should have a predictable nominal residual mean count value (eg,
    # 0.0 for a bias).   in general, use with ADDITIVE components
    if ($reject_imfile_mean > 0) {
	if (abs($mean) > $reject_imfile_mean * $stdev) {
	    print $logFile "Rejecting exposure based on bad imfile mean for $name: ";
	    $reject = 1;
	} else {
	    print $logFile "Imfile mean for $name meets requirements: ";
	}
	print $logFile "$mean vs $reject_imfile_mean * $stdev\n";
    }  else {
	print $logFile "No rejection on imfile mean for $name\n";
    }

    # reject exposure if, for any imfiles, the mean residual flux
    # deviates from the expected value by more than N sigma, (sigma =
    # total pixel variance).  this test is sensible for images which
    # should have a predictable nominal residual flux value (eg, 0.0
    # for a bias).  in general, use with ADDITIVE components
    if ($reject_imfile_flux > 0) {
	if (abs($flux) > $reject_imfile_flux) {
	    print $logFile "Rejecting exposure based on bad imfile flux for $name: ";
	    $reject = 1;
	} else {
	    print $logFile "Imfile flux for $name meets requirements: ";
	}
	print $logFile "$flux vs $reject_imfile_flux\n";
    }  else {
	print $logFile "No rejection on imfile flux for $name\n";
    }

    # reject exposure if, for any imfiles, the total pixel variance is
    # larger than the limit
    if ($reject_imfile_stdev > 0) {
	if ($stdev > $reject_imfile_stdev) {
	    print $logFile "Rejecting exposure based on bad imfile stdev for $name: ";
	    $reject = 1;
	} else {
	    print $logFile "Imfile stdev for $name meets requirements: ";
	}
	print $logFile "$stdev vs $reject_imfile_stdev\n";

    } else {
	print $logFile "No rejection on imfile stdev for $name\n";
    }

    # reject exposure if, for any imfiles, the skewness is
    # larger than the limit
    if ($reject_imfile_skewness > 0) {
	if ($stdev > $reject_imfile_skewness) {
	    print $logFile "Rejecting exposure based on bad imfile skewness for $name: ";
	    $reject = 1;
	} else {
	    print $logFile "Imfile skewness for $name meets requirements: ";
	}
	print $logFile "$skewness vs $reject_imfile_skewness\n";

    } else {
	print $logFile "No rejection on imfile skewness for $name\n";
    }

    # reject exposure if, for any imfiles, the kurtosis is
    # larger than the limit
    if ($reject_imfile_kurtosis > 0) {
	if ($stdev > $reject_imfile_kurtosis) {
	    print $logFile "Rejecting exposure based on bad imfile kurtosis for $name: ";
	    $reject = 1;
	} else {
	    print $logFile "Imfile kurtosis for $name meets requirements: ";
	}
	print $logFile "$kurtosis vs $reject_imfile_kurtosis\n";

    } else {
	print $logFile "No rejection on imfile kurtosis for $name\n";
    }

    # reject exposure if, for any imfiles, the variance of the imfile
    # component means is larger than the limit
    if ($reject_imfile_meanstdev > 0) {
	if ($meanStdev > $reject_imfile_meanstdev) {
	    print $logFile "Rejecting exposure based on bad imfile mean stdev for $name: ";
	    $reject = 1;
	} else {
	    print $logFile "Imfile mean stdev for $name meets requirements: ";
	}
	print $logFile "$meanStdev vs $reject_imfile_meanstdev\n";
    } else {
	print $logFile "No rejection on imfile mean stdev for $name\n";
    }

    # reject exposure if, for any imfiles, the signal-to-noise (ie,
    # the mean counts / total pixel variance) of the imfile component
    # means are less than the limit.  this test is sensible for images
    # which have finite residual flux such as a flat-field image.  
    if ($reject_imfile_snr > 0) {
	if ($mean < $stdev * $reject_imfile_snr) {
	    print $logFile "Rejecting exposure based on bad imfile S/N for $name: ";
	    $reject = 1;
	} else {
	    print $logFile "Imfile S/N for $name meets requirements: ";
	}
	print $logFile "mean: $mean vs stdev*SNlimit: " . $stdev * $reject_imfile_snr . "\n";
    } else {
	print $logFile "No rejection on imfile S/N for $name\n";
    }

    # reject exposure if, for any imfiles, the signal-to-noise of the
    # imfile component means, based on the stdev of the binned image
    # is less than the limit.  this test is sensible for images which
    # have finite residual flux such as a flat-field image.
    if ($reject_imfile_bin_stdev > 0) {
	if ($binStdev > $reject_imfile_bin_stdev) {
	    print $logFile "Rejecting exposure based on bad imfile binned stdev for $name: ";
	    $reject = 1;
	} else {
	    print $logFile "Imfile binned stdev for $name meets requirements: ";
	}
	print $logFile "$binStdev vs $reject_imfile_bin_stdev\n";
    } else {
	print $logFile "No rejection on imfile binned stdev for $name\n";
    }
    if ($reject_imfile_bin_snr > 0) {
	if ($mean < $binStdev * $reject_imfile_bin_snr) {
	    print $logFile "Rejecting exposure based on bad imfile binned S/N for $name: ";
	    $reject = 1;
	} else {
	    print $logFile "Imfile binned S/N for $name meets requirements: ";
	}
	print $logFile "mean: $mean vs binStdev*SNlimit: " . $binStdev * $reject_imfile_bin_snr . "\n";
    } else {
	print $logFile "No rejection on imfile binned S/N for $name\n";
    }
}

# basic ensemble stats
my $mean      	       = $stats->value_for_flag ("-bg");
my $meanStdev 	       = $stats->value_for_flag ("-bg_mean_stdev");
my $stdev     	       = $stats->value_for_flag ("-bg_stdev");
my $binStdev  	       = $stats->value_for_flag ("-bin_stdev");
my $fringe_mean        = $stats->value_for_flag ("-fringe_0");
my $fringe_err         = $stats->value_for_flag ("-fringe_1");
my $fringe_mean_stdev  = $stats->value_for_flag ("-fringe_2");
my $dfringe_mean       = $stats->value_for_flag ("-fringe_resid_0");
my $dfringe_err        = $stats->value_for_flag ("-fringe_resid_1");
my $dfringe_mean_stdev = $stats->value_for_flag ("-fringe_resid_2");

# other stats (flux depends on bg and exp_time)
my $fluxStats = Statistics::Descriptive::Sparse->new();	# Statistics calculator for means
$fluxStats->add_data(@fluxes);
my $flux = $fluxStats->mean();	# Mean of the imfile means

# other stats
my $exp_snr = 0.0;
if ($stdev > 0) { $exp_snr = $mean / $stdev; }

## Reject based on the exposure ensemble stats
# reject if the exposure ensemble mean is deviant
unless ($no_op) {
    print $logFile "Exposure mean $mean, stdev $stdev, mean stdev $meanStdev, exp s/n: $exp_snr\n";

    # reject exposure if the ensemble mean residual counts deviate
    # from the expected value by more than N sigma, (sigma = total
    # pixel variance).  this test is sensible for images which should
    # have a predictable nominal residual mean count value (eg, 0.0
    # for a bias).  in general, use with ADDITIVE components
    if ($reject_exp_mean > 0) {
	if (abs($mean) > $reject_exp_mean * $stdev) {
	    print $logFile "Rejecting exposure based on bad mean counts: ";
	    $reject = 1;
	} else {
	    print $logFile "Exposure mean counts meets requirements: ";
	}
	print $logFile "mean: $mean, stdev: $stdev (limit is: " . $reject_exp_mean * $stdev . ") \n";
    } else {
	print $logFile "No rejection for exp mean\n";
    }

    # reject exposure if, for any imfiles, the mean residual flux
    # deviates from the expected value by more than N sigma, (sigma =
    # total pixel variance).  this test is sensible for images which
    # should have a predictable nominal residual flux value (eg, 0.0
    # for a bias).  in general, use with ADDITIVE components
    if ($reject_exp_flux > 0) {
	if (abs($flux) > $reject_exp_flux * $stdev) {
	    print $logFile "Rejecting exposure based on bad mean flux: ";
	    $reject = 1;
	} else {
	    print $logFile "Exposure mean flux meets requirements: ";
	}
	print $logFile "flux: $flux, stdev: $stdev (limit is: " . $reject_exp_flux * $stdev . ")\n";
    } else {
	print $logFile "No rejection for exp mean\n";
    }

    # reject exposure if the total pixel variance is larger than the
    # limit
    if ($reject_exp_stdev > 0) {
	if ($stdev > $reject_exp_stdev) {
	    print $logFile "Rejecting exposure based on bad stdev: ";
	    $reject = 1;
	} else {
	    print $logFile "Exposure stdev meets requirements: ";
	}
	print $logFile "$stdev vs $reject_exp_stdev\n";
    } else {
	print $logFile "No rejection for exp stdev\n";
    }

    # reject exposure if the variance of the imfile means is larger
    # than the limit
    if ($reject_exp_meanstdev > 0) {
	if ($meanStdev > $reject_exp_meanstdev) {
	    print $logFile "Rejecting exposure based on bad mean stdev: ";
	    $reject = 1;
	} else {
	    print $logFile "Exposure mean stdev meets requirements: ";
	}
	print $logFile "$meanStdev vs $reject_exp_meanstdev\n";
    } else {
	print $logFile "No rejection for exp mean stdev\n";
    }

    # reject if the signal-to-noise is insufficient
    if ($reject_exp_snr > 0) {
	if (abs($mean) < abs($stdev * $reject_exp_snr)) {
	    print $logFile "Rejecting exposure based on poor S/N: \n";
	    $reject = 1;
	} else {
	    print $logFile "Exposure S/N meets requirements: \n";
	}
	print $logFile "signal: $mean vs noise: $stdev (s/n limit is: $reject_exp_snr)\n";
    } else {
	print $logFile "No rejection for exp S/N\n";
    }
    # reject if the exposure ensemble stdev is deviant
    if ($reject_exp_bin_stdev > 0) {
	if ($binStdev > $reject_exp_bin_stdev) {
	    print $logFile "Rejecting exposure based on bad binned stdev: ";
	    $reject = 1;
	} else {
	    print $logFile "Exposure binned stdev meets requirements: ";
	}
	print $logFile "$stdev vs $reject_exp_bin_stdev\n";
    } else {
	print $logFile "No rejection for exp binned stdev\n";
    }
    # reject if the signal-to-noise is insufficient
    if ($reject_exp_bin_snr > 0) {
	if (abs($mean) < abs($binStdev * $reject_exp_bin_snr)) {
	    print $logFile "Rejecting exposure based on poor binned S/N: \n";
	    $reject = 1;
	} else {
	    print $logFile "Exposure binned S/N meets requirements: \n";
	}
	print $logFile "signal: $mean vs noise: $binStdev (s/n limit is: $reject_exp_bin_snr)\n";
    } else {
	print $logFile "No rejection for exp binned S/N\n";
    }

    close $logFile;
}

$command  = "$dettool -addresidexp -det_id $det_id -iteration $iter -exp_id $exp_id";
$command .= " -recip $recipe1,$recipe2 -path_base $outroot ";
$command .= ' -reject' if $reject;
$command .= " -dbname $dbname" if defined $dbname;
$command .= $stats->cmdflags();

unless ($no_update) {
    ( $success, $error_code, $full_buf, $stdout_buf, $stderr_buf ) =
	run(command => $command, verbose => $verbose);
    unless ($success) {
	$error_code = (($error_code >> 8) or $PS_EXIT_PROG_ERROR);
	warn("Unable to perform dettool -addresidexp: $error_code\n");
	exit($error_code);
    }
} else {
    print "skipping command: $command\n";
}

END {
    my $status = $?;
    system("sync") == 0
        or die "failed to execute sync: $!" ;
    $? = $status;
}


sub my_die
{
    my $msg = shift; # Warning message on die
    my $det_id = shift;		# Detrend identifier
    my $iter = shift;		# Iteration
    my $exp_id = shift; # Exposure tag
    my $exit_code = shift; # Exit code to add

    carp($msg);
    if (defined $det_id and defined $iter and defined $exp_id and not $no_update) {
	my $command = "$dettool -addresidexp";
	$command .= " -det_id $det_id";
	$command .= " -iteration $iter";
	$command .= " -exp_id $exp_id";
	$command .= " -code $exit_code";
	$command .= " -dbname $dbname" if defined $dbname;
        system ($command);
    }
    exit $exit_code;
}

# Retrieve the requested rejection limit, dying if not extant
sub rejection_limit
{
    my $name = shift;		# Rejection limit to 
    my $type = shift;		# Type of exposure
    my $filter = shift;		# Filter

    my $value = $ipprc->rejection( $name, $det_type, $filter );
    if (not defined $value) {
	$filter = "(no filter)" if not defined $filter;
	die "Unable to determine $name rejection limit for $det_type with $filter.\n";
    }

    return $value;
}

__END__

####

## this function is not well though out.  it loads a collection of
## values (background mean and stdev) for a collection of imfile
## subcomponents.  it then measures the mean background, the
## background stdev (rms of ensemble stdevs), and the background mean
## stdev (rms of the means).  it then tries to reject based on the
## following criteria:
## (background / stdev > limit) for a single component
##    ---> this will ACCEPT for a poor images (large stdev)
## (stdev > limit)
## (mean background / stdev > limit) same problem
## (mean stdev > limit)

### I would suggest the following:
## 1) calculate the ensemble mean and stdev
## 2) for each component, is the (back - mean) / mean stdev > limit?
##    (ie, is it an outlier?)
## 3) is the component stdev > limit? (absolute test)
## 4) calculate the background stdev for the ensemble (excluding rejects)
## 5) is the mean stdev > limit (poor images)
## 6) calculate the ensemble stdev (rms) of remaining (excluding rejects)
## 7) is the ensemble stdev > limit 

## for flats, the value used for stdev should be the fractional stdev
## (stdev/mean) and no rejection should be performed on the basis of
## the mean value, but could still be done on the mean stdev

## the same logical cuts above can be applied to components in an
## imfile, imfiles in an exposure, and exposures in a stack

### this function needs to avoid div by zero: compare Signal vs Noise*limit
