Changeset 150 for trunk/SRC/ToBeReviewed/LECTURE/read_ncdf.pro

Timestamp:

08/09/06 12:12:54 (18 years ago)

Author:

navarro

Message:

english and nicer header (3a)

File:

• trunk/SRC/ToBeReviewed/LECTURE/read_ncdf.pro (modified) (15 diffs)

trunk/SRC/ToBeReviewed/LECTURE/read_ncdf.pro

@@ -1 @@
-;------------------------------------------------------------
-;------------------------------------------------------------
-;------------------------------------------------------------
 ;+
-;
-; PURPOSE:fonction de lecture pour fichier net_cdf.
-; Ce programme, est moins universel que ncdf_lec (il fait appelle au
-; variables declarees dans common.pro) mais il est du cop bcp plus
-; facile d''utilisation. Il prend en compte la declaration des
-; differents zoom qui ont ete definis (ixminmesh...premierx...) la
-; declaration de la variable key_shift... bref le resultat de
-; read_ncdf peut dorectement etre utilise dans plt...
-; C''est aussi ce programme qui est utilise par defaut dans mes
-; widgets pour la partie lecture.
-;
-; CATEGORY:lecture de fichiers NetCdf
-;
-; CALLING SEQUENCE:res = read_ncdf(name,debut[,fin])
-; 
-; INPUTS: name: un string definissant le champ a lire.
-;         debut et fin: sont relatifs a l''axe des temps. Ce peut etre
-;         - 2 dates du type yyyymmdd et ds ce cas on selectionne les
-;         dates qui sont comprisent entre ces 2 dates.
-;         - 2 indices qui definissent entre quel et quel pas de temps
-;           on doit extraire la dimension temporelle.
-;         exp: ne sert a rien!
-;
-; KEYWORD PARAMETERS: utilisables hors du contexte des widgets
-;
-;        BOXZOOM: contient la boxzoom sur laquelle on doit faire la
-;        lecture
-;        FILENAME: string contennant le nom du fichier
-;        /INIT; to call automatically initncdf, filename and thus
-;        redefine all the grid parameters
-;        GRID='[UTVWF]' to specify the type of grid. Defaut is (1)
-;        based on the name of the file if the file ends by
-;        GRID[._][TUVFW].NC (not case sensible) or (2) T if case (1)
-;        is not found.
-;        IODIRECTORY;a string giving the name of iodirectory (see
-;        isafile.pro for all possibilities). default value is common 
-;        variable iodir
-;        TIMESTEP:activer pour specifier que debut et fin font
-;        reference a des indices de l''axe du temps et non pas a des
-;        dates. 
-;        TOUT: activer si on veut lire le ficher sur l''ensemble du
-;        domaine sans tenir compte du sous domaine definit par boxzoom
-;        ou lon1,lon2,lat1,lat2,vert1,vert2.
-;        NOSTRUCT: activer si on ne veut pas que read_ncdf reourne
-;        une structure mais uniquement le tableau se rapportant au
-;        champ. 
-;        TIMEVAR: a string to define the name of the variable that
-;        contains the time axis. This keyword can be usefull if there
-;        is no unlimited dimension or if the time axis selected by defaut
-;        (the first 1D array with unlimited dimension) is not the good one
-; 
-;
-; OUTPUTS:une stucture lisible par litchamp.pro ou un simple tableau
-; si /NOSTRUCT est active 
-;
-; COMMON BLOCKS:common.pro
-;
-; SIDE EFFECTS:
-;
-; RESTRICTIONS:le champ doit avoir une dimension temporelle
-;
-; EXAMPLE:
-;
-; MODIFICATION HISTORY:Sebastien Masson (smasson@lodyc.jussieu.fr)
-;                      15/10/1999
+; @file_comments
+; Reading function for the file net_cdf.
+; This program is less universal than ncdf_lec (it appeal to declarated 
+; variables in common.pro) but it is very easier to be used. It considerate
+; the declaration of the different zooms which have been defined
+; (ixminmesh...premierx...), the declaration of the variable key_shift...
+; To put it in a nutshell, the result of read_ncdf can be directly used in plt...
+; This is also this program which is used by default inour reading widgets.  
+;
+; @categories
+; reading
+;
+; 
+; @param NAME {in}{required}
+; It is a string defining the field to be read.
+;
+; @param BEGINNING {in}{required}
+; Relative with the time axis.
+; These can be
+;  - 2 date of the  type yyyymmdd and in this case, we select dates 
+;  which are included between these two dates.
+;  - 2 indexes which define between which and which time step we have 
+;  to extract the telporal dimension.
+;
+; @param ENDING  {in}{required}
+; Relative with the time axis.
+; See BEGINNING.
+; 
+; @param COMPATIBILITY {in}{required}
+; Useless
+;  
+; @keyword BOXZOOM 
+; Contain the boxzoom on which we have to do the reading 
+; 
+; @keyword FILENAME
+; It is a string containing the file's name.
+; 
+; @keyword INIT
+; To call automatically initncdf, filename and thus
+; redefine all the grid parameters
+; 
+; @keyword GRID
+; ='[UTVWF]' to specify the type of grid. Defaut is (1)
+; based on the name of the file if the file ends by
+; GRID[._][TUVFW].NC (not case sensible) or (2) T if case (1)
+; is not found.
+; 
+; @keyword  IODIRECTORY
+; It isa string giving the name of iodirectory (see isafile.pro 
+; for all possibilities). default value is common variable iodir.
+; 
+; @keyword TIMESTEP
+; We activate to specify that BEGINNING and ENDING refer to indexes
+; of the time axis and not to dates
+;
+; @keyword TOUT
+; We activate it if we want to read the file on the whole domain without 
+; considerate the sub-domain defined by the boxzoom or 
+; lon1,lon2,lat1,lat2,vert1,vert2.
+; 
+; @keyword NOSTRUCT
+; We activate it if we do not want that read_ncdf send back a structure 
+; but only the array refering to the field.
+; 
+; @keyword TIMEVAR
+; It is a string which define the name of the variable that
+; contains the time axis. This keyword can be usefull if there
+; is no unlimited dimension or if the time axis selected by defaut
+; (the first 1D array with unlimited dimension) is not the good one.
+;
+; @keyword _EXTRA
+; Used to pass your keywords 
+;
+; @returns
+; Structure readable by litchamp.pro or an array if NOSRUCT is activated.
+; 
+; @uses
+; common.pro
+; 
+; @restrictions
+; The field must have a temporal dimension.
+; 
+; @history
+; Sebastien Masson (smasson@lodyc.jussieu.fr)
+;                      15/10/1999 
+; 
+; @version
+; $Id$ 
 ;-
