statistics: Fixed bug #7768: for cdfgam, the Scale parameter was, in fact, the Rate 83/1883/7
Michael Baudin [Fri, 10 Sep 2010 14:25:11 +0000 (16:25 +0200)]
Change-Id: I795f1c3da10774a66ee4acdb6f0b73849e67fa55

scilab/CHANGES_5.3.X
scilab/modules/statistics/help/en_US/cdfgam.xml
scilab/modules/statistics/sci_gateway/c/sci_cdfgam.c
scilab/modules/statistics/tests/unit_tests/cdfgam.dia.ref
scilab/modules/statistics/tests/unit_tests/cdfgam.tst

index 53896cd..272fc1f 100644 (file)
@@ -47,6 +47,8 @@ Bug Fixes:
 * bug 7364 fixed - The "Checked" property misworked for uimenus and they could
                    not have a callback.
 
+* bug 7768 fixed - for cdfgam, the Scale parameter was, in fact, the Rate.
+
 * bug 8068 fixed - Figures were not all closed at the end of a demonstration.
 
 * bug 8077 fixed - browsevar, scinotes, xcos functions were not disabled in -nwni
index 8a3be1e..e1a3b0b 100644 (file)
@@ -2,6 +2,7 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2000 - INRIA - Carlos Klimann
+ * Copyright (C) 2010 - DIGITEO - Michael Baudin
  * 
  * This file must be used under the terms of the CeCILL.
  * This source file is licensed as described in the file COPYING, which
  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:lang="en" xml:id="cdfgam">
+<refentry
+  xmlns="http://docbook.org/ns/docbook"
+  xmlns:xlink="http://www.w3.org/1999/xlink"
+  xmlns:svg="http://www.w3.org/2000/svg"
+  xmlns:mml="http://www.w3.org/1998/Math/MathML"
+  xmlns:db="http://docbook.org/ns/docbook"
+  version="5.0-subset Scilab"
+  xml:lang="en"
+  xml:id="cdfgam">
   <info>
     <pubdate>$LastChangedDate$</pubdate>
   </info>
   </refnamediv>
   <refsynopsisdiv>
     <title>Calling Sequence</title>
-    <synopsis>[P,Q]=cdfgam("PQ",X,Shape,Scale)
-[X]=cdfgam("X",Shape,Scale,P,Q)
-[Shape]=cdfgam("Shape",Scale,P,Q,X)
-[Scale]=cdfgam("Scale",P,Q,X,Shape)</synopsis>
+    <synopsis>
+      [P,Q]=cdfgam("PQ",X,Shape,Rate)
+      [X]=cdfgam("X",Shape,Rate,P,Q)
+      [Shape]=cdfgam("Shape",Rate,P,Q,X)
+      [Rate]=cdfgam("Rate",P,Q,X,Shape)
+    </synopsis>
   </refsynopsisdiv>
   <refsection>
     <title>Parameters</title>
     <variablelist>
       <varlistentry>
-        <term>P,Q,X,Shape,Scale</term>
+        <term>P,Q,X,Shape,Rate</term>
         <listitem>
           <para>five real vectors of the same size.</para>
         </listitem>
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term>Scale</term>
+        <term>Rate</term>
         <listitem>
-          <para> The scale parameter of the gamma density. Input range: (0, +infinity). Search range: (1E-300,1E300]</para>
+          <para> The rate parameter of the gamma density. Input range: (0, +infinity). Search range: (1E-300,1E300]</para>
         </listitem>
       </varlistentry>
     </variablelist>
   </refsection>
+
   <refsection>
     <title>Description</title>
     <para>
-    Calculates any one parameter of the gamma
-    distribution given values for the others.</para>
+      Calculates any one parameter of the gamma
+      distribution given values for the others.
+    </para>
+
     <para>
-    Cumulative distribution function (P) is calculated directly by
-    the code associated with:</para>
+      The gamma density is 
+    </para>
+
     <para>
-    DiDinato, A. R. and Morris, A. H. Computation of the  incomplete
-    gamma function  ratios  and their  inverse.   ACM  Trans.  Math.
-    Softw. 12 (1986), 377-393.</para>
+      <latex>
+        \begin{eqnarray}
+        f(x,a,r) = \frac{1}{r^{-a}\Gamma(a)} \int_0^x t^{a-1} \exp\left(-rt\right) dt
+        \end{eqnarray}
+      </latex>
+    </para>
+
     <para>
-    Computation of other parameters involve a seach for a value that
-    produces  the desired  value  of P.   The search relies  on  the
-    monotinicity of P with the other parameter.</para>
+      where a is the shape and r is the rate.
+    </para>
+
+
     <para>
