;+
; Project     : SOHO - CDS     
;                   
; Name        : CDS_AR_OBS
;               
; Purpose     : To find files which contain observations on a given AR.
;               
; Explanation : When the number of the given AR is entered, the files in
;               which there is reference to this AR will be located.
;               The filename, the old and new object ID, and the distance
;               from the centre of the observation to the position of the
;               AR can be returned for each file.
;
;               Descriptions used in new catalogue entry (eg for AR1234):
; 
;               AR1234 - Observation was AT OR VERY NEAR the predicted
;                        path of the AR within 2 days either side of 
;                        the AR's first and last mention in NOAA reports.  
;               
;               AR1234? - Observation was NEAR the predicted path of the
;                         AR within 2 days either side of the AR's first 
;                         and last mention in NOAA reports.
;               
;               AR0000 - The observer stated that an AR was being viewed
;                        although there were no recognised ARs nearby.  
;                        (Possibly a small, non-NOAA AR being viewed)
;
;               <<AR1234 - The raster area covered the predicted location
;                          of the AR but at a time more than 2 days prior 
;                          to its first mention in NOAA reports.
;
;               >>AR1234 - The raster area covered the predicted location
;                          of the AR but at a time more than 2 days after 
;                          its last mention in NOAA reports.
;
;               AR_LIMB_EAST/WEST - AR1234 - Observer recorded AR in
;                            catalogue.  The AR in question had just 
;                            disappeared off (in the case of West Limb 
;                            observations) or was about to appear on (in 
;                            the case of East Limb observations) the limb 
;                            and so was not in NOAA reports on that day.
;
;               AR_LIMB_EAST/WEST? - Observation on limb, no recognised
;                            AR's nearby and none just disappeared off 
;                            (WEST), or appearing on (EAST) limb, but 
;                            observer recorded AR in catalogue.   
;
;                AR1234, AR2345, (AR3456) - Observation covered 2 (or 3)
;                            AR's.
;
; Use         : IDL> cds_ar_obs, number [,file, catnew, dist, catold, /quiet]
;    
; Inputs      : number - the number of the AR being searched for.  Note special
;                        case where number = 0
;                        (If the first parameter is a string variable 
;                         beginning with the character 's' it is assumed
;                         to be a FITS file name and the entry for that
;                         is printed)
;               
; Opt. Inputs : None
;               
; Outputs     : None
;                 
; Opt. Outputs: file - the filename of the file in which the AR was
;                      observed
;               catnew - the new catalogue entry detailing the AR's
;                        to be found in the file
;               dist - the distance from the centre of the observation
;                      to the position of the AR (arcsecs)
;               catold - the old catalogue entry detailing the AR's
;                        to be found in the file
;               
; Keywords    : Quiet   - if set, no screen output.
;               Help    - gives explanation of format of new AR associations.
;               Outfile - specifies file in which to save results
; 
; Calls       : None
;
; Common      : None
;               
; Restrictions: None
;               
; Side effects: None
;               
; Category    : Catalogues
;               
; Prev. Hist. : None
;
; Written     : A N Pike, RAL, 3/8/98 
;               
; Modified    : Add OUTFILE keyword, CDP, 25-Mar-99 
;
; Version     : Version 1, 3/8/98 
;-            

pro cds_ar_obs, number, file, catnew, dist, catold, quiet= quiet, $
   help=help, outfile=outfile 


;
;  save possible output to file
;
text = strarr(5000)
if n_elements(outfile) eq 0 then outfile = ''

;
;  Set header.
;

header= 'Filename   Original     Distance(")   New Catalogue Entry '

printl= 0

;
;  If the help keyword has been set, information about the terms under
;  the 'New Catalogue Entry' heading is given.
;  

