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>