verbose.m

Go to the documentation of this file.

%>  \brief
%>  Return a MATLAB double, cell, or table matrix whose rows or
%>  columns are unrolled according to a prespecified ``weight``.
%>
%>  \param[in]  cmat    :   The input compact MATLAB double, cell, or table
%>                          matrix that is to be unrolled along an axis.
%>  \param[in]  dim     :   The input scalar MATLAB integer
%>                          that can be either ``1`` or ``2``
%>                          representing the axis along with the
%>                          array must be unrolled.<br>
%>                          An input value of ``1`` implies unrolling
%>                          along the rows of the input ``cmat``,
%>                          that is, unrolling the ``cmat`` columns.
%>  \param[in]  weight  :   The input MATLAB matrix of integer values
%>                          of size ``size(cmat, dim)`` containing the set
%>                          of weights to used for unrolling the input ``cmat``.
%>  \param[in]  checked :   The input scalar Python Boolean value.<br>
%>                          If ``true``, the condition ``~all(rem(weight, 1) == 0) || any(weight < 0)`` will be asserted.<br>
%>                          This can be useful for debugging, but can slow down the runtime performance.<br>
%>                          (**optional**, default = ``false``)
%>
%>  \return
%>  ``vmat``            :   The output MATLAB matrix of the same type and kind
%>                          as the input ``cmat``, containing the ``cmat`` that
%>                          is unrolled along the specified axis ``dim`` using
%>                          the input weights.<br>
%>
%>  \interface{verbose}
%>  \code{.m}
%>
%>      vmat = pm.array.verbose(cmat, dim, weight)
%>      vmat = pm.array.verbose(cmat, dim, weight, checked)
%>
%>  \endcode
%>
%>  \warning
%>  Negative weights lead to a runtime error.<br>
%>  Any entry corresponding to a zero weight is ignored in the output ``vmat``.<br>
%>
%>  \example{verbose}
%>  \include{lineno} example/array/verbose/main.m
%>  \output{verbose}
%>  \include{lineno} example/array/verbose/main.out.m
%>
%>  \final{verbose}
%>
%>  \author
%>  \JoshuaOsborne, May 21 2024, 4:24 PM, University of Texas at Arlington<br>
%>  \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
%>  \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
function vmat = verbose(cmat, dim, weight, checked)
    if  nargin < 4
        checked = false;
    end
    if  nargin < 3
        help("pm.array.verbose");
        error   ( newline ...
                + "At least three input arguments are required" + newline ...
                + "as described in the documentation above." + newline ...
                + newline ...
                );
    end
    if  checked
        if ~all(rem(weight, 1) == 0) || any(weight < 0)
            help("pm.array.verbose");
            disp("weight");
            disp( weight );
            error   ( newline ...
                    + "The input ``weight`` argument displayed above" + newline ...
                    + "must be all non-negative whole-numbers." + newline ...
                    + newline ...
                    );
        end
        if ~any(dim == [1, 2])
            help("pm.array.verbose");
            disp("dim");
            disp( dim );
            error   ( newline ...
                    + "The input ``dim`` argument displayed above" + newline ...
                    + "must be either 1 or 2." + newline ...
                    + newline ...
                    );
        end
        if  length(weight) ~= size(cmat, dim)
            help("pm.array.verbose");
            error   ( newline ...
                    + "The condition ``length(weight) == size(cmat, dim)``" + newline ...
                    + "must hold for the corresponding input arguments." + newline ...
                    + newline ...
                    + pm.io.tab() + "length(weight) = " + string(length(weight)) + newline ...
                    + pm.io.tab() + "size(cmat,dim) = " + string(size(cmat,dim)) + newline ...
                    + newline ...
                    );
        end
    end
    cumsumwei = cumsum(weight);
    sumwei = cumsumwei(end);
    nrow = size(cmat, 1);
    ncol = size(cmat, 2);
    if dim == 1
        if isa(cmat, "cell")
            vmat = cell(sumwei, ncol);
        elseif isa(cmat, "double")
            vmat = zeros(sumwei, ncol);
        else
            vmat = cmat;
        end
        istart = 1;
        for ientry = 1 : nrow
            iend = cumsumwei(ientry);
            for iwei = istart : iend
                vmat(iwei, :) = cmat(ientry, :);
            end
            istart = iend + 1;
        end
    else
        if isa(cmat, "cell")
            vmat = cell(nrow, sumwei);
        elseif isa(cmat, "double")
            vmat = zeros(nrow, sumwei);
        else
            vmat = cmat;
        end
        istart = 1;
        for ientry = 1 : ncol
            iend = cumsumwei(ientry);
            for iwei = istart : iend
                vmat(:, iwei) = cmat(:, ientry);
            end
            istart = iend + 1;
        end
    end
end