source: trunk/src/timeserie.pro @ 11

; docformat = 'rst'
;+
;
; plot time series
;
; :Categories: PNG Climatology AMSU OLR2
;
; :Params:
;   dataset : in, required, type='string: AMSU OLR'
;    dataset to plot
;   canal : in, optional, type='string: ax bx'
;    canal of AMSU
;
;    only used if AMSU dataset
;
; :Keywords:
;  UBOX : type='1D array of 4 items'
;   latitudes and longitudes of the box in this order : ulon1 ulon2 ulat1 ulat2
;
; :Restrictions:
;  - Requires SAXO
;
; :Returns:
;
; :Uses:
;  pltt_
;
;  .. _pltt: http://forge.ipsl.jussieu.fr/saxo/download/idldoc_html_output/ToBeReviewed/PLOTS/DESSINE/pltt.html
;
;  cm_4cal_
;
;  .. _cm\_4cal: http://forge.ipsl.jussieu.fr/saxo/download/idldoc_html_output/Commons/cm_4cal.html
;
; :Pre:
;  varamma_profile.sh_
;
;  .. _varamma_profile.sh: varamma_profile.sh.html
;
;  for AMSU dataset be sure to have ``cx.an*yyyy*.climato.nc`` ++
;  in the directory defined in ${VARAMMA_ID}/
;
;  for OLR dataset be sure to have ``olr.day.mean_climato_ng.nc``
;  in the directory defined in ${VARAMMA_ID}/
;
; :Post:
;  varamma_profile.sh_
;
;  PNG file is now present in ${VARAMMA_OD}
;
; :Todo:
;
;  ++ check ubox (lat and lon) validity
;
;  ++ exploitation du champ info des fichiers OLR
;
;  ++ split read and plot
;
;  ++ saveimage or openps (for image to provide to publisher)
;
;  ++ add _EXTRA keyword
;
; :Examples:
;
; To plot AMSU a4 climatology
; ::
;
;   IDL> timeserie, 'AMSU', 'a4', ubox=[-10.,+5.,-30.,45.]
;
; To plot OLR climatology
; ::
;
;   IDL> timeserie, 'OLR', 'n.a.', ubox=[-10.,+5.,-30.,45.]
;
; :History:
;
;  - fplod 2009-01-05T09:10:12Z aedon.locean-ipsl.upmc.fr (Darwin)
;
;    * add latitude and longitude boundaries in keywords (UBOX)
;
;  - fplod 2008-08-05T14:03:03Z zeus.locean-ipsl.upmc.fr (Linux)
;
;    * creation from hovmuller_latitude.pro
;    * extract from ananewvaramma3.pro 20080718 :
;      ::
;
;      ; series temporelles
;      mois=['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec']
;      mo_lon=[31,28,31,30,31,30,31,31,30,31,30,31]
;      canal='a5'
;      file='stagiaire/'+canal+'.climato.nc'
;      initncdf, file, xaxisname = 'xlon', yaxisname = 'ylat'
;
;      domdef,-10,5,15,25
;      imo=4   ; no du mois
;      im1=9
;      j1=total(mo_lon(0:imo-2)) & J2=total(mo_lon(0:im1-2))+mo_lon(im1-1)-1
;      ;imo=1   ; no du mois
;      ;im1=12
;      ;j1=0 & j2=364 ;J2=total(mo_lon(0:im1-2))+mo_lon(im1-1)-1
;      print,j1,j2
;      data=read_ncdf('moyenne_tb', j1,j2,/timestep,timevar = 'jours', file = file)
;      time=julday(imo,1,2000)+lindgen(jpt)
;      seriea5=(data.arr-min(data.arr))/(max(data.arr)-min(data.arr))
;      pltt,window=1,seriea5, 't',title='climatology time series',min=0.1,max=0.9
;      xyouts,max(time)+20,0.1,'a5',color=0,charsize=2
;
;
; :Version:
;  $Id$
;
;-
pro timeserie, dataset, canal $
             , UBOX=ubox
