Changeset 142 for trunk/SRC/ToBeReviewed/CALCULS/moyenne.pro

Timestamp:

07/21/06 14:47:49 (18 years ago)

Author:

navarro

Message:

english and nicer header (2a)

File:

• trunk/SRC/ToBeReviewed/CALCULS/moyenne.pro (modified) (21 diffs)

trunk/SRC/ToBeReviewed/CALCULS/moyenne.pro

@@ -3 +3 @@
 ;------------------------------------------------------------
 ;+
-; NAME: moyenne
-;
-; PURPOSE:  averages a 2- or 3-d field over a selected
+;
+; @file_comments  
+; averages a 2- or 3-d field over a selected
 ;           geographical area and along one ore more
 ;           selected axes (x, y or z)
 ;
-; CATEGORY:
-;
-; CALLING SEQUENCE: result = moyenne(tab,'direc',BOXZOOM=boxzoom)
-;
-; INPUTS:       tab = 2 or 3d field
-;               direc = 'x' 'y' 'z' 'xy' 'xz' 'yz' or 'xyz'
-;
-; KEYWORD PARAMETERS:
-;
-;               BOXZOOM = [xmin,xmax,ymin,ymax (,(zmin,)zmax)] pour plus
-;               de detail cf domdef.
-;               boxzoom peut prendre 5 formes: 
-;               [vert2], [vert1, vert2],[lon1, lon2, lat1, lat2],  
-;               [lon1, lon2, lat1, lat2, vert2],[lon1, lon2, lat1,
-;               lat2, vert1,vert2]
-;
-;               NAN: not a number, a activer si l''on peut faire veut
-;               faire une moyenne sans tenir compte de certaines
-;               valeurs masques de tab.
-;               si les valeurs masques de tab sont la valeur consacree
-;               par IDL (!values.f_nan), il suffit de mettre /NAN.
-;               si les valeurs masques de tab on pour valeur a (a doit
-;               etre differente de 1 (correspond a nan =
-;               !values.f_nan) et de 0 (qui desactive nan)
-;               il faut mettre NAN=a. 
-;               Rq: en sorties les points de result qui sont NAN
-;               auront pour valeur a ou !values.f_nan.
-;
-;               NODOMDEF: activer si l''on ne veut pas passer ds
-;               domdef bien que le mot cle boxzoom soit present (comme
-;               c''est le cas qd moyenne est appelee via checkfield) 
+; @categories
+;
+; @param        TAB {in}{required}
+; 2 or 3d field
+;
+; @param DIREC {in}{required}
+; 'x' 'y' 'z' 'xy' 'xz' 'yz' or 'xyz'
+;
+; @keyword BOXZOOM  
+; [xmin,xmax,ymin,ymax (,(zmin,)zmax)] to more details, see domdef
+; boxzoom can have 5 forms: 
+; [vert2], [vert1, vert2],[lon1, lon2, lat1, lat2],  
+; [lon1, lon2, lat1, lat2, vert2],[lon1, lon2, lat1, lat2, vert1,vert2]
+;
+; @keyword NAN 
+; not a number, we activate it if we want to average without considerate some masked values of TAB.
+; If masked values of TAB are values consecrated by IDL(!values.f_nan), wr just have to put NAN.
+; If masked values of TAB are valued a (a must be different of 1, corresponding to nan =
+; !values.f_nan and of 0, which desactivate nan). We have to put NAN=a. 
+; Comment: In output, rsult points which are NAN will be valued a or !values.f_nan.
 ;            
-;               INTEGRATION: pour faire une integrale plutot qu''une moyenne
+; @keyword NODOMDEF
+; We activate it if we do not want to pass in domdef even if the keyword boxzoom 
+; is present (like when grossemoyenne is called via checkfield)
+;
+; @keyword INTEGRATION 
+; To make an integral rather than an average
 ; 
-;         /WDEPTH: to specify that the field is at W depth instad of T 
-;         depth (automatically activated if vargrid eq 'W')
+; @keyword WDEPTH 
+; to specify that the field is at W depth instad of T 
+; depth (automatically activated if vargrid eq 'W') 
 ;            
-; OUTPUTS:  result:un tableau 
-;
-; COMMON BLOCKS:
-;       common   domdef
-;
-; SIDE EFFECTS:met les valeurs correspondants a la terre a 1e20
-;
-; RESTRICTIONS:
-;
-; EXAMPLE:
-;
-; MODIFICATION HISTORY: Jerome Vialard (jv@lodyc.jussieu.fr)
+; @returns
+; An array 
+;
+; @uses
+; common
+; domdef
+;
+; @restrictions Put values corresponding to land at 1.e20
+;
+; @history
+;  Jerome Vialard (jv@lodyc.jussieu.fr)
 ;                       2/7/98
 ;                       Sebastien Masson (smasson@lodyc.jussieu.fr)
-;                       mise au propre de certains truc (les terres...)
 ;                       14/8/98
 ;                       15/1/98
-;                       11/3/99 adaptation pour NAN
-;                       28/7/99 moyennes tableaux 1d
+;                       11/3/99 adaptation for NAN
+;                       28/7/99 Averages 1d arrays
+;
+; @version
+; $Id$
+;
 ;-
-;------------------------------------------------------------
-;------------------------------------------------------------
-; PLAN DU PROGRAMME:
-;------------------------------------------------------------
-;------------------------------------------------------------
-;I) preliminaires
-;   I.1) determination des directions de moyennes d''apres direc
-;   I.2) verification de la taille du tableau d''entree
-;   I.3) obtention des facteurs d''echelles et du masque sur le sous
-;   domaine concerne par la moyenne 
-;  ) moyennes pour les tableaux 1d (x,y)
-;II) moyennes pour les tableaux 2d (x,y)
-;   II.1) verification de la coherence de la taille du tableau a
-;   moyenner 
-;   II.2) differents types de moyennes possibles
-;III) moyennes pour les tableaux 3d (x,y,z)
-;   III.1) verification de la coherence de la taille du tableau a
-;   moyenner 
-;   III.2) differents types de moyennes possibles
-;IV ) finitions
-;   IV.1) on masque les terres par une valeur a 1e+20
-;   IV.2) on remplace, quand nan ne 1, !values.f_nan par nan
-;   IV.3) on revient au sous domaine initial.
-;------------------------------------------------------------
-;------------------------------------------------------------
+
 function moyenne, tab, direc, BOXZOOM = boxzoom, INTEGRATION = integration $
                   , NAN = nan, NODOMDEF = nodomdef, WDEPTH = wdepth $
