---------------------------------------------
PHAPLOT.PRO - Stephen Randall, Robert DiFabio
---------------------------------------------

1. OVERVIEW

    phaplot.pro is an IDL program located in ~/IDL/Master_Program. It can create xdr data files, as
    well as a wide number of plots/histograms involving M, Q, and M/Q. It is one of the two main
    programs that you'll use to analyze Cassini/MIMI/CHEMS data [the other is phaflux.pro].
    
    As you use the program, note that there is a helpful status label that attempts to tell you the
    progress of your current operation.
    
2. RUNNING PHAPLOT

    To run the program, open a Terminal window and enter the command "phaplot". This will compile
    all the necessary routines and open phaplot.pro. Alternatively, you may enter IDL by typing "idl"
    into the Terminal [idlmp opens IDL inside Master_Program], manually compiling each necessary
    routine [".r time_conv", ".r plot_proc", ".r cassini_analysis", ".r ephem_analysis", ".r phaplot"],
    and then running phaplot by entering "phaplot". Note that to enter these manually, your present
    working IDL directory must be Master_Program and that X11 must be open. It is highly recommended
    that you simply use the command provided to save time and avoid errors.
    
3. CREATING XDR FILES
    
    To create an xdr file, open phaplot. Note that most values have been filled in for you already,
    and that you should have good reason to change them. First, decide whether you want to enter a
    list of time ranges or a single time range, and ensure the correct radio button is pressed.
    
    Time Range List: Click "Edit", and add your time periods to the list. Note that the first line
    should read "Time Range(yyyy ddd hhmm)". This helps you remember what values to enter, so no data
    should be in the first line [phaplot actually skips it completely].
    
    Single Time Range: Simply enter your starting time, ending time. Note that this is the same
    information provided to phaflux in the time range list option, but is easier than editing a text
    file if you only want a single xdr file.
    
    xdr files hold data for Mass and MPQ Histograms, Mass v. MPQ plots, Mass v. Time plots, and MPQ
    v. Time plots. The six fields below the time range input allow you to set various parameters on
    the data held in the xdr file. The fractional bins give the bin sizes for their respective
    plots, the DPPS steps give the energy level of ions in the range [see the description at the
    CHEMS page for more info] where 0-7, 8-15, 16-23, 24-31, or 0-31 are the standard ranges ["all"
    makes xdr files for each of the standard ranges], and the time bins are the dT's in the v. time
    plots specified.
    
    To change where the xdr file is created, edit the path in "Output Directory". The default value
    is most often used for the website plots that are automatically created, so you may wish to
    instead place the file on the Desktop for easy access.
    
    The path in "PHA Directory" points to the PHA data files.This will almost never need to be changed.
    
4. WEBSITE PLOTS

    The CHEMS page shows MPQ v. time plots in 20 periods for each of the standard energy ranges. While
    the script will generate the plots on the website automatically, there may come a time when you
    wish to create one manually. The lower section on the "Get PHA Data" tab exists for this purpose,
    and is fairly self-explanatory. For more information on the ephemeris files, see the next section.
    
    The reason that this section exists is to facilitate standard plots without much customization,
    as the plotting tab is somewhat intimidating for someone simply trying to create a website-style
    plot.
    
5. PLOTTING

    To create a non-website plot, go to the "Plot PHA Data" tab. Either edit an xdr list, or select
    a single xdr file to use. Note that with a list of xdr files, the top line isn't read and that
    the start and stop times must be included. Also note that for any v. time plot, the list of xdr
    files need to be contiguous in time.
    
    The ephemeris files must be kept up to date; if the time range you wish to plot is outside
    their range, you'll need to update those [see the website script document]. You may ignore the
    ephemeris files if your plots are not v. time.
    
    Choose the type of plot you want to make, and select it from the "Get Data" drop down menu. This
    will either fill in the necessary values, or exit if there was an error in your input values. You
    may then edit the Min/Max column pairs to limit certain values for the plots. After adjusting the
    last three values [initial binsize, multiplication factor, and binsize used], choose whether you
    want the plots on a single page or separate pages.
    
6. DEFAULT VALUES

    If you ever want to change the default values that appear in the user interface of phaplot.pro,
    you have to edit the file defval_phahist.txt in Master_Program. The only two default values
    you should ever really need to worry about are the ephemeris files. Whenever you update the
    ephemeris files [as outlined in the website script document], simply replace the file paths
    to the old files with those of the new in defval_phahist. Also note that ephemeris files
    used in phaplot.pro must have a dT of 30 minutes. While the website script only requires a dT
    of an hour, ephemeris files of 30 min. dT should always be the default.
    
    [If you update the ephemeris files, in addition to updating this defaults file you should also
    update phaflux_defaults.txt in Master_Program. This is the defaults file for phaflux.pro.]
        
7. ISSUES

    - Ensure that there are no blank lines at the end of your list files.
    - Ensure that the xdr files represent contiguous time periods for plots v. time.
    
---------------------
Stephen Randall, 2012
---------------------