-    The gamma density is proportional to
-    <literal>T**(SHAPE - 1) * EXP(- SCALE * T)</literal></para>
+      Caution. As opposed to other technical computing languages,
+      this function makes use of the rate parameter, and not the
+      scale parameter.
+      The rate parameter is linked to the scale parameter with the equation rate=1/scale.
+    </para>
+
     <para>
-    From DCDFLIB: Library of Fortran Routines for Cumulative Distribution
-    Functions, Inverses, and Other Parameters (February, 1994)
-    Barry W. Brown, James Lovato and Kathy Russell. The University of
-    Texas.</para>
+      Computation of parameters such as X, Shape or Rate involve a seach for a value that
+      produces  the desired  value  of P.   The search relies on the
+      monotinicity of P with the other parameter.
+    </para>
+
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+    <para>
+      In the following example, we compute the probability of the event <literal>x=0.1</literal>
+      for the Gamma distribution function with <literal>Shape=1.0</literal> and 
+      <literal>Rate=1.0</literal>.
+    </para>
+
+    <programlisting role="example">
+      <![CDATA[ 
+    Shape = 0.1
+    Rate = 1.0
+    x = 0.1
+    // Expected : P = 0.8275518
+    [P,Q]=cdfgam("PQ",x,Shape,Rate) 
+ ]]>
+    </programlisting>
+
+    <para>
+      In the following example, we compute the probability of the event <literal>x=0.1</literal>
+      and check that the search algorithms allows to consistently invert the 
+      function.
+    </para>
+
+    <programlisting role="example">
+      <![CDATA[ 
+    Shape = 0.1
+    Rate = 2.0
+    x = 0.3
+    [P,Q]    = cdfgam("PQ",x,Shape,Rate)
+    [X1]     = cdfgam("X",Shape,Rate,P,Q)
+    [Shape1] = cdfgam("Shape",Rate,P,Q,x)
+    [Rate1] = cdfgam("Rate",P,Q,x,Shape)
+ ]]>
+  </programlisting>
+
+    <para>
+      In the following example, we draw the Gamma distribution function 
+      for various values of the shape and rate.
+    </para>
+
+    <programlisting role="example">
+      <![CDATA[ 
+    N = 1000;
+    x = linspace(0,20,N)';
+    Shape = [1 2 3 5 9];
+    Rate = 1 ./ [2 2 2 1 0.5];
+    C = ["red" "green" "blue" "cyan" "orange"];
+    lstr = [];
+    drawlater();
+    h = gcf();
+    for i = 1 : 5
+      P = cdfgam("PQ",x,Shape(i)*ones(N,1),Rate(i)*ones(N,1));
+      lstr(i) = msprintf("Shape=%s, Rate=%s",string(Shape(i)),string(Rate(i)));
+      plot(x,P);
+      h.children.children(1).children.foreground = color(C(i));
+    end
+    legend(lstr);
+    xtitle("CDF of the Gamma distribution function","X","P");
+    drawnow();
+ ]]>
+  </programlisting>
+
+</refsection>
+
+  <refsection>
+    <title>Bibliography</title>
+    <para>
+      Cumulative distribution function (P) is calculated directly by
+      the code associated with:
+    </para>
+    <para>
+      DiDinato, A. R. and Morris, A. H. Computation of the  incomplete
+      gamma function  ratios  and their  inverse.   ACM  Trans.  Math.
+      Softw. 12 (1986), 377-393.
+    </para>
+    <para>
+      From DCDFLIB: Library of Fortran Routines for Cumulative Distribution
+      Functions, Inverses, and Other Parameters (February, 1994)
+      Barry W. Brown, James Lovato and Kathy Russell. The University of
+      Texas.
+    </para>
   </refsection>
 </refentry>
index e2ff874..01e3ec1 100644 (file)
@@ -2,6 +2,7 @@
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2006-2008 - INRIA - 
  * Copyright (C) 2010 - DIGITEO - Allan CORNET
+ * Copyright (C) 2010 - DIGITEO - Michael Baudin
  *
  * This file must be used under the terms of the CeCILL.
  * This source file is licensed as described in the file COPYING, which