@@ -106 +79 @@
   ENDIF
 ;---------------------------------------------------------
-  tempsun = systime(1)          ; pour key_performance
-;------------------------------------------------------------
-;I) preliminaires
+  tempsun = systime(1)          ; To key_performance
+;------------------------------------------------------------
+;I) preliminaries
 ;------------------------------------------------------------
   dirt = 0
@@ -115 +88 @@
   dirz = 0
 ;------------------------------------------------------------
-; I.1) direction(s) suivants lesquelles on integre
+; I.1) Directions(s) we follow to integrate
 ;------------------------------------------------------------
   if ( strpos(direc, 't') ge 0 ) then dirt = 1
@@ -123 +96 @@
   if (dirx eq 0 and diry eq 0 and dirz eq 0) then return, tab
 ;------------------------------------------------------------
-; I.2) verification de la taille du tableau d'entree
+; I.2) verification of the input array's size
 ;------------------------------------------------------------
   taille = size(tab)
@@ -139 +112 @@
   endcase
 ;------------------------------------------------------------
-;   I.3) obtention des facteurs d''echelles et du masque sur le sous
-;   domaine concerne par la moyenne 
-; redefinition du domaine ajuste a boxzoom (a 6 elements)
-; ceci va nous permetre de faire les calcules que sur le sous domaine
-; comcerne par la moyenne. domdef, suivit de grille nous donne tous
-; les tableaux de la grille sur le sous domaine 
+;   I.3) Obtainment of scale's factors and of the mask on the subdomain concernedby the average.
+; Redefinition of the domain ajusted at boxzoom (at 6 elements)
+; This will allowed us to calculate only in the domain concerned by the average.
+; Domdef, followed by grid give us all arrays of the grid on the subdomain 
 ;------------------------------------------------------------
   if keyword_set(boxzoom) then BEGIN 
