Wish 12776 fulfilled: add a new option to histplot to draw freq polygon chart 03/12303/5
Mehran Khorshidi [Mon, 19 Aug 2013 19:18:33 +0000 (21:18 +0200)]
Change-Id: I179b9712e5ade24215c39f3793a991e4625d3170

scilab/CHANGES_5.5.X
scilab/modules/graphics/help/en_US/2d_plot/histplot.xml
scilab/modules/graphics/macros/histplot.sci
scilab/modules/helptools/etc/images_md5.txt
scilab/modules/helptools/images/histplot_en_US_4.png [new file with mode: 0644]

index a39ed36..5d0bfd3 100644 (file)
@@ -41,6 +41,10 @@ BDF methods with direct and preconditioned Krylov linear solvers, from ODEPACK.
   
 * Update Windows Solution to Visual Studio 2012.
 
+* The histplot command can now be used with the option polygon=%t/%f to add the
+  frequency polygon chart (thanks to Mehran Khorshidi).
+
+
 Syntax changes
 ===============
 
index f1dc15c..7bd3f4c 100644 (file)
@@ -1,4 +1,5 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version='1.0' encoding='UTF-8'?>
+
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) INRIA - Serge Steer
  * are also available at    
  * 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" xmlns:scilab="http://www.scilab.org"  xml:lang="en" xml:id="histplot">
+ --><!-- This document was created with Syntext Serna Free. -->
+
+<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" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="histplot">
+    
     <refnamediv>
+        
         <refname>histplot</refname>
+        
         <refpurpose>plot a histogram</refpurpose>
+        
     </refnamediv>
+    
     <refsynopsisdiv>
+        
         <title>Calling Sequence</title>
-        <synopsis>histplot(n, data, &lt;opt_args&gt;)
-            histplot(x, data, &lt;opt_args&gt;)
+        
+        <synopsis>histplot(n, data [,normalization] [,polygon], &lt;opt_args&gt;)
+            
+            histplot(x, data [,normalization] [,polygon], &lt;opt_args&gt;)
+            
         </synopsis>
+        
     </refsynopsisdiv>
+    
     <refsection>
+        
         <title>Arguments</title>
+        
         <variablelist>
+            
             <varlistentry>
+                
                 <term>n</term>
+                
                 <listitem>
+                    
                     <para>positive integer (number of classes)</para>
+                    
                 </listitem>
+                
             </varlistentry>
+            
             <varlistentry>
+                
                 <term>x</term>
+                
                 <listitem>
+                    
                     <para>
+                        
                         increasing vector defining the classes (<literal>x</literal> may have at least 2 components)
+                        
                     </para>
+                    
                 </listitem>
+                
             </varlistentry>
+            
             <varlistentry>
+                
                 <term>data</term>
+                
                 <listitem>
+                    
                     <para>vector (data to be analysed)</para>
+                    
+                </listitem>
+                
+            </varlistentry>
+            
+            <varlistentry>
+                
+                <term>normalization</term>
+                
+                <listitem>
+                    
+                    <para>a boolean (%t (default value) or %f)</para>
+                    
+                </listitem>
+                
+            </varlistentry>
+            
+            <varlistentry>
+                
+                <term>polygon</term>
+                
+                <listitem>
+                    
+                    <para>a boolean (%t or %f (default value))</para>
+                    
                 </listitem>
+                
             </varlistentry>
+            
             <varlistentry>
+                
                 <term>&lt;opt_args&gt;</term>
+                
                 <listitem>
+                    
                     <para>
+                        
                         This represents a sequence of statements <literal>key1=value1,key2=value2</literal>
+                        
                         ,... where <literal>key1</literal>,
-                        <literal>key2,...</literal> can be any optional <link linkend="plot2d">plot2d</link> parameter (<literal>style,strf,leg,
-                            rect,nax, logflag,frameflag, axesflag
-                        </literal>
-                        )or normalization. For this last one the corresponding
-                        value must be a boolean scalar (default value %t). 
+                        
+                        <literal>key2,...</literal> can be any optional <link linkend="plot2d">plot2d</link> parameter (<literal>style,strf,leg, rect,nax, logflag,frameflag, axesflag </literal>
+                        
+                        ).
+                        
                     </para>
+                    
                 </listitem>
+                
             </varlistentry>
+            
         </variablelist>
+        
     </refsection>
+    
     <refsection>
+        
         <title>Description</title>
+        
         <para>
+            
             This function plot a histogram of the <literal>data</literal> vector using the
+            
             classes <literal>x</literal>. When the number <literal>n</literal> of classes is provided
+            
             instead of <literal>x</literal>, the classes are chosen equally spaced and
-            <emphasis>x(1) = min(data) &lt;  x(2) = x(1) + dx  &lt;  ...  &lt; x(n+1) = max(data)</emphasis>
+            
+            <emphasis>x(1) = min(data) &lt; x(2) = x(1) + dx &lt; ... &lt; x(n+1) = max(data)</emphasis>
+            
             with <emphasis>dx = (x(n+1)-x(1))/n</emphasis>.
+            
         </para>
