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

Last change on this file since 338 was 338, checked in by smasson, 16 years ago

update documentation
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   
149    <h3>Parameters</h3>
150   
151
152    <a name="#_cmapply_product_keyword_x"></a>
153    <h4>x&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
154     
155     
156     
157     
158     
159     
160     
161     
162    </h4>
163
164   
165
166   
167   
168
169   
170
171   
172    </pre><h3>Version history</h3>
173   
174    <h4>Version</h4>
175 $Id: cmapply.pro 325 2007-12-06 10:04:53Z pinsard $
176
177   
178   
179
180    <h3>Known issues</h3>
181   
182   
183    <h4>Todo items</h4> seb
184   
185
186   
187   
188   
189   
190   
191   
192   
193
194    <font size="-3"><p>&nbsp;</p></font>
195    <hr size="1" color="#CCCCCC"/>
196     
197      <a name="#_cmapply_redim"></a>
198
199      <h2>cmapply_redim  </h2>
200
201      <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>
202
203   
204
205
206   
207
208   
209    <h3>Parameters</h3>
210   
211
212    <a name="#_cmapply_redim_keyword_newarr"></a>
213    <h4>newarr&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
214     
215     
216     
217     
218     
219     
220     
221     
222    </h4>
223
224   
225
226   
227
228    <a name="#_cmapply_redim_keyword_dimapply"></a>
229    <h4>dimapply&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
230     
231     
232     
233     
234     
235     
236     
237     
238    </h4>
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    <a name="#_cmapply_redim_keyword_nkeep"></a>
261    <h4>nkeep&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
262     
263     
264     
265     
266     
267     
268     
269     
270    </h4>
271
272   
273
274   
275
276    <a name="#_cmapply_redim_keyword_totcol"></a>
277    <h4>totcol&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
278     
279     
280     
281     
282     
283     
284     
285     
286    </h4>
287
288   
289
290   
291
292    <a name="#_cmapply_redim_keyword_totkeep"></a>
293    <h4>totkeep&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
294     
295     
296     
297     
298     
299     
300     
301     
302    </h4>
303
304   
305
306   
307   
308
309   
310
311   
312   
313   
314   
315   
316   
317
318    <h3>Known issues</h3>
319   
320   
321    <h4>Todo items</h4> seb
322
323   
324
325   
326   
327   
328   
329   
330   
331   
332
333    <font size="-3"><p>&nbsp;</p></font>
334    <hr size="1" color="#CCCCCC"/>
335     
336      <a name="#_cmapply"></a>
337
338      <h2>cmapply  <font size="-1" color="#006633">
339 Array
340</font></h2>
341
342      <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>
343
344   
345
346
347    <h3>Return value</h3>
348 An array of the required TYPE, whose elements are the result of
349 the requested operation.  Depending on the operation and number of
350 elements in the input array, the result may be vulnerable to
351 overflow or underflow.
352
353
354   
355    <h3>Parameters</h3>
356   
357
358    <a name="#_cmapply_keyword_op"></a>
359    <h4>op&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
360      <font size="-1" color="#006633">in</font>
361     
362     
363      <font size="-1" color="#006633">required</font>
364     
365      <font size="-1" color="#006633">type:</font> <font size="-1" color="#006633"><i>string</i></font>
366     
367     
368    </h4>
369
370   
371 The operation to perform, as a string.  May be upper or lower case.
372
373 If a user-defined operation is to be passed, then OP is of
374 the form, 'USER:FUNCTNAME', where FUNCTNAME is the name of
375 the user-defined function.
376
377   
378
379    <a name="#_cmapply_keyword_array"></a>
380    <h4>array&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
381      <font size="-1" color="#006633">in</font>
382     
383     
384      <font size="-1" color="#006633">required</font>
385     
386      <font size="-1" color="#006633">type:</font> <font size="-1" color="#006633"><i>array</i></font>
387     
388     
389    </h4>
390
391   
392 An array of values to be operated on.
393 Must not be of type STRING (7) or STRUCTURE (8).
394
395   
396
397    <a name="#_cmapply_keyword_dimapply"></a>
398    <h4>dimapply&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
399      <font size="-1" color="#006633">in</font>
400     
401      <font size="-1" color="#006633">optional</font>
402     
403     
404      <font size="-1" color="#006633">type:</font> <font size="-1" color="#006633"><i>array</i></font>
405      <font size="-1" color="#006633">default:</font> <font size="-1" color="#006633"><i>1 (ie, first dimension)</i></font>
406     
407    </h4>
408
409   
410 An array of dimensions that are to be "collapsed", where
411 the first dimension starts with 1 (ie, same convention
412 as IDL function TOTAL).  Whereas TOTAL only allows one
413 dimension to be added, you can specify multiple dimensions
414 to CMAPPLY.  Order does not matter, since all operations
415 are associative and transitive.  NOTE: the dimensions refer
416 to the *input* array, not the output array.  IDL allows a
417 maximum of 8 dimensions.
418
419   
420   
421
422   
423    <h3>Keywords</h3>
424
425   
426    <a name="#_cmapply_keyword_DOUBLE"></a>
427    <h4>DOUBLE&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
428     
429     
430     
431     
432     
433     
434      <font size="-1" color="#006633">default:</font> <font size="-1" color="#006633"><i>not set</i></font>
435     
436    </h4>
437
438   
439 Set this if you wish the internal computations to be done
440 in double precision if necessary.  If ARRAY is double
441 precision (real or complex) then DOUBLE=1 is implied.
442
443   
444    <a name="#_cmapply_keyword_TYPE"></a>
445    <h4>TYPE&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
446     
447     
448     
449     
450     
451     
452      <font size="-1" color="#006633">default:</font> <font size="-1" color="#006633"><i>same as input type</i></font>
453     
454    </h4>
455
456   
457 Set this to the IDL code of the desired output type (refer
458 to documentation of <a href="/Applications/itt/idl64/help/online_help/SIZE.html">SIZE</a>). Internal results will be
459 rounded to the nearest integer if the output type is an
460 integer type.
461
462   
463    <a name="#_cmapply_keyword_FUNCTARGS"></a>
464    <h4>FUNCTARGS&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
465     
466     
467     
468     
469     
470     
471     
472     
473    </h4>
474
475   
476 If OP is 'USER:...', then the contents of this keyword
477 are passed to the user function using the _EXTRA
478 mechanism.  This way you can pass additional data to
479 your user-supplied function, via keywords, without
480 using common blocks.
481 DEFAULT: undefined (i.e., no keywords passed by _EXTRA)
482
483   
484    <a name="#_cmapply_keyword_NOCATCH"></a>
485    <h4>NOCATCH&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
486     
487     
488     
489     
490     
491     
492     
493     
494    </h4>
495
496   
497   
498   
499
500    <h3>Examples</h3><pre>
501
502   First example: 
503   Shows how <a href="..//Matrix/cmapply.html">cmapply</a> can be used to total the second dimension of
504   the array called IN. This is equivalent to OUT = TOTAL(IN, 2)
505
506   IDL> IN  = INDGEN(5,5)
507   IDL> OUT = CMAPPLY('+', IN, [2])
508   IDL> HELP, OUT
509   OUT             INT       = Array[5]
510
511   Second example:  Input is assumed to be an 5x100 array of 1's and
512   0's indicating the status of 5 detectors at 100 points in time.
513   The desired output is an array of 100 values, indicating whether
514   all 5 detectors are on (=1) at one time.  Use the logical AND
515   operation.
516
517   IDL> IN = detector_status             ; 5x100 array
518   IDL> OUT = CMAPPLY('AND', IN, [1])    ; collapses 1st dimension
519   IDL> HELP, OUT
520   OUT             BYTE      = Array[100]
521
522   (note that MIN could also have been used in this particular case,
523   although there would have been more loop iterations).
524
525   Third example:  Shows sum over first and third dimensions in an
526   array with dimensions 4x4x4:
527
528   IDL> IN = INDGEN(4,4,4)
529   IDL> OUT = CMAPPLY('+', IN, [1,3])
530   IDL> PRINT, OUT
531        408     472     536     600
532
533   Fourth example:  A user-function (MEDIAN) is used:
534
535   IDL> IN = RANDOMN(SEED,10,10,5)
536   IDL> OUT = CMAPPLY('USER:MEDIAN', IN, 3)
537   IDL> HELP, OUT
538   OUT             FLOAT     = Array[10, 10]
539
540   (OUT[i,j] is the median value of IN[i,j,*])
541
542    </pre><h3>Version history</h3>
543   
544    <h4>Version</h4>
545 $Id: cmapply.pro 325 2007-12-06 10:04:53Z pinsard $
546
547    <h4>History</h4>
548 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.</font></p>
585
586  </body>
587</html>
Note: See TracBrowser for help on using the repository browser.