<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) R.F. Boisvert, C. De Boor (código da biblioteca FORTRAN CMLIB)
 * Copyright (C) B. Pincon (interface Scilab)
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
          xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
          xml:id="lsq_splin" xml:lang="pt">
    <refnamediv>
        <refname>lsq_splin</refname>
        <refpurpose>ajuste ponderado por spline cúbico de mínimos
            quadrados
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Seqüência de Chamamento</title>
        <synopsis>
            [y, d] = lsq_splin(xd, yd, x)
            [y, d] = lsq_splin(xd, yd, wd, x)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Parâmetros</title>
        <variablelist>
            <varlistentry>
                <term>xd, yd</term>
                <listitem>
                    <para>vetores de mesmo tamanho, dados a serem ajustados por um
                        spline cúbico
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>wd</term>
                <listitem>
                    <para>
                        (opcional) um vetor de mesmo formato que <literal>xd</literal>
                        e <literal>yd</literal>, pesos dos ajustes de mínimos quadrados.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>x</term>
                <listitem>
                    <para>vetor (linha ou coluna) estritamente crescente, pontos de
                        interrupção do spline cúbico
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y, d</term>
                <listitem>
                    <para>
                        vetores de mesmo formato que <literal>x</literal>, a
                        tripla(x,y,d) define o spline cúbico aproximado.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Descrição</title>
        <para>Esta função computa um spline cúbico aproximado
            <emphasis>s</emphasis> para os dados <literal>xd, yd, wd</literal> (a
            partir daqui <emphasis>m</emphasis> é suposto como o comprimento desses
            vetores) e, de uma escolha dos pontos de interrupção do spline, o vetor
            <literal>x</literal> (por exemplo, se você deseja n pontos de interrupção
            uniformemente escolhidos você pode usar
            <literal>x=linspace(min(xd),max(xd),n))</literal>). Se
            <emphasis>S</emphasis> é o espaço de todas as funções spline cúbicas com
            pontos de interrupção <emphasis>x1 &lt; x2 &lt; ... &lt; xn</emphasis>
            então, o spline resultante s é tal que:
        </para>
        <para>
            <latex style="display" fontsize="18" alt="∑_k=1→m wd(k).[s(xd(k))-yd(k)]² ⬅ ∑_k=1→m wd(k).[f(xd(k))-yd(k)]²">
                \sum_{k=1}^m wd(k)\left(s(xd(k))-yd(k)\right)^2 \,\leftarrow\,
                \sum_{k=1}^m wd(k)\left(f(xd(k))-yd(k)\right)^2
            </latex>
        </para>
        <para>
            para todo <emphasis>f em S</emphasis>, i.e., realiza o mínimo da
            soma de todos os erros quadrados sobre todas as funções de
            <emphasis>S</emphasis>.
        </para>
        <para>
            O spline <emphasis>s</emphasis> é completamente definido pela tripla
            <literal>(x,y,d)</literal> (<literal>y</literal> e <literal>d</literal>
            são os vetores das ordenadas dos splines e das derivadas primeiras nos xi
            's : <emphasis>yi=s(xi)</emphasis> e <emphasis>di=s'(xi)</emphasis>) e sua
            avaliação em alguns pontos deve ser feita pela função <link linkend="interp">interp</link>.
        </para>
    </refsection>
    <refsection>
        <title>Observações </title>
        <para>
            Quando <literal>wd</literal> não é dado, todos os pontos têm o mesmo
            peso 1
        </para>
        <para>
            Um ponto <emphasis>(xd(k),yd(k))</emphasis> é considerado no ajuste
            se <emphasis>xd(k) em [x1,xn] e wd(k) &gt; 0</emphasis>. Em particular,
            você pode colocar um peso nulo (ou mesmo negativo) a todos os pontos que
            você deseja que sejam ignorados no ajuste. Quando o número total de pontos
            levados em conta no "procedure" de ajuste é (estritamente) menor que 4,
            ocorre um erro.
        </para>
        <para>
            O vetor <literal>xd</literal> não necessita estar em ordem
            crescente
        </para>
        <para>
            Dependendo do número e das posições dos <emphasis>xd(k)</emphasis>
            's e da escolha dos <emphasis>x(i)</emphasis> 's podem haver várias
            soluções, mas apenas uma é selecionada. Quando isso ocorre, um aviso é
            exibido na janela de comando do Scilab. Esta função foi feita para ser
            usada quando <emphasis>m</emphasis> é muito maior que
            <emphasis>n</emphasis> e neste caso, tal tipo de problema não ocorre.
        </para>
    </refsection>
    <refsection>
        <title>Exemplos</title>
        <programlisting role="example"><![CDATA[
// este é um exemplo artificial, onde os dados xd e yd
// são contruídos a partir de uma função seno perturbada
a = 0; b = 2*%pi;
sigma = 0.1;  // desvio padrão do ruído gaussiano
m = 200;       // número de pontos experimentais
xd = linspace(a,b,m)';
yd = sin(xd) + grand(xd,"nor",0,sigma);

n = 6; // número de pontos de interrupção
x = linspace(a,b,n)';

// computando o spline
[y, d] = lsq_splin(xd, yd, x);  // usando pesos iguais

// plotando
ye = sin(xd);
ys = interp(xd, x, y, d);
clf()
plot2d(xd,[ye yd ys],style=[2 -2 3], ...
       leg="função exata@medidas experimentais (perturbação gaussiana)@spline ajustado")
xtitle("Um spline de mínimos quadrados")
show_window()
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>Ver Também</title>
        <simplelist type="inline">
            <member>
                <link linkend="backslash">backslash</link>
            </member>
            <member>
                <link linkend="datafit">datafit</link>
            </member>
            <member>
                <link linkend="interp">interp</link>
            </member>
            <member>
                <link linkend="splin">splin</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