+        
         <para> The classes are defined by C1 = [x(1), x(2)] and  Ci = ( x(i), x(i+1)] for i &gt;= 2.
+            
             Noting Nmax the total number of <literal>data</literal> (Nmax = length(data)) and Ni the number 
+            
             of <literal>data</literal> components falling in Ci, the value of the histogram for x in Ci 
+            
             is equal to <emphasis>Ni/(Nmax (x(i+1)-x(i)))</emphasis> when <literal>normalization</literal> is true
+            
             (default case) and else, simply equal to <emphasis>Ni</emphasis>. When normalization occurs the
+            
             histogram verifies: 
+            
         </para>
+        
         <para>
-            <latex style="display"><![CDATA[
-    \int_{x(1)}^{x(n+1)}h(x)\,\mathrm{d}x=1
-    ]]></latex>
+            
+            <latex style="display"><![CDATA[ \int_{x(1)}^{x(n+1)}h(x)\,\mathrm{d}x=1 ]]></latex>
+            
         </para>
+        
         <para>
+            
             when <emphasis>x(1)&lt;=min(data)</emphasis> and <emphasis>max(data) &lt;= x(n+1)</emphasis>
+            
         </para>
+        
         <para>
+            
             Any <link linkend="plot2d">plot2d</link> (optional) parameter may be provided; for instance to
+            
             plot a histogram with the color number 2 (blue if std colormap is used) and
+            
             to restrict the plot inside the rectangle [-3,3]x[0,0.5],
+            
             you may use <literal>histplot(n,data, style=2, rect=[-3,0,3,0.5])</literal>.
+            
+        </para>
+        
+        <para>
+            
+            Frequency polygon is a line graph drawn by joining all the midpoints of the top of the bins of a histogram. 
+            
+            Therefore we can use <literal>histplot</literal> function to plot a polygon frequency chart.
+            
         </para>
+        
+        
         <para>
+            
+            The optional argument <literal>polygon</literal> connects the midpoint of the top of each bar of a histogram with straight lines.  
+            
+        </para>
+        
+        
+        <para>
+            
+            If <literal>polygon=%t</literal> we will have a histogram with frequency polygon chart. 
+            
+        </para>
+        
+        <para>
+            
             Enter the command <literal>histplot()</literal> to see a demo.
+            
         </para>
+        
     </refsection>
+    
     <refsection>
+        
         <title>Examples</title>
+        
         <simplelist>
-            <member>
-                Example #1: variations around a histogram of a gaussian random sample 
+            
+            <member> Example #1: variations around a histogram of a gaussian random sample 
+                
                 <programlisting role="example"><![CDATA[ 
 d=rand(1,10000,'normal');  // the gaussian random sample
 clf();histplot(20,d)
@@ -106,13 +231,21 @@ clf();histplot(20,d,normalization=%f)
 clf();histplot(20,d,leg='rand(1,10000,''normal'')',style=5)
 clf();histplot(20,d,leg='rand(1,10000,''normal'')',style=16, rect=[-3,0,3,0.5]); 
 ]]></programlisting>
+                
                 <scilab:image>
+                    
                     d=rand(1,10000,'normal'); 
+                    
                     clf();histplot(20,d,leg='rand(1,10000,''normal'')',style=16, rect=[-3,0,3,0.5]);
+                    
                 </scilab:image>
+                
             </member>
+            
             <member>
+                
                 Example #2: histogram of a binomial (B(6,0.5)) random sample
+                
                 <programlisting role="example"><![CDATA[
 d = grand(1000,1,"bin", 6, 0.5);
 c = linspace(-0.5,6.5,8);
@@ -124,20 +257,35 @@ subplot(2,1,2)
 histplot(c, d, normalization=%f, style=5)
 xtitle("non normalized histogram")
 ]]></programlisting>
+                
                 <scilab:image localized="true">
+                    
                     d = grand(1000,1,"bin", 6, 0.5);
+                    
                     c = linspace(-0.5,6.5,8);
+                    
                     clf()
+                    
                     subplot(2,1,1)
+                    
                     histplot(c, d, style=2)
+                    
                     xtitle("normalized histogram")
+                    
                     subplot(2,1,2)
+                    
                     histplot(c, d, normalization=%f, style=5)
+                    
                     xtitle("non normalized histogram")
+                    
                 </scilab:image>
+                
             </member>
+            
             <member>
+                
                 Example #3: histogram of an exponential random sample 
+                
                 <programlisting role="example"><![CDATA[
 lambda = 2;
 X = grand(100000,1,"exp", 1/lambda);
@@ -148,32 +296,86 @@ x = linspace(0,max(Xmax),100)';
 plot2d(x,lambda*exp(-lambda*x),strf="000",style=5)
 legend(["exponential random sample histogram" "exact density curve"]);
 ]]></programlisting>
+                
                 <scilab:image localized="true">
                     
+                    
+                    
                     lambda = 2;
+                    
                     X = grand(100000,1,"exp", 1/lambda);
+                    
                     Xmax = max(X);
+                    
                     clf()
+                    
                     histplot(40, X, style=2)
+                    
                     x = linspace(0,max(Xmax),100)';
