;=====================================================================

; IDL TOOL NAME:
; faverage.pro
; Public directory:	 /home/ppq/idl_tools_public/release 
;
; USAGE:                             
;    faverage, 960713,1024,10,/fplots_en,pa_range=[0,30]
;
; MANDATORY ARGUMENTS:
;		1st argument:  YYMMDD or YYYYMMDD
;		2nd argument: 'HH:MM:SS','HH:MM',HHMMSS,HHMM,HH.HHH,H
;		3rd argument:  # of minutes
;
; MANDATORY KEYWORDS (only one at a time):
;   /fplots_en		; log<f> vs. energy, nine plots per page
;   /cplots_en		; log<C> vs. energy, nine plots per page
;
; OPTIONAL KEYWORDS:
;
; Data filters
;   pa_range=[min,max]  ; Pitch-angle filter (in degrees)
;		(default is all pitch angles)
;   /alias_tog		; Split the distribution into 1/2 block chunks
;			; but plot both halves TOGether on the same graph
;		(default is to plot the whole block of data)
;   /alias_sep		; Split the distribution into 1/2 block chunks
;			; and plot each half SEPerately
;		(default is to plot the whole block of data)
;
; Output devices
;   /display		; display on screen (default)
;   /print		; create a post-script file AND print at UIowa
;   /ps			; create a post-script file, idl.ps
;   /gif		; create a gif file, idl.gif
;   nwindow=number	; designate an IDL window number other than 0
;
; Species
;   /ions		; plot ions 
;   /electrons		; plot electrons (default)
;
; Energy range
;   e_range=[min,max] 	; Energy range to be plotted in eV
;		(default is whole energy range)
;   /high		; Energy range from 0 to 1000eV, linear scale
;   /noshift		; Don't shift the measurements by the SC
;                         potential, denote location of SC potential
;                         with a dashed line
;
; Input directory path for the level1 data
;   indir='input_directory_path_string'
;
; NOTES:
; For the /*plot*_* plots, viewing the next page of graphs 
; is done by hitting any key
;
; KEEPING THE DATA SET:
; If you want to use the data set for other purposes, you can easily make
; an IDL save set by using the keyword /keep_data.  The file created is
; 'idlsave.dat' and can be restored within your own procedure by typing:
;		restore, 'idlsave.dat'
; The variable saved is l1_data, as described below.
;
; l1_data is an array of structures defined as such: 
; l1_data = replicate(data,nblocks) where nblocks is the number of blocks
; that were extracted, and data is a structure of the form: 
;   data = {data, $
;	species:fix(0),$		; -1 for ele, 1 for ion
;	mode:fix(0),$			; Block mode
;	sc_potential:float(0.),$	; As reported by EFI, in eV
;	sc_potential_stat:long(0),$	; 0=unknown, 1=EFI, 2=EFI+2eV
;	min_index:long(0),$		; IDL index of first positive
;					; energy level, whole block
;	min_index1:long(0),$		; IDL index of first positive
;					; energy level, 1st half of blk
;	min_index2:long(0),$		; IDL index of first positive
;					; energy level, 2nd half of blk
;	npts:long(0),$			; # of energy levels, whole blk
;	npts_ta:long(0),$		; # of energy levels, 1/2 blk
;	time:double(0.),$		; Block time in seconds
;	count:lonarr(110),$		; # of measmnts comprising faverage(i)
;	count1:lonarr(110),$		; # of measmnts comprising faverage1(i)
;	count2:lonarr(110),$		; # of measmnts comprising faverage2(i)
;	count_all:lonarr(110),$		; Total # measmnts in energy(i) shell
;	count1_all:lonarr(110),$	; Total # measmnts in energy1(i) shell
;	count2_all:lonarr(110),$	; Total # measmnts in energy2(i) shell
;	faverage:dblarr(110),$		; Spin-averaged dist. fnc.,whole block
;	faverage1:dblarr(110),$		; Spin-averaged dist. fnc., 1st half
;	faverage2:dblarr(110),$		; Spin-averaged dist. fnc., 2nd half
;	caverage:dblarr(110),$		; Spin-averaged corr. cnts, whole
;	caverage1:dblarr(110),$		; Spin-averaged corr. cnts, 1st half
;	caverage2:dblarr(110),$		; Spin-averaged corr. cnts, 2nd half
;	energy:dblarr(110),$		; S/C corrected energy, whole block
;	energy1:dblarr(110),$		; S/C corrected energy, 1st half
;	energy2:dblarr(110),$		; S/C corrected energy, 2nd half
;	onef:dblarr(110),$		; One-count level for faverage
;	onef1:dblarr(110),$		; One-count level for faverage1
;	onef2:dblarr(110),$		; One-count level for faverage2
;	onec:dblarr(110),$		; One-count level for caverage
;	onec1:dblarr(110),$		; One-count level for caverage1
;	onec2:dblarr(110)}		; One-count level for caverage2
;
; So, for example, the block times are stored in l1_data(*).time, the 
; <f> array for the first time is stored in l1_data(0).faverage, the energy
; array associated with this <f> is stored in l1_data(0).energy, etc. 
; You don't need to define this structure explicitly in your own IDL
; procedure.  Just restore it and use it as you like.
;
; History:
;   1st version: 	8/30/96 Written, Pamela Puhl-Quinn
;Recompiled, 10/24/96, ppq
;Recompiled, 12/22/96, ppq  b1_42
;Recompiled, 1/6/97, ppq b1_43
;Recompiled, 3/3/97, ppq b1_43
;Recompiled, 3/7/97, ppq b1_44
;Recompiled, 3/26/97, ppq b1_45
;Level 1 read standard, 4/7/97, ppq
;Combined f_average_plots and f_pitch, 4/8/97, ppq
;Recompiled, 7/28/97, ppq b1_50 - level0 is still usable
;Rewrite using the new calibration variables, level0 not
; usable,9/8/97, ppq
;Fixed error in faverage_l1.pro involving sorting the arrays, also
; confirmed the meaning of the one-cnt levels, 10/20/97, ppq
; (NOTE: one-cnt level is calculated with v_obs not v_deb!!)
;Assigned versions, faverage and faverage_l1 versions must match,
; added noshift option to ALL plots (not just fplots_en), added usage
; help when no arguments are given, 10/21/97,ppq
;=====================================================================