<?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) Rice University - CNRS (France)
-->


<refentry xml:id="scale" 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>scale</refname><refpurpose>Scale a signal using the Mellin transform.</refpurpose>
  </refnamediv>



  <refsynopsisdiv>
    <title>Calling Sequence</title>
    <synopsis>
      S=scale(X)
      S=scale(X,A)
      S=scale(X,A,FMIN,FMAX)
      S=scale(X,A,FMIN,FMAX,N)
      S=scale(X,A,FMIN,FMAX,N,TRACE)
    </synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Parameters</title>
    <variablelist>
      <varlistentry><term> X :</term> <listitem><para> signal in time
      to be scaled (Nx=length(X)).</para></listitem></varlistentry>
      <varlistentry><term>	A :</term>
      <listitem><para> scale factor. A &lt; 1 corresponds to a compression in the time  domain. A can be a vector.(default : 2)</para></listitem></varlistentry>
      <varlistentry><term> FMIN,FMAX :</term> <listitem><para>
      respectively lower and upper frequency bounds of the analyzed
      signal. These parameters fix the equivalent frequency bandwidth
      (expressed in Hz). When unspecified, you have to enter them at
      the command line from the plot of the spectrum. FMIN and FMAX
      must be &gt;0 and &lt;=0.5.</para></listitem></varlistentry>
      <varlistentry><term> N :</term> <listitem><para> number of
      analyzed voices (default : automatically
      determined).</para></listitem></varlistentry>
      <varlistentry><term> TRACE :</term> <listitem><para> if nonzero,
      the progression of the algorithm is shown (default :
      0).</para></listitem></varlistentry>
      <varlistentry><term> S :</term> <listitem><para> the A-scaled
      version of signal X. Length of S can be larger than length of X
      if A &gt; 1. If A is a vector of length L, S is a matrix with L
      columns. S has the same energy as
      X.</para></listitem></varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Description</title>
    <para>
      scale computes the A-scaled version of signal X : A^(-1/2) X(T/A) using its Mellin transform.
    </para>
  </refsection>

  <refsection>
    <title>Examples</title>
    <programlisting role="example"><![CDATA[
    N=128;a=2;
    sig=klauder(N); S=scale(sig,a,.05,.45,128);
    clf;
    subplot(211); 
    plot(sig);gca().tight_limits="on"; 
    title("The signal")
    subplot(212); 
    plot(real(S))
    //focus on the scaled signal's middle
    ax=gca();
    ax.data_bounds(1,1)=1+N/a;
    ax.data_bounds(2,1)=a*N-N/a;
    ax.tight_limits="on";
    title("A focus on the middle of the scaled signal")
    ]]></programlisting>
  <scilab:image><![CDATA[
    N=128;a=2;
    sig=klauder(N); S=scale(sig,a,.05,.45,128);
    clf;
    subplot(211); 
    plot(sig);gca().tight_limits="on"; 
    title("The signal")
    subplot(212); 
    plot(real(S))
    //focus on the scaled signal's middle
    ax=gca();
    ax.data_bounds(1,1)=1+N/a;
    ax.data_bounds(2,1)=a*N-N/a;
    ax.tight_limits="on";
     title("A focus on the middle of the scaled signal")
    ]]></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>
    </simplelist>
  </refsection>
</refentry>
