* Bugs 16337 16455 fixed: [..,..,ku] = unique(..) implemented
[scilab.git] / scilab / modules / elementary_functions / help / en_US / setoperations / unique.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) 2017 - 2019 - 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="unique" xml:lang="en">
20     <refnamediv>
21         <refname>unique</refname>
22         <refpurpose>extracts (and sorts) distinct elements, rows or columns of a matrix</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             [U, km, ku, nb] = unique(M)
28             [U, km, ku, nb] = unique(M, orient)
29             [U, km, ku, nb] = unique(.., "keepOrder")
30             [U, km, ku, nb] = unique(.., "uniqueNan")
31         </synopsis>
32     </refsynopsisdiv>
33     <refsection role="parameters">
34         <title>Arguments</title>
35         <variablelist>
36             <varlistentry>
37                 <term>M</term>
38                 <listitem>
39                     vector, matrix, or hypermatrix of booleans, numbers, or text.
40                     <para/>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>orient</term>
45                 <listitem>
46                     flag with possible values : 1 or "r", 2 or "c". It can't be used if
47                     <varname>M</varname> is an hypermatrix.
48                     <para/>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>U</term>
53                 <listitem>
54                   <itemizedlist>
55                     <listitem>
56                         If <varname>orient</varname> is not used: Vector of extracted
57                         <varname>M</varname> components sorted in ascending order.
58                         If <varname>M</varname> is a row vector, <varname>U</varname> is
59                         also a row vector. In all other <varname>M</varname> cases,
60                         <varname>U</varname> is a column vector.
61                         <para/>
62                     </listitem>
63                     <listitem>
64                       If <varname>orient</varname> is used: Matrix of extracted
65                       <varname>M</varname> rows or columns, sorted in lexicographic ascending order.
66                     </listitem>
67                   </itemizedlist>
68                   <para/>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>km</term>
73                 <listitem>
74                     Vector of indices of first encountered occurrences, such that
75                     <literal>U = M(km)</literal> or <literal>U = M(km,:)</literal>
76                     or <literal>U = M(:,km)</literal>.
77                     <para/>
78                     <varname>km</varname> is a row if <varname>M</varname> is a row or if
79                     <literal>orient="c"</literal> is used. Otherwise it's a column.
80                     <para/>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>ku</term>
85                 <listitem>
86                     Array of indices in U, such that, according to the <varname>orient</varname> option
87                     <itemizedlist>
88                         <listitem>
89                             "*": <varname>ku</varname> is of size size(M), and <literal>U(ku) = M</literal>
90                         </listitem>
91                         <listitem>
92                             "r": <varname>ku</varname> is of size [size(M,1), 1], and <literal>U(ku,:) = M</literal>
93                         </listitem>
94                         <listitem>
95                             "c": <varname>ku</varname> is of size [1, size(M,2)], and <literal>U(:,ku) = M</literal>
96                         </listitem>
97                     </itemizedlist>
98                     <para/>
99                 </listitem>
100             </varlistentry>
101             <varlistentry>
102                 <term>nb</term>
103                 <listitem>
104                     Vector of integers > 0, with the same <varname>km</varname> shape:
105                     Numbers of occurrences in <varname>M</varname> of respective unduplicated
106                     entities (components, rows, columns) returned in <varname>U</varname>.
107                     <para/>
108                 </listitem>
109             </varlistentry>
110         </variablelist>
111     </refsection>
112     <refsection role="description">
113         <title>Description</title>
114         <para>
115             <literal>unique(M)</literal> returns a vector which retains the
116             unique entries of <literal>M</literal> in ascending order.
117         </para>
118         <para>
119             <literal>unique(M,"r")</literal> or  <literal>unique(M,1)</literal> removes all
120             duplicates of <varname>M</varname> rows and returns unique rows  in lexicographic
121             ascending order.
122         </para>
123         <para>
124             <literal>unique(M,"c")</literal> or  <literal>unique(M,2)</literal> removes all
125             duplicates of <varname>M</varname> columns and returns unique columns in lexicographic
126             ascending order.
127         </para>
128         <para>
129             <literal>unique(M,.. "keepOrder")</literal> returns <varname>M</varname> unduplicated
130             entries in their original order in <varname>M</varname>.
131             <literal>"keepOrder"</literal> is case-insensitive.
132         </para>
133         <para>
134             <literal>unique(M,.. "uniqueNan")</literal> considers all Nan values as the same one,
135             and unduplicates them. By default, any Nan is different
136             from any other Nan, including itself: <literal>%nan&lt;>%nan</literal> is true, unless
137             <literal>"uniqueNan"</literal> is used. Specifying
138             <literal>"uniqueNan"</literal> is case-insensitive.
139         </para>
140         <para>
141             For booleans, <literal>unique(…)</literal> is useful mainly with the "r" or "c" options.
142         </para>
143         <para>
144             <note>
145                 Complex numbers are sorted first by increasing magnitudes, then by increasing
146                 phases on [-π,π].
147             </note>
148         </para>
149     </refsection>
150     <refsection role="examples">
151         <title>Examples</title>
152         <para>With some numbers:</para>
153         <programlisting role="example"><![CDATA[
154 M = int8([2  0  2  2  1  1  1  2  1  1  0  1  1  0  1  1
155           0  1  2  0  1  2  2  0  1  1  2  0  1  0  0  0
156           ])
157 [u, km] = unique(M)
158 [uc, kmc] = unique(M, "c")
159  ]]></programlisting>
160     <screen><![CDATA[
161 --> M
162  M =
163   2  0  2  2  1  1  1  2  1  1  0  1  1  0  1  1
164   0  1  2  0  1  2  2  0  1  1  2  0  1  0  0  0
165
166 --> [u, km] = unique(M)
167  u  =
168   0
169   1
170   2
171
172  km  =
173    2.
174    4.
175    1.
176
177 --> [uc, kmc] = unique(M, "c")
178  uc  =
179   0  0  0  1  1  1  2  2
180   0  1  2  0  1  2  0  2
181
182  kmc  =
183    14.   2.   11.   12.   5.   6.   1.   3.
184 ]]></screen>
185         <para/>
186         <para>With complex numbers:</para>
187         <programlisting role="example"><![CDATA[
188 i = %i;
189 c = [1+i, 1-i, -i, i, -i, 1+i]
190 [u, k] = unique(c)
191 [uc, kc] = unique(c, "c")
192  ]]></programlisting>
193     <screen><![CDATA[
194 --> c = [1+i, 1-i, -i, i, -i, 1+i]
195  c  =
196    1. + i    1. - i    0. - i    0. + i    0. - i    1. + i
197
198 --> [u, k] = unique(c)
199  u  =
200    0. - i    0. + i    1. - i    1. + i
201  k  =
202    3.   4.   2.   1.
203
204 --> [uc, kc] = unique(c, "c")
205  uc  =
206    0. - i    0. + i    1. - i    1. + i
207  kc  =
208    3.   4.   2.   1.
209 ]]></screen>
210         <para/>
211         <para>With some texts:</para>
212         <programlisting role="example"><![CDATA[
213 t = ["BA" "BB" "AB" "BA" "AB" "BA" "AB" "AB" "BA" "AA" "AB" "BA" "BA" "BA" "AA"
214      "AA" "AB" "AA" "AA" "BB" "BB" "BB" "BA" "AB" "AB" "BB" "BB" "AB" "AB" "AA"
215     ]
216 u = unique(t)'
217 [u, kt, ku, nb] = unique(t(1,:))
218 [u, kt] = unique(t(1,:), "keepOrder")  // In original order of row#1 elements
219 [uc, ktc, kuc, nb] = unique(t, "c")
220 [uc, ktc, kuc, nb] = unique(t, "c", "keepOrder")  // In original order of columns
221 [and(t(:,ktc)==uc), and(uc(:,kuc)==t) ]
222  ]]></programlisting>
223     <screen><![CDATA[
224 --> t = ["BA" "BB" "AB" "BA" "AB" "BA" "AB" "AB" "BA" "AA" "AB" "BA" "BA" "BA" "AA"
225   >      "AA" "AB" "AA" "AA" "BB" "BB" "BB" "BA" "AB" "AB" "BB" "BB" "AB" "AB" "AA"
226   >     ]
227  t  =
228 !BA  BB  AB  BA  AB  BA  AB  AB  BA  AA  AB  BA  BA  BA  AA  !
229 !AA  AB  AA  AA  BB  BB  BB  BA  AB  AB  BB  BB  AB  AB  AA  !
230
231 --> u = unique(t)'
232  u  =
233 !AA  AB  BA  BB  !
234
235 --> [u, kt, ku, nb] = unique(t(1,:)); u, kt, nb
236  u  =
237 !AA  AB  BA  BB  !
238
239  kt  =
240    10.   3.   1.   2.
241
242  nb  =
243    2.   5.   7.   1.
244
245 --> [u, kt] = unique(t(1,:), "keepOrder")  // Keeping the original order
246  u  =
247 !BA  BB  AB  AA  !
248
249  kt  =
250    1.   2.   3.   10.
251
252 --> [uc, ktc, kuc, nb] = unique(t, "c")
253  uc  =
254 !AA  AA  AB  AB  AB  BA  BA  BA  BB  !             Sorted columns
255 !AA  AB  AA  BA  BB  AA  AB  BB  AB  !
256
257  ktc  =
258    15.   10.   3.   8.   5.   1.   9.   6.   2.
259
260  nb  =
261    1.   1.   1.   1.   3.   2.   3.   2.   1.
262
263 --> [uc, ktc, kuc, nb] = unique(t, "c", "keepOrder")  // Keeping the original order
264  uc  =
265 !BA  BB  AB  AB  BA  AB  BA  AA  AA  !
266 !AA  AB  AA  BB  BB  BA  AB  AB  AA  !
267
268  ktc  =
269    1.   2.   3.   5.   6.   8.   9.   10.   15.
270
271  nb  =
272    2.   1.   1.   3.   2.   1.   3.   1.   1.
273
274 --> [and(t(:,ktc)==uc), and(uc(:,kuc)==t) ]
275  ans  =
276   T  T
277 ]]></screen>
278         <para/>
279         <para>With Nan (and Inf) values. "uniqueNan" option:</para>
280         <programlisting role="example"><![CDATA[
281 M = [2  2  %nan  1     2  0     1  %nan  0    %nan
282      1  0  1     %nan  0  %inf  0  1     %inf 1
283     ];
284 [v, km, kv, n] = unique(M); v',n'
285 [v, km, kv, n] = unique(M, "uniqueNan"); v',n'
286 unique(M, "c")
287 [v, kmc, kvc, n] = unique(M, "c", "uniqueNan")
288  ]]></programlisting>
289     <screen><![CDATA[
290 --> M
291  M  =
292    2.   2.   Nan   1.    2.   0.    1.   Nan   0.    Nan
293    1.   0.   1.    Nan   0.   Inf   0.   1.    Inf   1.
294
295 --> [v, km, kv, n] = unique(M); v',n'
296  ans  =
297    0.   1.   2.   Inf   Nan   Nan   Nan   Nan
298
299  ans  =
300    5.   6.   3.   2.   1.   1.   1.   1.
301
302 --> [v, km, kv, n] = unique(M, "uniqueNan"); v',n'
303  ans  =
304    0.   1.   2.   Inf   Nan
305
306  ans  =
307    5.   6.   3.   2.   4.
308
309 --> unique(M, "c")
310  ans  =
311    0.    1.   1.    2.   2.   Nan   Nan   Nan
312    Inf   0.   Nan   0.   1.   1.    1.    1.
313
314 --> [v, kmc, kvc, n] = unique(M, "c", "uniqueNan")
315  v  =
316    0.    1.   1.    2.   2.   Nan
317    Inf   0.   Nan   0.   1.   1.
318
319  kmc  =
320    6.   7.   4.   2.   1.   3.
321
322  n  =
323    2.   1.   1.   2.   1.   3.
324 ]]></screen>
325     </refsection>
326     <refsection role="see also">
327         <title>See also</title>
328         <simplelist type="inline">
329             <member>
330                 <link linkend="members">members</link>
331             </member>
332             <member>
333                 <link linkend="gsort">gsort</link>
334             </member>
335             <member>
336                 <link linkend="vectorfind">vectorfind</link>
337             </member>
338             <member>
339                 <link linkend="grep">grep</link>
340             </member>
341             <member>
342                 <link linkend="union">union</link>
343             </member>
344             <member>
345                 <link linkend="intersect">intersect</link>
346             </member>
347         </simplelist>
348     </refsection>
349     <refsection role="history">
350         <title>History</title>
351         <revhistory>
352             <revision>
353                 <revnumber>6.0.2</revnumber>
354                 <revdescription>
355                     unique() can now be used to unduplicate complex numbers.
356                 </revdescription>
357             </revision>
358             <revision>
359                 <revnumber>6.1.0</revnumber>
360                 <revdescription>
361                     <itemizedlist>
362                         <listitem>
363                             Extension to booleans.
364                         </listitem>
365                         <listitem>
366                             "keepOrder" and "uniqueNan" options introduced.
367                         </listitem>
368                         <listitem>
369                             Fourth output argument <literal>nb</literal> introduced.
370                         </listitem>
371                     </itemizedlist>
372                 </revdescription>
373             </revision>
374             <revision>
375                 <revnumber>6.1.1</revnumber>
376                 <revdescription>
377                     ku 3rd output implemented.
378                 </revdescription>
379             </revision>
380         </revhistory>
381     </refsection>
382 </refentry>