-;------------------------------------------------------------
-;------------------------------------------------------------
-;------------------------------------------------------------
-FUNCTION read_ncdf, name, debut, fin, pour_etre_compatible, BOXZOOM = boxzoom, FILENAME = filename $
+;---------------------------------------------------------
+;---------------------------------------------------------
+;---------------------------------------------------------
+
+FUNCTION read_ncdf, name, beginning, ending, compatibility, BOXZOOM = boxzoom, FILENAME = filename $
                     , PARENTIN = parentin, TIMESTEP = timestep, TIMEVAR = timevar $
                     , TOUT = tout, NOSTRUCT = nostruct, CONT_NOFILL = CONT_NOFILL, INIT = init $
@@ -98 +119 @@
   filename = isafile(filename = filename, IODIRECTORY = iodir, _EXTRA = ex)
 ;------------------------------------------------------------
-; ouverture du fichier nom
+; Opening of the name file
 ;------------------------------------------------------------
   if size(filename, /type) NE 7 then $
@@ -118 +139 @@
   if keyword_set(init) THEN initncdf, filename, _extra = ex
 ;------------------------------------------------------------
-; check the time axis and the debut and fin dates
-;------------------------------------------------------------
-  if n_elements(debut) EQ 0 then begin
-    debut = 0
+; check the time axis and the debut and ending dates
+;------------------------------------------------------------
+  if n_elements(beginning) EQ 0 then begin
+    beginning = 0
     timestep = 1
   endif
   if keyword_set(timestep) then begin
-    firsttps = debut[0]
-    if n_elements(fin) NE 0 then lasttps = fin[0] ELSE lasttps = firsttps
+    firsttps = beginning[0]
+    if n_elements(ending) NE 0 then lasttps = ending[0] ELSE lasttps = firsttps
     jpt = lasttps-firsttps+1
     time = julday(1, 1, 1) + lindgen(jpt)
@@ -136 +157 @@
       currentfile = (where(filelist EQ filename))[0]
       time = (*(extractatt(top_uvalue, 'fileparameters'))[currentfile]).time_counter
-      date1 = date2jul(debut[0])
-      if n_elements(fin) NE 0 then date2 = date2jul(fin[0]) ELSE date2 = date1
+      date1 = date2jul(beginning[0])
+      if n_elements(ending) NE 0 then date2 = date2jul(ending[0]) ELSE date2 = date1
       firsttps = where(time EQ date1) & firsttps = firsttps[0]
       lasttps = where(time EQ date2) & lasttps = lasttps[0]
