<?xml version='1.0' encoding='UTF-8' standalone='no'?>
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="_matrix__util_8cpp">
<title>/Users/bernard/b20/bsoft/src/util/matrix_util.cpp File Reference</title>
<indexterm><primary>/Users/bernard/b20/bsoft/src/util/matrix_util.cpp</primary></indexterm>
<para>

<para>Utility functions for matrices. </para>
 
</para>
<programlisting>#include &quot;matrix_util.h&quot;
#include &quot;Matrix.h&quot;
#include &quot;matrix_linear.h&quot;
#include &quot;math_util.h&quot;
#include &quot;utilities.h&quot;
</programlisting><simplesect>
    <title>Functions    </title>
        <itemizedlist>
            <listitem><para>int <link linkend="_matrix__util_8cpp_1a72dad3674d558a983deca8b742f6d719">matrix_normalize</link> (<link linkend="_class_matrix">Matrix</link> &amp;m)</para>

<para>Normalizes a matrix. </para>
</listitem>
            <listitem><para>double <link linkend="_matrix__util_8cpp_1a88f47aa3a1524bc7df387a8d811f94f9">matrix_find_cutoff_for_number</link> (<link linkend="_class_matrix">Matrix</link> m, int n)</para>

<para>Calculates a cutoff to ensure that the given number of elements fall below it. </para>
</listitem>
            <listitem><para>int <link linkend="_matrix__util_8cpp_1ab760d1b03236dc515d741650ac83e26c">matrix_log_1_R</link> (<link linkend="_class_matrix">Matrix</link> matrix)</para>

<para>Calculates the logarithmic derivative of an R-factor in a matrix. </para>
</listitem>
            <listitem><para>int * <link linkend="_matrix__util_8cpp_1a4fb5ae437952c1447fda018b94ac357a">matrix_find_linear_sequence</link> (<link linkend="_class_matrix">Matrix</link> matrix, int window)</para>

<para>Finds a linear sequence of elements based on a pairwise matrix. </para>
</listitem>
            <listitem><para>int <link linkend="_matrix__util_8cpp_1a625d867bbc505e46d7ece6d479d101b7">matrix_permute</link> (int i, int j, <link linkend="_class_matrix">Matrix</link> matrix, int *order, double *best_R, int *best_order)</para>

<para>Permutes the order of a pairwise matrix and calculate a distance criterion. </para>
</listitem>
            <listitem><para>double <link linkend="_matrix__util_8cpp_1aa7d7b9944998599401c54eaf3a83516e">matrix_calc_dist_fit</link> (<link linkend="_class_matrix">Matrix</link> matrix, int *order)</para>

<para>Calculates an R-factor for a specific order of elements in a pairwise matrix. </para>
</listitem>
            <listitem><para><link linkend="_class_bimage">Bimage</link> * <link linkend="_matrix__util_8cpp_1aaae000c4ba82e0d66acffd40ad0aef6d">img_from_matrix</link> (<link linkend="_class_matrix">Matrix</link> &amp;matrix, long scale)</para>

<para>Converts a matrix to an image. </para>
</listitem>
        </itemizedlist>
</simplesect>
<simplesect>
    <title>Variables    </title>
        <itemizedlist>
            <listitem><para>int <link linkend="_matrix__util_8cpp_1a0b2caeb4b6f130be43e5a2f0267dd453">verbose</link></para>
</listitem>
        </itemizedlist>
</simplesect>
<section>
<title>Detailed Description</title>

<para>Utility functions for matrices. </para>

<para><formalpara><title>Author: </title>

<para>Bernard Heymann </para>
</formalpara>
<formalpara><title>Date: </title>

<para>Created: 20010723 </para>

<para>Modified: 20150124 </para>
</formalpara>
</para>
</section>
<section>
<title>Function Documentation</title>
<anchor xml:id="_matrix__util_8cpp_1aaae000c4ba82e0d66acffd40ad0aef6d"/>    <section>
    <title>img_from_matrix()</title>
