<?xml version="1.0" encoding="UTF-8"?>
<!--
This file is part of the Scilab time frequency toolbox
This file must be used under the terms of the CeCILL.
This source file is licensed as described in the file COPYING, which
you should have received as part of this distribution.  The terms
are also available at
http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
-->

<refentry xml:id="tfrgrd" xml:lang="en"
          xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg"
          xmlns:scilab="http://www.scilab.org"
          xmlns:ns3="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:db="http://docbook.org/ns/docbook">

  <refnamediv>
    <refname>tfrgrd</refname>
	<refpurpose>Generalized rectangular time-frequency distribution</refpurpose>
  </refnamediv>

<refsynopsisdiv>
   <title>Calling Sequence</title>
   <synopsis>
   	[TFR,T,F] = tfrgrd(X)
   	[TFR,T,F] = tfrgrd(X, T)
   	[TFR,T,F] = tfrgrd(X, T, N)
   	[TFR,T,F] = tfrgrd(X, T, N, G)
   	[TFR,T,F] = tfrgrd(X, T, N, G, H)
   	[TFR,T,F] = tfrgrd(X, T, N, G, H, RS)
   	[TFR,T,F] = tfrgrd(X, T, N, G, H, RS, MOVERN)
   	[TFR,T,F] = tfrgrd(X, T, N, G, H, RS, MOVERN, TRACE)
   	[TFR,T,F] = tfrgrd(...,'plot')
   </synopsis>
</refsynopsisdiv>
<refsection>
   <title>Parameters</title>
   <variablelist>
   <varlistentry>
     <term>X :</term>
     <listitem>
       <para> A Nx elements vector (auto-GRD)  or a Nx by 2 array signal (cross-GRD).</para>
     </listitem>
   </varlistentry>

   <varlistentry>
     <term> T:</term> 
     <listitem>
       <para> a real Nt vector : time instant(s) (default: 1:NX).</para>
     </listitem>
   </varlistentry>

   <varlistentry>
     <term> N:</term> 
     <listitem><para> a positive integer: the number of frequency bins (default:NX).</para>
   </listitem>
   </varlistentry>

   <varlistentry>
     <term> G:</term> 
     <listitem>
       <para> a real vector with odd length: the time smoothing window,  (default :Hamming(N/10)).</para>
       <para>It will be normalized such as the middle point equals 1 to preserve signal energy.</para>
   </listitem>
   </varlistentry>

   <varlistentry>
     <term> H :</term> 
     <listitem>
       <para> real vector with odd length: the frequency smoothing window,(default: Hamming(N/4)).</para>
       <para>It will be normalized such as the middle point equals 1 to preserve signal energy.</para>
   </listitem>
   </varlistentry>
   <varlistentry>
     <term> RS :</term> 
     <listitem>
       <para> a positive scalar: the kernel width (default : 1).</para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term> MOVERN :</term>
     <listitem>
       <para> a positive scalar: the dissymmetry ratio (default : 1).</para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term> TRACE :</term> 
     <listitem>
       <para> if nonzero,the progression of the algorithm is shown
       (default : 0).</para>
     </listitem>
   </varlistentry>

   <varlistentry>
     <term>'plot':</term> <listitem><para> if one input parameter is
     'plot', <link linkend="tfrqview">tfrqview</link> is called and
     the time-frequency representation will be plotted.</para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term> TFR :</term> 
     <listitem>
       <para> A real N by Nt array: the time-frequency representation.</para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term> F :</term> 
     <listitem>
       <para> A N vector of normalized frequencies.</para>
     </listitem>
   </varlistentry>
   </variablelist>
</refsection>

<refsection>
   <title>Parameters</title>
   <variablelist>
   <varlistentry><term> X :</term> <listitem><para> signal if
   auto-GRD, or [X1,X2] if cross-GRD.</para></listitem></varlistentry>
   <varlistentry><term> T :</term> <listitem><para> time instant(s)
   (default : 1:length(X)).</para></listitem></varlistentry>
   <varlistentry><term> N :</term> <listitem><para> number of
   frequency bins (default :
   length(X)).</para></listitem></varlistentry>
   <varlistentry><term> G :</term> <listitem><para> time smoothing
   window, G(0) being forced to 1. (default :
   Hamming(N/10)).</para></listitem></varlistentry>
   <varlistentry><term> H :</term> <listitem><para> frequency
   smoothing window, H(0) being forced to 1.  (default :
   Hamming(N/4)).</para></listitem></varlistentry>
   <varlistentry><term> RS :</term> <listitem><para> kernel width
   (default : 1).</para></listitem></varlistentry>
   <varlistentry><term> MOVERN :</term> <listitem><para> dissymmetry
   ratio (default : 1).</para></listitem></varlistentry>
   <varlistentry><term> TRACE :</term> <listitem><para> if nonzero,
   the progression of the algorithm is shown (default :
   0).</para></listitem></varlistentry>
   <varlistentry><term>'plot':</term> <listitem><para> if one input
   parameter is 'plot', tfrgrd runs tfrqview. and TFR will be
   plotted</para></listitem></varlistentry>
   <varlistentry><term> TFR :</term> <listitem><para> time-frequency
   representation.</para></listitem></varlistentry>
   <varlistentry><term> F :</term> <listitem><para> vector of
   normalized frequencies.</para></listitem></varlistentry>
   </variablelist>
</refsection>

<refsection>
   <title>Description</title>
   <para>
tfrgrd computes the Generalized Rectangular distribution of a
discrete-time signal X, or the cross GRD representation between two
signals.
</para>
</refsection>

<refsection>
   <title>Examples</title>
   <para> Interactive use </para>
   <programlisting role="example"><![CDATA[
N = 128
sig = fmlin(N,0.05,0.3) + fmlin(N,0.15,0.4);
g = window("kr",9,3*%pi);
h = window("kr",27,3*%pi);
t = 1:N;
tfrgrd(sig,t,N,g,h,36,1/5,1,'plot');
   ]]></programlisting>

 <para>Non interactive use</para>

   <programlisting role="example"><![CDATA[
N = 128;
sig = fmlin(N,0.05,0.3) + fmlin(N,0.15,0.4);
g = window("kr",9,3*%pi);
h = window("kr",27,3*%pi);
t = 1:N; 
[TFR,T,F] = tfrgrd(sig,t,N,g,h,36,1/5);
clf; gcf().color_map = jetcolormap(128);
grayplot(T,F,TFR');
   ]]></programlisting>
  <scilab:image><![CDATA[
N = 128;
sig = fmlin(N,0.05,0.3) + fmlin(N,0.15,0.4);
g = window("kr",9,3*%pi);
h = window("kr",27,3*%pi);
t = 1:N; 
[TFR,T,F] = tfrgrd(sig,t,N,g,h,36,1/5);
clf; gcf().color_map = jetcolormap(128);
grayplot(T,F,TFR');
    ]]></scilab:image>
</refsection>

<refsection>
   <title>Authors</title>
   <simplelist type="vert">
   <member>H. Nahrstaedt - Aug 2010</member>
   <member>	F. Auger, May-August 1994, July 1995.</member>
   <member>	Copyright (c) 1996 by CNRS (France).</member>
   </simplelist>
</refsection>
</refentry>
