source: trunk/SRC/Documentation/idldoc_assistant_output/Matrix/cmapply.html @ 177

Last change on this file since 177 was 177, checked in by smasson, 18 years ago

updates of html files...

File size: 13.4 KB
Line 
1
2
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4  <head>
5    <title>cmapply.pro (SAXO Documentation Assistant)</title>
6  </head>
7
8  <body text="#000000" bgcolor="#FFFFFF">
9
10   
11<!-- Navbar template takes a structure with the following fields:
12       overview_href :
13       overview_selected :
14       dir_overview_href :
15       dir_overview_selected :
16       categories_href :
17       categories_selected :
18       index_href :
19       index_selected :
20       search_href :
21       search_selected :
22       file_selected :
23       source_href :
24       source_selected :
25       help_href :
26       help_selected :
27       etc_selected :
28
29       prev_file_href :
30       next_file_href :
31
32       view_single_page_href :
33       view_frames_href :
34
35       summary_fields_href :
36       summary_routine_href :
37       details_routine_href :
38
39       title :
40       subtitle :
41       user :
42-->
43
44
45<table border="0" cellpadding="0" cellspacing="0" width="98%" bgcolor="#F0F0FF" valign="bottom">
46  <tr>
47    <td width="10%">
48<a href=""><img src="./../prev.gif" border="0" alt="Previous"></a></td>
49    <td width="80%" align="center" valign="center">
50<font size=-1><i>SAXO Documentation Assistant</i>: <a href="./../home.html">Overview</a></font></td>
51    <td width="10%" align="right">
52<a href="cmset_op.html"><img src="./../next.gif" border="0" alt="Next"></a></td>
53  </tr>
54</table>
55
56
57    <h1><font size="-2">Matrix/</font></h1>
58    <h2>cmapply.pro</h2>
59
60    <dl>
61    </dl>
62
63   
64 Utility function, adapted from CMPRODUCT
65
66
67 cmapply_redim : Utility function, used to collect collaped dimensions
68
69
70 Applies a function to specified dimensions of an array
71
72 Description:
73
74 CMAPPLY will apply one of a few select functions to specified
75 dimensions of an array.  Unlike some IDL functions, you *do* have
76 a choice of which dimensions that are to be "collapsed" by this
77 function.  Iterative loops are avoided where possible, for
78 performance reasons.
79
80   The possible functions are:             (and number of loop iterations:)
81     +     - Performs a sum (as in TOTAL)       number of collapsed dimensions
82     AND   - Finds LOGICAL "AND" (not bitwise)  same
83     OR    - Finds LOGICAL "OR"  (not bitwise)  same
84     *     - Performs a product                 LOG_2[no. of collapsed elts.]
85
86     MIN   - Finds the minimum value            smaller of no. of collapsed
87     MAX   - Finds the maximum value            or output elements
88
89     USER  - Applies user-defined function      no. of output elements
90
91
92   It is possible to perform user-defined operations arrays using
93   CMAPPLY.  The OP parameter is set to 'USER:FUNCTNAME', where
94   FUNCTNAME is the name of a user-defined function.  The user
95   defined function should be defined such that it accepts a single
96   parameter, a vector, and returns a single scalar value.  Here is a
97   prototype for the function definition:
98
99      FUNCTION FUNCTNAME, x, KEYWORD1=key1, ...
100         scalar = ... function of x or keywords ...
101         RETURN, scalar
102      END
103
104   The function may accept keywords.  Keyword values are passed in to
105   CMAPPLY through the FUNCTARGS keywords parameter, and passed to
106   the user function via the _EXTRA mechanism.  Thus, while the
107   definition of the user function is highly constrained in the
108   number of positional parameters, there is absolute freedom in
109   passing keyword parameters.
110
111   It's worth noting however, that the implementation of user-defined
112   functions is not particularly optimized for speed.  Users are
113   encouraged to implement their own array if the number of output
114   elements is large.
115
116
117   
118    <h2>Routine summary</h2>
119
120    <dl>
121     
122      <dt><a href="#_cmapply_product"><i>result = </i>cmapply_product(<i>x</i>)</a><dt>
123      <dd><font size="-1"></font></dd>
124     
125      <dt><a href="#_cmapply_redim">cmapply_redim<i>, newarr, dimapply, dimkeep, nkeep, totcol, totkeep</i></a><dt>
126      <dd><font size="-1"></font></dd>
127     
128      <dt><a href="#_cmapply"><i>result = </i>cmapply(<i>op, array[, dimapply]</i>, double=<i>double</i>, type=<i>type</i>, functargs=<i>functargs</i>, nocatch=<i>nocatch</i>)</a><dt>
129      <dd><font size="-1"> </font></dd>
130     
131    </dl>
132
133    <p>&nbsp;</p>
134   
135
136     
137      <a name="#_cmapply_product"></a>
138
139      <h2>cmapply_product  </h2>
140
141      <p><font face="Courier"><i>result = </i>cmapply_product(<i><a href="#_cmapply_product_keyword_x">x</a></i>)</font></p>
142
143   
144
145   
146
147   
148    <h3>Parameters</h3>
149   
150
151    <a name="#_cmapply_product_keyword_x"></a>
152    <h4>x&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
153     
154     
155     
156     
157     
158     
159     
160     
161    </h4>
162
163   
164
165
166   
167   
168
169   
170
171   
172    <h3>Version history</h3>
173   
174    <h4>Version</h4> $Id: cmapply.pro 163 2006-08-29 12:59:46Z navarro $
175
176   
177   
178
179    <h3>Known issues</h3>
180   
181   
182    <h4>Todo items</h4> seb
183   
184
185   
186   
187   
188   
189   
190   
191   
192
193    <font size="-3"><p>&nbsp;</p></font>
194    <hr size="1" color="#CCCCCC"/>
195     
196      <a name="#_cmapply_redim"></a>
197
198      <h2>cmapply_redim  </h2>
199
200      <p><font face="Courier">cmapply_redim<i>, <a href="#_cmapply_redim_keyword_newarr">newarr</a>, <a href="#_cmapply_redim_keyword_dimapply">dimapply</a>, <a href="#_cmapply_redim_keyword_dimkeep">dimkeep</a>, <a href="#_cmapply_redim_keyword_nkeep">nkeep</a>, <a href="#_cmapply_redim_keyword_totcol">totcol</a>, <a href="#_cmapply_redim_keyword_totkeep">totkeep</a></i></font></p>
201
202   
203
204   
205
206   
207    <h3>Parameters</h3>
208   
209
210    <a name="#_cmapply_redim_keyword_newarr"></a>
211    <h4>newarr&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
212     
213     
214     
215     
216     
217     
218     
219     
220    </h4>
221
222   
223
224
225   
226
227    <a name="#_cmapply_redim_keyword_dimapply"></a>
228    <h4>dimapply&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
229     
230     
231     
232     
233     
234     
235     
236     
237    </h4>
238
239   
240
241
242   
243
244    <a name="#_cmapply_redim_keyword_dimkeep"></a>
245    <h4>dimkeep&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
246     
247     
248     
249     
250     
251     
252     
253     
254    </h4>
255
256   
257
258
259   
260
261    <a name="#_cmapply_redim_keyword_nkeep"></a>
262    <h4>nkeep&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
263     
264     
265     
266     
267     
268     
269     
270     
271    </h4>
272
273   
274
275
276   
277
278    <a name="#_cmapply_redim_keyword_totcol"></a>
279    <h4>totcol&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
280     
281     
282     
283     
284     
285     
286     
287     
288    </h4>
289
290   
291
292
293   
294
295    <a name="#_cmapply_redim_keyword_totkeep"></a>
296    <h4>totkeep&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
297     
298     
299     
300     
301     
302     
303     
304     
305    </h4>
306
307   
308
309
310   
311   
312
313   
314
315   
316   
317   
318   
319   
320   
321
322    <h3>Known issues</h3>
323   
324   
325    <h4>Todo items</h4> seb
326   
327
328   
329   
330   
331   
332   
333   
334   
335
336    <font size="-3"><p>&nbsp;</p></font>
337    <hr size="1" color="#CCCCCC"/>
338     
339      <a name="#_cmapply"></a>
340
341      <h2>cmapply  <font size="-1" color="#006633"> 
342 Array
343</font></h2>
344
345      <p><font face="Courier"><i>result = </i>cmapply(<i><a href="#_cmapply_keyword_op">op</a>, <a href="#_cmapply_keyword_array">array</a>[, <a href="#_cmapply_keyword_dimapply">dimapply</a>]</i>, <a href="#_cmapply_keyword_double">double</a>=<i>double</i>, <a href="#_cmapply_keyword_type">type</a>=<i>type</i>, <a href="#_cmapply_keyword_functargs">functargs</a>=<i>functargs</i>, <a href="#_cmapply_keyword_nocatch">nocatch</a>=<i>nocatch</i>)</font></p>
346
347   
348
349
350    <h3>Return value</h3>
351 An array of the required TYPE, whose elements are the result of
352 the requested operation.  Depending on the operation and number of
353 elements in the input array, the result may be vulnerable to
354 overflow or underflow.
355
356
357   
358    <h3>Parameters</h3>
359   
360
361    <a name="#_cmapply_keyword_op"></a>
362    <h4>op&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
363      <font size="-1" color="#006633">in</font>
364     
365     
366      <font size="-1" color="#006633">required</font>
367     
368      <font size="-1" color="#006633">type:</font> <font size="-1" color="#006633"><i>string</i></font>
369     
370     
371    </h4>
372
373   
374 The operation to perform, as a string.  May be upper or lower case.
375
376 If a user-defined operation is to be passed, then OP is of
377 the form, 'USER:FUNCTNAME', where FUNCTNAME is the name of
378 the user-defined function.
379
380   
381
382    <a name="#_cmapply_keyword_array"></a>
383    <h4>array&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
384      <font size="-1" color="#006633">in</font>
385     
386     
387      <font size="-1" color="#006633">required</font>
388     
389      <font size="-1" color="#006633">type:</font> <font size="-1" color="#006633"><i>array</i></font>
390     
391     
392    </h4>
393
394     
395 An array of values to be operated on.
396 Must not be of type STRING (7) or STRUCTURE (8).
397
398   
399
400    <a name="#_cmapply_keyword_dimapply"></a>
401    <h4>dimapply&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
402      <font size="-1" color="#006633">in</font>
403     
404      <font size="-1" color="#006633">optional</font>
405     
406     
407      <font size="-1" color="#006633">type:</font> <font size="-1" color="#006633"><i>array</i></font>
408      <font size="-1" color="#006633">default:</font> <font size="-1" color="#006633"><i>1 (ie, first dimension)</i></font>
409     
410    </h4>
411
412   
413 An array of dimensions that are to be "collapsed", where
414 the the first dimension starts with 1 (ie, same convention
415 as IDL function TOTAL).  Whereas TOTAL only allows one
416 dimension to be added, you can specify multiple dimensions
417 to CMAPPLY.  Order does not matter, since all operations
418 are associative and transitive.  NOTE: the dimensions refer
419 to the *input* array, not the output array.  IDL allows a
420 maximum of 8 dimensions.
421
422   
423   
424
425   
426    <h3>Keywords</h3>
427
428   
429    <a name="#_cmapply_keyword_double"></a>
430    <h4>double&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
431     
432     
433     
434     
435     
436     
437      <font size="-1" color="#006633">default:</font> <font size="-1" color="#006633"><i>not set</i></font>
438     
439    </h4>
440
441   
442 Set this if you wish the internal computations to be done
443 in double precision if necessary.  If ARRAY is double
444 precision (real or complex) then DOUBLE=1 is implied.
445
446   
447    <a name="#_cmapply_keyword_type"></a>
448    <h4>type&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
449     
450     
451     
452     
453     
454     
455      <font size="-1" color="#006633">default:</font> <font size="-1" color="#006633"><i>same as input type</i></font>
456     
457    </h4>
458
459   
460 Set this to the IDL code of the desired output type (refer
461 to documentation of SIZE()).  Internal results will be
462 rounded to the nearest integer if the output type is an
463 integer type.
464
465   
466    <a name="#_cmapply_keyword_functargs"></a>
467    <h4>functargs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
468     
469     
470     
471     
472     
473     
474     
475     
476    </h4>
477
478   
479 If OP is 'USER:...', then the contents of this keyword
480 are passed to the user function using the _EXTRA
481 mechanism.  This way you can pass additional data to
482 your user-supplied function, via keywords, without
483 using common blocks.
484 DEFAULT: undefined (i.e., no keywords passed by _EXTRA)
485
486   
487    <a name="#_cmapply_keyword_nocatch"></a>
488    <h4>nocatch&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
489     
490     
491     
492     
493     
494     
495     
496     
497    </h4>
498
499   
500   
501   
502
503    <h3>Examples</h3>
504
505   First example:  Shows how CMAPPLY can be used to total the second dimension of the
506   array called IN.  This is equivalent to OUT = TOTAL(IN, 2)
507
508   IDL> IN  = INDGEN(5,5)
509   IDL> OUT = CMAPPLY('+', IN, [2])
510   IDL> HELP, OUT
511   OUT             INT       = Array[5]
512
513   Second example:  Input is assumed to be an 5x100 array of 1's and
514   0's indicating the status of 5 detectors at 100 points in time.
515   The desired output is an array of 100 values, indicating whether
516   all 5 detectors are on (=1) at one time.  Use the logical AND
517   operation.
518
519   IDL> IN = detector_status             ; 5x100 array
520   IDL> OUT = CMAPPLY('AND', IN, [1])    ; collapses 1st dimension
521   IDL> HELP, OUT
522   OUT             BYTE      = Array[100]
523
524   (note that MIN could also have been used in this particular case,
525   although there would have been more loop iterations).
526
527   Third example:  Shows sum over first and third dimensions in an
528   array with dimensions 4x4x4:
529
530   IDL> IN = INDGEN(4,4,4)
531   IDL> OUT = CMAPPLY('+', IN, [1,3])
532   IDL> PRINT, OUT
533        408     472     536     600
534
535   Fourth example:  A user-function (MEDIAN) is used:
536
537   IDL> IN = RANDOMN(SEED,10,10,5)
538   IDL> OUT = CMAPPLY('USER:MEDIAN', IN, 3)
539   IDL> HELP, OUT
540   OUT             FLOAT     = Array[10, 10]
541
542   (OUT[i,j] is the median value of IN[i,j,*])
543
544    <h3>Version history</h3>
545   
546    <h4>Version</h4> $Id: cmapply.pro 163 2006-08-29 12:59:46Z navarro $
547
548    <h4>History</h4> Mar 1998, Written, CM
549   Changed usage message to not bomb, 24 Mar 2000, CM
550   Significant rewrite for *, MIN and MAX (inspired by Todd Clements
551     <Todd_Clements@alumni.hmc.edu>); FOR loop indices are now type
552     LONG; copying terms are liberalized, CM, 22, Aug 2000
553   More efficient MAX/MIN (inspired by Alex Schuster), CM, 25 Jan
554     2002
555   Make new MAX/MIN actually work with 3d arrays, CM, 08 Feb 2002
556   Add user-defined functions, ON_ERROR, CM, 09 Feb 2002
557   Correct bug in MAX/MIN initialization of RESULT, CM, 05 Dec 2002
558
559  Author: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
560  craigm@lheamail.gsfc.nasa.gov
561
562   
563
564   
565   
566   
567   
568   
569
570   
571   
572   
573   
574   
575   
576   
577
578    <font size="-3"><p>&nbsp;</p></font>
579    <hr size="1" color="#CCCCCC"/>
580     
581
582   
583
584    <p><font color="gray" size="-3">&nbsp;&nbsp;Produced by IDLdoc 2.0 on Wed Sep 13 16:32:16 2006.</font></p>
585
586  </body>
587</html>
Note: See TracBrowser for help on using the repository browser.