<?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="tfrparam" 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>tfrparam</refname>
	<refpurpose>parametric time-frequency representation</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>Calling Sequence</title>
    <synopsis>
      [tfr,t,f] = tfrparam(x)
      [tfr,t,f] = tfrparam(x, t)
      [tfr,t,f] = tfrparam(x, t, N)
      [tfr,t,f] = tfrparam(x, t, N, p)
      [tfr,t,f] = tfrparam(x, t, N, p, L)
      [tfr,t,f] = tfrparam(x, t, N, p, L, ptrace)
      [tfr,t,f] = tfrparam(x, t, N, p, L, ptrace, Rxtype)
      [tfr,t,f] = tfrparam(x, t, N, p, L, ptrace, Rxtype, method)
      [tfr,t,f] = tfrparam(x, t, N, p, L, ptrace, Rxtype, method, q)
      [tfr,t,f] = tfrparam(...,"plot")
    </synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Parameters</title>
    <variablelist>
      <varlistentry>
        <term>X      :</term>
        <listitem>
          <para>a vector of complex numbers of size Nx: the signal</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>T      :</term>
        <listitem>
          <para>a vector with integer values in [1 Nx]: time instant(s) (default : 1:Nx).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>N:</term>
        <listitem>
          <para>a positive integer: the number of frequency bins (default : max(256,Nx) ).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>p      :</term>
        <listitem>
          <para>a positive integer: the last autocorrelation lag (default : 2 ).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>L:</term>
        <listitem>
          <para>an odd positive integer: the length of the window around
          the analyzed time sample (default : max(51,round(Nx/10))).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Rxtype :</term>
        <listitem>
          <para>character string with possible values 'hermitian',
          'fbhermitian', 'burg' or 'fbburg': the choice of the
          correlation matrix algorithm (default :
          'fbhermitian')</para>
          <para>Case does not matter.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>method :</term>
        <listitem>
          <para>a character string:  can be either 'ar', 'periodogram', 'capon',
          'capnorm', 'lagunas', or 'genlag'.</para>
          <para>Case does not matter.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>q      :</term>
        <listitem>
          <para> parameter for the generalized Lagunas method.</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>
    </variablelist>
  </refsection>

  <refsection>
    <title>Examples</title>
    <programlisting role="example"><![CDATA[
    x = fmconst(256,0.1) + fmlin(256,0.15,0.30) + fmlin(256,0.2,0.45);
    clf; gcf().color_map = jetcolormap(128);
    subplot(221)
    [tfr,t,f] = tfrparam(x,1:256,256,3,21,%f,'fbhermitian','ar');
    grayplot(t,f,tfr'); title("AR")
    subplot(222)
    [tfr,t,f] = tfrparam(x,1:256,256,3,21,%f,'fbhermitian','periodogram');
    grayplot(t,f,tfr'); title("Periodogram")
    subplot(223)
    [tfr,t,f] = tfrparam(x,1:256,256,3,21,%f,'fbhermitian','capon');
    grayplot(t,f,tfr'); title("Capon")
    subplot(224)
    [tfr,t,f] = tfrparam(x,1:256,256,3,21,%f,'fbhermitian','lagunas');
    grayplot(t,f,tfr'); title("Lagunas")
    ]]></programlisting>
 <scilab:image><![CDATA[
    x=fmconst(256,0.1)+fmlin(256,0.15,0.30)+fmlin(256,0.2,0.45);
    clf;gcf().color_map= jetcolormap(128);
    subplot(221)
    [tfr,t,f]=tfrparam(x,1:256,256,3,21,%f,'fbhermitian','ar');
    grayplot(t,f,tfr');title("AR")
    subplot(222)
    [tfr,t,f]=tfrparam(x,1:256,256,3,21,%f,'fbhermitian','periodogram');
    grayplot(t,f,tfr');title("Periodogram")
    subplot(223)
    [tfr,t,f]=tfrparam(x,1:256,256,3,21,%f,'fbhermitian','capon');
    grayplot(t,f,tfr');title("Capon")
    subplot(224)
    [tfr,t,f]=tfrparam(x,1:256,256,3,21,%f,'fbhermitian','lagunas');
    grayplot(t,f,tfr');title("Lagunas")
  ]]></scilab:image>
  </refsection>

  <refsection>
    <title>Authors</title>
    <simplelist type="vert">
      <member>H. Nahrstaedt - Aug 2010</member>
      <member>F. Auger, july, november 1998, april 99.</member>
    </simplelist>
  </refsection>
</refentry>