;
 compile_opt idl2, strictarrsubs
;
@cm_4cal
;
; ++ check required and optional parameters
;
CASE dataset OF
 'AMSU' : BEGIN
          END
 'OLR' : BEGIN
          END
 ELSE  : BEGIN
  msg = 'eee : invalid dataset parameter = ' + dataset
  ras = report(msg)
  msg = 'eee : dataset must be AMSU or OLR'
  ras = report(msg)
  RETURN
         END
 ENDCASE

; check input parameters
 IF (dataset EQ 'AMSU') THEN BEGIN
  CASE strmid(canal,0,1) OF
  'a' : BEGIN
   CASE strmid(canal,1) OF
   '1' :
   '2' :
   '3' :
   '4' :
   '5' :
   '6' :
   '7' :
   '8' :
   '9' :
   '15' : BEGIN
    msg = 'iii : valid canal parameter = ' + canal
    ras = report(msg)
        END
   ELSE : BEGIN
    msg = 'eee : invalid canal parameter = ' + canal
    ras = report(msg)
    msg = 'eee : canal must be a1, a2, a3, a4, a5, a6, a7, a8, a9 or a15'
    ras = report(msg)
    RETURN
          END
   ENDCASE
        END
  'b' : BEGIN
   CASE strmid(canal,1) OF
   '1' :
   '2' :
   '3' :
   '4' :
   '5' : BEGIN
    msg = 'iii : valid canal parameter = ' + canal
    ras = report(msg)
        END
   ELSE : BEGIN
    msg = 'eee : invalid canal parameter = ' + canal
    ras = report(msg)
    msg = 'eee : canal must be b1, b2, b3, b4 or b15'
    ras = report(msg)
    RETURN
          END
   ENDCASE
        END
  ELSE  : BEGIN
   msg = 'eee : invalid canal parameter = ' + canal
   ras = report(msg)
   msg = 'eee : canal must be start with a or b'
   ras = report(msg)
   RETURN
          END
  ENDCASE
 ENDIF
;
IF (keyword_set(UBOX)) THEN BEGIN
 IF (N_ELEMENTS(ubox) NE 4) THEN BEGIN
  msg = 'eee : axe must be latitude or longitude'
  ras = report(msg)
  RETURN
 ENDIF ELSE BEGIN
  ulon1 = ubox[0]
  ulon2 = ubox[1]
  ulat1 = ubox[2]
  ulat2 = ubox[3]
 ; ++ check lat and lon validity
 ENDELSE
ENDIF ELSE BEGIN
 msg = 'eee : no box user defined'
 ras = report(msg)
 RETURN
ENDELSE
;
; ++ parametrisation date début date fin
mois=['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec']
 mo_lon=[31,28,31,30,31,30,31,31,30,31,30,31]

 imo=4
 im1=10
;
; check for input file
;
; test if ${VARAMMA_ID} defined
 varamma_id_env=GETENV('VARAMMA_ID')
 CASE varamma_id_env OF
  ''  :  BEGIN
   msg = 'eee : ${VARAMMA_ID} is not defined'
   ras = report(msg)
   RETURN
         END
  ELSE: BEGIN
   msg = 'iii : ${VARAMMA_ID} is ' + varamma_id_env
   ras = report(msg)
        END
 ENDCASE
;
 iodirin = isadirectory(varamma_id_env)
;
; existence and protection of ${VARAMMA_ID}
 IF (FILE_TEST(iodirin, /DIRECTORY, /EXECUTABLE, /READ) EQ 0) THEN BEGIN
  msg = 'eee : the directory' + iodirin  + ' is not accessible.'
  ras = report(msg)
  RETURN
 ENDIF
