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>