if keyword_set(help) then begin
 
   print,' '    
   print,'Terms used under "New Catalogue Entry":'
   print,' '
   print,'   AR1234 - Observation was AT OR VERY NEAR the predicted'
   print,'            path of the AR within 2 days either side of' 
   print,'            the ARs first and last mention in NOAA reports.'  
   print,' '
   print,'   AR1234? - Observation was NEAR the predicted path of the'
   print,'             AR within 2 days either side of the ARs first' 
   print,'             and last mention in NOAA reports.'
   print,' '            
   print,'   AR0000 - The observer stated that an AR was being viewed'
   print,'            although there were no recognised ARs nearby.'  
   print,'            (Possibly a small, non-NOAA AR being viewed)'
   print,' '
   print,'   <<AR1234 - The raster area covered the predicted location'
   print,'              of the AR but at a time more than 2 days prior'
   print,'              to its first mention in NOAA reports.'
   print,' ' 
   print,'   >>AR1234 - The raster area covered the predicted location'
   print,'              of the AR but at a time more than 2 days after' 
   print,'              its last mention in NOAA reports.'
   print,' '
   print,'   AR_LIMB_EAST/WEST - AR1234 - Observer recorded AR in'
   print,'              catalogue.  The AR in question had just'
   print,'              disappeared off (in the case of West Limb'
   print,'              observations) or was about to appear on (in'
   print,'              the case of East Limb observations) the limb' 
   print,'              and so was not in NOAA reports on that day.'
   print,' '
   print,'    AR_LIMB_EAST/WEST? - Observation on limb, no recognised'
   print,'              ARs nearby and none just disappeared off' 
   print,'              (WEST) or appearing on (EAST) limb, but' 
   print,'              observer recorded AR in catalogue.'   
   print,' '
   print,'    AR1234, AR2345, (AR3456) - Observation covered 2 (or 3)'
   print,'              ARs.'
   return
endif


;
;  If no parameters are specified, the range of AR numbers in each 
;  catalogue is printed on screen.
;

if n_params() eq 0 then begin
   print,' '
   print,'An AR number, or datafile name, must be specified.'
   print,'   1996 AR range: 7946 - 8008 '
   print,'   1997 AR range: 8009 - 8130 '
   print,'   1998 AR range: 8124 - 8257 '
   print,' '
   return
endif

;
;  check likely file exists
;
if not file_exist(concat_dir('$CDS_HEAD_CAT','AR_all_1996')) then begin
   print,'Files: $CDS_HEAD_CAT/AR_all_199n (n=6,7,8) do not exist'
   return
endif


;
;  trap datafile name case
;
if datatype(number,0) eq 'STR' then begin
   if strlowcase(strmid(number,0,1)) ne 's' then begin
      print,'Data file name invalid:'
      return
   endif
   if strpos(strlowcase(number),'r') gt 0 then begin
      fnum = fix(str_pick(number,'s','r'))
   endif else begin
      fnum = fix(str_pick(number,'s'))
   endelse
   if fnum le 6382 then begin
      t= rd_ascii(concat_dir('$CDS_HEAD_CAT','AR_all_1996'))
   endif
   if fnum ge 6383  and fnum le 10086 then begin
      t= rd_ascii(concat_dir('$CDS_HEAD_CAT','AR_all_1997'))
   endif
   if fnum ge 10087 and fnum le 11520 then begin
      t= rd_ascii(concat_dir('$CDS_HEAD_CAT','AR_all_1998'))
   endif
   break_file,number,disk,dir,ff,ext
   n = where(strpos(t,strlowcase(ff)) ge 0,count)
   if count gt 0 then begin
      t = t(n)

      text = [text,' ','Filename         Original         New Catalogue Entry'+$
               '                  Distance(") ',' ',t]
      nt = where(text ne '',count)
      if count gt 0 then text = text(nt)
      
      if not keyword_set(quiet) then begin
         print,' '
         print,'Filename         Original         New Catalogue Entry'+$
               '                  Distance(") '
         print_str,t
         print,' '
      endif
      if outfile ne '' then print_str,text,/q,file=outfile,/keep
      file = t
      return
   endif else begin
      print,'No ARs associated with file: '+number
      return
   endelse
endif


;
;  Make sure number is within specified range (ie between 7946 and 8257)
;


if number ne 0 then begin
   if number lt 7946 or number gt 8257 then begin
      print,' '
      print,'AR number must be between 7946 and 8257.'
      print,' '
      return
   endif
endif 



;
;  Files on AR's with numbers between 7946 and 8008 are found in the 
;  1996 catalogue.
;

if number ge 7946 and number le 8008 then begin
   if not keyword_set(quiet) then begin
      print,' '
      print,'Searching 1996 catalogue...'
      print,' '
   endif
   t= rd_ascii(concat_dir('$CDS_HEAD_CAT','AR_all_1996'))
endif

;
;  Files on AR's with numbers between 8009 and 8124 are found in the
;  1997 catalogue.
;

