<?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="tfrunter" 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>tfrunter</refname><refpurpose>Unterberger time-frequency distribution.</refpurpose>
  </refnamediv>



  <refsynopsisdiv>
    <title>Calling Sequence</title>
    <synopsis>
      [TFR,T,F]=tfrunter(X,)
      [TFR,T,F]=tfrunter(X,T)
      [TFR,T,F]=tfrunter(X,T,FORM)
      [TFR,T,F]=tfrunter(X,T,FORM,FMIN,FMAX)
      [TFR,T,F]=tfrunter(X,T,FORM,FMIN,FMAX,N)
      [TFR,T,F]=tfrunter(X,T,FORM,FMIN,FMAX,N,TRACE)
      [TFR,T,F]=tfrunter(...,'plot')
    </synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Parameters</title>
    <variablelist>
      <varlistentry>
        <term>X :</term>
        <listitem>
          <para>a real or complex Nx elements real 
          (auto-Untenberger) or a Nx by 2 array signal
          (cross-Untenberger).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term> T:</term> 
        <listitem>
          <para> a real Nt vector with elements in [1 Nx] : time
          instant(s) on which the TFR is evaluated (default:
          1:NX).</para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term> FORM :</term> 
        <listitem>
          <para>a character with possible values 'A' for active, 'P' for passive Unterberger
          distribution.(default : 'A'). Cas do not matter.</para>
        </listitem>
      </varlistentry>
     <varlistentry>
        <term> FMIN:</term> 
        <listitem>
          <para>
            a positive scalar in ]0 0.5], the normalized lower
            frequency bound in (Hz) of the analyzed signal. When
            unspecified, you have to enter it at the command line from
          the plot of the spectrum. </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term> FMAX :</term> 
        <listitem>
          <para> a positive scalar in ]0 0.5], the normalized upper
          frequency bound (in Hz) of the analyzed signal.  When
          unspecified, you have to enter it at the command line from
          the plot of the spectrum.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>N :</term> 
        <listitem>
          <para>a positive integer: number of analyzed voices.  When
          unspecified, you have to enter it at the command line.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term> TRACE :</term> 
        <listitem>
          <para>A boolean (or a real scalar) if true (or nonzero),the
          progression of the algorithm is shown (default : %f).</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>Description</title>
    <para>
      tfrunter generates the auto- or cross-Unterberger distribution
      (active or passive form).
    </para>
  </refsection>

  <refsection>
    <title>Examples</title>
    <para> Interactive use </para>
    <programlisting role="example"><![CDATA[
    N=128;
    sig=altes(N,0.1,0.45); 
    tfrunter(sig);
    ]]></programlisting>

    <para>Non-interactive use</para>
    <programlisting role="example"><![CDATA[
    N=128;
    sig=altes(N,0.1,0.45); 
    [tfr,t,f]=tfrunter(sig,1:N,"A",0.1,0.35,56);
    gcf().color_map= jetcolormap(128);
    grayplot(t,f,tfr');
    ]]></programlisting>
    <scilab:image><![CDATA[
    N=128;
    sig=altes(N,0.1,0.45); 
    [tfr,t,f]=tfrunter(sig,1:N,"A",0.1,0.35,56);
    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>	P. Goncalves, November 95 - O. Lemoine, June 1996.</member>
      <member>	Copyright (c) 1995 Rice University - CNRS (France) 1996.</member>
    </simplelist>
  </refsection>
</refentry>