@@ -162 +133 @@
   ENDIF 
 ;---------------------------------------------------------------
-; attribution du mask et des tableaux de longitude et latitude...
+; attribution of the mask and of longitude and latitude arrays...
 ;---------------------------------------------------------------
   IF vargrid EQ 'W' THEN wdepth = 1
@@ -168 +139 @@
 ;------------------------------------------------------------
 ;------------------------------------------------------------
-; II) Cas du tableau 1d
+; II) Case of the 1d array
 ;------------------------------------------------------------
 ;------------------------------------------------------------
@@ -177 +148 @@
     ENDIF
     case 1 of
-      nx EQ 1 AND ny EQ 1:BEGIN ;vecteur suivant z
+      nx EQ 1 AND ny EQ 1:BEGIN ;vector following z
         case n_elements(tab) of
           jpk:res = tab[firstz:lastz]
@@ -194 +165 @@
         ENDELSE 
       END
-      ny EQ 1:BEGIN             ;vecteur suivant x
+      ny EQ 1:BEGIN             ;vector following x
         case n_elements(tab) of
           jpi:res = tab[firstx:lastx]
@@ -211 +182 @@
         ENDELSE
       END
-      nx EQ 1:BEGIN             ;vecteur suivant y
+      nx EQ 1:BEGIN             ;vector following y
         case n_elements(tab) of
           jpj:res = tab[firsty:lasty]
@@ -232 +203 @@
 ;------------------------------------------------------------
 ;------------------------------------------------------------
-; II) Cas du tableau 2d
+; II) Case of the 2d array
 ;------------------------------------------------------------
 ;------------------------------------------------------------
   if (dim eq '2d') then begin
 ;---------------------------------------------------------------
-;   II.1) verification de la coherence de la taille du tableau a
-;   moyenner 
-; verification de la coherence entre la taille du tableau et le
-; domaine definit par domdef
-; le tableau en entree doit avoir soit la taille du domaine total
-; (jpi,jpj) soit celle du domaine reduit (nx,ny)
+;   II.1) verification of the coherence of the array's size to average
+; Verification of the coherence between the array's size and the domain defined by domdef
+; The input array must have either the total domain's size (jpi,jpj) or this 
+; one of the reduced domain (nx,ny)
 ;---------------------------------------------------------------
     case 1 of
@@ -254 +223 @@
     ENDCASE
     if keyword_set(nan) NE 0 then BEGIN 
-      if nan NE 1 then BEGIN    ; si nan n''est pas !values.f_nan 
-; on le met a !values.f_nan
+      if nan NE 1 then BEGIN    ; If nan is not !values.f_nan 
+; we put it at !values.f_nan
         if abs(nan) LT 1e6 then notanumber = where(res EQ nan) $
         ELSE notanumber = where(abs(res) GT abs(nan)/10.)
@@ -262 +231 @@
     ENDIF
 ;---------------------------------------------------------------
-; rq IL FAUT FAIRE ATTENTION AUX CAS OU LA DIM A MOYENNER = 1, ET
-; S'ASSURER QU'ELLE EXISTE BIEN. D'OU LES reform(...,nx,ny,...) QUI
-; PEUVENT SEMBLER INUTILE AU DEPART
+; Comment : WE HAVE TO BE CAREFUL ABOUT CASES WHERE THE DIMENSION TO AVERAGE = 1, 
+; AND MAKE SURE THAT IT EXIST. THAT IS WHY WE USE reform(...,nx,ny,...) WHICH CAN 
+; LOOK USELESS AT THE BEGINNING
 ;---------------------------------------------------------------
     if nx EQ 1 OR ny EQ 1 then BEGIN 
