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

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

update documentation
File size: 11.0 KB
Line 
1
2
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4  <head>
5    <title>cmset_op.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="cmapply.html"><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="different.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>cmset_op.pro</h2>
59
60    <dl>
61    </dl>
62
63   
64 Simplified version of CMSET_OP_UNIQ which sorts, and takes the
65 "first" value, whatever that may mean.
66
67
68 Performs an AND, OR, or XOR operation between two sets
69
70 Description: SET_OP performs three common operations between two sets. The
71 three supported functions of OP are:
72
73        OP          Meaning
74      'AND' - to find the intersection of A and B;
75      'OR'  - to find the union of A and B;
76      'XOR' - to find the those elements who are members of A or B
77              but not both;
78
79   Sets as defined here is one dimensional array composed of
80   numeric or string types. Comparisons of equality between elements
81   are done using the IDL EQ operator.
82
83   The complements of either set can be taken as well, by using the
84   NOT1 and NOT2 keywords. For example, it may be desirable to find
85   the elements in A but not B, or B but not A (they are different!).
86   The following IDL expressions achieve each of those effects:
87
88      SET = CMSET_OP(A, 'AND', /NOT2, B)   ; A but not B
89      SET = CMSET_OP(/NOT1, A, 'AND', B)   ; B but not A
90
91   Note the distinction between NOT1 and NOT2.  NOT1 refers to the
92   first set (A) and NOT2 refers to the second (B).  Their ordered
93   placement in the calling sequence is entirely optional, but the
94   above ordering makes the logical meaning explicit.
95
96   NOT1 and NOT2 can only be set for the 'AND' operator, and never
97   simultaneously. This is because the results of an operation with
98   'OR' or 'XOR' and any combination of NOTs -- or with 'AND' and
99   both NOTs -- formally cannot produce a defined result.
100
101   The implementation depends on the type of operands. For integer
102   types, a fast technique using HISTOGRAM is used. However, this
103   algorithm becomes inefficient when the dynamic range in the data
104   is large. For those cases, and for other data types, a technique
105   based on SORT() is used. Thus the compute time should scale
106   roughly as (A+B)*ALOG(A+B) or better, rather than (A*B) for the
107   brute force approach. For large arrays this is a significant
108   benefit.
109
110
111   
112
113     
114      <a name="#_cmset_op"></a>
115
116      <h2>cmset_op  <font size="-1" color="#006633">
117 Array
118</font></h2>
119
120      <p><font face="Courier"><i>result = </i>cmset_op(<i><a href="#_cmset_op_keyword_a">a</a>, <a href="#_cmset_op_keyword_op0">op0</a>, <a href="#_cmset_op_keyword_b">b</a></i>, <a href="#_cmset_op_keyword_NOT1">NOT1</a>=<i>NOT1</i>, <a href="#_cmset_op_keyword_NOT2">NOT2</a>=<i>NOT2</i>, <a href="#_cmset_op_keyword_COUNT">COUNT</a>=<i>COUNT</i>, <a href="#_cmset_op_keyword_EMPTY1">EMPTY1</a>=<i>EMPTY1</i>, <a href="#_cmset_op_keyword_EMPTY2">EMPTY2</a>=<i>EMPTY2</i>, <a href="#_cmset_op_keyword_MAXARRAY">MAXARRAY</a>=<i>MAXARRAY</i>, <a href="#_cmset_op_keyword_INDEX">INDEX</a>=<i>INDEX</i>)</font></p>
121
122   
123
124
125    <h3>Return value</h3>
126 The resulting set as a one-dimensional array. The set may be
127 represented by either an array of data values (default), or an
128 array of indexes (if INDEX is set). Duplicate elements, if any,
129 are removed, and element order may not be preserved.
130
131 The empty set is represented as a return value of -1L, and COUNT
132 is set to zero. Note that the only way to recognize the empty set
133 is to examine COUNT.
134
135 SEE ALSO:
136
137  SET_UTILS.PRO by RSI
138
139
140   
141    <h3>Parameters</h3>
142   
143
144    <a name="#_cmset_op_keyword_a"></a>
145    <h4>a&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
146      <font size="-1" color="#006633">in</font>
147     
148     
149      <font size="-1" color="#006633">required</font>
150     
151     
152     
153     
154    </h4>
155
156   
157 The two sets to be operated on. A one dimensional array of
158 either numeric or string type. A and B must be of the same
159 type. Empty sets are permitted, and are either represented
160 as an undefined variable, or by setting EMPTY1 or EMPTY2.
161
162   
163
164    <a name="#_cmset_op_keyword_op0"></a>
165    <h4>op0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
166      <font size="-1" color="#006633">in</font>
167     
168     
169      <font size="-1" color="#006633">required</font>
170     
171      <font size="-1" color="#006633">type:</font> <font size="-1" color="#006633"><i>string</i></font>
172     
173     
174    </h4>
175
176   
177 a string, the operation to be performed. Must be one of
178 'AND', 'OR' or 'XOR' (lower or mixed case is permitted).
179 Other operations will cause an error message to be produced.
180
181   
182
183    <a name="#_cmset_op_keyword_b"></a>
184    <h4>b&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
185      <font size="-1" color="#006633">in</font>
186     
187     
188      <font size="-1" color="#006633">required</font>
189     
190     
191     
192     
193    </h4>
194
195   
196 See A
197
198   
199   
200
201   
202    <h3>Keywords</h3>
203
204   
205    <a name="#_cmset_op_keyword_NOT1"></a>
206    <h4>NOT1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
207     
208     
209     
210     
211     
212     
213     
214     
215    </h4>
216
217   
218 If set and OP is 'AND', then the complement of A (for
219 NOT1) or B (for NOT2) will be used in the operation.
220 NOT1 and NOT2 cannot be set simultaneously.
221
222   
223    <a name="#_cmset_op_keyword_NOT2"></a>
224    <h4>NOT2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
225     
226     
227     
228     
229     
230     
231     
232     
233    </h4>
234
235   
236 See NOT1
237
238   
239    <a name="#_cmset_op_keyword_COUNT"></a>
240    <h4>COUNT&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
241     
242     
243     
244     
245     
246     
247     
248     
249    </h4>
250
251   
252 upon return, the number of elements in the result set.
253 This is only important when the result set is the empty
254 set, in which case COUNT is set to zero.
255
256   
257    <a name="#_cmset_op_keyword_EMPTY1"></a>
258    <h4>EMPTY1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
259     
260     
261     
262     
263     
264     
265     
266     
267    </h4>
268
269   
270 If set, then A (for EMPTY1) or B (for EMPTY2) are
271 assumed to be the empty set. The actual values
272 passed as A or B are then ignored.
273
274   
275    <a name="#_cmset_op_keyword_EMPTY2"></a>
276    <h4>EMPTY2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
277     
278     
279     
280     
281     
282     
283     
284     
285    </h4>
286
287   
288 See EMPTY1
289
290   
291    <a name="#_cmset_op_keyword_MAXARRAY"></a>
292    <h4>MAXARRAY&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
293     
294     
295     
296     
297     
298     
299     
300     
301    </h4>
302
303   
304   
305    <a name="#_cmset_op_keyword_INDEX"></a>
306    <h4>INDEX&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
307     
308     
309     
310     
311     
312     
313     
314     
315    </h4>
316
317   
318 if set, then return a list of indexes instead of the array
319 values themselves. The "slower" set operations are always
320 performed in this case.
321
322 The indexes refer to the *combined* array [A,B]. To
323 clarify, in the following call: I = CMSET_OP(..., /INDEX);
324 returned values from 0 to NA-1 refer to A[I], and values
325 from NA to NA+NB-1 refer to B[I-NA].
326
327   
328   
329
330    <h3>Examples</h3><pre>
331 Utility function, similar to UNIQ, but allowing choice of taking
332 first or last unique element, or non-unique elements.
333 Unfortunately this doesn't work because of implementation dependent
334 versions of the SORT() function.
335
336 function cmset_op_uniq, a, first=first, non=non, count=ct, sort=sortit
337   if n_elements(a) LE 1 then return, 0L
338   sh = (2L*keyword_set(first)-1L)*(-2L*keyword_set(non)+1)
339
340   if keyword_set(sortit) then begin
341       ;; Sort it manually
342       ii = sort(a) & b = a[ii]
343       if keyword_set(non) then wh = where(b EQ shift(b, sh), ct) $
344       else                     wh = where(b NE shift(b, sh), ct)
345       if ct GT 0 then return, ii[wh]
346   endif else begin
347       ;; Use the user's values directly
348       if keyword_set(non) then wh = where(a EQ shift(a, sh), ct) $
349       else                     wh = where(a NE shift(a, sh), ct)
350       if ct GT 0 then return, wh
351   endelse
352
353   if keyword_set(first) then return, 0L else return, n_elements(a)-1
354 end
355
356 Simplified version of CMSET_OP_UNIQ which sorts, and takes the
357 "first" value, whatever that may mean.
358
359    </pre><h3>Version history</h3>
360   
361    <h4>Version</h4>
362 $Id: cmset_op.pro 325 2007-12-06 10:04:53Z pinsard $
363
364    <h4>History</h4>
365 Written, CM, 23 Feb 2000
366   Added empty set capability, CM, 25 Feb 2000
367   Documentation clarification, CM 02 Mar 2000
368   Incompatible but more consistent reworking of EMPTY keywords, CM,
369     04 Mar 2000
370   Minor documentation clarifications, CM, 26 Mar 2000
371   Corrected bug in empty_arg special case, CM 06 Apr 2000
372   Add INDEX keyword, CM 31 Jul 2000
373   Clarify INDEX keyword documentation, CM 06 Sep 2000
374   Made INDEX keyword always force SLOW_SET_OP, CM 06 Sep 2000
375   Added CMSET_OP_UNIQ, and ability to select FIRST_UNIQUE or
376     LAST_UNIQUE values, CM, 18 Sep 2000
377   Removed FIRST_UNIQUE and LAST_UNIQUE, and streamlined
378     CMSET_OP_UNIQ until problems with SORT can be understood, CM, 20
379     Sep 2000 (thanks to Ben Tupper)
380   Still trying to get documentation of INDEX and NOT right, CM, 28
381     Sep 2000 (no code changes)
382   Correct bug for AND case, when input sets A and B each only have
383     one unique value, and the values are equal.  CM, 04 Mar 2004
384     (thanks to James B. jbattat at cfa dot harvard dot edu)
385   Add support for the cases where the input data types are mixed,
386      but still compatible; also, attempt to return the same data
387      type that was passed in; CM, 05 Feb 2005
388   Fix bug in type checking (thanks to "marit"), CM, 10 Dec 2005
389   Work around a stupidity in the built-in IDL HISTOGRAM routine,
390      which tries to "help" you by restricting the MIN/MAX to the
391      range of the input variable (thanks to Will Maddox), CM, 16 Jan 2006
392
393   Author: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
394   craigm@lheamail.gsfc.nasa.gov
395
396   
397
398   
399   
400   
401   
402   
403
404   
405   
406   
407   
408   
409   
410   
411
412    <font size="-3"><p>&nbsp;</p></font>
413    <hr size="1" color="#CCCCCC"/>
414     
415
416   
417
418    <p><font color="gray" size="-3">&nbsp;&nbsp;Produced by IDLdoc 2.0.</font></p>
419
420  </body>
421</html>
Note: See TracBrowser for help on using the repository browser.