* Bug 15841 fixed: intersect() now accepts sparse
[scilab.git] / scilab / modules / elementary_functions / help / en_US / setoperations / intersect.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2018 - 2020 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17         xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
18         xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19         xmlns:scilab="http://www.scilab.org" xml:id="intersect" xml:lang="en">
20     <refnamediv>
21         <refname>intersect</refname>
22         <refpurpose>
23             elements or rows or columns met in both input arrays, without duplicates
24         </refpurpose>
25     </refnamediv>
26     <refsynopsisdiv>
27         <title>Syntax</title>
28         <synopsis>
29             M = intersect(a, b)
30             M = intersect(a, b, orient)
31             [M, ka] = intersect(..)
32             [M, ka, kb] = intersect(..)
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
36         <title>Arguments</title>
37         <variablelist>
38             <varlistentry>
39                 <term>a, b</term>
40                 <listitem>
41                     vectors, matrices or hypermatrices of booleans, encoded integers, real or
42                     complex numbers, or text. <varname>a</varname> and <varname>b</varname> must
43                     have the same datatype.
44                     For text inputs, UTF characters are accepted.
45                     Sparse numeric or boolean matrices are accepted : Either <varname>a</varname> or
46                     <varname>b</varname> or both <varname>a</varname> and <varname>b</varname> may
47                     be sparse.
48                     <para/>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>orient</term>
53                 <listitem>
54                     flag with possible values : 1 or "r", 2 or "c". Can't be used if
55                     <varname>a</varname> or/and <varname>b</varname> is an hypermatrix.
56                     <para/>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>M</term>
61                 <listitem>
62                     <para>
63                         matrix of the same datatype as <varname>a</varname> and <varname>b</varname>.
64                         <itemizedlist>
65                             <listitem>
66                                 Without <varname>orient</varname>: <varname>M</varname> is a row vector.
67                             </listitem>
68                             <listitem>
69                                 With <literal>orient="r"|1</literal>: <varname>M</varname> is a
70                                 matrix stacking the common rows of <varname>a</varname> and
71                                 <varname>b</varname>.
72                             </listitem>
73                             <listitem>
74                                 With <literal>orient="c"|2</literal>: <varname>M</varname> is a
75                                 matrix stacking the common columns of <varname>a</varname> and
76                                 <varname>b</varname>.
77                             </listitem>
78                         </itemizedlist>
79                     </para>
80                     <para>
81                         <varname>M</varname> is sparse as soon as either <varname>a</varname> or
82                         <varname>b</varname> is sparse and none is empty.
83                     </para>
84                 </listitem>
85             </varlistentry>
86             <varlistentry>
87                 <term>ka</term>
88                 <listitem>
89                     Dense row vector of indices in <varname>a</varname>.
90                     <para/>
91                 </listitem>
92             </varlistentry>
93             <varlistentry>
94                 <term>kb</term>
95                 <listitem>
96                     Dense row vector of indices in <varname>b</varname>.
97                     <para/>
98                 </listitem>
99             </varlistentry>
100         </variablelist>
101     </refsection>
102     <refsection>
103         <title>Description</title>
104         <para>
105             <literal>intersect(a,b)</literal> returns a row vector of unique values
106             present in both <literal>a</literal> and <literal>b</literal> arrays. Values are
107             sorted in increasing order
108             <itemizedlist>
109                 <listitem>
110                     for complex numbers : par increasing magnitudes, then by increasing phases
111                 </listitem>
112                 <listitem>
113                     for text : in alphabetical order.
114                 </listitem>
115             </itemizedlist>
116         </para>
117         <warning>
118             Two NaN elements are always considered as different. So NaN or rows or columns having
119             NaN will never be in the result <literal>M</literal>.
120         </warning>
121         <para>
122             <literal>[M, ka, kb] = intersect(a,b)</literal> additionally returns the vectors
123             <literal>ka</literal> and <literal>kb</literal> of indices in <literal>a</literal>
124             and <literal>b</literal> of selected components firstly met, such that
125             <literal>M=a(ka)</literal> and <literal>M=b(kb)</literal>.
126         </para>
127         <refsect3>
128             <title>Common rows or columns</title>
129         <para>
130             When the <varname>orient</varname> argument is provided, the comparison is performed
131             between the rows of <literal>a</literal> and <literal>b</literal> -- each one being
132             considered as a whole --, or between their columns.
133         </para>
134         <para>
135             <literal>intersect(a,b,"r")</literal> or <literal>intersect(a,b,1)</literal> will return
136             the matrix of stacked unduplicated rows met in both  <literal>a</literal> and
137             <literal>b</literal>, sorted in lexicographic ascending order.
138             If <literal>a</literal> and <literal>b</literal> don't have the same number of columns,
139             [] is returned without comparing the values.
140         </para>
141         <para>
142             <literal>[M,ka,kb] = intersect(a,b,"r")</literal> additionally returns the vectors
143             <literal>ka</literal> and <literal>kb</literal> of the minimal indices of common rows,
144             respectively in <literal>a</literal> and <literal>b</literal>,
145             such that <literal>M=a(ka,:)</literal> and <literal>M=b(kb,:)</literal>.
146         </para>
147         <para>
148             <literal>intersect(a,b,"c")</literal> or <literal>intersect(a,b,2)</literal> does
149             the same for columns.
150         </para>
151         </refsect3>
152     </refsection>
153     <refsection>
154         <title>Examples</title>
155         <programlisting role="example"><![CDATA[
156 A = grand(3, 3, "uin", 0, 9)
157 B = grand(2, 4, "uin", 0, 9)
158 intersect(A, B)
159 [N, ka, kb] = intersect(A,B);
160 ka, kb
161  ]]></programlisting>
162     <screen><![CDATA[
163 --> A = grand(3, 3, "uin", 0, 9)
164  A  =
165    0.   6.   4.
166    6.   6.   6.
167    2.   7.   9.
168
169 --> B = grand(2, 4, "uin", 0, 9)
170  B  =
171    1.   8.   0.   2.
172    6.   2.   2.   1.
173
174 --> intersect(A, B)
175  ans  =
176    0.   2.   6.
177
178 --> [N, ka, kb] = intersect(A,B);
179 --> ka, kb
180  ka  =
181    1.   3.   2.
182  kb  =
183    5.   4.   2.
184 ]]></screen>
185     <para>
186         In the above example, note that 6 is met four times in A, at indices [2 4 5 8].
187         Only the minimal index 2 is returned in ka. Same situation for 2 in B.
188     </para>
189     <para/>
190     <para>
191     NaN values can never be in the result:
192     </para>
193     <programlisting role="example"><![CDATA[
194 %nan == %nan
195 intersect([1 -2 %nan 3 6], [%nan 1:3])
196  ]]></programlisting>
197     <screen><![CDATA[
198 --> %nan == %nan
199  ans  =
200   F
201
202 --> intersect([1 -2 %nan 3 6], [%nan 1:3])
203  ans  =
204    1.   3.
205 ]]></screen>
206     <para/>
207     <para>
208         intersect() can also process some characters or some texts. Since Scilab is great with UTF
209         characters, here is an example with some Arabic contents, getting characters present in
210         both sentences:
211     </para>
212         <programlisting role="example"><![CDATA[
213 A = strsplit("هو برنامج علمي كبير ""Scilab""")'
214 B = strsplit("فهو حر ومفتوح")'
215 intersect(A,B)
216  ]]></programlisting>
217     <screen><![CDATA[
218 --> A = strsplit("هو برنامج علمي كبير ""Scilab""")'
219  A  =
220 !ه  و     ب  ر  ن  ا  م  ج     ع  ل  م  ي     ك  ب  ي  ر     "  S  c  i  l  a  b  "  !
221
222 --> B = strsplit("فهو حر ومفتوح")'
223  B  =
224 !ف  ه  و     ح  ر     و  م  ف  ت  و  ح  !
225
226 --> intersect(A,B)
227  ans  =
228 !   ر  م  ه  و  !
229 ]]></screen>
230     <para/>
231     <para>
232         Column-wise or Row-wise processing of two matrices: Here we process 2 matrices of
233         signed 1-byte integers, and get the common columns:
234     </para>
235     <programlisting role="example"><![CDATA[
236 A = int8(grand(3,5,"uin",0,1))
237 B = int8(grand(3,9,"uin",0,1))
238 [M,ka,kb] = intersect(A, B, "c");
239 M, ka, kb
240  ]]></programlisting>
241     <screen><![CDATA[
242 --> A = int8(grand(3,5,"uin",0,1))
243  A  =
244   0  0  1  1  1
245   0  0  1  1  0
246   0  0  0  0  1
247
248 --> B = int8(grand(3,9,"uin",0,1))
249  B  =
250   1  0  1  1  1  0  1  1  1
251   1  0  0  1  1  1  0  0  0
252   1  0  1  0  1  1  1  0  0
253
254 --> [M,ka,kb] = intersect(A, B, "c");
255 --> M, ka, kb
256  M  =
257   0  1  1
258   0  0  1
259   0  1  0
260
261  ka  =
262    1.   5.   3.
263
264  kb  =
265    2.   3.   4.
266 ]]></screen>
267     <para/>
268     <para>
269         <literal>intersect()</literal> for booleans is mainly useful with the "r" or "c" option.
270         Here is an example with a sparse boolean matrix:
271     </para>
272     <programlisting role="example"><![CDATA[
273 [F, T] = (%f, %t);
274 A = [F F T F T F ; T F F T T T ; T T F T F F]
275 B = [F T F T F F ; T F F F T F ; F T F F T F]
276 [M,ka,kb] = intersect(A, sparse(B), "c");
277 issparse(M), full(M), ka, kb
278  ]]></programlisting>
279     <screen><![CDATA[
280 --> A = [F F T F T F ; T F F T T T ; T T F T F F]
281  A  =
282   F F T F T F
283   T F F T T T
284   T T F T F F
285
286 --> B = [F T F T F F ; T F F F T F ; F T F F T F]
287  B  =
288   F T F T F F
289   T F F F T F
290   F T F F T F
291
292 --> [M,ka,kb] = intersect(A, sparse(B), "c");
293 --> issparse(M), full(M), ka, kb
294  ans  =
295   T
296
297  ans  =
298   F F T
299   T T F
300   F T F
301
302  ka  =
303    6.   1.   3.
304
305  kb  =
306    1.   5.   4.
307 ]]></screen>
308     </refsection>
309     <refsection role="see also">
310         <title>See also</title>
311         <simplelist type="inline">
312             <member>
313                 <link linkend="members">members</link>
314             </member>
315             <member>
316                 <link linkend="unique">unique</link>
317             </member>
318             <member>
319                 <link linkend="gsort">gsort</link>
320             </member>
321             <member>
322                 <link linkend="union">union</link>
323             </member>
324         </simplelist>
325     </refsection>
326     <refsection role="history">
327         <title>History</title>
328         <revhistory>
329             <revision>
330                 <revnumber>6.1.0</revnumber>
331                 <revdescription>
332                     Complex numbers are now accepted.
333                 </revdescription>
334             </revision>
335             <revision>
336                 <revnumber>6.1.1</revnumber>
337                 <revdescription>
338                     Sparse matrices are now accepted (numbers or booleans).
339                 </revdescription>
340             </revision>
341         </revhistory>
342     </refsection>
343 </refentry>