<?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) CNRS - France 1999.
-->

<refentry xml:id="instfreq" 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>instfreq</refname><refpurpose>Instantaneous frequency estimation.</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>Calling Sequence</title>
    <synopsis>
      [FNORMHAT,T]=instfreq(X)
      [FNORMHAT,T]=instfreq(X,T)
      [FNORMHAT,T]=instfreq(X,T,L)
      [FNORMHAT,T]=instfreq(X,T,L,TRACE)
    </synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Parameters</title>
    <variablelist>
      <varlistentry>
        <term>X :</term>
        <listitem>
          <para>a complex vector of size N: the analytic signal to be analyzed.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>T :</term>
        <listitem>
          <para>a vector with integer elements in [L, N-L]: the Time
          instants (default : 2:length(X)-1).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>L :</term>
        <listitem>
          <para>An integer >=1:</para>
          <para> If L=1 (the default value) computes the (normalized) instantaneous
          frequency of the signal X defined as angle(X(T+1)*conj(X(T-1)) ;</para>

          <para>if L&gt;1, computes a Maximum Likelihood estimation of
          the instantaneous frequency of the deterministic part of the
          signal blurried in a white gaussian noise.</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>FNORMHAT :</term>
        <listitem>
          <para>a column vector with same size as T: the  (normalized) instantaneous frequency.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>T :</term>
        <listitem>
          <para>a row vector: the  time instants.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Description</title>
    <para>
      instfreq computes the instantaneous frequency of the analytic
      signal X at time instant(s) T, using the trapezoidal integration
      rule.  The result FNORMHAT lies between 0.0 and 0.5.
    </para>
  </refsection>

  <refsection>
    <title>Examples</title>
    <programlisting role="example"><![CDATA[
    [x,iflaw]=fmsin(70,0.05,0.35,25); 
    [instf,t]=instfreq(x); 
    clf;plot(t',instf,t',iflaw(2:$-1))
    xlabel(_("Time"));ylabel(_("Frequency"))
    legend(_("Theoritical"),_("Estimated"))
    ]]></programlisting>
     <scilab:image><![CDATA[
    [x,iflaw]=fmsin(70,0.05,0.35,25); 
    [instf,t]=instfreq(x); 
    clf;plot(t',instf,t',iflaw(2:$-1))
    xlabel(_("Time"));ylabel(_("Frequency"))
    legend(_("Theoritical"),_("Estimated"))
    ]]></scilab:image>
  </refsection>

  <refsection>
    <title>See also</title>
    <simplelist type="inline">
      <member><link linkend="kaytth">kaytth</link></member>
      <member><link linkend="sgrpdlay">sgrpdlay</link></member>
    </simplelist>
  </refsection>

  <refsection>
    <title>Authors</title>
    <simplelist type="vert">
      <member>H. Nahrstaedt - Aug 2010</member>
      <member>F. Auger, March 1994, July 1995.</member>
    </simplelist>
  </refsection>
</refentry>
