\documentclass[a4paper,10pt]{report}


\title{mp software documentation}
\author{Dobies\l{}aw Ircha, Marek Barwi{\'n}ski}


\begin{document}
\maketitle

\section{Signal section construction}

For a signal of size N read from file a memory of size 3{}N is allocated. The central part [N,2N-1] is the signal and the left and right parts are padded with zeroes. In consecutive iterations the values on left and right third part of the signal may change in the case when the Gabor subtracted from the signal has non-zero values outside of the [N,2N-1] range. Three sections that combined form the 3N long section will be referred to as section I, II and III.

\section{Loading the signal and finding the Gabors}

The Gabors are fitted so that the center of the Gabor is only between points N and 2N-1.

\section{Options and switches}


\subsection{mp}

\begin{description}
\item [mp] \textbf{filename} runs the mp algorithm on a signal with default settings.
\end{description}

\subsection{set}

\begin{description}
\item [set]\textbf{-e} \textbf{{[}precision{]}} the program deconstructs the signal until a certain percentage of the original signal energy is explained
\item [set]\textbf{-i} \textbf{{[}length of decomposition{]}} amount of iterations that the program will perform
\end{description}

\subparagraph{default settings}

precision:0.95 

number of iterations:64 


\subsection{reinit}

\begin{description}
\item [reinit]\textbf{-O} \textbf{{[}signal size{]}} signal size. Necessary for proper dictionary construction.
\item [reinit]\textbf{-R} \textbf{{[}dictionary size{]}} 
\item [reinit]\textbf{-t {[}dictionary type{]}} choice of the dictionary type:
fullstoch - dictionary in which all neighbor Gabor atoms have the same scalar product, \emph{stoch} comes from adding slight noise to parameters to remove possible decomposition artifacts (see publications on stochastic dictionaries)\\
box - emulating the original dyadic recipe of Mallat where the density of the dictionary is defined by user either by the ultimate dictionary size or by the choice of multiplicative factor \\
random - all three Gabor parameters are drawn from a uniform distribution
\item [reinit]\textbf{-D{[}dictionary adaptation{]}} removes percentage of the dictionary atoms from consideration after the first iteration. The atoms with the lowest scalar product are removed.
\item [reinit]\textbf{-B {[}dictionary base{]}} for fullstoch and box this is the choice which determines the dictionary size for a given signal length.
\end{description}
Fullstoch dictionary size based on signal size N and base a:
\begin{equation}
 \frac{N\cdot\pi}{2 \ln{a}\ln{\frac{1}{2}\left(a+a^{-1}\right)}}
\end{equation}
Box dictionary size based on signal size N and base a:
\begin{equation}
N\cdot\frac{\ln{\left( N\right)}}{\ln{a}}
\end{equation}

\paragraph{Example}

We have a 1024 point signal and want a 300k large fullstoch dictionary:\\
\textbf{\emph{reinit -O 1024 -R 300000 -t fullstoch }}\\
fullstoch is a default choice

\subsection{loadsig}

loadsig - an option necessary to load the signal.

\begin{description}
\item [loadsig]\textbf{-O} \textbf{{[}filename{]}}
\item [loadsig]\textbf{-c} \textbf{{[}channel number{]}} load the channel from the signal. Start with 1. The reading standard is: 1st epoch, all channels, 2nd epoch all channels. So picking 3rd channel out of K channels and signal length N and offset M means that what will be extracted from the file are data points between start: MNK+2N and end:  MNK+3N
\item [loadsig]\textbf{-h} \textbf{{]}number of channels{]}}s
\item [loadsig]\textbf{-\#} \textbf{{]}offset{]}} starts with 0. Will start reading the signal from this point (see also {[}channel number{]}
\item [loadsig]\textbf{-t} \textbf{ascii|float|short} file data type
\item [loadsig]\textbf{-F} \textbf{sampling frequency [Hz]}
\item [loadsig]\textbf{-C} \textbf{conv} converts the point value to Volts.
\item [loadsig]\textbf{-e} \textbf{ref1} first reference electrode
\item [loadsig]\textbf{-f} \textbf{ref2} second reference electrode - if two defined an average is taken.
\item [loadsig]\textbf{-s} \textbf{shift} skips the first number of bytes in the file (in case of headers)
\end{description}

\paragraph{Examples}

Let's analyze 256 points from the 3rd channel from point 15. Four channels are re cored and stored in a binary format. The signal has a length of 2048 (4x512) points and is sampled at 32Hz.  First 128 bytes are the file's header. Fourth channel is the reference electrode.

\textbf{\emph{reinit -O 256}}

\textbf{\emph{loadsig -O filename -F 128 -c 3 -h 4 -\# 14 -t float -s 128 -e 4}}

\textbf{\emph{mp}} 

\textbf{\emph{save -O bookFilename}}\\
 save is described below


\paragraph{Default settings }

filetype: ascii 

  file header size: 0 

  sampling rate:1 Hz

  channel number:1 

  number of channels:1 

  offset:0 

  no reference electrodes

  conv: 1

\subsection{save}

We will refer to the saved file as a \emph{book} as a tribute to EEG traditional method of storing the recorded signals in a nicely folded stack of paper sheets.
\begin{description}
\item [save]\textbf{-O} \textbf{filename} book will be saved to a file
\item [save]\textbf{-a -O} \textbf{filename} appends to a filename
\item [save]\textbf{-s} creates a new book
\end{description}

\subsection{reset}


\subsection{norm}

\begin{description}
\item [norm] normalize the read signal
\end{description}

\subsection{type}

\begin{description}
\item [type]\textbf{-O} \textbf{filename} writes to a file the residual signal after an mp decomposition
\end{description}

\subsection{Running a script}
It is also possible to run a whole set of commands. They must be put into a text file as separate lines. Then simply run:\\
\textbf{./mp4 filename.txt}\\
from the command line.
\end{document}