#!/usr/bin/env perl
# -*- perl -*- 

# Graph the (science) data from a file
# Version: $Id: c_graph,v 2.2 2008/11/04 16:05:15 goeke Exp goeke $
# Assume data is from lf_hist in form
#    Channel D1 D2 D3 D4 D5 D6
#
########################################################################
# initial constants
########################################################################

$DIR = $ENV{CRATERTOOLS};   # needed to find stuff
$LLD = 10;                  # default LLD eliminates pure noise
$HLD = 4094;                # default HLD eliminates saturated events
$INFILE  = "cplot-temp-input.dat"; # if data comes from STDIN, we need
                                   # this for a temp spool file
$OUTFILE = "cplot.ps";      # default output print file
$DET = "123456";            # default detectors plotted

########################################################################
# Main program
########################################################################

&Setup;
&Display;
&Shutdown;
exit 0;

########################################################################
# Subroutines follow
########################################################################
########################################################################
# Display Results
# First line of the data determines how many columns we have;
#   so even if it is an info line, it needs to have the right count
# The first line may also have the serial number and time embedded
#   but it is discarded after reading, even if it was data
# We set up gnuplot, generate the print file first, then replot to xterm
########################################################################
sub Display {
    my ($ii,$jj,@line);

    @line = split(" ",<FILE>);             # get first line
    $Words .= ' --' if (defined($Words));   # Add to title if available
    if (!defined($Title)) {
	if ($line[0] =~ /^[0-9]/) {        # No header info in this file
	    my $bar = `date`; chop($bar);
	    $Title = sprintf("Data Processed %s",$bar);
	} else {
	    $Title = sprintf("%s CRaTER S/N %d\\nData starts at %s %s",
			     $Words,$line[3],$line[5],$line[6]);
	}
    }

    # NB gnuplot starts with terminal set to console display; i.e. x11
    if ($Plot) {
	$GNU_Header = "
set title \"$Title\"
set xlabel \"Time\"
set ylabel \"Value\"
set grid
$Log
"; 
    } else {
    $GNU_Header = "
set title \"$Title\"
set xlabel \"ADU\"
set ylabel \"Counts\"
set xrange [$LLD:$HLD]
set grid
$Log
";
}
    print DISP $GNU_Header;
#    print DISP "set multiplot layout 2,1 \n";

    my @graphs = split(" ",$Detectors);    # multiple detector plots?
    foreach $kk (@graphs) {
	print DISP "set terminal x11 $kk\nplot ";
	# After "plot" and first data set must insert comma before 
	#   each subsequent set, but not at the end!
	@line = split(" ",<FILE>) if $Plot;  # get second, mnemonic line
	for ($howmany=0,$jj=1; $jj<=$#line; $jj++) {
	    next if ($kk !~ /$jj/);
	    if ($Plot) {
		printf DISP "%s \"%s\" using 1:%d title \"%s\" $Plotopt", 
		$howmany?',':'', $File, $jj+1, "$line[$jj]";
		$howmany++;
	    } else {
		printf DISP "%s \"%s\" using 1:%d title \"%s\" with lines", 
		$howmany?',':'', $File, $jj+1, "D$jj";
		$howmany++;
	    }
	}
	print DISP "\nset terminal postscript landscape $PC\n"; 
	print DISP "replot\n";                # this puts plot into PS file
    }

    print DISP "q\n";                     # and quit gnuplot
    close DISP;

    my ($size,$name) = split(" ",`ls -s $PSOut`);    # Consistency check
    if ($size) {
	print ">>> Writing Postscript for printing to \"$PSOut\"\n";
	print ">>> Hit \"q\" in the xterm window to close it\n";
    } else {
	print "\n>>> *** No non-zero data to plot ***\n\n";
    }
}

########################################################################
# Give Help
########################################################################
sub Help {
    print "Usage: $0 [-a #] [-b #] [-c] [-d 246] [-h] [-l] \\
                  [-o outfile] [-t|T Title] [-v] [-z] [file_name]\n";

    $Detectors = $DET if (!defined($Detectors));

	print "
flags: -a #    specifies the lowest channel of interest [$LLD]
       -b #    specifies the highest channel of interest [$HLD]
       -c      make print file in color Postscript (default momochrome)
       -d      specifies the detector numbers of interest [$Detectors]
               there may be multiple -d flags yielding multiple plots
       -h      gets full help message
       -l      make plot scales linear (default is log-log)
       -L      make plot scale log-linear
       -o      specifies name of output print file [$PSOut]
       -t      add words to nominal plot title (S/N & date)
       -T      use following words as full title
       -v      makes the output verbose (to STDERR)
       -z      zipper the plot points together with lines
       file_nmae   read data from this file [STDIN]

Graphs a histogram of primary science data to an X window display.
Input data format must be {A/D_Channel Det1 Det2 Det3 ...}

" if ($Verbose);
}