<indexterm><primary>img_from_matrix</primary><secondary>matrix_util.cpp</secondary></indexterm>
<indexterm><primary>matrix_util.cpp</primary><secondary>img_from_matrix</secondary></indexterm>
<para><computeroutput><link linkend="_class_bimage">Bimage</link>* img_from_matrix (<link linkend="_class_matrix">Matrix</link> &amp; matrix, long scale)</computeroutput></para><para>

<para>Converts a matrix to an image. </para>
</para>

<para>
                <formalpara>
                    <title>
Parameters                    </title>
                    <para>
                    <table frame="all">
                        <tgroup cols="2" align="left" colsep="1" rowsep="1">
                        <colspec colwidth="1*"/>
                        <colspec colwidth="4*"/>
                        <tbody>
                            <row>
                                <entry>matrix</entry>
                                <entry>
<para>matrix. </para>
</entry>
                            </row>
                            <row>
                                <entry>scale</entry>
                                <entry>
<para>integer scale for enlarging the image. </para>
</entry>
                            </row>
                        </tbody>
                        </tgroup>
                    </table>
                    </para>
                </formalpara>
                <formalpara><title>Returns: </title>

<para>Bimage* new image. </para>
</formalpara>
</para>
<para>
Definition at line 298 of file matrix_util.cpp.</para>
    </section><anchor xml:id="_matrix__util_8cpp_1aa7d7b9944998599401c54eaf3a83516e"/>    <section>
    <title>matrix_calc_dist_fit()</title>
<indexterm><primary>matrix_calc_dist_fit</primary><secondary>matrix_util.cpp</secondary></indexterm>
<indexterm><primary>matrix_util.cpp</primary><secondary>matrix_calc_dist_fit</secondary></indexterm>
<para><computeroutput>double matrix_calc_dist_fit (<link linkend="_class_matrix">Matrix</link> matrix, int * order)</computeroutput></para><para>

<para>Calculates an R-factor for a specific order of elements in a pairwise matrix. </para>
</para>

<para>
                <formalpara>
                    <title>
Parameters                    </title>
                    <para>
                    <table frame="all">
                        <tgroup cols="2" align="left" colsep="1" rowsep="1">
                        <colspec colwidth="1*"/>
                        <colspec colwidth="4*"/>
                        <tbody>
                            <row>
                                <entry>matrix</entry>
                                <entry>
<para>pairwise square matrix. </para>
</entry>
                            </row>
                            <row>
                                <entry>*order</entry>
                                <entry>
<para>n-value array holding the order. </para>
</entry>
                            </row>
                        </tbody>
                        </tgroup>
                    </table>
                    </para>
                </formalpara>
                <formalpara><title>Returns: </title>

<para>double the R-factor. <literallayout><computeroutput>A new matrix is composed with the lower triangle taken from the input
matrix in the given order, and the upper triangle calculated as the 
sum of the diagonal elements between the indices of the element. 
I.e, if i and j are the indices of an upper triangle element, then 
it is the sum of all the diagonal elements from i to j:
    up(i,j) = sum(mat(k,k+1)) for i&lt;=k&lt;j
The difference between the lower and upper triangles is then calculated
as:
              1      up(i,j) - upmin   lo(j,i) - lomin
    R = sum(----- * (--------------- - ---------------) )
            i - j     upmax - upmin     lomax - lomin
where upmin, upmax, lomin, and lomax are the extremes in each triangle.
</computeroutput></literallayout> </para>
</formalpara>
</para>
<para>
Definition at line 232 of file matrix_util.cpp.</para>
    </section><anchor xml:id="_matrix__util_8cpp_1a88f47aa3a1524bc7df387a8d811f94f9"/>    <section>
    <title>matrix_find_cutoff_for_number()</title>
<indexterm><primary>matrix_find_cutoff_for_number</primary><secondary>matrix_util.cpp</secondary></indexterm>
<indexterm><primary>matrix_util.cpp</primary><secondary>matrix_find_cutoff_for_number</secondary></indexterm>
<para><computeroutput>double matrix_find_cutoff_for_number (<link linkend="_class_matrix">Matrix</link> m, int n)</computeroutput></para><para>

