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

Last change on this file since 234 was 234, checked in by pinsard, 17 years ago

new idldoc html and assistant outputs

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   
173    </pre><h3>Version history</h3>
174   
175    <h4>Version</h4> $Id: cmapply.pro 232 2007-03-20 16:59:36Z 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    <h3>Parameters</h3>
209   
210
211    <a name="#_cmapply_redim_keyword_newarr"></a>
212    <h4>newarr&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
213     
214     
215     
216     
217     
218     
219     
220     
221    </h4>
222
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
245    <a name="#_cmapply_redim_keyword_dimkeep"></a>
246    <h4>dimkeep&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
247     
248     
249     
250     
251     
252     
253     
254     
255    </h4>
256
257   
258
259
260   
261
262    <a name="#_cmapply_redim_keyword_nkeep"></a>
263    <h4>nkeep&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
264     
265     
266     
267     
268     
269     
270     
271     
272    </h4>
273
274   
275
276
277   
278
279    <a name="#_cmapply_redim_keyword_totcol"></a>
280    <h4>totcol&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
281     
282     
283     
284     
285     
286     
287     
288     
289    </h4>
290
291   
292
293
294   
295
296    <a name="#_cmapply_redim_keyword_totkeep"></a>
297    <h4>totkeep&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
298     
299     
300     
301     
302     
303     
304     
305     
306    </h4>
307
308   
309
310
311   
312   
313
314   
315
316   
317   
318   
319   
320   
321   
322
323    <h3>Known issues</h3>
324   
325   
326    <h4>Todo items</h4> seb
327   
328
329   
330   
331   
332   
333   
334   
335   
336
337    <font size="-3"><p>&nbsp;</p></font>
338    <hr size="1" color="#CCCCCC"/>
339     
340      <a name="#_cmapply"></a>
341
342      <h2>cmapply  <font size="-1" color="#006633"> 
343 Array
344</font></h2>
345
346      <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>
347
348   
349
350
351    <h3>Return value</h3>
352 An array of the required TYPE, whose elements are the result of
353 the requested operation.  Depending on the operation and number of
354 elements in the input array, the result may be vulnerable to
355 overflow or underflow.
356
357
358   
359    <h3>Parameters</h3>
360   
361
362    <a name="#_cmapply_keyword_op"></a>
363    <h4>op&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
364      <font size="-1" color="#006633">in</font>
365     
366     
367      <font size="-1" color="#006633">required</font>
368     
369      <font size="-1" color="#006633">type:</font> <font size="-1" color="#006633"><i>string</i></font>
370     
371     
372    </h4>
373
374   
375 The operation to perform, as a string.  May be upper or lower case.
376
377 If a user-defined operation is to be passed, then OP is of
378 the form, 'USER:FUNCTNAME', where FUNCTNAME is the name of
379 the user-defined function.
380
381   
382
383    <a name="#_cmapply_keyword_array"></a>
384    <h4>array&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
385      <font size="-1" color="#006633">in</font>
386     
387     
388      <font size="-1" color="#006633">required</font>
389     
390      <font size="-1" color="#006633">type:</font> <font size="-1" color="#006633"><i>array</i></font>
391     
392     
393    </h4>
394
395     
396 An array of values to be operated on.
397 Must not be of type STRING (7) or STRUCTURE (8).
398
399   
400
401    <a name="#_cmapply_keyword_dimapply"></a>
402    <h4>dimapply&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
403      <font size="-1" color="#006633">in</font>
404     
405      <font size="-1" color="#006633">optional</font>
406     
407     
408      <font size="-1" color="#006633">type:</font> <font size="-1" color="#006633"><i>array</i></font>
409      <font size="-1" color="#006633">default:</font> <font size="-1" color="#006633"><i>1 (ie, first dimension)</i></font>
410     
411    </h4>
412
413   
414 An array of dimensions that are to be "collapsed", where
415 the the first dimension starts with 1 (ie, same convention
416 as IDL function TOTAL).  Whereas TOTAL only allows one
417 dimension to be added, you can specify multiple dimensions
418 to CMAPPLY.  Order does not matter, since all operations
419 are associative and transitive.  NOTE: the dimensions refer
420 to the *input* array, not the output array.  IDL allows a
421 maximum of 8 dimensions.
422
423   
424   
425
426   
427    <h3>Keywords</h3>
428
429   
430    <a name="#_cmapply_keyword_double"></a>
431    <h4>double&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
432     
433     
434     
435     
436     
437     
438      <font size="-1" color="#006633">default:</font> <font size="-1" color="#006633"><i>not set</i></font>
439     
440    </h4>
441
442   
443 Set this if you wish the internal computations to be done
444 in double precision if necessary.  If ARRAY is double
445 precision (real or complex) then DOUBLE=1 is implied.
446
447   
448    <a name="#_cmapply_keyword_type"></a>
449    <h4>type&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
450     
451     
452     
453     
454     
455     
456      <font size="-1" color="#006633">default:</font> <font size="-1" color="#006633"><i>same as input type</i></font>
457     
458    </h4>
459
460   
461 Set this to the IDL code of the desired output type (refer
462 to documentation of SIZE()).  Internal results will be
463 rounded to the nearest integer if the output type is an
464 integer type.
465
466   
467    <a name="#_cmapply_keyword_functargs"></a>
468    <h4>functargs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
469     
470     
471     
472     
473     
474     
475     
476     
477    </h4>
478
479   
480 If OP is 'USER:...', then the contents of this keyword
481 are passed to the user function using the _EXTRA
482 mechanism.  This way you can pass additional data to
483 your user-supplied function, via keywords, without
484 using common blocks.
485 DEFAULT: undefined (i.e., no keywords passed by _EXTRA)
486
487   
488    <a name="#_cmapply_keyword_nocatch"></a>
489    <h4>nocatch&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
490     
491     
492     
493     
494     
495     
496     
497     
498    </h4>
499
500   
501   
502   
503
504    <h3>Examples</h3><pre>
505
506   First example:  Shows how CMAPPLY can be used to total the second dimension of the
507   array called IN.  This is equivalent to OUT = TOTAL(IN, 2)
508
509   IDL> IN  = INDGEN(5,5)
510   IDL> OUT = CMAPPLY('+', IN, [2])
511   IDL> HELP, OUT
512   OUT             INT       = Array[5]
513
514   Second example:  Input is assumed to be an 5x100 array of 1's and
515   0's indicating the status of 5 detectors at 100 points in time.
516   The desired output is an array of 100 values, indicating whether
517   all 5 detectors are on (=1) at one time.  Use the logical AND
518   operation.
519
520   IDL> IN = detector_status             ; 5x100 array
521   IDL> OUT = CMAPPLY('AND', IN, [1])    ; collapses 1st dimension
522   IDL> HELP, OUT
523   OUT             BYTE      = Array[100]
524
525   (note that MIN could also have been used in this particular case,
526   although there would have been more loop iterations).
527
528   Third example:  Shows sum over first and third dimensions in an
529   array with dimensions 4x4x4:
530
531   IDL> IN = INDGEN(4,4,4)
532   IDL> OUT = CMAPPLY('+', IN, [1,3])
533   IDL> PRINT, OUT
534        408     472     536     600
535
536   Fourth example:  A user-function (MEDIAN) is used:
537
538   IDL> IN = RANDOMN(SEED,10,10,5)
539   IDL> OUT = CMAPPLY('USER:MEDIAN', IN, 3)
540   IDL> HELP, OUT
541   OUT             FLOAT     = Array[10, 10]
542
543   (OUT[i,j] is the median value of IN[i,j,*])
544
545    </pre><h3>Version history</h3>
546   
547    <h4>Version</h4> 
548 $Id: cmapply.pro 232 2007-03-20 16:59:36Z pinsard $
549
550    <h4>History</h4> 
551 Mar 1998, Written, CM
552   Changed usage message to not bomb, 24 Mar 2000, CM
553   Significant rewrite for *, MIN and MAX (inspired by Todd Clements
554     <Todd_Clements@alumni.hmc.edu>); FOR loop indices are now type
555     LONG; copying terms are liberalized, CM, 22, Aug 2000
556   More efficient MAX/MIN (inspired by Alex Schuster), CM, 25 Jan
557     2002
558   Make new MAX/MIN actually work with 3d arrays, CM, 08 Feb 2002
559   Add user-defined functions, ON_ERROR, CM, 09 Feb 2002
560   Correct bug in MAX/MIN initialization of RESULT, CM, 05 Dec 2002
561
562  Author: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
563  craigm@lheamail.gsfc.nasa.gov
564
565   
566
567   
568   
569   
570   
571   
572
573   
574   
575   
576   
577   
578   
579   
580
581    <font size="-3"><p>&nbsp;</p></font>
582    <hr size="1" color="#CCCCCC"/>
583     
584
585   
586
587    <p><font color="gray" size="-3">&nbsp;&nbsp;Produced by IDLdoc 2.0.</font></p>
588
589  </body>
590</html>
Note: See TracBrowser for help on using the repository browser.