@@ -159 +180 @@
 ; we find the FIRST time axis      
         timeid = 0
-        repeat BEGIN       ; tant que l''on a pas trouve une variable qui n''a qu''
-                                ; une dimension: la dimension infinie
-          timecontient = ncdf_varinq(cdfid, timeid) ; que contient la variable
+        repeat BEGIN       ; As long as we have not find a variable having only one dimension: the infinite one
+          timecontient = ncdf_varinq(cdfid, timeid) ; that the variable contain.
           timeid = timeid+1
         endrep until (n_elements(timecontient.dim) EQ 1 $
@@ -188 +208 @@
 ;
 ; now we try to find the attribut called calendar...
-; the the attribute "calendar" exists?
+; the attribute "calendar" exists?
 ; If no, we suppose that the calendar is gregorian calendar
 ;
@@ -248 +268 @@
         end
       ENDCASE
-      date1 = date2jul(debut[0])
-      if n_elements(fin) NE 0 then date2 = date2jul(fin[0]) ELSE date2 = date1
+      date1 = date2jul(beginning[0])
+      if n_elements(ending) NE 0 then date2 = date2jul(ending[0]) ELSE date2 = date1
       time = double(time)
       firsttps = where(time GE date1) & firsttps = firsttps[0]
@@ -271 +291 @@
   ENDELSE
 ;------------------------------------------------------------
-; nom de la grille a laquelle se rapporte le champ
+; Name of the grid on which the field refer to.
 ;------------------------------------------------------------
   IF keyword_set(grid) THEN vargrid = strupcase(grid) ELSE BEGIN
@@ -294 +314 @@
 
 ;---------------------------------------------------------------
-; redefinition du domaine 
+; redefinition of the  domain
 ;---------------------------------------------------------------
   if keyword_set(tout) then begin
@@ -331 +351 @@
     ENDIF
     grille, mask, glam, gphi, gdep, nx, ny, nz, firstx, firsty, firstz, lastx, lasty, lastz
-    undefine, glam & undefine, gphi & ; on libere un peu de memoire!
+    undefine, glam & undefine, gphi & ; We liberate some memoty!
   ENDELSE
 ;---------------------------------------------------------------------
-; on initialise les ixmindta, iymindta au besoin
+; We initializate ixmindta, iymindta if needed
 ;---------------------------------------------------------------------
   if n_elements(jpidta) EQ 0 THEN jpidta = jpiglo
@@ -352 +372 @@
   IF izmaxdta EQ -1 then izmaxdta = jpkdta-1
 ;----------------------------------------------------------------
-; on va lire le fichier
+; We will read the file
 ;---------------------------------------------------------------
   if n_elements(key_stride) LE 2 then key_stride = [1, 1, 1]
@@ -401 +421 @@
     AND (strupcase(vargrid) EQ 'U' OR strupcase(vargrid) EQ 'F') THEN key_shift =  key_shift+1
 ;---------------------------------------------------------------------
-; on definit les variables globales rattachees a la variable
+; We define global variable joined with the variable.
 ;---------------------------------------------------------------------
 ; varname
@@ -434 +454 @@
   ENDELSE
 ; vardate
-; on construit une belle date lisible en fonction du langage specifie !!!
-  year = long(debut[0])/10000
-  month = (long(debut[0])/100) MOD 100
-  day = (long(debut[0]) MOD 100)
+; We make a legible date in function of the specified language.
+  year = long(beginning[0])/10000
+  month = (long(beginning[0])/100) MOD 100
+  day = (long(beginning[0]) MOD 100)
   vardate = string(format = '(C(CMoA))', 31*(month-1))+' '+strtrim(day, 1)+', '+strtrim(year, 1)
   varexp = file_basename(filename)
@@ -446 +466 @@
   if keyword_set(key_zreverse) AND (size(res))[0] EQ 4 THEN res = reverse(temporary(res), 3)
 
-; on applique la valeur valmask sur les points terre
+; We apply the value valmask on land points.
   if NOT keyword_set(cont_nofill) then begin
     valmask = 1e20
@@ -482 +502 @@
 ;    ENDIF ELSE missing = -1
   ENDIF ELSE missing = -1
-; on applique les add_offset, scale_factor et missing_value
+; we apply add_offset, scale_factor and missing_value 
   if scale_factor NE 1 then res = temporary(res)*scale_factor
   if add_offset NE 0 then res = temporary(res)+add_offset