;
; build input and output filenames
; define field to be plot (field)
; define the title of the plot (title)
; define the interval of each color level (int)
; for hovmuller latitude
; ++for hovmuller longitude
CASE dataset OF
 'AMSU' : BEGIN
   filename_in=canal+'.climato.nc'
   field='moyenne_tb'
   title='climatology time series '+ dataset + ' ' + canal
   int = .5
   filename_out=canal+ $
   string(imo,format='(I2.2)')+ $
   string(im1,format='(I2.2)')+ $
   '-climato-'+ $
   string(abs(ulon1),format='(I3.3)')+ $
   '-'+ $
   string(abs(ulon2),format='(I3.3)')+ $
  '.png'
          END
 'OLR' : BEGIN
   filename_in='olr.day.mean_climato_ng.nc'
   field='olr'
   title='climatology time series '+ dataset
   int = 8
   filename_out='olr.day.mean_'+ $
   string(imo,format='(I2.2)')+ $
   string(im1,format='(I2.2)')+ $
   '-climato-'+ $
   string(abs(ulon1),format='(I3.3)')+ $
   '-'+ $
   string(abs(lon2),format='(I3.3)')+ $
  '.png'
          END
 ELSE  : BEGIN
  msg = 'eee : invalid dataset parameter = ' + dataset
  ras = report(msg)
  msg = 'eee : dataset must be AMSU or OLR'
  ras = report(msg)
  RETURN
         END
 ENDCASE
;
; check if this file exists
 fullfilename_in = isafile(iodirin + filename_in, NEW=0, /MUST_EXIST)
 IF fullfilename_in[0] EQ '' THEN BEGIN
  msg = 'eee : the file ' + fullfilename_in + ' was not found.'
  ras = report(msg)
  RETURN
 ENDIF
;
; test if ${VARAMMA_OD} defined
 varamma_od_env=GETENV('VARAMMA_OD')
 CASE varamma_od_env OF
  '' : BEGIN
   msg = 'eee : ${VARAMMA_OD} is not defined'
   ras = report(msg)
   RETURN
       END
  ELSE: BEGIN
   msg = 'iii : ${VARAMMA_OD} is ' + varamma_od_env
   ras = report(msg)
        END
 ENDCASE
;
; check if output data will be possible
 iodirout = isadirectory(varamma_od_env)
;
; existence and protection
 IF (FILE_TEST(iodirout, /DIRECTORY, /WRITE) EQ 0) THEN BEGIN
  msg = 'eee : the directory' + iodirout  + ' was not found.'
  ras = report(msg)
  RETURN
 ENDIF
;
 fullfilename_out = iodirout + filename_out
;
; in order to avoid unexpected overwritten
 IF (FILE_TEST(fullfilename_out) EQ 1) THEN BEGIN
  msg = 'eee : the file ' + fullfilename_out  + ' already exists.'
  ras = report(msg)
  RETURN
 ENDIF
;
 initncdf, fullfilename_in[0], xaxisname = 'xlon', yaxisname = 'ylat'
;
; reduce geographic domain
 domdef,ulon1,ulon2,ulat1,ulat2
;
; reduce temporal domain
 date1=20000401L
 date2=20001101L
;
; read data to be plot
 data=read_ncdf(field, date1,date2,timevar = 'jours', file = fullfilename_in[0])
;
; redefinition axe temps
 ;++time=julday(imo,1,2000)+lindgen(jpt)
;
; define font
!P.FONT = 0
DEVICE, SET_FONT = "-adobe-helvetica-medium-r-normal--17-120-100-100-p-88-iso8859-1"
;
; plot timeserie diagram
; with no contour (/nocontour)
; using color palette 64 (lct=64)
; maximizing the size of the plot in the window (/rempli)
; window keyword is uses to create a new window each time this procedure
; is used
; ++ DIGITSYEAR=0 is a attempt to suppress year in x label
 pltt, data, 't', $
 title=title,/nocontour, int = int, format='(f5.1)', $
 lct = 64, /rempli, $
 window=0
 pltt, data, $
 title=title,/nocontour, int = int, format='(f5.1)', $
 lct = 64, /rempli, $
 window=1, DIGITSYEAR=0
;
; save an image file
 saveimage, fullfilename_out,/png

END