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