########################################################################
# Do the setup
########################################################################
sub Setup {
    my ($foo,$linearX);
    my $gnuflags = '';         # default is no flags to gnuplot
    $PSOut = $OUTFILE;         # default plot file name
    $Display = 1;              # default is to generate X display output
    $PC = 'monochrome';        # default is to print in monochrome
    $Plot = 0;                 # default is to run as c_graph
    $Plotopt = "";             # default is to plot dots

    $0 =~ s@.*/(\w+)@$1@;     # trim off abosolute path, if given
    if ($0 =~ /c_graph/) {
	$Log = 'set logscale';     # default is log-log scale
    } elsif ($0 =~ /c_plot/) {
	$log = 'set linear';
	$Plot++;
	$Log = '';                   # use linear scale
	$linearX++;
    } else {
	die "called as unknown program namn";
    }
    while ($foo = shift(@ARGV)) {
	if ($foo =~ /^-[aA]/) {        # LLD flag
	    $LLD = shift(@ARGV);     # get number
	    if (!defined($LLD) || $LLD =~ /\D/) {
		print STDERR "Flag $foo requires numeric argument.\n";
		&Help; exit 2;
	    }
	    next;
	}
	if ($foo =~ /^-[bB]/) {        # HLD flag
	    $HLD = shift(@ARGV);     # get number
	    if (!defined($HLD) || $HLD =~ /[^0-9+]/) {
		print STDERR "Flag $foo requires numeric argument.\n";
		&Help; exit 2;
	    }
	    next;
	}
	if ($foo =~ /^-[cC]/) {        # print in color
	    $PC = "color";
	    next;
	}
	if ($foo =~ /^-[dD]/) {         # Detector select
	    if ($Plot) {
		print STDERR "flag $foo not valid to $0 program\n";
		&Help; exit 2;
	    }
	    $Detectors = $Detectors . " " . shift(@ARGV); 
	    if (!defined($Detectors) || $Detectors =~ /[^1-6] /) {
		print STDERR "Flag $foo requires numbers in range 1-6.\n";
		&Help; exit 2;
	    }
	    next;
	}
	if ($foo =~ /^-[hH]/) {
	    $Verbose++; &Help; exit 0;
	}
	if ($foo =~ /^-l/) {
	    $Log = '';                   # use linear scale
	    $linearX++;
	    next;
	}
	if ($foo =~ /^-L/) {
	    $Log = 'set logscale y';
	    $linearX++;
	    next;
	}
	if ($foo =~ /^-[oO]/) {          # Provide a graph title
	    $PSOut = shift(@ARGV);       # get the detector set
	    if (!defined($PSOut) || $PSOut =~ /^-/) {
		print STDERR "Flag $foo requires a following string\n";
		&Help; exit 2;
	    }
	    next;
	}
	if ($foo =~ /^-t/) {             # Provide a graph title
	    $Words = shift(@ARGV);       # get the detector set
	    if (!defined($Words) || $Words =~ /^-/) {
		print STDERR "Flag $foo requires a following string\n";
		&Help; exit 2;
	    }
	    $Words =~ s/\"//g;           # strip off quotes, if present
	    next;
	}
	if ($foo =~ /^-T/) {             # Provide a graph title
	    $Title = shift(@ARGV);       # get the detector set
	    if (!defined($Title) || $Title =~ /^-/) {
		print STDERR "Flag $foo requires a following string\n";
		&Help; exit 2;
	    }
	    $Title =~ s/\"//g;           # strip off quotes, if present
	    next;
	}
	if ($foo =~ /^-[vV]/) {          # verbose
	    $Verbose++;
	    next;
	}
	if ($foo =~ /^-[zZ]/) {           # connect the dots with lines
	    $Plotopt = "with lines";
	    next;
	}
	if ($foo =~ /^-/) {
	    print STDERR "Unknown flag: $foo\n";
	    &Help; exit 1;
	}
	if ($File) {
	    print STDERR "Too many input file names provided\n";
	    &Help; exit 1;
	} else {
	    $File = $foo;
	    next;
	}
    }

    $Detectors = $DET if (!defined($Detectors));
    if ($LLD < 1 && !$linearX) {
	print STDERR "LLD must be >0 if using log scale for ADU\n";
	&Help; exit 4;
    }

    if (!defined($File)) {
	print STDERR "Spooling STDIN to $INFILE\n" if $Verbose;
	$File = $INFILE;
	open(SPOOL,">$File") || 
	    die "Could not open spool file $File for write";
	print SPOOL while (<>);
	close SPOOL;
    } else {
	print STDERR "Using $File as input source\n" if $Verbose;
    }

    printf STDERR "Setting LLD to $LLD; setting HLD to $HLD\n" if ($Verbose);
    printf STDERR "Processing detectors $Detectors\n" if ($Verbose && !$Plot);

    open(FILE,"$File") || 
	die "Could not open input pipe";

    # NB although "persist" exists as a "set" option in gnuplot-4
    #    it must be a command line option in 3.7 (and must come first!)
    $foo = `which gnuplot`;
    if ($foo =~ /(^\/)|(^.\/)/) {
	$gnuflags .= " 2>/dev/null" if (!$Verbose);
	open(DISP,"| gnuplot -persist - $gnuflags  >$PSOut") ||
	    die "Could not open gnuplot pipe";
    } else {
	printf STDERR "Sorry, but could not find \"gnuplot\"\n";
	printf STDERR "   We looked in $ENV{PATH}\n";
	exit 5;
    }
}