+                    
                     plot2d(x,lambda*exp(-lambda*x),strf="000",style=5)
+                    
                     legend(["exponential random sample histogram" "exact density curve"]);
+                    
+                </scilab:image>
+                
+            </member>
+            
+            <member> 
+                
+                Example #4: the frequency polygon chart and the histogram of a gaussian random sample 
+                
+                <programlisting role="example"><![CDATA[
+n=10; 
+data=rand(1,1000,"normal"); 
+clf(); histplot(n, data, style=12, polygon=%t); 
+legend(["normalized histogram" "frequency polygon chart"]);
+]]></programlisting>
+                
+                <scilab:image localized="true">
+                    
+                    n=10; 
+                    
+                    data=rand(1,1000,"normal"); 
+                    
+                    clf(); histplot(n,data,style=12,polygon=%t); 
+                    
+                    legend(["normalized histogram" "frequency polygon chart"]); 
+                    
                 </scilab:image>
             </member>
+            
         </simplelist>
+        
     </refsection>
+    
     <refsection role="see also">
+        
         <title>See Also</title>
+        
         <simplelist type="inline">
+            
             <member>
+                
                 <link linkend="hist3d">hist3d</link>
+                
             </member>
+            
             <member>
+                
                 <link linkend="plot2d">plot2d</link>
+                
             </member>
+            
             <member>
+                
                 <link linkend="dsearch">dsearch</link>
+                
             </member>
+            
         </simplelist>
+        
     </refsection>
+    
 </refentry>
+
index 7355507..23e6581 100644 (file)
@@ -3,6 +3,7 @@
 // Copyright (C) Bruno Pincon
 // Copyright (C) 2010 - Samuel Gougeon
 // Copyright (C) 2012 - Scilab Enterprises - Adeline CARNIS
+// Copyright (C) 2013 - A. Khorshidi (new option)
 //
 // This file must be used under the terms of the CeCILL.
 // This source file is licensed as described in the file COPYING, which
@@ -11,7 +12,7 @@
 // http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
 
 
-function histplot(n,data,style,strf,leg,rect,nax,logflag,frameflag,axesflag,normalization)
+function histplot(n,data,style,strf,leg,rect,nax,logflag,frameflag,axesflag,normalization,polygon)
     // histplot(n,data,<opt_arg_seq>)
     // draws histogram of entries in  data put into n classes
     //
@@ -72,6 +73,7 @@ function histplot(n,data,style,strf,leg,rect,nax,logflag,frameflag,axesflag,norm
 
     // this is the only specific optionnal argument for histplot
     if ~exists("normalization","local") then, normalization=%t,end
+    if ~exists("polygon","local") then, polygon=%f,end
 
     // now parse optionnal arguments to be sent to plot2d
     opt_arg_seq = []
@@ -108,6 +110,12 @@ function histplot(n,data,style,strf,leg,rect,nax,logflag,frameflag,axesflag,norm
 
     if normalization then y=y ./ (p *(x(2:$)-x(1:$-1))),end
 
+    if polygon then
+        xmid=(x(1:$-1)+x(2:$))/2;...
+        xp=[x(1)-(x(2)-x(1))/2 xmid x($)+(x($)-x($-1))/2];...
+        yp=[0 y 0];
+    end // new lines
+
     // now form the polyline
     //    X = [x1 x1 x2 x2 x2 x3 x3 x3  x4 ...   xn xn+1 xn+1]'
     //    Y = [0  y1 y1 0  y2 y2 0  y3  y3 ... 0 yn yn   0 ]'
@@ -120,13 +128,10 @@ function histplot(n,data,style,strf,leg,rect,nax,logflag,frameflag,axesflag,norm
 
     if opt_arg_seq == [] then
         plot2d(X,Y)
+        if polygon then plot(xp,yp,"b-o"), end // new line
     else
         execstr("plot2d(X,Y"+opt_arg_seq+")")
+        if polygon then plot(xp,yp,"r-o"), end // new line
     end
 
 endfunction
-
-
-
-
-
index 4a4f48e..45d4162 100644 (file)
@@ -841,6 +841,7 @@ hist3d_ru_RU_1.png=9031d249fda1aeea0a14f05417e56bd7
 histplot_1.png=becfb3115ba4cd9eaee18c2535dc557a
 histplot_en_US_2.png=8117e3f08f726740eb7a4e19b7c80cf1
 histplot_en_US_3.png=cd3e60e8f0a028549da7547fbf4b7222
+histplot_en_US_4.png=ac27914effe5c72bfcd955f7a90d43d2
 histplot_fr_FR_2.png=d7eff354adbf2b188f02d60ae6a83c8c
 histplot_fr_FR_3.png=77b4c00287c0149ee45394cb8d7c90f9
 histplot_ru_RU_2.png=8117e3f08f726740eb7a4e19b7c80cf1
diff --git a/scilab/modules/helptools/images/histplot_en_US_4.png b/scilab/modules/helptools/images/histplot_en_US_4.png
new file mode 100644 (file)
index 0000000..eba2d9a
Binary files /dev/null and b/scilab/modules/helptools/images/histplot_en_US_4.png differ