6dea44df985d2387e76a49ba6cbb45625b3d8f04
[scilab.git] / scilab / modules / elementary_functions / help / en_US / matrixoperations / max.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 - 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="max" xml:lang="en">
20     <refnamediv>
21         <refname>max</refname>
22         <refpurpose>maximum</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             m = max(A)
28             Col = max(A, 'c')
29             Row = max(A, 'r'|'m')
30             M = max(A1, A2,..., An)
31             M = max(list(A1, A2,..., An))
32             [.., K] = max(..)
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
36         <title>Arguments</title>
37         <variablelist>
38             <varlistentry>
39                 <term>A, A1, ..., An</term>
40                 <listitem>
41                     <para>
42                         scalars, vectors, matrices or hypermatrices of encoded integers or of real
43                         numbers, in dense or sparse format. They must have the same sizes, or be
44                         mixed with scalars (scalars are then implicitly expanded to the arrays sizes).
45                         Sparse arrays can't be mixed with dense ones, except with dense
46                         <emphasis>negative</emphasis> scalars.
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>m</term>
52                 <listitem>
53                     <para>
54                         single number = maximum of all values of <varname>A</varname> elements.
55                         Always in dense format, even when <varname>A</varname> is sparse encoded.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>Col</term>
61                 <listitem>
62                     <para>
63                         column vector if <varname>A</varname> is a 2D matrix, or hypermatrix of
64                         size(A) with size(A,2) set to 1: Maxima over columns (for each row).
65                         If <varname>A</varname> is sparse, then <varname>Col</varname> is sparse
66                         as well.
67                     </para>
68                 </listitem>
69             </varlistentry>
70             <varlistentry>
71                 <term>Row</term>
72                 <listitem>
73                     <para>
74                         row vector if <varname>A</varname> is a 2D matrix, or hypermatrix of
75                         size(A) with size(A,1) set to 1: Maxima over rows (for each column).
76                         If <varname>A</varname> is sparse, then <varname>Row</varname> is sparse
77                         as well.
78                     </para>
79                 </listitem>
80             </varlistentry>
81             <varlistentry>
82                 <term>M</term>
83                 <listitem>
84                     <para>
85                         Array of size = <literal>size(A1)</literal>, such that for any q
86                         <literal>M(q) = max(A1(q),A2(q),..An(q))</literal>
87                         If <varname>A</varname>,..,<varname>An</varname> are sparse, then
88                         <varname>M</varname> is sparse as well.
89                     </para>
90                 </listitem>
91             </varlistentry>
92             <varlistentry>
93                 <term>K</term>
94                 <listitem>
95                     <para>
96                         Indices in <varname>A</varname>.. of the (first) maximum found.
97                         When <literal>[m,K]=max(A)</literal> is used,
98                         <itemizedlist>
99                             <listitem>
100                                 If <literal>A</literal> is a vector, K is a scalar.
101                             </listitem>
102                             <listitem>
103                                 Otherwise, <varname>K</varname> is a row vector [i,j,..] of subscripts.
104                             </listitem>
105                         </itemizedlist>
106                     </para>
107                     <para>
108                         For other syntaxes, <varname>K</varname> has the shape and sizes of
109                         <varname>Col</varname>, <varname>Row</varname>, and <varname>M</varname>.
110                     </para>
111                     <para>
112                         With the <literal>[M,K] = max(A1,A2,..,An)</literal> syntax, we have,
113                         for any linear index q:
114                         <literal>[M(q),K(q)] = max([A1(q) A2(q) .. An(q)])</literal>.
115                     </para>
116                     <para>
117                         <warning>
118                             <varname>K</varname> is always in dense format, even when
119                             <varname>A, A1,..,An</varname> are sparse-encoded. Hence, when the
120                             <literal>[M,K]=max(A1,A2,..)</literal> syntax is used with huge but
121                             sparse matrices, this may lead to a huge <emphasis>dense</emphasis>
122                             <varname>K</varname> matrix. The user must check that enough memory
123                             is available for it.
124                         </warning>
125                     </para>
126                 </listitem>
127             </varlistentry>
128         </variablelist>
129     </refsection>
130     <refsection>
131         <title>Description</title>
132         <para>
133             For <literal>A</literal>, a real vector or matrix, <literal>max(A)</literal> is the
134             greatest element of <literal>A</literal>.
135         </para>
136         <para>
137             <literal>[m,K]=max(A)</literal> gives in addition the indices of the first maximum.
138         </para>
139         <para>
140             A second argument of type string <literal>'r'</literal> or
141             <literal>'c'</literal> can be used : <literal>'r'</literal> is used to get
142             a row vector <literal>Row</literal> such that <literal>Row(j)</literal>
143             contains the maximum of the <literal>j</literal>th column <literal>A(:,j)</literal>,
144             <literal>K(j)</literal> gives the index of the row
145             which contains the maximum, for the column #<literal>j</literal>.
146         </para>
147         <para>
148             <literal>'c'</literal> is used for the dual operation on the rows of
149             <literal>A</literal>. <literal>'m'</literal> is used for compatibility with Matlab.
150         </para>
151         <para>
152             <literal>[M,K]=max(list(A1,...,An))</literal> is an equivalent
153             syntax of <literal>[M,K]=max(A1,A2,...,An)</literal>.
154         </para>
155         <note>
156             <itemizedlist>
157                 <listitem>
158                     max() ignores NaN values (unless there are only NaN values).
159                 </listitem>
160                 <listitem>
161                     <literal>max([])</literal> returns
162                     <literal>[]</literal> for values and <varname>K</varname>.
163                 </listitem>
164             </itemizedlist>
165         </note>
166     </refsection>
167     <refsection>
168         <title>Examples</title>
169         <programlisting role="example"><![CDATA[
170 [m, k] = max([])
171 [m, k] = max([1 5 ; 3 %nan])
172 [m, k] = max([1 5 ; 3 %nan], 2.5)
173 [m, k] = max([5 -1 1], [1 0 3], [2 1 3])
174 [m, k] = max(list([5 -1 1], [1 0 3], [2 1 3]))
175  ]]></programlisting>
176     <screen><![CDATA[
177 --> [m, k] = max([])
178  m  =
179     []
180  k  =
181     []
182
183 --> [m, k] = max([1 5 ; 3 %nan])
184  m  =
185    5.
186
187  k  =
188    1.   2.
189
190 --> [m, k] = max([1 5 ; 3 %nan], 2.5)
191  m  =
192    2.5   5.
193    3.    2.5
194
195  k  =
196    2.   1.
197    1.   2.
198
199 --> [m, k] = max([5 -1 1], [1 0 3], [2 1 3])
200  m  =
201    5.   1.   3.
202
203  k  =
204    1.   3.   2.
205 ]]></screen>
206         <para>
207             <emphasis role="bold">With the "r" or "c" options</emphasis>:
208         </para>
209         <programlisting role="example"><![CDATA[
210 A = grand(4,6,"uin",0,30); A(3,4) = %nan
211 [Row, K] = max(A, "r")
212 [Col, K] = max(A, "c")
213  ]]></programlisting>
214     <screen><![CDATA[
215 --> A = grand(4,6,"uin",0,30); A(3,4) = %nan
216  A  =
217    18.   3.    22.   0.    13.   28.
218    16.   20.   25.   6.    10.   1.
219    25.   26.   20.   Nan   2.    21.
220    5.    9.    16.   15.   24.   25.
221
222 --> [Row, K] = max(A, "r")
223  Row  =
224    25.   26.   25.   15.   24.   28.
225
226  K  =
227    3.   3.   2.   4.   4.   1.
228
229 --> [Col, K] = max(A, "c")
230  Col  =
231    28.
232    25.
233    26.
234    25.
235
236  K  =
237    6.
238    3.
239    2.
240    6.
241  ]]></screen>
242         <para>
243             <emphasis role="bold">With sparse inputs</emphasis>:
244         </para>
245         <programlisting role="example"><![CDATA[
246 s = sprand(5,4,0.5); k = s~=0; s(k) = round((s(k)-0.5)*10), full(s)
247 [Row, K] = max(s, "r")
248 [Col, K] = max(s, "c")
249 [M, K] = max(s, -1);   [full(s)  ones(s(:,1))*%nan  full(M)]
250 issparse(M)
251 K
252  ]]></programlisting>
253     <screen><![CDATA[
254 --> s = sprand(5,4,0.5); k = s~=0; s(k) = round((s(k)-0.5)*10), full(s)
255  s  =
256 (  5,  4) sparse matrix
257 (  1,  2)    -2.
258 (  1,  3)    -4.
259 (  1,  4)     3.
260 (  2,  1)    -5.
261 (  2,  4)     3.
262 (  3,  2)    -2.
263 (  3,  3)    -4.
264 (  4,  2)     4.
265 (  4,  4)     2.
266 (  5,  2)    -5.
267 (  5,  3)     5.
268 (  5,  4)    -4.
269
270  ans  =
271    0.  -2.  -4.   3.
272   -5.   0.   0.   3.
273    0.  -2.  -4.   0.
274    0.   4.   0.   2.
275    0.  -5.   5.  -4.
276
277 --> [Row, K] = max(s, "r")
278  Row  =
279 (  1,  4) sparse matrix
280 (  1,  2)     4.
281 (  1,  3)     5.
282 (  1,  4)     3.
283
284  K  =
285    1.   4.   5.   1.
286
287 --> [Col, K] = max(s, "c")
288  Col  =
289 (  5,  1) sparse matrix
290 (  1,  1)     3.
291 (  2,  1)     3.
292 (  4,  1)     4.
293 (  5,  1)     5.
294
295  K  =
296    4.
297    4.
298    1.
299    2.
300    3.
301
302 --> [M, K] = max(s, -1);   [full(s)  ones(s(:,1))*%nan  full(M)]
303  ans  =
304    0.  -2.  -4.   3.   Nan   0.  -1.  -1.   3.
305   -5.   0.   0.   3.   Nan  -1.   0.   0.   3.
306    0.  -2.  -4.   0.   Nan   0.  -1.  -1.   0.
307    0.   4.   0.   2.   Nan   0.   4.   0.   2.
308    0.  -5.   5.  -4.   Nan   0.  -1.   5.  -1.
309
310 --> issparse(M)
311  ans  =
312    1.
313
314 --> K
315  K  =
316    1.   2.   2.   1.
317    2.   1.   1.   1.
318    1.   2.   2.   1.
319    1.   1.   1.   1.
320    1.   2.   1.   2.
321 ]]> </screen>
322     </refsection>
323     <refsection role="see also">
324         <title>See also</title>
325         <simplelist type="inline">
326             <member>
327                 <link linkend="min">min</link>
328             </member>
329             <member>
330                 <link linkend="strange">strange</link>
331             </member>
332             <member>
333                 <link linkend="mean">mean</link>
334             </member>
335             <member>
336                 <link linkend="gsort">gsort</link>
337             </member>
338             <member>
339                 <link linkend="find">find</link>
340             </member>
341             <member>
342                 <link linkend="full">full</link>
343             </member>
344         </simplelist>
345     </refsection>
346     <refsection role="history">
347         <title>History</title>
348         <revhistory>
349             <revision>
350                 <revnumber>6.0.2</revnumber>
351                 <revdescription>
352                     max() now actually works with sparse matrices
353                 </revdescription>
354             </revision>
355         </revhistory>
356     </refsection>
357 </refentry>