<?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  terms of the GNU General Public License 
as published by the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

Copyright (c) 1996 by CNRS (France)
-->

<refentry xml:id="tfrideal" 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>tfrideal</refname><refpurpose>Ideal TFR for given instantaneous frequency laws.</refpurpose>
  </refnamediv>



  <refsynopsisdiv>
    <title>Calling Sequence</title>
    <synopsis>
      [TFR,T,F]=tfrideal(IFLAWS)
      [TFR,T,F]=tfrideal(IFLAWS,T,)
      [TFR,T,F]=tfrideal(IFLAWS,T,N)
      [TFR,T,F]=tfrideal(IFLAWS,T,N,TRACE)
      [TFR,T,F]=tfrideal(...,'plot')
    </synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Parameters</title>
    <variablelist>
      <varlistentry>
        <term>	IFLAWS :</term>
        <listitem>
          <para> (M,P)-matrix where each column corresponds to the
          instantaneous frequency law of an (M,1)-signal, These P
          signals do not need to be present at the same time (missing
          values are represented by NaN's. The values of IFLAWS must
          be between 0 and 0.5.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	T      :</term>
        <listitem>
          <para>a vector of integer: the time instant(s) (default : 1:M).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	N      :</term>
        <listitem>
          <para>a positive integer: the number of frequency bins (default : M).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	TRACE  :</term>
        <listitem>
          <para> if non zero or %t, the progression of the algorithm is shown   (default : %f).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>'plot':</term>
        <listitem>
          <para>if one input parameter is 'plot',  tfrideal runs <link linkend="tfrqview">tfrqview</link>. and TFR will be plotted</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	TFR    :</term>
        <listitem>
          <para>a real N by length(T) matrix with values in {0 1 %nan}: the output time-frequency matrix.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	F      :</term>
        <listitem>
          <para>a real vector: the normalized frequencies.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Description</title>
    <para>
      tfrideal generates the ideal time-frequency representation corresponding to the
      instantaneous frequency laws of the components of a signal.
    </para>
  </refsection>

  <refsection>
    <title>Examples</title>
    <programlisting role="example"><![CDATA[
    N=140; 
    [x1,if1]=fmlin(N,0.05,0.3);
    [x2,if2]=fmsin(70,0.35,0.45,60);
    if2=[zeros(35,1)*%nan;if2;zeros(35,1)*%nan];
    [tfr,t,f]=tfrideal([if1 if2],1:N-1);
    clf;
    contour(t,f,tfr',1);
    xlabel(_('Time')); ylabel(_('Normalized frequency'));
    title(_('Ideal time-frequency representation'));
    ]]></programlisting>
  <scilab:image><![CDATA[
    N=140; 
    [x1,if1]=fmlin(N,0.05,0.3);
    [x2,if2]=fmsin(70,0.35,0.45,60);
    if2=[zeros(35,1)*%nan;if2;zeros(35,1)*%nan];
    [tfr,t,f]=tfrideal([if1 if2],1:N-1);
    clf;
    contour(t,f,tfr',1);
    xlabel(_('Time')); ylabel(_('Normalized frequency'));
    title(_('Ideal time-frequency representation'));
  ]]></scilab:image>
  </refsection>

  <refsection>
    <title>Authors</title>
    <simplelist type="vert">
      <member>H. Nahrstaedt - Aug 2010</member>
      <member>	O. Lemoine, F. Auger - March, April 1996.</member>
    </simplelist>
  </refsection>
</refentry>
