Changeset 133 for trunk/SRC/Matrix/cmapply.pro

Timestamp:

07/07/06 11:57:27 (18 years ago)

Author:

navarro

Message:

english and nicer header (1)

Location:

trunk/SRC/Matrix

Files:

• . (added)
• cmapply.pro (moved) (moved from trunk/SRC/ToBeReviewed/MATRICE/cmapply.pro) (11 diffs)

trunk/SRC/Matrix/cmapply.pro

@@ +1 @@
+;; Utility function, adapted from CMPRODUCT
 ;+
-; NAME:
-;   CMAPPLY
-;
-; AUTHOR:
-;   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
-;   craigm@lheamail.gsfc.nasa.gov
-;
-; PURPOSE:
-;   Applies a function to specified dimensions of an array
-;
-; MAJOR TOPICS:
-;   Arrays
-;
-; CALLING SEQUENCE:
-;   XX = CMAPPLY(OP, ARRAY, DIMS, [/DOUBLE], [TYPE=TYPE])
-;
-; DESCRIPTION:
-;   CMAPPLY will apply one of a few select functions to specified 
+; @todo seb
+;-
+;
+function cmapply_product, x
+;
+  compile_opt idl2, strictarrsubs
+;
+  sz = size(x)
+  n = sz[1]
+
+  while n GT 1 do begin
+      if (n mod 2) EQ 1 then x[0,*] = x[0,*] * x[n-1,*]
+      n2 = floor(n/2)
+      x = x[0:n2-1,*] * x[n2:*,*]
+      n = n2
+  endwhile
+  return, reform(x[0,*], /overwrite)
+end
+
+;; Utility function, used to collect collaped dimensions
+;+
+; @todo seb
+;-
+;
+pro cmapply_redim, newarr, dimapply, dimkeep, nkeep, totcol, totkeep
+;
+  compile_opt idl2, strictarrsubs
+;
+  sz = size(newarr)
+  ;; First task: rearrange dimensions so that the dimensions
+  ;; that are "kept" (ie, uncollapsed) are at the back
+  dimkeep = where(histogram(dimapply,min=1,max=sz[0]) ne 1, nkeep)
+  if nkeep EQ 0 then return
+
+  newarr = transpose(temporary(newarr), [dimapply-1, dimkeep])
+  ;; totcol is the total number of collapsed elements
+  totcol = sz[dimapply[0]]
+  for i = 1, n_elements(dimapply)-1 do totcol = totcol * sz[dimapply[i]]
+  totkeep = sz[dimkeep[0]+1]
+  for i = 1, n_elements(dimkeep)-1 do totkeep = totkeep * sz[dimkeep[i]+1]
+
+  ;; this new array has two dimensions:
+  ;;   * the first, all elements that will be collapsed
+  ;;   * the second, all dimensions that will be preserved
+  ;; (the ordering is so that all elements to be collapsed are
+  ;;  adjacent in memory)
+  newarr = reform(newarr, [totcol, totkeep], /overwrite)
+end
+
+;; Main function
+;+
+;
+; @file_comments 
+; Applies a function to specified dimensions of an array
+;
+;   Description:
+;
+;      CMAPPLY will apply one of a few select functions to specified 
 ;   dimensions of an array.  Unlike some IDL functions, you *do* have
 ;   a choice of which dimensions that are to be "collapsed" by this
@@ -59 +100 @@
 ;   elements is large.
 ;
-;
-; INPUTS:
-;
-;   OP - The operation to perform, as a string.  May be upper or lower
+; @categories Arrays
+;
+; @param OP {in}{required} The operation to perform, as a string.  May be upper or lower
 ;        case.
 ;
@@ -69 +109 @@
 ;        the user-defined function.
 ;
-;   ARRAY - An array of values to be operated on.  Must not be of type
+; @param ARRAY {in}{required} An array of values to be operated on.  Must not be of type
 ;           STRING (7) or STRUCTURE (8).
 ;
-; OPTIONAL INPUTS:
-;
-;   DIMS - An array of dimensions that are to be "collapsed", where
+; @param DIMS {in}{optional}{default=1 (ie, first dimension)} 
+;          An array of dimensions that are to be "collapsed", where
 ;          the the first dimension starts with 1 (ie, same convention
 ;          as IDL function TOTAL).  Whereas TOTAL only allows one
@@ -84 +123 @@
 ;          DEFAULT: 1 (ie, first dimension)
 ;
-; KEYWORDS:
-;
-;   DOUBLE - Set this if you wish the internal computations to be done
+; @keyword DOUBLE Set this if you wish the internal computations to be done
 ;            in double precision if necessary.  If ARRAY is double 
 ;            precision (real or complex) then DOUBLE=1 is implied.
 ;            DEFAULT: not set
 ;