if number ge 8009 and number lt 8124 then begin
   if not keyword_set(quiet) then begin
      print,' '
      print,'Searching 1997 catalogue...'
      print,' '
   endif
   t= rd_ascii(concat_dir('$CDS_HEAD_CAT','AR_all_1997'))
endif

;
;  Files on AR's with numbers between 8130 and 8257 are found in the
;  1998 catalogue.
;

if number gt 8130 and number le 8257 then begin
   if not keyword_set(quiet) then begin
      print,' '
      print,'Searching 1998 catalogue...'
      print,' '
   endif
   t= rd_ascii(concat_dir('$CDS_HEAD_CAT','AR_all_1998'))
endif

;
;  Files on AR's with numbers between 8124 and 8130 are found in both
;  the 1997 and 1998 catalogues.
;

if number ge 8124 and number le 8130 then begin
   if not keyword_set(quiet) then begin
      print,' '
      print,'Searching 1997 and 1998 catalogues...'
      print,' '
   endif
   s= rd_ascii(concat_dir('$CDS_HEAD_CAT','AR_all_1997'))
   t= [s, rd_ascii(concat_dir('$CDS_HEAD_CAT','AR_all_1998'))]
endif

;
;  If 0 is entered for the number, the 1511 files in which it was stated
;  that an AR was being observed but no recognised AR was close to the
;  observation will be found.  These will be in all three catalogues.
;  Dist will appear as -1 because the position of the 'AR' was unknown.
;

if number eq 0 then begin
   if not keyword_set(quiet) then begin
      print,' '
      print,'Searching 1996, 1997 and 1998 catalogues...'
      print,' '
   endif
   r= rd_ascii(concat_dir('$CDS_HEAD_CAT','AR_all_1996'))
   s= rd_ascii(concat_dir('$CDS_HEAD_CAT','AR_all_1997'))
   t= [r, s, rd_ascii(concat_dir('$CDS_HEAD_CAT','AR_all_1998'))]
endif 

;
;  Searches for and counts where 'AR' + the number appears in the files.
;

n= where(strpos(t,'AR' + trim(number)) gt 0, count)

;
;  If no files are found, this AR was not observed.  A list of the ARs
;  which were not observed is printed.
;

if count eq 0 then begin
   print,' '
   print,'This AR was not observed.  
   print,' '        
   print,'All ARs were observed by CDS from AR7946 to AR8257,'
   print,'except for the following fourteen:'
   print,' '
   print,'AR7947  AR7948  AR7966  AR8001  AR8002  AR8006  AR8007'
   print,'AR8008  AR8012  AR8013  AR8098  AR8101  AR8149  AR8256'
   print,' '
   file = '' & catnew = '' & dist = -1 & catold = ''
   return
endif

;
;  If the count is greater than 0, the file, catold, catnew and dist
;  values are found.
;

if count gt 0 then t = t(n)

nl= n_elements(t)   

file= strarr(nl)
catold= strarr(nl)
catnew= strarr(nl)
dist= intarr(nl)

for i= 0, nl-1 do begin
   file(i)= strmid(t(i),0,11)
   catold(i)= str_pick(t(i),'{','}')
   catnew(i)= strtrim(str_pick(t(i),'}','['),2)
   dist(i)= fix(str_pick(t(i),'[',']'))

;
;  If the keyword 'quiet' is not set, these values will be printed on 
;  screen.
;

   if not keyword_set(quiet) then begin 
      if printl eq 0 then begin
         print,' '
         print,header
         print,' '
      endif
      print,strpad(strmid(t(i),0,10),12,/after) $  
            +  strpad(str_pick(t(i),'{','}',/inc_f,/inc_l), 15,/after)  $ 
            +  strpad(str_pick(t(i),'[',']',/inc_f,/inc_l),10,/after) $
            +  strmid(t(i),31,40)
   endif

   if printl eq 0 then text = [' ',header,' ']
   printl= 1
   text = [text,strpad(strmid(t(i),0,10),12,/after) $  
            +  strpad(str_pick(t(i),'{','}',/inc_f,/inc_l), 15,/after)  $ 
            +  strpad(str_pick(t(i),'[',']',/inc_f,/inc_l),10,/after) $
            +  strmid(t(i),31,40)]
endfor

;
;  save to file if requested
;
if outfile ne '' then print_str,text,/q,/keep,file=outfile

end