@@ -40,37 +41,37 @@ int cdfgamI(char* fname,unsigned long l)
     if ( strcmp(cstk(l1),"PQ")==0)
     {
         static int callpos[5] = {3,4,0,1,2};
-        CdfBase(fname,3,2,callpos,"PQ",_("X,Shape and Scale"),1,C2F(cdfgam),
+        CdfBase(fname,3,2,callpos,"PQ",_("X,Shape and Rate"),1,C2F(cdfgam),
             cdfgamErr);
     }
     else if ( strcmp(cstk(l1),"X")==0)
     {
         static int callpos[5] = {2,3,4,0,1};
-        CdfBase(fname,4,1,callpos,"X",_("Shape,Scale,P and Q"),2,C2F(cdfgam),
+        CdfBase(fname,4,1,callpos,"X",_("Shape,Rate,P and Q"),2,C2F(cdfgam),
             cdfgamErr);
     }
     else if ( strcmp(cstk(l1),"Shape")==0)
     {
         static int callpos[5] = {1,2,3,4,0};
-        CdfBase(fname,4,1,callpos,"Shape",_("Scale,P,Q and X"),3,C2F(cdfgam),
+        CdfBase(fname,4,1,callpos,"Shape",_("Rate,P,Q and X"),3,C2F(cdfgam),
             cdfgamErr);
     }
-    else if ( strcmp(cstk(l1),"Scale")==0)
+    else if ( strcmp(cstk(l1),"Rate")==0)
     {
         static int callpos[5] = {0,1,2,3,4};
-        CdfBase(fname,4,1,callpos,"Scale",_("P,Q,X and Shape"),4,C2F(cdfgam),
+        CdfBase(fname,4,1,callpos,"Rate",_("P,Q,X and Shape"),4,C2F(cdfgam),
             cdfgamErr);
     }
     else
     {
-        Scierror(999,_("%s: Wrong value for input argument #%d: '%s', '%s', '%s' or '%s' expected.\n"),fname,1,"PQ","X","Shape","Scale");
+        Scierror(999,_("%s: Wrong value for input argument #%d: '%s', '%s', '%s' or '%s' expected.\n"),fname,1,"PQ","X","Shape","Rate");
     }
     return 0;
 }
 /*--------------------------------------------------------------------------*/
 static void cdfgamErr(int status,double bound)
 {
-    static char *param[7]={"X", "P","Q","X","Shape","Scale"};
+    static char *param[7]={"X", "P","Q","X","Shape","Rate"};
     switch ( status )
     {
     case 1 :
index 69eecc3..0ea0878 100644 (file)
@@ -1,6 +1,6 @@
 // =============================================================================
 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
-// Copyright (C) 2010 - INRIA - Michael Baudin
+// Copyright (C) 2010 - DIGITEO - Michael Baudin
 //
 //  This file is distributed under the same license as the Scilab package.
 // =============================================================================
@@ -174,10 +174,10 @@ for i = 1 : ntests
   q = table(i,6);
   // Caution: this is the rate !
   rate = 1/scale;
-  [p1,q1]=cdfgam("PQ",x,shape,rate);
-  x1     = cdfgam("X",shape,rate,p,q);
-  shape1 = cdfgam("Shape",rate,p,q,x);
-  rate1 = cdfgam("Scale",p,q,x,shape);
+  [p1,q1] = cdfgam("PQ",x,shape,rate);
+  x1      = cdfgam("X",shape,rate,p,q);
+  shape1  = cdfgam("Shape",rate,p,q,x);
+  rate1   = cdfgam("Rate",p,q,x,shape);
   if ( %t ) then
     assert_close ( p1 , p , precision );
     assert_close ( q1 , q , precision );
index 9c4d1f7..c8b144b 100644 (file)
@@ -1,6 +1,6 @@
 // =============================================================================
 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
-// Copyright (C) 2010 - INRIA - Michael Baudin
+// Copyright (C) 2010 - DIGITEO - Michael Baudin
 //
 //  This file is distributed under the same license as the Scilab package.
 // =============================================================================
@@ -186,10 +186,10 @@ for i = 1 : ntests
   q = table(i,6);
   // Caution: this is the rate !
   rate = 1/scale;
-  [p1,q1]=cdfgam("PQ",x,shape,rate);
-  x1     = cdfgam("X",shape,rate,p,q);
-  shape1 = cdfgam("Shape",rate,p,q,x);
-  rate1 = cdfgam("Scale",p,q,x,shape);
+  [p1,q1] = cdfgam("PQ",x,shape,rate);
+  x1      = cdfgam("X",shape,rate,p,q);
+  shape1  = cdfgam("Shape",rate,p,q,x);
+  rate1   = cdfgam("Rate",p,q,x,shape);
   if ( %t ) then
     assert_close ( p1 , p , precision );
     assert_close ( q1 , q , precision );