<para>Calculates a cutoff to ensure that the given number of elements fall below it. </para>
</para>

<para>
                <formalpara>
                    <title>
Parameters                    </title>
                    <para>
                    <table frame="all">
                        <tgroup cols="2" align="left" colsep="1" rowsep="1">
                        <colspec colwidth="1*"/>
                        <colspec colwidth="4*"/>
                        <tbody>
                            <row>
                                <entry>m</entry>
                                <entry>
<para>pairwise square matrix. </para>
</entry>
                            </row>
                            <row>
                                <entry>n</entry>
                                <entry>
<para>number of elements below cutoff. </para>
</entry>
                            </row>
                        </tbody>
                        </tgroup>
                    </table>
                    </para>
                </formalpara>
                <formalpara><title>Returns: </title>

<para>double cutoff. <literallayout><computeroutput>Each column is scanned and the cutoff adjusted so that at least the
given number of elements will fall below it.
</computeroutput></literallayout> </para>
</formalpara>
</para>
<para>
Definition at line 78 of file matrix_util.cpp.</para>
    </section><anchor xml:id="_matrix__util_8cpp_1a4fb5ae437952c1447fda018b94ac357a"/>    <section>
    <title>matrix_find_linear_sequence()</title>
<indexterm><primary>matrix_find_linear_sequence</primary><secondary>matrix_util.cpp</secondary></indexterm>
<indexterm><primary>matrix_util.cpp</primary><secondary>matrix_find_linear_sequence</secondary></indexterm>
<para><computeroutput>int* matrix_find_linear_sequence (<link linkend="_class_matrix">Matrix</link> matrix, int window)</computeroutput></para><para>

<para>Finds a linear sequence of elements based on a pairwise matrix. </para>
</para>

<para>
                <formalpara>
                    <title>
Parameters                    </title>
                    <para>
                    <table frame="all">
                        <tgroup cols="2" align="left" colsep="1" rowsep="1">
                        <colspec colwidth="1*"/>
                        <colspec colwidth="4*"/>
                        <tbody>
                            <row>
                                <entry>matrix</entry>
                                <entry>
<para>pairwise square matrix. </para>
</entry>
                            </row>
                            <row>
                                <entry>window</entry>
                                <entry>
<para>range of elements to permute. </para>
</entry>
                            </row>
                        </tbody>
                        </tgroup>
                    </table>
                    </para>
                </formalpara>
                <formalpara><title>Returns: </title>

<para>int* the best order, NULL on error. </para>
</formalpara>
</para>
<para>
Definition at line 129 of file matrix_util.cpp.</para>
    </section><anchor xml:id="_matrix__util_8cpp_1ab760d1b03236dc515d741650ac83e26c"/>    <section>
    <title>matrix_log_1_R()</title>
<indexterm><primary>matrix_log_1_R</primary><secondary>matrix_util.cpp</secondary></indexterm>
<indexterm><primary>matrix_util.cpp</primary><secondary>matrix_log_1_R</secondary></indexterm>
<para><computeroutput>int matrix_log_1_R (<link linkend="_class_matrix">Matrix</link> matrix)</computeroutput></para><para>

<para>Calculates the logarithmic derivative of an R-factor in a matrix. </para>
</para>

<para>
                <formalpara>
                    <title>
Parameters                    </title>
                    <para>
                    <table frame="all">
                        <tgroup cols="2" align="left" colsep="1" rowsep="1">
                        <colspec colwidth="1*"/>
                        <colspec colwidth="4*"/>
                        <tbody>
                            <row>
                                <entry>matrix</entry>
                                <entry>
<para>pairwise square matrix. </para>
</entry>
                            </row>
                        </tbody>
                        </tgroup>
                    </table>
                    </para>
                </formalpara>
                <formalpara><title>Returns: </title>

<para>int 0. </para>
</formalpara>
</para>
<para>
Definition at line 107 of file matrix_util.cpp.</para>
    </section><anchor xml:id="_matrix__util_8cpp_1a72dad3674d558a983deca8b742f6d719"/>    <section>
    <title>matrix_normalize()</title>