-;   TYPE - Set this to the IDL code of the desired output type (refer
+; @keyword TYPE Set this to the IDL code of the desired output type (refer
 ;          to documentation of SIZE()).  Internal results will be
 ;          rounded to the nearest integer if the output type is an
@@ -97 +134 @@
 ;          DEFAULT: same is input type
 ;
-;   FUNCTARGS - If OP is 'USER:...', then the contents of this keyword
+; @keyword FUNCTARGS If OP is 'USER:...', then the contents of this keyword
 ;               are passed to the user function using the _EXTRA
 ;               mechanism.  This way you can pass additional data to
@@ -104 +141 @@
 ;               DEFAULT: undefined (i.e., no keywords passed by _EXTRA)
 ;
-; RETURN VALUE:
-;
-;   An array of the required TYPE, whose elements are the result of
+; @returns An array of the required TYPE, whose elements are the result of
 ;   the requested operation.  Depending on the operation and number of
 ;   elements in the input array, the result may be vulnerable to
 ;   overflow or underflow.
 ;
-; EXAMPLES:
-;   Shows how CMAPPLY can be used to total the second dimension of the
+; @examples 
+;   
+;   First example:  Shows how CMAPPLY can be used to total the second dimension of the
 ;   array called IN.  This is equivalent to OUT = TOTAL(IN, 2)
 ;
@@ -120 +156 @@
 ;   OUT             INT       = Array[5]
 ;
-;   Second example.  Input is assumed to be an 5x100 array of 1's and
+;   Second example:  Input is assumed to be an 5x100 array of 1's and
 ;   0's indicating the status of 5 detectors at 100 points in time.
 ;   The desired output is an array of 100 values, indicating whether
@@ -134 +170 @@
 ;   although there would have been more loop iterations).
 ;
-;   Third example.  Shows sum over first and third dimensions in an
+;   Third example:  Shows sum over first and third dimensions in an
 ;   array with dimensions 4x4x4:
 ;
@@ -142 +178 @@
 ;        408     472     536     600
 ;
-;   Fourth example. A user-function (MEDIAN) is used:
+;   Fourth example:  A user-function (MEDIAN) is used:
 ;
 ;   IDL> IN = RANDOMN(SEED,10,10,5)
@@ -151 +187 @@
 ;   (OUT[i,j] is the median value of IN[i,j,*])
 ;
-; MODIFICATION HISTORY:
-;   Mar 1998, Written, CM
+; @history Mar 1998, Written, CM
 ;   Changed usage message to not bomb, 24 Mar 2000, CM
 ;   Signficant rewrite for *, MIN and MAX (inspired by Todd Clements
@@ -163 +198 @@
 ;   Correct bug in MAX/MIN initialization of RESULT, CM, 05 Dec 2002
 ;
-;  $Id$
+;  Author: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
+;  craigm@lheamail.gsfc.nasa.gov
+;
+; @version $Id$
 ;
 ;-
-; Copyright (C) 1998, 2000, 2002, Craig Markwardt
-; This software is provided as is without any warranty whatsoever.
-; Permission to use, copy, modify, and distribute modified or
-; unmodified copies is granted, provided this copyright and disclaimer
-; are included unchanged.
-;-
-
-;; Utility function, adapted from CMPRODUCT
-function cmapply_product, x
-;
-  compile_opt idl2, strictarrsubs
-;
-  sz = size(x)
-  n = sz[1]
-
-  while n GT 1 do begin
-      if (n mod 2) EQ 1 then x[0,*] = x[0,*] * x[n-1,*]
-      n2 = floor(n/2)
-      x = x[0:n2-1,*] * x[n2:*,*]
-      n = n2
-  endwhile
-  return, reform(x[0,*], /overwrite)
-end
-
-;; Utility function, used to collect collaped dimensions
-pro cmapply_redim, newarr, dimapply, dimkeep, nkeep, totcol, totkeep
-;
-  compile_opt idl2, strictarrsubs
-;
-  sz = size(newarr)
-  ;; First task: rearrange dimensions so that the dimensions
-  ;; that are "kept" (ie, uncollapsed) are at the back
-  dimkeep = where(histogram(dimapply,min=1,max=sz[0]) ne 1, nkeep)
-  if nkeep EQ 0 then return
-
-  newarr = transpose(temporary(newarr), [dimapply-1, dimkeep])
-  ;; totcol is the total number of collapsed elements
-  totcol = sz[dimapply[0]]
-  for i = 1, n_elements(dimapply)-1 do totcol = totcol * sz[dimapply[i]]
-  totkeep = sz[dimkeep[0]+1]
-  for i = 1, n_elements(dimkeep)-1 do totkeep = totkeep * sz[dimkeep[i]+1]
-
-  ;; this new array has two dimensions:
-  ;;   * the first, all elements that will be collapsed
-  ;;   * the second, all dimensions that will be preserved
-  ;; (the ordering is so that all elements to be collapsed are
-  ;;  adjacent in memory)
-  newarr = reform(newarr, [totcol, totkeep], /overwrite)
-end
-
-;; Main function
 function cmapply, op, array, dimapply, double=dbl, type=type, $
                   functargs=functargs, nocatch=nocatch