########################################################################
# Clean up any mess -- remove spool file if used
# NB there would be a problem unlinking this file if the writes in
#   &Display haven't completed. So instead of using a non-buffered
#   output up there, we explicity close the pipe, which does a flush
#   before returning and coming down here  (it seems).
########################################################################
sub Shutdown {
    unlink $INFILE || die $!;  # doesn't actually care if $INFILE exists
}

########################################################################
# Pod follows
########################################################################

=for html 
<head><title>CRaTER -- c_graph, c_plot</title></head>

=head2 NAME

B<c_graph, c_plot> -- Generate histogram of primary science results

=head2 USAGE

     c_graph|c_plot [-a #] [-b #] [-c] [-d 246] [-h] [-l] [-o outfile] \
             [-t|T Title] [-v] [-z] [file_name]

=head2 FLAGS

       -a #    specifies the lowest channel/time of interest
       -b #    specifies the highest channel/time of interest
       -c      make print file in color Postscript
       -d      specifies the detector numbers of interest;
	       multiple -d flags result in multiple plots
       -h      gets full help message
       -l      make plot scales linear (default is log-log)
       -L      make plot scales log-linear
       -o      specify name of output print file
       -t      prefix default title information (s/n & date) with Title
       -T      replace default title information with Title
       -v      makes the output verbose (to STDERR)
       -z      zipper the plot points together with lines
       file_name   read data from this file; if not provided, use STDIN

=head2 DESCRIPTION

In the default case, we read a tab-separated histogram of science
data in the form {Channel D1 D2 D3 D4 D5 D6}, one entry per line.  
The lower and 
upper bounds of the channels of interest may be chosen with the B<-a>
and B<-b> flags, respectively.  The plot scales are log-log by
default, but may be set to either linear or log-linear.  The program
generates a Postscript file for printing in parallel with displaying
the plot in a separate X-window.

If multiple B<-d> flags with arguments are given, a separate plot is
made for each instance; in the Postscript file each plot appears on a
separate page in the common output file.

The program B<c_hist> generates histograms from raw CRaTER science packets
which are compatible with this program.  The first line in those histograms
is of the form

   ### CRaTER SerialNumber nn   Time    hh:mm:ss mm/dd/yy

If that line is present, B<c_graph> will label the plots with the 
instrument serial number and date the data was taken.

The plots will look cleaner if the B<-z> flag is used to plot using 
lines rather than points.  If there are discontinuities in the data,
however, the result can be misleading.

=head2 ENVIRONMENT

    perl5.002     Minimum version of Perl interpreter required
    gnuplot       This script works with version 3.7 and 4.0
    CRATERTOOLS   Environment variable containing path to CRaTER utilities

=head2 BUGS

The spool file for STDIN is hardcoded and both it and the Postscript
file are written to the current directory, rather than /tmp.  

=head2 SEE ALSO

lf_hist, gnuplot

=head2 AUTHOR

Bob Goeke

=head2 RCS Information

$Id: c_graph,v 2.2 2008/11/04 16:05:15 goeke Exp goeke $

=cut

########################################################################
# history follows
########################################################################

# $Log: c_graph,v $
# Revision 2.2  2008/11/04 16:05:15  goeke
# Expanded functionality to plot arbitrary engineering mnemonic values
# Now responds to "c_plot" as $0 as well as "c_graph" for histograms
#
# Revision 2.1  2007/05/04 13:45:40  goeke
# Name change from lf_graph and associated POD updates
#
# Revision 1.10  2007/05/04 12:49:36  goeke
# Edit help and POD
# Deal with lack of info line at top of data file
#
# Revision 1.9  2007/04/26 16:00:55  goeke
# Minor text edits in title and POD
#
# Revision 1.8  2007/04/26 15:44:20  goeke
# Use s/n and date info in first line for title
#
# Revision 1.7  2007/04/26 13:53:21  goeke
# Remove -w flag to specify window numbers (now part of multiple -d flags)
# Added check for zero length plot files so user isn't confused
# Added check for LLD>0 when using log on X axis
#
# Revision 1.6  2007/04/26 12:42:46  goeke
# Enable multiple -d flags
#
# Revision 1.5  2007/04/24 15:44:47  goeke
# Allows use of STDIN for data.
# By using "persist" on x11, gnuplot can now close right away.
#
# Revision 1.4  2007/04/24 14:04:23  goeke
# Converted to gnuplot
#
# Revision 1.3  2007/04/23 19:03:51  goeke
# Add flag to provide graph title; date is default
#
# Revision 1.2  2007/04/23 18:13:20  goeke
# Redid how printing was handled; numerous small changes.
#
# Revision 1.1  2007/04/20 17:22:34  goeke
# Initial revision
#
# Revision 1.1  2007/04/19 17:41:27  goeke
# Initial revision
#