<indexterm><primary>matrix_normalize</primary><secondary>matrix_util.cpp</secondary></indexterm>
<indexterm><primary>matrix_util.cpp</primary><secondary>matrix_normalize</secondary></indexterm>
<para><computeroutput>int matrix_normalize (<link linkend="_class_matrix">Matrix</link> &amp; m)</computeroutput></para><para>

<para>Normalizes a matrix. </para>
</para>

<para>
                <formalpara>
                    <title>
Parameters                    </title>
                    <para>
                    <table frame="all">
                        <tgroup cols="2" align="left" colsep="1" rowsep="1">
                        <colspec colwidth="1*"/>
                        <colspec colwidth="4*"/>
                        <tbody>
                            <row>
                                <entry>&amp;m</entry>
                                <entry>
<para>matrix. </para>
</entry>
                            </row>
                        </tbody>
                        </tgroup>
                    </table>
                    </para>
                </formalpara>
                <formalpara><title>Returns: </title>

<para>int 0. <literallayout><computeroutput>The rows and columns are alternatively iteratively normalized until
the error is small enough.
</computeroutput></literallayout> </para>
</formalpara>
</para>
<para>
Definition at line 27 of file matrix_util.cpp.</para>
    </section><anchor xml:id="_matrix__util_8cpp_1a625d867bbc505e46d7ece6d479d101b7"/>    <section>
    <title>matrix_permute()</title>
<indexterm><primary>matrix_permute</primary><secondary>matrix_util.cpp</secondary></indexterm>
<indexterm><primary>matrix_util.cpp</primary><secondary>matrix_permute</secondary></indexterm>
<para><computeroutput>int matrix_permute (int i, int j, <link linkend="_class_matrix">Matrix</link> matrix, int * order, double * best_R, int * best_order)</computeroutput></para><para>

<para>Permutes the order of a pairwise matrix and calculate a distance criterion. </para>
</para>

<para>
                <formalpara>
                    <title>
Parameters                    </title>
                    <para>
                    <table frame="all">
                        <tgroup cols="2" align="left" colsep="1" rowsep="1">
                        <colspec colwidth="1*"/>
                        <colspec colwidth="4*"/>
                        <tbody>
                            <row>
                                <entry>i</entry>
                                <entry>
<para>start of window within the order array. </para>
</entry>
                            </row>
                            <row>
                                <entry>j</entry>
                                <entry>
<para>end of window within the order array. </para>
</entry>
                            </row>
                            <row>
                                <entry>matrix</entry>
                                <entry>
<para>pairwise square matrix. </para>
</entry>
                            </row>
                            <row>
                                <entry>*order</entry>
                                <entry>
<para>n-value array holding the current order. </para>
</entry>
                            </row>
                            <row>
                                <entry>*best_R</entry>
                                <entry>
<para>R-factor for the best order. </para>
</entry>
                            </row>
                            <row>
                                <entry>*best_order</entry>
                                <entry>
<para>n-value array holding the best order. </para>
</entry>
                            </row>
                        </tbody>
                        </tgroup>
                    </table>
                    </para>
                </formalpara>
                <formalpara><title>Returns: </title>

<para>int 0. <literallayout><computeroutput>A recursive function to pass through all possible permutations
within a given window.
</computeroutput></literallayout> </para>
</formalpara>
</para>
<para>
Definition at line 182 of file matrix_util.cpp.</para>
</section>
</section>
<section>
<title>Variable Documentation</title>
<anchor xml:id="_matrix__util_8cpp_1a0b2caeb4b6f130be43e5a2f0267dd453"/>    <section>
    <title>verbose</title>
<indexterm><primary>verbose</primary><secondary>matrix_util.cpp</secondary></indexterm>
<indexterm><primary>matrix_util.cpp</primary><secondary>verbose</secondary></indexterm>
<para><computeroutput>int verbose</computeroutput></para></section>
</section>
</section>
