---------------------------------------------
PHAFLUX.PRO - Stephen Randall, Robert DiFabio
---------------------------------------------
1. OVERVIEW
phaflux.pro is an IDL program located in ~/IDL/Master_Program. It can create and combine flux
files, as well as make a variety of plots. It is one of the two main programs that you'll use to
analyze Cassini/MIMI/CHEMS data [the other is phaplot.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 PHAFLUX
To run the program, open a Terminal window and enter the command "phaflux". This will compile
all the necessary routines and open phaflux.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 phaflux_analysis", ".r trangedata_analysis", ".r phaflux"], and then running phaflux by
entering "phaflux". 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 FLUX FILES
To create a flux file, open phaflux. 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) deltaT(min)". This helps you remember what values to
place where, so no data should be in the first line [phaflux actually skips it completely].
Single Time Range: Simply enter your starting time, ending time, and time bin [dT]. 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 flux file.
To change where the flux 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 paths in "Box File", "PHA Directory", and "Science Rates Dir" point to the species delimiters
[box file] and the data files [PHA, Sci Rates]. These will almost never need to be changed.
4. COMBINING FLUX FILES
If you have a number of flux files that you want to use to create a single plot, you can combine
flux files in the lower half of the "Calculating Flux" tab. Simply give a list of Flux_incr.txt
path names, edit the output directory path if necessary, and set a prefix for your output files
[this gives prefixFlux_cmbn.txt and prefix_FluxMix_cmbn.txt].
Note that if you want to create a plot of any quantity v. time, your flux file list must represent
a contiguous time period.
5. PLOTTING
As with flux file creation, all the values in the user interface have been filled in for you and
you should have a good reason for changing them. First, edit the flux file list and enter all the
paths of the flux files you want plotted. Make sure that there are no blank lines at the end of
the file. 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.
The plot title box value is simply a prefix to a more informative actual plot title. This shouldn't
be edited unless you're specifically asked to do so.
The abundance range is the default for spectrograms, and will need to be changed for most of the
other plots. We cover this in more detail below.
When plotting, "Single Page" will put data from all four telescopes on a single page, whereas
"Separate Pages" will put each telescope on its own page [4 pages total; 1, 2, 3, all] in
a landscape layout.
There are two main classes of plots you can create: spectrograms and abundance/ratio vs. time plots.
Spectrograms: Select the ion species you want to plot, whether or not you want an output text data
file, and the exact type of plot [A v. E/Q lets you choose either Flux or Number Density vs. E/Q;
E/Q v. T lets you choose whether you want all telescopes on a single page, or separate pages].
Abundance/Ratio v. Time Plots: The control files probably won't ever need to change. These specify
the DPPS step at which the counts transition from doubles to triples. Simply select the plot type
you want from the drop down menus. Note that the abundance range for these is roughly 1E-8, 1E-9 to
0.01, 0.001 for partial number densities and 0.001, 0.01 to 1E4, 1E5 for the fluxes.
6. DEFAULT VALUES
If you ever want to change the default values that appear in the user interface of phaflux.pro,
you have to edit the file phaflux_defaults.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 phaflux_defaults. Also note that ephemeris files
used in phaflux.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 defval_phahist.txt in Master_Program. This is the defaults file for phaplot.pro.]
7. ISSUES
- Ensure that there are no blank lines at the end of your list files.
- Ensure that the flux files represent contiguous time periods for plots v. time.
---------------------
Stephen Randall, 2012
---------------------