@@ -274 +243 @@
       mask =  reform(mask, nx, ny, nz, /over)
 ;---------------------------------------------------------------
-; II.3) differents types de moyennes
+; II.3) Different types of average
 ;---------------------------------------------------------------
     mask = mask[*, *, 0]
@@ -330 +299 @@
 ;------------------------------------------------------------
 ;------------------------------------------------------------
-; III) Cas du tableau 3d
+; III) Case 3d arrays series (tab4d)
 ;------------------------------------------------------------
 ;------------------------------------------------------------
   if (dim eq '3d') then begin
 ;---------------------------------------------------------------
-; III.1) verification de la coherence de la taille du tableau a
-; moyenner 
-; verification de la coherence entre la taille du tableau et le
-; domaine definit par domdef 
-; le tableau en entree doit avoir soit la taille du domaine total
-; (jpi,jpj,jpk) soit celle du domaine reduit (nx,ny,ny)
+; III.1) Verification of the coherence of the array to average size 
+; Verification of the coherence between the array's size and the domain 
+; defind by domdef 
+; The input array must have either the total domain size (jpi,jpj,jpk) 
+; or this one of the reduced domain (nx,ny,ny)
 ;---------------------------------------------------------------
     case 1 of
@@ -356 +324 @@
     endcase
     if keyword_set(nan) NE 0 then BEGIN 
-      if nan NE 1 then BEGIN    ; si nan n''est pas !values.f_nan 
-; on le met a !values.f_nan
+      if nan NE 1 then BEGIN    ; if nan is not !values.f_nan 
+; we put it at !values.f_nan
         if abs(nan) LT 1e6 then notanumber = where(res EQ nan) $
         ELSE notanumber = where(abs(res) GT abs(nan)/10.)
@@ -364 +332 @@
     ENDIF
 ;---------------------------------------------------------------
-; rq IL FAUT FAIRE ATTENTION AUX CAS OU LA DIM A MOYENNER = 1, ET
-; S'ASSURER QU'ELLE EXISTE BIEN. D'OU LES reform(...,nx,ny,...) QUI
-; PEUVENT SEMBLER INUTILE AU DEPART
+; Comment : WE HAVE TO BE CAREFUL ABOUT CASES WHERE THE DIMENSION TO AVERAGE = 1, 
+; AND MAKE SURE THAT IT EXIST. THAT IS WHY WE USE reform(...,nx,ny,...) WHICH CAN 
+; LOOK USELESS AT THE BEGINNING
 ;---------------------------------------------------------------
     if nx EQ 1 OR ny EQ 1 OR nz EQ 1 then BEGIN 
@@ -387 +355 @@
     ENDIF ELSE bottom = -1
 ;---------------------------------------------------------------
-; III.2) differents types de moyennes
+; III.2) different average types
 ;---------------------------------------------------------------
     if keyword_set(nan) NE 0 then msknan = finite(res) ELSE msknan = -1
@@ -570 +538 @@
 ;------------------------------------------------------------
 ;------------------------------------------------------------
-;IV ) finitions
-;------------------------------------------------------------
-;------------------------------------------------------------
-; IV.1) on masque les terres par une valeur a 1e+20
+;IV ) finishing
+;------------------------------------------------------------
+;------------------------------------------------------------
+; IV.1) We mask land by a value equal to 1.e+20
 ;------------------------------------------------------------
   valmask = 1e+20
@@ -581 +549 @@
   ENDIF  
 ;------------------------------------------------------------
-; IV.2) on remplace, quand nan ne 1, !values.f_nan par nan
+; IV.2) We replace, when nan equal 1, !values.f_nan by nan
 ;------------------------------------------------------------
   if keyword_set(nan) NE 0 then BEGIN 
@@ -592 +560 @@
   ENDIF
 ;------------------------------------------------------------
-; IV.3) on se remplace ds le sous domaine qui etait definit a l''entree de
-; moyenne 
+; IV.3) We replace in the domain whch was defined at the entry of average
 ;------------------------------------------------------------
   if keyword_set(savedbox) THEN restoreboxparam, 'boxparam4moyenne.dat'