<?xml version="1.0" encoding="UTF-8"?>
<!--
This file is part of theScilab 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="tfrscalo" 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>tfrscalo</refname><refpurpose>Scalogram, for Morlet or Mexican hat wavelet.</refpurpose>
  </refnamediv>



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

  <refsection>
    <title>Description</title>
    <para>
      tfrscalo computes the scalogram (squared magnitude of a continuous
      wavelet transform).
    </para>
  </refsection>

  <refsection>
    <title>Parameters</title>
    <variablelist>
      <varlistentry>
        <term> X :</term> 
        <listitem>
          <para> signal (in time)
          to be analyzed (Nx=length(X)). Its analytic version is used
          (z=hilbert(real(X))).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term> T :</term> 
        <listitem>
          <para> a real Nt vector with elements in [1 Nx] : time
          instant(s) on wich the tfr is computed. (default:
          1:NX).</para>
         
        </listitem>
      </varlistentry>
      <varlistentry>
        <term> WAVE :</term> 
        <listitem>
          <para> half length of
          the Morlet analyzing wavelet at coarsest scale. If WAVE = 0, the
          Mexican hat is used. WAVE can also be a vector containing the time
          samples of any bandpass function, at any scale.  (default :
          sqrt(Nx)).</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>positive integer: number of analyzed voices.  When
          unspecified, you have to enter it at the command line from
          the plot of the spectrum.</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> N by Nt real array: the time-frequency
          matrix containing the coefficients of the decomposition (abscissa
          correspond to uniformly sampled time, and ordinates correspond to a
          geometrically sampled frequency). First row of TFR corresponds to
          the lowest frequency.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term> F :</term> 
        <listitem>
          <para> vector of
          normalized frequencies (geometrically sampled from FMIN to
          FMAX).
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term> WT :</term> 
        <listitem>
          <para> N by Nt complex array
          containing the corresponding wavelet transform. The scalogram TFR
          is the square modulus of WT multiplied by a constant factor.</para>
        </listitem>
      </varlistentry>

    </variablelist>
  </refsection>


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

    <para>Non-interactive use</para>

    <programlisting role="example"><![CDATA[
    N=128;
    sig=altes(N,0.1,0.45); 
    T=1:N;
    wave=sqrt(N);
    fmin=0.1; fmax=0.35;
    [tfr,t,f,wt]=tfrscalo(sig,T,wave,fmin,fmax,128);
    clf;gcf().color_map= jetcolormap(128);
    grayplot(t,f,tfr');
    ]]></programlisting>
    <scilab:image><![CDATA[
    N=128;
    sig=altes(N,0.1,0.45); 
    T=1:N;
    wave=sqrt(N);
    fmin=0.1; fmax=0.35;
    [tfr,t,f,wt]=tfrscalo(sig,T,wave,fmin,fmax,128);
    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>	P. Goncalves, October 1995 - O. Lemoine, June 1996.</member>
      <member>	Copyright (c) 1995 Rice University - CNRS 1996.</member>
    </simplelist>
  </refsection>
</refentry>
