22c16b795c3a57d82924f32a762e90f3127d35f4
[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             [N, km, kn, nb] = unique(M)
28             [N, km, kn, nb] = unique(M, orient)
29             [N, km, kn, nb] = unique(.., "keepOrder")
30             [N, km, kn, 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 numbers or of strings.
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>N</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>N</varname> is
59                         also a row vector. In all other <varname>M</varname> cases,
60                         <varname>N</varname> is a matrix or 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>N(i) = M(km(i))</literal> or <literal>N(i,:) = M(km(i),:)</literal>
76                     or <literal>N(:,i) = M(:,km(i))</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>kn</term>
85                 <listitem>
86                     Not yet implemented.
87                     Vector of indices of first encountered occurrences, such that
88                     <literal>M(i) = N(kn(i))</literal> or <literal>M(i,:) = N(kn(i),:)</literal>
89                     or <literal>M(:,i) = N(:,kn(i))</literal>.
90                     <para/>
91                 </listitem>
92             </varlistentry>
93             <varlistentry>
94                 <term>nb</term>
95                 <listitem>
96                     Vector of integers > 0, with the same <varname>km</varname> shape:
97                     Numbers of occurrences in <varname>M</varname> of respective unduplicated
98                     entities (components, rows, columns) returned in <varname>N</varname>.
99                     <para/>
100                 </listitem>
101             </varlistentry>
102         </variablelist>
103     </refsection>
104     <refsection role="description">
105         <title>Description</title>
106         <para>
107             <literal>unique(M)</literal> returns a vector which retains the
108             unique entries of <literal>M</literal> in ascending order.
109         </para>
110         <para>
111             <literal>unique(M,"r")</literal> or  <literal>unique(M,1)</literal> removes all
112             duplicates of <varname>M</varname> rows and returns unique rows  in lexicographic
113             ascending order.
114         </para>
115         <para>
116             <literal>unique(M,"c")</literal> or  <literal>unique(M,2)</literal> removes all
117             duplicates of <varname>M</varname> columns and returns unique columns in lexicographic
118             ascending order.
119         </para>
120         <para>
121             <literal>unique(M,.. "keepOrder")</literal> returns <varname>M</varname> unduplicated
122             entries in their original order in <varname>M</varname>.
123             <literal>"keepOrder"</literal> is case-insensitive.
124         </para>
125         <para>
126             <literal>unique(M,.. "uniqueNan")</literal> considers all Nan values as the same one,
127             and unduplicates them. By default, any Nan is different
128             from any other Nan, including itself: <literal>%nan&lt;>%nan</literal> is true, unless
129             <literal>"uniqueNan"</literal> is used. Specifying
130             <literal>"uniqueNan"</literal> is case-insensitive.
131         </para>
132     </refsection>
133     <refsection role="examples">
134         <title>Examples</title>
135         <para>With some numbers:</para>
136         <programlisting role="example"><![CDATA[
137 M = int8([2  0  2  2  1  1  1  2  1  1  0  1  1  0  1  1
138           0  1  2  0  1  2  2  0  1  1  2  0  1  0  0  0
139           ])
140 [u, km] = unique(M)
141 [uc, kmc] = unique(M, "c")
142  ]]></programlisting>
143     <screen><![CDATA[
144 --> M
145  M =
146   2  0  2  2  1  1  1  2  1  1  0  1  1  0  1  1
147   0  1  2  0  1  2  2  0  1  1  2  0  1  0  0  0
148
149 --> [u, km] = unique(M)
150  u  =
151   0
152   1
153   2
154
155  km  =
156    2.
157    4.
158    1.
159
160 --> [uc, kmc] = unique(M, "c")
161  uc  =
162   0  0  0  1  1  1  2  2
163   0  1  2  0  1  2  0  2
164
165  kmc  =
166    14.   2.   11.   12.   5.   6.   1.   3.
167 ]]></screen>
168         <para/>
169         <para>With complex numbers:</para>
170         <programlisting role="example"><![CDATA[
171 i = %i;
172 c = [1+i, 1-i, -i, i, -i, 1+i]
173 [u, k] = unique(c)
174 [uc, kc] = unique(c, "c")
175  ]]></programlisting>
176     <screen><![CDATA[
177 --> c = [1+i, 1-i, -i, i, -i, 1+i]
178  c  =
179    1. + i     1. - i  -i    i   -i    1. + i
180
181 --> [u, k] = unique(c)
182  u  =
183   -i    i    1. - i   1. + i
184
185  k  =
186    3.   4.   2.   1.
187 ]]></screen>
188         <para/>
189         <para>With some texts:</para>
190         <programlisting role="example"><![CDATA[
191 t = ["BA" "BB" "AB" "BA" "AB" "BA" "AB" "AB" "BA" "AA" "AB" "BA" "BA" "BA" "AA"
192      "AA" "AB" "AA" "AA" "BB" "BB" "BB" "BA" "AB" "AB" "BB" "BB" "AB" "AB" "AA"
193     ]
194 u = unique(t)'
195 [u, kt, ku, nb] = unique(t(1,:))
196 [u, kt] = unique(t(1,:), "keepOrder")  // Keeping the original order of row#1 elements
197 [uc, ktc, kuc, nb] = unique(t, "c")
198 [uc, ktc, kuc, nb] = unique(t, "c", "keepOrder")  // Keeping the original order of columns
199  ]]></programlisting>
200     <screen><![CDATA[
201 --> t = ["BA" "BB" "AB" "BA" "AB" "BA" "AB" "AB" "BA" "AA" "AB" "BA" "BA" "BA" "AA"
202   >      "AA" "AB" "AA" "AA" "BB" "BB" "BB" "BA" "AB" "AB" "BB" "BB" "AB" "AB" "AA"
203   >     ]
204  t  =
205 !BA  BB  AB  BA  AB  BA  AB  AB  BA  AA  AB  BA  BA  BA  AA  !
206 !AA  AB  AA  AA  BB  BB  BB  BA  AB  AB  BB  BB  AB  AB  AA  !
207
208 --> u = unique(t)'
209  u  =
210 !AA  AB  BA  BB  !
211
212 --> [u, kt, ku, nb] = unique(t(1,:)); u, kt, nb
213  u  =
214 !AA  AB  BA  BB  !
215
216  kt  =
217    10.   3.   1.   2.
218
219  nb  =
220    2.   5.   7.   1.
221
222 --> [u, kt] = unique(t(1,:), "keepOrder")  // Keeping the original order
223  u  =
224 !BA  BB  AB  AA  !
225
226  kt  =
227    1.   2.   3.   10.
228
229 --> [uc, ktc, kuc, nb] = unique(t, "c")
230  uc  =
231 !AA  AA  AB  AB  AB  BA  BA  BA  BB  !             Sorted columns
232 !AA  AB  AA  BA  BB  AA  AB  BB  AB  !
233
234  ktc  =
235    15.   10.   3.   8.   5.   1.   9.   6.   2.
236
237  nb  =
238    1.   1.   1.   1.   3.   2.   3.   2.   1.
239
240 --> [uc, ktc, kuc, nb] = unique(t, "c", "keepOrder")  // Keeping the original order
241  uc  =
242 !BA  BB  AB  AB  BA  AB  BA  AA  AA  !
243 !AA  AB  AA  BB  BB  BA  AB  AB  AA  !
244
245  ktc  =
246    1.   2.   3.   5.   6.   8.   9.   10.   15.
247
248  nb  =
249    2.   1.   1.   3.   2.   1.   3.   1.   1.
250 ]]></screen>
251         <para/>
252         <para>With Nan (and Inf) values. "uniqueNan" option:</para>
253         <programlisting role="example"><![CDATA[
254 M = [2  2  %nan  1     2  0     1  %nan  0    %nan
255      1  0  1     %nan  0  %inf  0  1     %inf 1
256     ];
257 [v, km, kv, n] = unique(M); v',n'
258 [v, km, kv, n] = unique(M, "uniqueNan"); v',n'
259 unique(M, "c")
260 [v, kmc, kvc, n] = unique(M, "c", "uniqueNan")
261  ]]></programlisting>
262     <screen><![CDATA[
263 --> M
264  M  =
265    2.   2.   Nan   1.    2.   0.    1.   Nan   0.    Nan
266    1.   0.   1.    Nan   0.   Inf   0.   1.    Inf   1.
267
268 --> [v, km, kv, n] = unique(M); v',n'
269  ans  =
270    0.   1.   2.   Inf   Nan   Nan   Nan   Nan
271
272  ans  =
273    5.   6.   3.   2.   1.   1.   1.   1.
274
275 --> [v, km, kv, n] = unique(M, "uniqueNan"); v',n'
276  ans  =
277    0.   1.   2.   Inf   Nan
278
279  ans  =
280    5.   6.   3.   2.   4.
281
282 --> unique(M, "c")
283  ans  =
284    0.    1.   1.    2.   2.   Nan   Nan   Nan
285    Inf   0.   Nan   0.   1.   1.    1.    1.
286
287 --> [v, kmc, kvc, n] = unique(M, "c", "uniqueNan")
288  v  =
289    0.    1.   1.    2.   2.   Nan
290    Inf   0.   Nan   0.   1.   1.
291
292  kmc  =
293    6.   7.   4.   2.   1.   3.
294
295  n  =
296    2.   1.   1.   2.   1.   3.
297 ]]></screen>
298     </refsection>
299     <refsection role="see also">
300         <title>See also</title>
301         <simplelist type="inline">
302             <member>
303                 <link linkend="members">members</link>
304             </member>
305             <member>
306                 <link linkend="gsort">gsort</link>
307             </member>
308             <member>
309                 <link linkend="vectorfind">vectorfind</link>
310             </member>
311             <member>
312                 <link linkend="grep">grep</link>
313             </member>
314             <member>
315                 <link linkend="union">union</link>
316             </member>
317             <member>
318                 <link linkend="intersect">intersect</link>
319             </member>
320         </simplelist>
321     </refsection>
322     <refsection role="history">
323         <title>History</title>
324         <revhistory>
325             <revision>
326                 <revnumber>6.0.2</revnumber>
327                 <revdescription>
328                     unique() can now be used to unduplicate complex numbers.
329                 </revdescription>
330             </revision>
331             <revision>
332                 <revnumber>6.1.0</revnumber>
333                 <revdescription>
334                     <itemizedlist>
335                         <listitem>
336                             "keepOrder" and "uniqueNan" options introduced.
337                         </listitem>
338                         <listitem>
339                             Fourth output argument <literal>nb</literal> introduced.
340                         </listitem>
341                     </itemizedlist>
342                 </revdescription>
343             </revision>
344         </revhistory>
345     </refsection>
346 </refentry>