PRO eis_mapper_obs_str, year=year, month=month, overwrite=overwrite, _extra=extra, $
                        outdir=outdir, atlas=atlas, $
                        xcen=xcen, ycen=ycen, $
                        slot=slot, narrow=narrow, slit_index=slit_index, wvl=wvl, $
                        fovx=fovx

;+
; NAME:
;     EIS_MAPPER_OBS_STR
;
; PURPOSE:
;     Creates eis_obs_structure output files and saves them to the
;     eis_mapper directory
;
; CATEGORY:
;     Hinode/EIS; mapper
;
; CALLING SEQUENCE:
;     EIS_MAPPER_OBS_STR
;
; INPUTS:
;     None.
;
; OPTIONAL INPUTS:
;     Year:  An integer specifying the year for which you want the EIS
;            data. If not specified then current year is used.
;     Month: An integer (from 1 to 12) specifying the month for which
;            you want EIS data. Use this with YEAR to get data only
;            for a specific month. If not specified then all months in
;            the year will be processed (for current year will cover
;            all months up to current month).
;     Xcen:    A 2D array specifying a range of in which the raster
;              Xcen must lie.
;     Ycen:    A 2D array specifying a range of in which the raster
;              Ycen must lie.
;     Wvl:     Specifies a wavelength (or wavelengths)  that must lie
;              in the raster's wavelength bands.
;     Fovx:    Scalar specifying a minimum field-of-view for X.
;     Slit_Index: An integer or integer array specifying a slit index
;                 (must be 0, 1, 2 or 3). Only rasters using the
;                 specified slit will be returned.
;	
; KEYWORD PARAMETERS:
;     OVERWRITE: By default the routine does not overwrite the data
;                files if they already exist. This routine forces an
;                overwrite.
;     ATLAS:  If set, then only save spectral atlas rasters to the
;             output.
;     SLOT:   Only return slot data.
;     NARROW: Only return narrow slit data.
;
; OUTPUTS:
;     Creates files of the form obs_struc_[YEAR][MONTH].save in the
;     directory $EIS_MAPPER/data, where MONTH is given as a 2-digit
;     integer. For example, obs_struc_201609.save for September
;     2016. 
;
; CALLS:
;     EIS_OBS_STRUCTURE, EIS_FILTER_OBS_STRUC
;
; EXAMPLE:
;     IDL> eis_mapper_obs_str, year=2016
;     IDL> eis_mapper_obs_str, year=2016, month=9
;
; MODIFICATION HISTORY:
;     Ver.1, 09-Mar-2020, Peter Young
;     Ver.2, 30-Mar-2020, Peter Young
;       Modified default behavior when YEAR and/or MONTH not
;       specified.
;     Ver.3, 01-Apr-2020, Peter Young
;       Added /atlas keyword and fixed bug from previous call.
;     Ver.4, 02-Apr-2020, Peter Young
;       Fixed bug when month specified.
;     Ver.5, 03-Apr-2020, Peter Young
;       Fixed bug when /atlas set but structure has no entries.
;     Ver.6, 18-Jan-2021, Peter Young
;       Added a set of keywords that are passed to
;       eis_filter_obs_struc.
;     Ver.7, 20-Jan-2021, Peter Young
;       Now force all existing files to be deleted when /overwrite is
;       set, even if there are no entries for that month.
;-


eis_mapper_dir=getenv('EIS_MAPPER')

IF n_elements(outdir) NE 0 THEN BEGIN
  chck=file_search(outdir,count=count)
  IF count EQ 0 THEN file_mkdir,outdir
ENDIF ELSE BEGIN 
  IF eis_mapper_dir EQ '' THEN BEGIN
    print,'% EIS_MAPPER_OBS_STR: the $EIS_MAPPER environment variable is not defined.'
    return
  ENDIF ELSE BEGIN
    outdir=eis_mapper_dir
  ENDELSE
ENDELSE 


;
; By default the routine derives the structure for the last full month.
;
t=systime(/julian,/utc)
caldat,t,curr_month,dd,curr_year


datadir=concat_dir(outdir,'data')
chck=file_info(datadir)
IF chck.exists EQ 0 THEN file_mkdir,datadir

IF n_elements(year) EQ 0 THEN BEGIN
  yy=curr_year
  print,'% EIS_MAPPER_OBS_STR: YEAR not specified. Using current year ('+trim(yy)+').'
  IF n_elements(month) EQ 0 THEN mm=indgen(curr_month)+1
ENDIF ELSE BEGIN
  yy=year
  IF n_elements(month) EQ 0 THEN mm=indgen(12)+1 ELSE mm=month
ENDELSE 



nm=n_elements(mm)
FOR i=0,nm-1 DO BEGIN
  yystr=trim(yy)
  mmstr=strpad(trim(mm[i]),2,fill='0')
  outfile='obs_str_'+yystr+mmstr+'.save'
  outfile=concat_dir(datadir,outfile)
  chck=file_info(outfile)
  IF chck.exists EQ 1 THEN BEGIN
     IF keyword_set(overwrite) THEN BEGIN
        file_delete,outfile
     ENDIF ELSE BEGIN 
        print,'% EIS_MAPPER_OBS_STR: the file '+file_basename(outfile)+' exists. Use keyword /overwrite to overwrite it.'
        CONTINUE 
     ENDELSE
  ENDIF
 ;
  t0=yystr+'-'+mmstr+'-01'
  IF mm[i] EQ 12 THEN BEGIN
     t1=trim(yy+1)+'-01-01'
  ENDIF ELSE BEGIN
     t1=yystr+'-'+strpad(trim(mm[i]+1),2,fill='0')+'-01'
  ENDELSE
  obs=eis_obs_structure(t0,t1,count=count,_extra=extra,/quiet)
   ;
   ; Now filter using optional keywords.
   ;
  IF count NE 0 THEN BEGIN 
     obsx=eis_filter_obs_struc(obs, xcen=xcen, ycen=ycen, $
                               wvl=wvl, fovx=fovx, narrow=narrow,$
                               slit_index=slit_index, slot=slot,count=count)
     obs=temporary(obsx)
  ENDIF 
   ;
  IF keyword_set(atlas) AND count NE 0 THEN BEGIN
     k=where(obs.atlas EQ 1,count)
     IF count NE 0 THEN obs=obs[k]
  ENDIF
   ;
  IF count NE 0 THEN BEGIN
     save,file=outfile,obs
     print,'% EIS_MAPPER_OBS_STR: created file '+file_basename(outfile)+'.'
  ENDIF ELSE BEGIN
     print,'% EIS_MAPPER_OBS_STR: no EIS entries for '+yystr+mmstr+'.'
  ENDELSE 
ENDFOR 

END