text:
\documentclass[a4paper,11pt]{article}

\usepackage[T1]{fontenc}\usepackage{lmodern}\usepackage[sc]{mathpazo}\linespread{1.1}% Palatino font
\usepackage[colorlinks,urlcolor=black,linkcolor=black]{hyperref}
\usepackage{upquote,fancyvrb,subfig,microtype,sistyle,refstyle,wasysym}
\usepackage[process=auto,crop=pdfcrop]{pstool}

\newcommand\ytick[1]{\ensuremath{\mathcal R(e^{#1 i})}}

\newcommand\matlabfrag{\texorpdfstring{\href{http://www.mathworks.com/matlabcentral/fileexchange/21286}{{\ttfamily matlabfrag}}}{matlabfrag}}
\newcommand\psfragname{\texorpdfstring{\href{http://www.ctan.org/tex-archive/help/Catalogue/entries/psfrag.html}{{\ttfamily psfrag}}}{psfrag}}
\newcommand\pstoolname{\texorpdfstring{\href{http://www.ctan.org/tex-archive/help/Catalogue/entries/pstool.html}{{\ttfamily pstool}}}{pstool}}
\newcommand\matlab{\texorpdfstring{{\sc Matlab}}{Matlab}}
\newcommand\tex{\texorpdfstring{{\sc .tex}}{.tex}}
\newcommand\eps{\texorpdfstring{{\sc .eps}}{.eps}}
\newcommand\pdf{\texorpdfstring{{\sc .pdf}}{.pdf}}
\def\'#1'{{\ttfamily \textquotesingle #1\textquotesingle}}

% Get rid of that stupid S thing in section references.
\newref{sec}{%
  name    = \RSsectxt,
  names   = \RSsecstxt,
  Name    = \RSSectxt,
  Names   = \RSSecstxt,
  refcmd  = {\ref{#1}},
  rngtxt  = \RSrngtxt,
  lsttxt  = \RSlsttxt}

\title{\matlabfrag\ user guide}
\author{Zebb Prime}

\begin{document}
  \maketitle
  \tableofcontents
  \section{Introduction}%
    \matlabfrag\ is a function which exports a \matlab\ figure to \eps\ and \tex\ files for use in LaTeX
    with \psfragname. It is inspired by LaPrint, but is intended to be more WYSIWYG, by respecting figure
    handles better. The main reasons to use \matlabfrag\ are the same as those for using \psfragname: figure
    font matching that of the document, and the ability to have complex mathematical expressions typeset
    by LaTeX.

  \section{Background}%
    I wrote \matlabfrag\ after becoming frustrated with the default LaPrint behaviour, including it
    putting the line to insert the graphic in the output \tex\ file: \verb|\includegraphics{FileName.eps}|

    Whilst these problems could be addressed using one of the many options in LaPrint, I decided to
    take a stand against the many \matlab\ scripts and functions available which try to impose their
    own sense of style on my figures, and instead write a function which does everything possible to
    respect the figure handles. Everyone has their own sense of style, for better or worse, and I'm sure
    most users have their own little scripts set up to format their figures in their own way.

    The problem I have with the \verb|\includegraphics{FileName.eps}| line in the \tex\
    file is that I keep my figures in a {\ttfamily graphics} subdirectory of my main document. This meant I had to
    manually edit the \tex\ file every time I exported the figure from \matlab.

  \section{Compared to LaPrint}%
    In this section I compare the output from {\ttfamily LaPrint} and \matlabfrag\ for an identical
    figure. I have chosen some examples that shows some of the weaknesses of {\ttfamily LaPrint}, so
    be sure to take these comparisons with a grain of salt.

    The code for the first comparison is given in\par
    {\verb|examples/comparison01.m|}\par\noindent
    and the results are shown in \Figref{comparison01}. Notice that the legend box for the LaPrint
    output has been shrunk, and is too small for the equation, and the y axis scale has disappeared.
    I am unwilling to blame {\ttfamily LaPrint} for the equation not rendering as it may by a bug
    in any stage of the fairly complicated conversion process (which has nothing to do with
    \matlabfrag). The output \tex\ and \eps\ files appear to have the text conversion set up
    properly.
    \begin{figure}[ht]
      \centering
      \subfloat[graphics/comparison01-matlabfrag]{\figlabel{comparison01-matlabfrag}%
      \fbox{\psfragfig{graphics/comparison01-matlabfrag}}}
      \,
      \subfloat[graphics/comparison01-laprint]{\fbox{\psfragfig{graphics/comparison01-laprint}}}
      \caption{\matlabfrag\ output versus {\ttfamily LaPrint} output for a simple graph. Notice the
        legend box for the {\ttfamily LaPrint} is incorrectly sized, and the y axis scale has
        disappeared. I am unsure why the equation is not rendering in the {\ttfamily LaPrint}
        version, and it is unlikely to be the fault of {\ttfamily LaPrint}.}
      \figlabel{comparison01}
    \end{figure}

    In this second comparison a scaled version of the \matlab\ {\ttfamily peaks} function is
    presented. The \matlab\ code for this example is given in:\par
    {\verb|examples/comparison02.m|}\par\noindent
    and the results are shown in \Figref{comparison02}. The axis labels are handled better by
    \matlabfrag\, and it also manages to reproduce the x and y axis scales, but I stress that they
    only work well for the default orientation of a {\ttfamily surf} plot. If you start rotating
    the image they are unlikely to come out correctly. This is discussed further in \Secref{adv-axis}.
    \begin{figure}[ht]
      \centering
      \subfloat[graphics/comparison02-matlabfrag]{\fbox{\psfragfig{graphics/comparison02-matlabfrag}}}
      \,
      \subfloat[graphics/comparison02-laprint]{\fbox{\psfragfig{graphics/comparison02-laprint}}}
      \caption{\matlabfrag\ output versus {\ttfamily LaPrint}.}
      \figlabel{comparison02}
    \end{figure}

  \section{Usage}%
    \subsection{Within \matlab}%
      Using \matlabfrag\ within \matlab\ is easy. Simply format the figure how you like it, then run
      \matlabfrag. The format for the \matlabfrag\ command is:
      \begin{verbatim}
matlabfrag(FileName,OPTIONS)
      \end{verbatim}
      where {\ttfamily FileName} (required) is the file name for the output \tex\ and \eps\ files, and
      {\ttfamily OPTIONS} are key-value pairs for the optional options:
      \begin{itemize}
        \item[{\'handle'}] The handle for the figure to export. The default is {\ttfamily gcf} (`get
		  current figure').
        \item[{\'epspad'}] The number of points to pad the output \eps\ file by. The default is {\ttfamily [0,0,0,0]}.
        \item[{\'renderer'}] The output renderer. The default is {\ttfamily painters}. The renderer is
          discussed in more detail in \Secref{renderers}.
        \item[{\'dpi'}] The output resolution (DPI or more appropriately, PPI) of the figure.
          For the {\ttfamily painters} renderer this defaults to 3200, and when
          using the {\ttfamily opengl} or {\ttfamily zbuffer} renderers the default is 300.
          A discussion of renderers is given in \Secref{renderers}.
      \end{itemize}
      Some examples are given below.\nobreak
      \VerbatimInput[firstline=7,lastline=12]{ex01.m}
      See \Figref{ex01} for the output.
      \begin{figure}[ht]
        \centering
        \subfloat[graphics/ex01-1]{\fbox{\psfragfig[crop=preview]{graphics/ex01-1}}}\quad
        \subfloat[graphics/ex01-2]{\fbox{\psfragfig[crop=preview]{graphics/ex01-2}}}
        \caption{\matlabfrag\ options example showing the {\ttfamily epspad} option at work.}
        \figlabel{ex01}
      \end{figure}

      If you wish to show something different in \matlab\ and in the \tex\ document, then you
      can add it into the {\ttfamily UserData} property of the text, with a {\ttfamily matlabfrag:} prefix. This is
      especially useful if you have macros in LaTeX which you want to use, or if you want to use some
      commands not included in the \matlab\ LaTeX installation. In this example, the \verb|\LaTeX| macro
      typesets LaTeX as \LaTeX.
      \VerbatimInput[firstline=7,lastline=11]{ex02.m}
      See \Figref{ex02} for the output.
      \begin{figure}[ht]
        \centering
        \psfragfig{graphics/ex02}
        \caption{UserData example; X-label should say `Plays nice with \LaTeX'.}
        \figlabel{ex02}
      \end{figure}

    \subsection{Within LaTeX}\seclabel{in-latex}%
      The \tex\ and \eps\ files can be included in a LaTeX document (pdfLaTeX is treated seperately below)
      by either loading the \psfragname\ package and including the \tex\ file before the \eps\ file:
      \begin{verbatim}
\documentclass{article}
\usepackage{graphicx,psfrag}
\begin{document}
  \input{FileName.tex}
  \includegraphics{FileName.eps}
\end{document}
      \end{verbatim}
      or my preferred method; loading the \pstoolname\ package (v1.2 onwards), and using the
      \verb|\psfragfig| macro:
      \begin{verbatim}
\documentclass{article}
\usepackage{pstool}
\begin{document}
  \psfragfig{FileName}
\end{document}
      \end{verbatim}
      Notice the lack of a file extension in the \verb|\psfragfig| macro. This is a requirement of \pstoolname.
      \pstoolname\ also loads the {\ttfamily graphicx}, {\ttfamily psfrag} and {\ttfamily color} packages (as well as a few others),
      so it is not necessary to explicitly load these packages.

      For more information about \pstoolname\ or \psfragname\ please see their respective manuals.

      The text replacement performed by \psfragname\ occurs somewhere between the conversion from
      \textsc{dvi} to \textsc{ps} in some seemingly magical process that I don't understand. This means
      that if you look at the \textsc{dvi} output directly you will see a {\ttfamily PSFrag replacements}
      table next to the figure. This is normal, so do not panic.

    \subsection{Within pdfLaTeX}%
      There are several ways to include files with PostScript commands (such as \psfragname) in pdfLaTeX such
      as {\ttfamily pst-pdf}, {\ttfamily auto-pst-pdf}, {\ttfamily ps4pdf} and \pstoolname, by far the most useful of which is
      \pstoolname.  The document is set up the same way as the LaTeX example above:
      \begin{verbatim}
\documentclass{article}
\usepackage{pstool}
\begin{document}
  \psfragfig{FileName}
\end{document}
      \end{verbatim}
      The only difference being that \pstoolname\ runs some external processes to run the postscript commands,
      and as such it needs the \verb|-shell-escape| command when being called:\par
{\verb|pdflatex -shell-escape example.tex|}\par\noindent
      where {\ttfamily example.tex} is the code above.

    \subsection{Within LyX}\seclabel{in-lyx}%
      Using \matlabfrag\ withing LyX is relatively simple. The steps to setting LyX up with \pstoolname\
      are:
      \begin{enumerate}
        \item Ensure \pstoolname\ is installed in your LaTeX distribution. If you wish to use \pstoolname\
          with non-\textsc{pdf} output, please ensure \pstoolname\ is v1.2 or greater.
        \item Load \pstoolname\ in the document preamble by going to: {\ttfamily Document - Settings}, then
          choose {\ttfamily LaTeX Preamble} in the navigation panel in the left. Insert the line
          \verb|\usepackage{pstool}| and apply the settings.
        \item Enable \verb|-shell-escape| in pdfLaTeX by going to: {\ttfamily Tools - Preferences}, then
          choose {\ttfamily Converters} in the navigation panel in the left. Under {\ttfamily Converter Definitions}
          find the {\ttfamily LaTeX (pdflatex) -> PDF (pdflatex)} entry. Below this change the line\par
          {\verb|pdflatex $$i|}\par\noindent
          to\par
          {\verb|pdflatex -shell-escape $$i|}\par\noindent
          then click {\ttfamily Modify} to the
          upper right, then {\ttfamily Apply} and {\ttfamily Save} down the bottom.
      \end{enumerate}
      Please note that these steps were written for LyX version 1.5.6, but they should be similar for other
      versions.

      Once \pstoolname\ is set up for use in LyX, \matlabfrag\ images can be inserted by clicking on the
      \TeX\ button (Insert Tex Code), and placing the {\ttfamily psfragfig} command in:\par
      {\verb|\psfragfig{FileName}|}\par\noindent
      The {\ttfamily ERT} box created with the {\ttfamily psfragfig} command inside it should be placed as you
      would place a normal figure, for example inside a {\ttfamily float:Figure}.

      Please also read the discussion at the end of \Secref{in-latex} regarding the \textsc{dvi} output.
      Naturally the same applies for the \textsc{dvi} output from LyX as well.

  \section{Creating figures in \matlab}%
    I am now going to suggest a few ways to manipulate figures in \matlab\ before exporting them using \matlabfrag.

    \subsection{Sizing}%
      I suggest that the first thing you do when creating a figure is setting it to the size that you want
      in the final document. This way the figure does not need to be resized at any stage, which prevents
      line sizes changing, text over-running borders, etc.  This can be done within \matlab\ using:
      \VerbatimInput[firstline=4,lastline=10]{ex03.m}
      See \Figref{ex03} for the output from this example, {\ttfamily examples/ex03.m}.
      \begin{figure}[ht]
        \centering
        \psfragfig{graphics/ex03}
        \caption{Resizing example; the figure is sized to \SI{8}{cm} by \SI{3}{cm}.}
        \figlabel{ex03}
      \end{figure}

    \subsection{{\ttfamily Color}}%
      The {\ttfamily color} property is a three element vector representing the RGB colour of the text.
      \matlabfrag\ will respect the colour set in \matlab, but may require that you load the {\ttfamily color}
      package in LaTeX (\pstoolname\ implicitly loads the {\ttfamily color} package).
      \VerbatimInput[firstline=7,lastline=11]{ex04.m}
      See \Figref{ex04} for the output from this example, {\ttfamily examples/ex04.m}.
      \begin{figure}[ht]
        \centering
        \psfragfig{graphics/ex04}
        \caption{{\ttfamily Color} example; the text should be coloured.}
        \figlabel{ex04}
      \end{figure}

    \subsection{{\ttfamily FontSize}}%
      All text in \matlab\ figures has a {\ttfamily FontSize} property which \matlabfrag\ respects; the size
      specified in the figure is the size it will be in the LaTeX output document.
      \VerbatimInput[firstline=7,lastline=11]{ex05.m}
      See \Figref{ex05} for the output from this example, {\ttfamily examples/ex05.m}.
      \begin{figure}[ht]
        \centering
        \psfragfig{graphics/ex05}
        \caption{{\ttfamily FontSize} example; the text should be different sizes.}
        \figlabel{ex05}
      \end{figure}

    \subsection{{\ttfamily FontAngle}}%
      {\ttfamily FontAngle} is a property shared by all text in a \matlab\ figure. \matlabfrag\ respects
      {\ttfamily FontAngle} in that {\ttfamily italic} and {\ttfamily oblique} will be italic in the LaTeX output
      document.
      \VerbatimInput[firstline=7,lastline=11]{ex06.m}
      See \Figref{ex06} for the output from this example, {\ttfamily examples/ex06.m}.
      \begin{figure}[ht]
        \centering
        \psfragfig{graphics/ex06}
        \caption{{\ttfamily FontAngle} example; Oblique and Italic font should both be italic here.}
        \figlabel{ex06}
      \end{figure}

    \subsection{{\ttfamily FontWeight}}%
      Another text property from \matlab\ figures that \matlabfrag\ respects is {\ttfamily FontWeight}, such
      that any text set to {\ttfamily bold} will be made bold in the output LaTeX document. {\ttfamily light},
      {\ttfamily demi} and {\ttfamily normal} have no effect on the font in the LaTeX output.
      \VerbatimInput[firstline=7,lastline=12]{ex07.m}
      See \Figref{ex07} for the output from this example, {\ttfamily examples/ex07.m}.
      \begin{figure}[ht]
        \centering
        \psfragfig{graphics/ex07}
        \caption{{\ttfamily FontWeight} example; bold should be bold, demi and light do not really translate to
        LaTeX, so they should default to normal.}
        \figlabel{ex07}
      \end{figure}

    \subsection{{\ttfamily FontName}}%
      {\ttfamily FontName} is a property that \matlabfrag\ \emph{does not} respect, with one exception. One
      of the basic ideas behind using \matlabfrag\ and \psfragname\ is to match the font in figures to
      that of the text, so it does not make sense to use this property, except when it has been set to
      {\ttfamily FixedWidth}, in which case the font in the output LaTeX document will be fixed-width (i.e.,
      \verb|\ttfamily|).
      \VerbatimInput[firstline=7,lastline=11]{ex08.m}
      See \Figref{ex08} for the output from this example, {\ttfamily examples/ex08.m}.
      \begin{figure}[ht]
        \centering
        \psfragfig{graphics/ex08}
        \caption{{\ttfamily FontName} example; fixed-width should be in a typewriter font, while Comic Sans should
        be changed to the font of the document.}
        \figlabel{ex08}
      \end{figure}

    \subsection{{\ttfamily Interpreter}}%
      \matlab\ has three (well, two really) text interpreters that is uses to render the text. These
      are {\ttfamily tex}, {\ttfamily latex} and {\ttfamily none}. I generally don't recommend the use of the default
      {\ttfamily tex} interpreter if rendering anything mathematical and using \matlabfrag, as while the {\ttfamily tex}
      interpreter may render a mathematical expression fine, it may not work in LaTeX.

      The {\ttfamily latex} interpreter is especially useful for rendering mathematical formula.
      \VerbatimInput[firstline=7,lastline=11]{ex09.m}
      See \Figref{ex09} for the output from this example, {\ttfamily examples/ex09.m}.
	    \begin{figure}[ht]
	      \centering
		  \psfragfig{graphics/ex09}
		  \caption{{\ttfamily Interpreter} example; both equations should be the same, despite using a different
		    interpreter in \matlab.}
		  \figlabel{ex09}
	    \end{figure}

    \subsection{Multi-line text}%
      Multi-line text can be entered into \matlab\ using either a cell or a two-dimensional character
      matrix. If using a character matrix, \matlabfrag\ preserves all of the white spaces, so if you
      do not wish for this to occur, use cells instead (or check out the {\ttfamily cellstr} function).

      \matlabfrag\ recreates multi-line text using a {\ttfamily tabular} environment. If you also use the
      {\ttfamily UserData} property, you will need to manually put the {\ttfamily tabular} environment in, as
      \matlabfrag\ will ignore any {\ttfamily UserData} that is not a string.
      \VerbatimInput[firstline=7,lastline=13]{ex10.m}
      See \Figref{ex10} for the output from this example, {\ttfamily examples/ex10.m}.
      \begin{figure}[ht]
        \centering
        \psfragfig{graphics/ex10}
        \caption{Multi-line example; three different ways to make multi-line text. 2D arrays, cells
          and using {\ttfamily tabular}.}
        \figlabel{ex10}
      \end{figure}

    \subsection{Custom tick labels}%
      Custom tick labels can be added directly as strings for LaTeX to interpret. In this example,
      the \verb|\ytick| macro has been defined in the preamble of this document as:
      \par{\verb|\newcommand\ytick[1]{\ensuremath{\mathcal R(e^{#1 i})}}|}\par\noindent
      The \matlab\ example code is:
      \VerbatimInput[firstline=7,lastline=12]{ex11.m}
      See \Figref{ex11} for the output from this example, {\ttfamily examples/ex11.m}.
      \begin{figure}[ht]
        \centering
        \psfragfig{graphics/ex11}
        \caption{Custom tick label example.}
        \figlabel{ex11}
      \end{figure}

    \subsection{Legends}\seclabel{legends}%
      Legends can, with a bit of manipulation, be used in exactly the same way as other text objects.

      If LaTeX strings are entered into the legend, the LaTeX interpreter can be turned
      on using the legend handle directly:
      \begin{verbatim}
hleg = legend($\ddot\alpha$,$\ddot\beta$);
set(hleg,'interpreter','latex');
      \end{verbatim}

      To use the \matlabfrag\ {\ttfamily userdata} auto-substitution feature with legend texts,
      the text objects inside the legend need to be accessed directly.  Each legend entry
      appears as three child objects of the legend ({\ttfamily line}, {\ttfamily marker} and
      {\ttfamily text} in that order), and the entries are in reverse order to that which
      they were entered into {\ttfamily legend} as. Knowing this order, the {\ttfamily userdata}
      property of the text objects can be set:
      \VerbatimInput[firstline=7,lastline=11]{ex12.m}
      If each legend string is unique, then another method is find the text object is to use
      the {\ttfamily findobj} function in \matlab.
      \VerbatimInput[firstline=12,lastline=13]{ex12.m}
      The output from this example, {\ttfamily examples/ex12.m}, is given in \Figref{ex12}.
      \begin{figure}
        \centering
        \psfragfig{graphics/ex12}
        \caption{Using the {\ttfamily userdata} feature with legends.}
        \figlabel{ex12}
      \end{figure}

    \subsection{Tick scaling values}\seclabel{axis-scaling}%
      Tick values automatically generated by \matlab\ may have a scaling value placed at the end
      of the axis. In two-dimensional plots these will be handled by \matlabfrag\ fairly well, but
      in some circumstances, such as three-dimensional plots, they will work badly. An example of
      them being automatically placed in the figure is given in \Figref{comparison02} and the file\par
      {\verb|examples/comparison02.m|}\par\noindent
      When \matlabfrag\ fails to insert the scaling properly, I suggest you manually modify the
      axis ticks, and place the scaling in either the axis label, or place it manually as a text
      object. Example code for doing this is:
      \VerbatimInput[firstline=7,lastline=17]{ex13.m}
      See \Figref{ex13} for the output from this example, {\ttfamily examples/ex13.m}.
      \begin{figure}[ht]
        \centering
        \psfragfig{graphics/ex13}
        \caption{Manually inserted axis scalings.}
        \figlabel{ex13}
      \end{figure}
      You can read more about why this is necessary in \Secref{adv-axis}.

  \section{Frequently (occasionally) asked questions}%
    \subsection{Why does the output have three digit numbers all through it?}

	  Either you are looking at the \eps\ output and that is how it is supposed to look,
	  or there was a problem processing the image with \psfragname. Check out the troubleshooting section
	  below.

	  \subsection{Why doesn't the \tex\ file have the
	  \texorpdfstring{{\ttfamily includegraphics}}{includegraphics} statement in it like LaPrint does?}

	  Firstly, read the Background section above. With all the image files stored in a
	  {\ttfamily graphics} subdirectory of the main document, I would have to manually open the \tex\ file and
	  insert the path into the that line. This was one of the reasons I wrote \matlabfrag\ in the first
	  place.

	  I have considered including an option to produce this output for those who would rather use this
	  behaviour than load \pstoolname\ but decided against it due to the directory problems. From v1.2 onwards
	  \pstoolname\ works fine in LaTeX so there really is no need to manually put the \verb|\includegraphics|
	  line in.

    \section{Troubleshooting}
      \subsection{I get an error in \matlab!}
        The only errors that should be generated from \matlabfrag\ are from using it with an old version
        of \matlab\ or calling it with invalid parameters. Unfortunately the error messages generated from
        the {\ttfamily inputParser} class are a bit cryptic, but you should be able to work out if it is a
        parameter error. A simple way to check this is to use an example that is known to work.

        If using a version of \matlab\ older than v7, you will receive a parse error, rather than a sane
        error message telling you your version of matlab is too old.  An example of this error is:
        \begin{verbatim}
"identifier" expected, "(" found.
        \end{verbatim}
        As this is a parse error, it occurs before any code in the script has run, hence I am unable to
        output a sane error message.  The only way to output a sane error message in such an old version
        of \matlab\ would be to rewrite \matlabfrag\ so that it doesn't use anonymous functions, which I
        don't want to do.

        No other errors should be generated by \matlabfrag. If you encounter one it is most likely a bug.
        Please email the smallest self-contained example that reproduces the bug to me at
        \par\noindent{\ttfamily zebb.prime+matlabfrag@gmail.com}

      \subsection{I get a warning in \matlab!}
        Warnings created by \matlabfrag\ are there for a reason. Read through them, as they explain what
        the problem is and what \matlabfrag\ is doing about it.

      \subsection{I get the {\ttfamily Unable to interpret TeX string} warning in \matlab!}
        This warning occurs when the TeX or LaTeX interpreter (whichever is chosen) cannot
        interpret the string, and can be caused by calling macros which don't exist in
        the version of LaTeX that ships with \matlab\ or by trying to interpret a LaTeX string
        with the TeX interpreter (and vice versa).

        To troubleshoot, ensure the string is correct, and the appropriate interpreter is used.
        An example known to work is:
        \begin{verbatim}
title('Force versus $\sin(\alpha)$','interpreter','latex');
        \end{verbatim}
        The {\ttfamily none} interpreter can also be used, however the box around the text may end up
        a very different size to the final text. The following example also works, but the bounding box
        in \matlab\ is much wider than in the final document:
        \begin{verbatim}
title('Force versus $\sin(\alpha)$','interpreter','none');
        \end{verbatim}
        Another alternative is to use the {\ttfamily userdata}
        feature of \matlabfrag\ with a placeholder for the screen text. A working example is:
        \begin{verbatim}
title('Force versus sin(a)','userdata',...
  'matlabfrag:Force versus $\sin(\alpha)$');
        \end{verbatim}
        This is also a good option for using macros that aren't included with the version of LaTeX
        that ships with \matlab. For example, in \Secref{legends}, the \verb|\SI| macro is used to format the
        numbers and units. The package that provides this command, {\ttfamily sistyle}, is loaded
        in the preamble of this document.

        As this warning has to do with the way \matlab\ renders text on screen and not \matlabfrag,
        please do not contact me about it.

      \subsection{My graphic exports from \matlab\ fine, but does not compile in LaTeX/pdfLaTeX/LyX!}
	    \begin{enumerate}
	      \item Check that all LaTeX statements in your figure are valid. If you are having problems, try a
	        simple example that is known to work.
	      \item If you have manually loaded the {\ttfamily graphicx} package, make sure you don't have a
	        driver (e.g. {\ttfamily pdftex}) specified.
	      \item If using pdfLaTeX and \pstoolname, check:
	      \begin{enumerate}
	        \item \verb|-shell-escape| option is set when calling pdfLaTeX.
	      \end{enumerate}
	      \item If using LaTeX and \pstoolname, check:
	      \begin{enumerate}
	        \item \pstoolname\ is at least at version 1.2. An alternative location to finding \pstoolname\ is
		      \url{http://github.com/wspr/pstool/}.
	      \end{enumerate}
	      \item If using LaTeX or pdfLaTeX with anything else:
	      \begin{enumerate}
	        \item Install \pstoolname !
	      \end{enumerate}
	      \item If using LyX:
  	    \begin{enumerate}
	        \item Check to see if the \pstoolname\ package is loading by going to {\ttfamily Document -- LaTeX log},
	          and trying to find the \pstoolname\ entry. If it is not found then try repeating the instructions
	          in \Secref{in-lyx}. If it is there, check to see if it is issuing a warning that \verb|-shell-escape|
	          is disabled. If so, follow the instructions in \Secref{in-lyx}.
	      \end{enumerate}
	  \end{enumerate}

    \subsection{My graphic exports from \matlab\ and compiles in LaTeX/\texorpdfstring{\\}{}pdfLaTeX/LyX but doesn't look right!}
      \begin{enumerate}
      \item If you use a {\ttfamily includegraphics} option such as {\ttfamily rotate}, there is a bug
	      in \pstoolname\ prior to v1.2b that caused the option to be applied twice.
      \item The text is running over lines or is cut out!
      \begin{enumerate}
        \item This most likely happens if you resize the image in LaTeX using a \verb|[width=x]| argument.
          It is usually better to size the image in \matlab\ in the first place, and do no further resizing.
        \item If you have mathematical equations, use the {\ttfamily latex} interpreter. This will make the
          text object be roughly the right size, which will let \matlab\ place it properly. This is
          especially useful for legends, as shown in \Figref{comparison01-matlabfrag}.
        \item If the text appears to be cropped from the outside of the graphic then try padding the \eps\
          file using the {\ttfamily epspad} option, or try the {\ttfamily pdfcrop} option
          for \pstoolname:\par
          {\verb|\usepackage[crop=pdfcrop]{pstool}|}
      \end{enumerate}
	    \item A complicated graphic appears different on screen than it does in the document.
	      \begin{enumerate}
	        \item This is most likely an issue caused by a renderer. For more information, read the discussion
	          on renderers in \Secref{renderers}.
	      \end{enumerate}
	    \end{enumerate}

    \section{Advanced usage: a discussion on renderers}\seclabel{renderers}%
      \matlab\ has three different renderers that it uses to render a graphic on screen; {\ttfamily Painters},
      {\ttfamily OpenGL}, and {\ttfamily Z-Buffer}. Of these, only the {\ttfamily Painters} renderer can export
      an image in a native text format which is needed for the text substitution process. If one of the
      other renderers is used the text becomes rasterised, and hence normally no text replacement can take place.

      As of \matlabfrag\ {\ttfamily v0.6.0}\footnote{There have been a series of bug fixes since
      {\ttfamily v0.6.0}, so I always recommend using the latest version.},
      an {\ttfamily EXPORTFIG} and {\ttfamily epscombine} style hack
      has been included, which manually places text objects inside rasterised \eps\ images. The result of this
      is that text can now be substituted with LaTeX font and code, but also that all the text now appears
      in the foreground (i.e. all text appears in front of the image, regardless of its placement in the
      original image).

      A downside to placing a rasterised image inside an \eps\ file is that it is uncompressed, which creates
      a very large \eps\ file. However, during the conversion to {\ttfamily pdf} the image is compressed to a
      reasonable file size.  If you are using \pstoolname, from {\ttfamily v1.3} it defaults to a lossless
      compression technique similar to \textsc{png}. This is the most suitable compression for technical
      graphics, but should you prefer it, lossy compression can be turned on. For more information, refer to
      the \pstoolname\ documentation.

      When printing a rasterised image, the resolution is set using the {\ttfamily dpi} option in \matlabfrag.
      The default is 300 for {\ttfamily OpenGL} and {\ttfamily Z-Buffer} rendered images, which is usually
      considered to be print quality.  The default for the {\ttfamily Painters} renderer is 3200. Using a large
      {\ttfamily dpi} value for {\ttfamily Painters} rendered images reduces quantisation error while only
      increasing the file size by a small amount.

      By default \matlabfrag\ will use the {\ttfamily Painters} renderer unless either the figure has had
      the renderer manually set (which causes the {\ttfamily renderermode} property to become {\ttfamily manual}),
      or the {\ttfamily renderer} option is set in \matlabfrag.

      An example of choosing the renderer in \matlabfrag, and increasing the image DPI is given in
      \par{\verb|examples/ex14.m|}\par\noindent
      an extract of which is:
      \VerbatimInput[firstline=7,lastline=15]{ex14.m}
      The output for this example is given in \Figref{ex14}.
      \begin{figure}[ht]
        \centering
        \psfragfig{graphics/ex14}
        \caption{Example showing the use of the {\ttfamily OpenGL} renderer.}
        \figlabel{ex14}
      \end{figure}

      An example showing \matlabfrag\ detecting a manually set renderer is given in
      \par{\verb|examples/ex15.m|}\par\noindent
      which is largely based off of the ``Moving the Camera Through a Scene'' example in the \matlab\
      documentation. An extract of this example is:
      \VerbatimInput[firstline=41,lastline=45]{ex15.m}
      The output from this example is given in \Figref{ex15}.
      \begin{figure}[ht]
        \centering
        \psfragfig{graphics/ex15}
        \caption{Example output when the renderer is set to {\ttfamily zbuffer} and shading set to
        {\ttfamily phong}.}
        \figlabel{ex15}
      \end{figure}

   \section{Advanced usage: a discussion on axis ticks}\seclabel{adv-axis}%
     Easily the hardest part about writing \matlabfrag\ has been dealing with axis ticks. Their positioning
     and circumstances when the labels are modified are completely hidden from the user. For example, if the
     axis is logarithmic, and the ticks occur at powers of 10, then the {\ttfamily xticklabel} properties
     are written as the power of ten (e.g. 2) and rendered as the 10 to the power of the number (e.g. $10^2$).
     \matlabfrag\ handles this case by detecting whether {\ttfamily xscale} is set to {\ttfamily log}, and
     {\ttfamily xticklabelmode} is set to {\ttfamily auto}. If so, it automatically inserts the appropriate
     LaTeX code. A simple example of this behaviour can be shown with the code:
     \VerbatimInput[firstline=7,lastline=8]{ex16.m}
     from {\ttfamily examples/ex16.m}, which produces \Figref{ex16}.
     \begin{figure}[ht]
       \centering
       \psfragfig{graphics/ex16}
       \caption{An example {\ttfamily bodemag} plot demonstrating ticks of the format $10^x$. Note that
         the axis tick labels are grey. This is due to the {\ttfamily bodemag} function setting them grey
         using the {\ttfamily xcolor} and {\ttfamily ycolor} axis properties.}
       \figlabel{ex16}
     \end{figure}

     The above case is fairly simple in comparison to how \matlab\ handles axes that have been scaled by
     a power of ten. For example, if $x\in[0\quad10^{-3}]$, then the x ticks would read, say
     $[0\quad0.5\quad1]$, and a $\times10^{-3}$ would be placed to the lower right of the x axis.
     Unfortunately, this $\times10^{-3}$ text object is completely hidden from the user, and as soon as
     the tick labels are modified by the user it disappears. Both \matlabfrag\ and {\ttfamily LaPrint}
     have to modify the tick labels to make it possible for \psfragname\ to do text substitution, thus
     we have to manually recreate this scaling. In \matlabfrag\ this is performed by detecting when:
     \begin{enumerate}
       \item {\ttfamily xticklabelmode} is set to {\ttfamily auto}, and
       \item there is a scaling value between the {\ttfamily xtick} and {\ttfamily xticklabel} that is
         equal to a power of ten.
     \end{enumerate}
     In these circumstances, \matlabfrag\ does its best to place the scaling value in the most appropriate
     location. For two-dimensional graphs this isn't too bad, but for three-dimensional plots it is very
     difficult.

     The locations for all of the scaling values for all permutations of x and y axis locations
     in a two dimensional plot are shown in \Figref{ex17}. The code for this example is given in:\par
     {\verb|examples/ex17.m|}.
     \begin{figure}[ht]
       \centering
       \psfragfig{graphics/ex17}
       \caption{Axis scale positions for all permutations of the x and y axis locations.}
       \figlabel{ex17}
     \end{figure}

     Lastly, support for tick scaling in three-dimensional plots has been added to \matlabfrag\ for
     the default orientation of {\ttfamily surf} plots, such as that shown previously in
     \Figref{comparison02}. If you start to rotate the orientation of the plot it will probably break
     horribly. In these circumstances I suggest you manually place the scaling in the axis label, or
     as a text object. Please read through \Secref{axis-scaling} for some information and an example
     of how to do this.

\end{document}

max_stars_repo_name: changyaochen/Matlab-library

max_issues_repo_name: changyaochen/Matlab-library

max_forks_repo_name: changyaochen/Matlab-library


text:
\subsection{Convolution in one grid (without stride)}
%Firstly, as mentioned before, an image type
%data with multichannel can be understand as
%vector valued functions
%$$
%f \in \mathbb{R}^{(2^m+1)\times(2^n+1) \times c}, \quad \text{or}\quad [f]_i \in
%\mathbb{R}^{(2^m+1)\times(2^n+1)}, \quad i = 1:c,
%$$
Here we mention our new set up for all the next notes as all image with
size like
\begin{equation}\label{eq:size_f}
m = m_1 = 2^{s} + 1,  \quad n = n_1 = 2^t  +1.
\end{equation}
By the linear finite element discretization and bilinear finite element discretization,
we have \eqref{2d-fe0} and \eqref{2d-fe1} respectively.
A more general form for the discretization systems  is the so
called convolution for $ g \in \mathbb{R}^{m\times n}$ with padding as:
%We first consider $\theta$ a convolution operator (with stride $1$)
%and padding:
\begin{equation}\label{con1}
[K \ast g]_{i,j} = \sum_{p,q=-k}^k K_{k+1+p,k+1+q} g_{i + p, j + q}, \quad i=1:m + 1, j = 1:n + 1.
\end{equation}
The coefficients in \eqref{con1} constitute  a kernel matrix
\begin{equation}
K \in \mathbb{R}^{(2k+1) \times (2k+1)},
\end{equation}
where $k$ is often taken as small integers.
Here padding means how choose $ g_{i+ p, j + q}$
when $(i+ p, j + q)$ is out of $1:m$ or $1:n$.
Those next three choices are often used
\begin{equation}\label{eq:padding}
f_{i + p, j + q} = \begin{cases}
0,  \quad &\text{zero padding}, \\
f_{(i + p)\pmod{m}, (s + q)\pmod{n}},  \quad &\text{periodic padding}, \\
f_{|i-1 +p|, |j -1  +q|},  \quad &\text{reflected padding}, \\
\end{cases}
\end{equation}
if
\begin{equation}
i + p \notin \{1, 2, \dots, m\} ~\text{or} ~  j+ q \notin \{1, 2, \dots, n\}.
\end{equation}
Here $ d \pmod{m} \in \{1, \cdots, m\} $  means the remainder when $d$ is divided by $m$.

By the definition of convolution \eqref{con1}, we can rewrite \eqref{2d-fe0} and \eqref{2d-fe1} as follows:
\begin{equation}
K_A\ast:  \mathbb{R}^{m\times n}\rightarrow \mathbb{R}^{m\times n},~~~K_A\ast u=f,
\end{equation}
where
\begin{equation}\label{fe0_Ka}
	K_A=
	\begin{pmatrix}
	0 &-1&0\\
	-1& 4&-1\\
	0 &-1& 0
	\end{pmatrix}
	\end{equation}
for linear finite element discretization or
	\begin{equation}\label{fe1_Ka}
	K_A=
	\begin{pmatrix}
	-1 &-1&-1\\
	-1& 8&-1\\
	-1 &-1& -1
	\end{pmatrix}.
	\end{equation}
for bilinear finite element discretization.

The gradient descent method for \eqref{laplace} or \eqref{laplace-h} can be derived as following
\begin{itemize}
	\item $\min_{x\in \mathbb{R}^n} J(x)$ with $ J(x) =
          \frac{1}{2}u^TA u - f^Tu$
	\item Gradient:
	$$
	\nabla J= Au - f := - r.
	$$
	\item Given $u^k$, a new approximate solution is computed by two steps:
	$$
	r^k = f-Au^k,\quad u^{k+1} = u^k + \frac{\omega}{4} r^k.
	$$
\end{itemize}
Here we can clearly see that gradient descent method is equivalent to damped Jacobi method. Usually, we call this as
smoother. A commonly used
damped Jacobi is the one with damped coefficient $\omega$ with $\omega \in (0,2)$,
which can be written as $S_{0}:\mathbb R^{m\times n}\mapsto
\mathbb R^{m\times n}$ satisfying
\begin{equation}
\label{jacobi1}
(S_{0}f)_{i,j}={\omega\over 4}f_{i,j},
\end{equation}
for equation \eqref{laplace-h} with initial guess zero.
If we apply the Jacobian iteration twice, then
$$
S_1(f) = S_{0} f + S_0(f - A(S_{0}f)),
$$
with element-wise form
\begin{equation}
\begin{aligned}
\label{jacobi2}
[S_1(f)]_{i,j} &={1\over 4}\omega(2-\omega)f_{i,j} + {\omega^2\over 16}(f_{i+1,j}+f_{i-1,j}+f_{i,j+1}+f_{i,j-1}).
\end{aligned}
\end{equation}
Then by the definition of convolution \eqref{con1}, we have
 \begin{equation}\label{eq:convS}
S_{0}f = K_{S_{0}} \ast f \quad S_1 f = K_{S_1} \ast f.
\end{equation}
with
\begin{equation}\label{eq:kernel-S}
K_{S_{0}} = {\omega \over 4},
\end{equation}
and
\begin{equation}\label{eq:kernel-S2}
K_{S_1} = \begin{pmatrix}
0 & \frac{\omega^2}{16} & 0 \\
\frac{\omega^2}{16} & {\omega(2-\omega) \over 4} & \frac{\omega^2}{16}  \\
0 & \frac{\omega^2}{16}  & 0
\end{pmatrix}.
\end{equation}

%Then we remark that, if we take convolution without pooling, there is a
%shift with
%$$
%i+ p  \rightarrow i + k+ p,
%$$
%and also for $j$ such that all index $(i + k+ p, j + k+ p)$ is during
%$1:n$.

%\input{6DL/MgNet_ConvStride.tex}

ext: tex


text:
  \documentclass{mynotes}

%\geometry{showframe}% for debugging purposes -- displays the margins

\newcommand{\E}{\mbox{E}}
\newcommand{\MSE}{\mbox{MSE}}
\newcommand{\var}{\mbox{var}}
\newcommand{\bx}{\mathbf{x}}

\usepackage{amsmath}
%\usepackage[garamond]{mathdesign}
\usepackage{url}

% Set up the images/graphics package
\usepackage{graphicx}
\setkeys{Gin}{width=\linewidth,totalheight=\textheight,keepaspectratio}
\graphicspath{{graphics/}}

\title[Exercises 4 $\cdot$ SSC 383D]{Exercises 5: Hierarchical Linear Models}
%\author[ ]{ }
\date{}  % if the \date{} command is left out, the current date will be used

% The following package makes prettier tables.  We're all about the bling!
\usepackage{booktabs}

% The units package provides nice, non-stacked fractions and better spacing
% for units.
\usepackage{units}

% The fancyvrb package lets us customize the formatting of verbatim
% environments.  We use a slightly smaller font.
\usepackage{fancyvrb}
\fvset{fontsize=\normalsize}

% Small sections of multiple columns
\usepackage{multicol}

% Provides paragraphs of dummy text
\usepackage{lipsum}

% These commands are used to pretty-print LaTeX commands
\newcommand{\doccmd}[1]{\texttt{\textbackslash#1}}% command name -- adds backslash automatically
\newcommand{\docopt}[1]{\ensuremath{\langle}\textrm{\textit{#1}}\ensuremath{\rangle}}% optional command argument
\newcommand{\docarg}[1]{\textrm{\textit{#1}}}% (required) command argument
\newenvironment{docspec}{\begin{quote}\noindent}{\end{quote}}% command specification environment
\newcommand{\docenv}[1]{\textsf{#1}}% environment name
\newcommand{\docpkg}[1]{\texttt{#1}}% package name
\newcommand{\doccls}[1]{\texttt{#1}}% document class name
\newcommand{\docclsopt}[1]{\texttt{#1}}% document class option name

\newcommand{\N}{\mbox{N}}
\newcommand{\thetahat}{\hat{\theta}}
\newcommand{\sigmahat}{\hat{\sigma}}
\newcommand{\betahat}{\hat{\beta}}

\begin{document}

\maketitle% this prints the handout title, author, and date

\section{Price elasticity of demand}

The data in ``cheese.csv'' are about sales volume, price, and advertisting display activity for packages of Borden sliced ``cheese.'' The data are taken from Rossi, Allenby, and McCulloch's textbook on \textit{Bayesian Statistics and Marketing.} For each of 88 stores (store) in different US cities, we have repeated observations of the weekly sales volume (vol, in terms of packages sold), unit price (price), and whether the product was advertised with an in-store display during that week (disp = 1 for display).

Your goal is to estimate, on a store-by-store basis, the effect of display ads on the demand curve for cheese.  A standard form of a demand curve in economics is of the form $Q = \alpha P^\beta$, where $Q$ is quantity demanded (i.e.~sales volume), $P$ is price, and $\alpha$ and $\beta$ are parameters to be estimated.  You'll notice that this is linear on a log-log scale,
$$
\log Q = \log \alpha + \beta \log P \,
$$
which you should feel free to assume here.  Economists would refer to $\beta$ as the price elasticity of demand (PED).  Notice that on a log-log scale, the errors enter multiplicatively.

There are several things for you to consider in analyzing this data set.
\begin{compactenum}
\item The demand curve might shift (different $\alpha$) and also change shape (different $\beta$) depending on whether there is a display ad or not in the store.
\item Different stores will have very different typical volumes, and your model should account for this.
\item Do different stores have different PEDs?  If so, do you really want to estimate a separate, unrelated $\beta$ for each store?
\item If there is an effect on the demand curve due to showing a display ad, does this effect differ store by store, or does it look relatively stable across stores?
\item Once you build the best model you can using the log-log specification, do see you any evidence of major model mis-fit?
\end{compactenum}
Propose an appropriate hierarchical model that allows you to address these issues, and use Gibbs sampling to fit your model.

\section{A hierarchical probit model}

Read the following paper (or read some distillation of the paper in a book/blog post/slides/etc).
\begin{quotation}
``Bayesian Analysis of Binary and Polychotomous Response Data.''  James H. Albert and Siddhartha Chib.  \textit{Journal of the American Statistical Association}, Vol.~88, No.~422 (Jun.,~1993), pp.~669-679
\end{quotation}

The paper describes a Bayesian treatment of probit regression (similar to logistic regression) using the trick of \textit{data augmentation}---that is, introducing ``latent variables'' that turn a hard problem into a much easier one.  Briefly summarize your understanding of the key trick proposed by this paper.  Then see you if you can apply the trick in the following context, which is more complex than ordinary probit regression.

In ``polls.csv'' you will find the results of several political polls from the 1988 U.S.~presidential election.  The outcome of interest is whether someone plans to vote for George Bush (senior, not junior).  There are several potentially relevant demographic predictors here, including the respondent's state of residence.  The goal is to understand how these relate to the probability that someone will support Bush in the election.  You can imagine this information would help a great deal in poll re-weighting and aggregation (ala Nate Silver).

Use Gibbs sampling, together with the Albert and Chib trick, to fit a hierarchical probit model of the following form:
\begin{eqnarray*}
\mbox{Pr}(y_{ij} = 1) &=& \Phi(z_{ij})  \\
z_{ij} &=& \mu_i + x_{ij}^T \beta_i \, .
\end{eqnarray*}
Here $y_{ij}$ is the response (Bush=1, other=0) for respondent $j$ in state $i$; $\Phi(\cdot)$ is the probit link function, i.e.~the CDF of the standard normal distribution; $\mu_i$ is a state-level intercept term; $x_{ij}$ is a vector of respondent-level demographic predictors; and $\beta_i$ is a vector of regression coefficients for state $i$.

Notes:
\begin{enumerate}
\item There are severe imbalances among the states in terms of numbers of survey respondents. Following the last problem, the key is to impose a hierarchical prior on the state-level parameters.
\item The data-augmentation trick from the Albert and Chib paper above is explained in many standard references on Bayesian analysis.  If you want to get a quick introduction to the idea, you can consult one of these.  A good presentation is in Section 8.1.1 of ``Bayesian analysis for the social sciences'' by Simon Jackman, available as an ebook through lib.utexas.edu.
\item You are welcome to use the logit model instead of the probit model.  If you do this, you'll need to read the following paper, rather than Albert and Chib: Polson, N.G., Scott, J.G. and Windle, J. (2013). Bayesian inference for logistic models using Polya-Gamma latent variables. J. Amer. Statist. Assoc. 108 1339--1349.    You can find a routine for simulation Polya-Gamma random variables in the BayesLogit R package and the pypolyagamma python library.
\end{enumerate}

\end{document}


text:
\documentclass{beamer}
\usepackage{appendixnumberbeamer}
\graphicspath{{figures/}}
%
% Choose how your presentation looks.
%
% For more themes, color themes and font themes, see:
% http://deic.uab.es/~iblanes/beamer_gallery/index_by_theme.html
%
\mode<presentation>
{
  \usetheme{Warsaw}      % or try Darmstadt, Madrid, Warsaw, ...
  \usecolortheme{beaver} % or try albatross, beaver, crane, ...
  \usefonttheme{default}  % or try serif, structurebold, ...
  \setbeamertemplate{navigation symbols}{}
  \setbeamertemplate{caption}[numbered]
  \setbeamertemplate{footline}[frame number]
  \setbeamertemplate{headline}{}
}

\usepackage{graphicx}
\usepackage[english]{babel}
\usepackage[utf8x]{inputenc}
\usepackage{subcaption}
\usepackage{amsmath,amssymb,bm,bbm}
\usepackage{graphicx}
\usepackage[]{natbib}
\bibliographystyle{aer}
\usepackage{hyperref}
\hypersetup{colorlinks,citecolor=blue,urlcolor=blue,linkcolor=blue}

\DeclareMathOperator*{\argmin}{arg\,min}

\title[]{Policy Targeting with Strategic Agents }

\author{Evan Munro (Stanford GSB)}
\date{Econometrics Lunch \\ October 18, 2021 }
\begin{document}

\begin{frame}
  \titlepage
\end{frame}

\section{Introduction}
\begin{frame}{Personalized Policy}
    \textbf{Motivation}
    \begin{itemize}
  \item If individual treatment effects are heterogeneous, a planner might improve outcomes by treating individuals heterogeneously rather than uniformly
  \item With more individual-level data available, personalized policy is increasingly common (ex. airfare shown to customer depends on browsing history)
  \item Problem: Treating individuals heterogeneously based on observed characteristics introduces incentives for individuals to change their behavior to receive a better treatment.
    \end{itemize}
  \textbf{Research Question}  \begin{itemize}

   \item How to estimate the optimal treatment rule when agents are strategic ?
   \item Treatment rule: A method of allocating treatments heterogeneously on the basis of observed covariates.
\end{itemize}
       \end{frame}

\begin{frame}{Examples }
 \begin{enumerate}
 \item Heterogeneous pricing of consumer products based on device usage patterns.

\item Fraud detection based on spending patterns.
\item Credit decisions based on non-traditional consumer metrics, such as cellphone data.

   \end{enumerate}
   \vspace{0.5in}
   \textbf{Personalized Policy Introduces Incentives to Misreport}
   \begin{itemize}
       \item Incentives in all three of these settings for individuals to change characteristics to receive a better treatment (lower price, better prediction, or more credit)
   \end{itemize}

\end{frame}

\begin{frame}{Related Literature}
\begin{itemize}
\item CS/econ theory literature on strategic classification and manipulation:  \cite{dong2018strategic}, \cite{hardt2016strategic}, \cite{ball2020scoring}, \cite{frankel2019improving}, \cite{bjorkegren2020manipulation}
    \begin{itemize}
        \item This paper applies to more general problems than existing approaches.
    \end{itemize}
\item Causal inference and experiment design:
 \cite{angrist2000interpretation}, \cite{athey2020policy}, \cite{wager2019experimenting}
 \begin{itemize}
     \item Existing literature treats observed characteristics as i.i.d.
 \end{itemize}

     \item Bandit literature: \cite{flaxman2004online}, \cite{duchi2015optimal}
     \begin{itemize}
         \item Existing literature on zero-th order optimization of black box functions does not usually exploit cross-sectional variation.
     \end{itemize}
      \item Robustness: \cite{bergemann2013robust}
      \begin{itemize}
          \item The procedure is robust to different distributions of types and different actions of individuals.
      \end{itemize}
    \end{itemize}
\end{frame}

\begin{frame}{Overview}
\begin{itemize}
\item Formalize the problem of strategic behavior in a treatment targeting setting as a Stackelberg Game.
\item Show that existing approaches for estimating treatment rules are sub-optimal in this setting.
\item Show that new results from zero-th order optimization literature (\textcolor{blue}{Chen, Lai, Li and Zhang, 2021}) can be used to design a sequential experiment that performs estimation and inference on the optimal rule.
\end{itemize}
\end{frame}

\begin{frame}{Treatment Targeting as a Stackelberg Game}

\begin{enumerate}
\item Planner chooses a targeting rule, which maps covariates $X_i \in \mathcal X$ to treatments $W_i \in \mathcal \{0, 1\}\footnote{Extension to continuous treatments also possible}$.
\[ \delta: \mathcal X \rightarrow [0, 1] \]
$\delta(x) = Pr(W_i = 1 | X_i =x)$.
\item For $ i \in [n]$, player $i$ reports covariates $X_i \in \mathcal X$:
\[ X_i(\delta) = \arg \max_{x}  \delta(x) U_i(x, 1) + (1 - \delta(x)) U_i(x, 0)  \]
$X_i$ maximizes expected utility, where the distribution of $W_i$ conditional on $x$ is determined by $\delta(x)$.

\item For $i \in [n]$, $W_i$ is sampled from $\delta(X_i)$.
\item The outcome $Y_i = Y_i(W_i)$ is observed

\end{enumerate}
\end{frame}

\begin{frame}{Planner's Objective}
Let $Y_i(\cdot)$ and $U_i(\cdot)$ be drawn i.i.d. from some distribution $\theta$.
The planner would like to minimize the average risk:

\[ R(\delta) =  \mathbb E\Big[r(\delta(X_i), Y_i)\Big]\]

Example Loss Functions:
\begin{enumerate}
\item Outcome maximization:
\[ r(\delta(X_i), Y_i) = -Y_i \]
\item Binary classification:
\[ r(\delta(X_i), Y_i) = - \log(\delta(X_i)) Y_i - \log((1- \delta(X_i)) ( 1- Y_i) \]
\end{enumerate}

\end{frame}

\begin{frame}{Outcome Maximization}
\begin{itemize}
\item Examine more closely maximizing $\mathbb E[Y_i(W_i)]$.
\item With exogenous $X_i$, existing literature suggest a cutoff rule is optimal for average risk (e.g. Hirano and Porter, 2009).
\end{itemize}
\bigskip
\begin{equation*}
\begin{split}
&\tau(x) = \mathbb E[ Y_i(1) - Y_i(0) | X_i = x] \\
& \delta(x) = \mathbbm{1} (\tau(x) >0 )
\end{split}
\end{equation*}

\textbf{Question: } Is it still optimal when observed covariates are generated by strategic behavior?

\end{frame}

\begin{frame}{Example}
Examine this question in a simple model. $n$ individuals have unobserved $Z_i \sim \mbox{Bernoulli}(0.5)$ and $C_i = 0.75$.

\[ X_i(\delta) = Z_i + (1 - Z_i) \mathbbm{1}(\delta(1) - \delta(0) > C_i)  \]
\[ Y_i(W_i) = Z_i W_i + (1- W_i) ( 1- Z_i) \]

Under randomized treatment assignment, so that $\delta^{0}(x) = \frac{1}{2}$:

 \centering
 \includegraphics[width= 0.7\textwidth]{../figures/separated.png}

Objective value $R(\delta^0) = 0.5 $

\end{frame}

\begin{frame} {Targeted Treatments(1) }
From the randomized experiment, we can estimate CATEs:
\[ \hat \tau^0 (x) =  \frac{ \sum \limits_{i=1}^n Y_i \mathbbm 1(X_i = x, W_i =1 ) }{ \sum \limits_{i=1}^n \mathbbm 1(X_i = x, W_i =1)} - \frac{ \sum \limits_{i=1}^n Y_i \mathbbm 1(X_i=x, W_i = 0 )}{ \sum \limits_{i=1}^n \mathbbm 1(X_i = x, W_i =0 ) } \]

\begin{itemize}
\item Under randomized assignment, then $\hat \tau^0(1) = 1$ and $\hat \tau^0(0) = -1$.
\item We might try to improve outcomes by implementing Manski (2004) CES rule: $\delta^c(1) = 1$ and $\delta^c(0) = 0$.
\end{itemize}

\end{frame}

\begin{frame}{Targeted Treatments (2) }

Under $\delta^c(x)$, those with $Z_i = 0$ report $X_i= 1$ in order to receive the treatment which is valuable to them but results in worse outcomes for the planner.

 \centering
 \includegraphics[width= 0.7\textwidth]{../figures/pooled.png}

Objective value $R(\delta^c) = 0.5$

\end{frame}

\begin{frame}{}

\textbf{Problem}: The distribution of $Y_i(\cdot)$ conditional on $x$ now depends on the choice of $\delta(x)$. Correct the notation of the cutoff rule:

\begin{equation*}
\begin{split}
&\tau^{\delta}(x) = \mathbb E[ Y_i(1) - Y_i(0) | X_i = x, \delta(x)] \\
& \delta^c(x) = \mathbbm{1} (\tau^{\delta^c} (x) >0 )
\end{split}
\end{equation*}

\textbf{Question: } Does the optimal targeting rule have this form?
\end{frame}

\begin{frame}{An Optimal Rule }

 \begin{itemize}
 \item $\delta^*(1)  = 0.75$ and $\delta^*(0) = 0$ is optimal
 \item Under this rule, everyone with $X_i = 1$ has a positive CATE, but the planner does not treat them with probability 1 in order to maintain a distribution that is more amenable to targeting.
 \end{itemize}

  \centering
 \includegraphics[width= 0.7\textwidth]{../figures/separated.png}

 Objective value $R(\delta^c) = 0.75$

\end{frame}

\begin{frame} {Finding an Optimal Rule}
\begin{itemize}
\item With exogenous $X_i$, we can randomize $W_i$, estimate CATEs, and treat those with $\tau(x) > 0$. This is no longer possible.
\item How can we estimate the optimal $\delta^*(x)$?
\pause
\item Restrict our attention to treatment rules that are parametrized by $\beta \in \mathbb R^d$
\item We can write the planner objective as
\[ R(\beta) = \mathbb E[r(Y_i, W_i, \beta)] \]

when $Pr(W_i = 1) = \delta(X_i; \beta)$.
\item Goal: design an experiment that performs estimation and inference on
\[ \beta^* = \arg \max_{\beta} R(\beta) \]
\end{itemize}
\end{frame}

\begin{frame}{Experiment Design}

\begin{itemize}
\item We allow the planner to randomize the targeting rule at the individual level
\item With some smoothness assumptions on $R(\beta)$ the simplest experiment would use grid-randomization to find an $\epsilon$-critical point.

\item For some set of candidate $\{ \beta^k \}$ for $k \in [K]$, randomly assign a batch of individuals to each $\beta^k$ and observe the loss for each of them:

\[ \hat R(\beta^k) = \sum \limits_{i=1}^n \mathbbm{1}(\beta_i = \beta^k) r(Y_i, W_i, \beta_i) \]
\item Choose the $\beta^k$ that has the smallest $\hat R(\beta^k)$
\item But this requires a sample size that grows exponentially in the dimension of the parameters $d$
\end{itemize}

\end{frame}

\begin{frame}{Gradient-based Methods}

Let $R_i(W_i) = r(Y_i(W_i), W_i)$. For a continuous covariate, the gradient is as follows:
\footnotesize
\[ \nabla R(\beta) = \mathbb E \left [ \Big (\frac{\partial R_i(W_i) }{ \partial y }[\textcolor{blue}{Y_i (1) - Y_i(0)}] + \textcolor{blue}{ R_i(1) - R_i(0) }\Big) \Big(\frac{\partial \delta(X_i)}{\partial \beta} + \frac{\partial \delta (X_i)}{\partial x}  \textcolor{red}{\frac{\partial X_i}{\partial \beta}} \Big )\right]  \]

\normalsize
\begin{itemize}
\item \textcolor{blue}{Blue} - estimable via a randomized experiment; Black - known in advance by the researcher; \textcolor{red}{Red} - Unknown
\break
\pause
\item Can find local minimum by finding $\beta^*: \nabla R(\beta^*) = 0$
\item Naive risk minimization solves for optimum assuming that $\frac{\partial X_i}{\partial \beta} = 0$
\item Existing literature tends to specify some parametric assumptions on agent behavior so that $ \frac{\partial X_i}{\partial \beta}$ comes from a model (e.g. agents have a quadratic cost of changing their behavior).
\item For general treatment targeting problem, want to be robust to many forms of strategic behavior.
\end{itemize}
\end{frame}

\begin{frame}{Sequential Experiment}

\begin{itemize}
\item For $t = 1, \ldots, T$ periods, a batch of $n$ agents arrive
\item Can be some temporal dependence in agents, but each agent's decision problem is static
\item Start with a naive estimate of $\hat \beta_0$
\item Draw $n$ perturbations $\bm u_i$ from the unit sphere in $\mathbb R^d$
\end{itemize}

\begin{itemize}
\item Let $R_i(\beta) = r(Y_i, W_i, \beta)$.  Update $\hat \beta$ over time using gradient-free stochastic optimization.
\end{itemize}

\[ \hat \beta_t = \hat \beta_{t-1} - \eta_t \hat \nabla R(\hat \beta_{t-1}), \]

where
\[ \hat \nabla R(\beta_{t-1}) = \frac{d}{2n \mu_t} \sum \limits_{i=1}^n R_i(\hat \beta_{t-1} + \mu_t \bm u_i)\bm u_i.  \]

\end{frame}

\begin{frame}{Required Assumptions}

The minimum of $R(\beta)$ is achieved at $\beta^*$. Let $H$ and $S$ be the Hessian and Score matrix at $\beta^*$.

\begin{enumerate}
\item \textbf{Smooth} and \textbf{Strongly Convex}: $R(\beta)$ is twice continuously differentiable and $\lambda I_d \leq \nabla^2 R(\beta) \leq LI_d $ for any $\bm \beta \in \mathbb R^d$ and some $L > \lambda > 0$.

\item $\textbf{Not too large}$: For $0 \leq \delta \leq 2$, $\mathbb E ||\nabla R_i(\beta) - \nabla R(\beta) ||^{2 + \delta} \leq M (|| \beta||^{2 + \delta} + 1)$.
\item $\textbf{Hessian Lipschitz continuous}$:  For any $x, y \in \mathbb R^d$,

\[ \mathbb E || \nabla^2 R_i(\bm x) - \nabla^2 R_i(\bm y) ||^2 \leq L_h || \bm x - \bm y||^2 \]
\end{enumerate}

\end{frame}

\begin{frame}{Conjecture: Convergence Guarantees}
Lemma 1 from Chen et al, 2021:

\begin{lemma}
Set the step size as $\eta_t = \eta t^{-\alpha}$ for $n, \alpha > 0$. Let $\mu_t \leq \mu \eta_t$. For all $\frac{1}{2} < \alpha < 1$, then :

\[ \mathbb E || \hat \beta_t - \beta^* ||^2 \leq Ct^{-\alpha} \]
\end{lemma}
\end{frame}

\begin{frame}{Conjecture: Asymptotic Normality}

Letting $\bar \beta_t = \frac{1}{t} \sum \limits_{i=1}^t \hat \beta_t$, then :

\begin{theorem}
The average random gradient estimator is asymptotically normal
\[ \sqrt t( \bar \beta_t - \beta^*) \rightarrow_d N(0, H^{-1} Q H^{-1}),  \]
where $Q = \frac{d}{n (d+2)} (2S + \mbox{tr}(S) I_d) + \frac{n-1}{n} S$

\end{theorem}

For large $n$, then $Q \approx S$ and then the limiting covariance matrix achieves the Cramer-Rao lower bound. For finite $n$, gradient-free optimization compared to SGD has a higher limiting covariance matrix (\textcolor{blue}{Polyak and Juditsky, 1992}).

\end{frame}

\begin{frame}{Gradient Free Inference}

Through a slightly more complex randomization scheme, it is possible to come up with an estimator for the Hessian based on zero-th order approximations to second derivatives that are averaged over the iterates. This estimator is $\hat H_t$.
\break
For the score matrix,

\[ \hat Q_t = \frac{1}{t} \sum \limits_{i=1}^t \hat \nabla R(\beta_{s-1}) \hat \nabla R(\beta_{s-1})^{\top} \]

In the Chen et al paper:

\[ \mathbb E || \hat H_t^{-1} \hat Q_t \hat H_t^{-1} - H^{-1} Q H^{-1} || \leq C t^{-\alpha/2}\]

\end{frame}

       \begin{frame}{Simulation: Price Discrimination}
\begin{itemize}
    \item Revenue-maximizing planner selling insurance coverage
  \item $\beta = [\delta_0, \delta_1]$, so the price shown to individual $i$ is:
          \[ W_i = \delta(x_i; \beta_i) = \delta_0 + \delta_1x_i \]
\end{itemize}
Individual Outcomes:
  \begin{itemize}
      \item  Individual type $\theta_i$
      \item $Y_i$ is demand for coverage as a function of price  \[Y_i = y(W_i,\theta_i) \]
      \item Pre-treatment features $X_i \in \mathbb R^{d_x}$ might be susceptible to manipulation (ex. self-reported miles driven, self-reported income, browsing history)

      \[ X_i = x(\beta_i, \theta_i) \]
      \end{itemize}
Planner maximizes revenue:
          \[  \beta^* = \arg\max_{\beta} R(\beta) =  E[W_iY_i ] \]
       \end{frame}
\begin{frame}{Simulation (2)}

    \begin{itemize}
    \item Goal: Find profit-maximizing linear pricing rule when agents are strategic
    \item Make some assumptions on DGP so $y$ and $x$ are simple and $x_i$ is correlated with demand for good
    \item Estimate $\beta$ using four different approaches:
    \begin{enumerate}
    \item Full information: Solve for $\beta^*$ directly
    \item Naive Risk Minimization: Assume $x_i$ is i.i.d. and estimate $\hat \beta$ based on sample of data with no manipulation.
    \item Repeated Naive Risk Minimization: Find $\beta$ that is optimal based on latest batch of data, assuming $x_i$ is i.i.d each time.
    \item Dynamic Experiment
    \end{enumerate}
    \item Plot estimated amount of price discrimination  of each approach at each of $t=1, \ldots, 500$ steps when batch of $n=1000$ agents arrive at each step
    \end{itemize}
\end{frame}

\begin{frame}{Simulation: Finding Optimal $p_1$}
\begin{figure}
    \centering
    \includegraphics[width=1\textwidth]{../figures/price_disc.pdf}
    \caption{Converge of Dynamic Experiment to Optimal Solution}
\end{figure}
\end{frame}

\begin{frame}{Simulations: Regret}
\begin{table}
    \centering
    \begin{tabular}{| c|r | }
    \hline
        \textbf{Method} & \textbf{Regret} \\
        \hline
         Full Information &  0.00  \\
         Iterative Learning & -0.19 \\
         Repeated Naive Risk Minimization  & -24.38 \\
         Naive Risk Minimization & -48.40 \\
         \hline
    \end{tabular}
    \caption{Average Regret}
    \end{table}
\end{frame}

\begin{frame}{Example 2: Prediction with Strategic Agents}

\begin{itemize}
\item Objective is minimizing prediction error when predicting target based on manipulable features: $r(W_i, Y_i) = (W_i - Y_i)^2$:
\item Treatment $w_i = \beta x_i$ is the prediction of $Y_i$
\item  $Y_i$ is target characteristic that is unobserved initially
\item $X_i \in \mathbb R^k$ is observed features used to predict target characteristic       \end{itemize}
\end{frame}

\section{Experiment}
\begin{frame}{MTurk Experiment }

\begin{itemize}
    \item Treatment is linear prediction of how much a respondent likes math (1-5) from whether or not they get a factoring question correct

    \[ LikeMath_i = \beta_0 + \beta_1 Correct_i + \epsilon_i \]
    \item Goal is finding prediction-error minimizing treatment allocation function when respondents have varying incentives to fill out the factoring question
\end{itemize}

\centering
\includegraphics[width = \textwidth]{figures/incentive.png}
\begin{itemize}
    \item In the baseline survey, there is no bonus payment
\end{itemize}

\end{frame}

\begin{frame}{Distribution Shift}
\begin{table}[ht]
\centering
\begin{tabular} {|l | r c c |}
\hline
 & \textbf{No Incentive} & \textbf{50 Cents Bonus}
 & \textbf{100 Cents Bonus}\\
 \hline
\hline
\textbf{Variable} & \textbf{Mean (s.d.)}& \textbf{Mean (s.d.)} & \textbf{Mean (s.d.)} \\
\hline
$LikeMath$ & 3.16 (1.20) & 3.10 (1.14) &  3.16 (1.26)  \\
$MathSkill$ & 3.18 (1.04) & 3.09 (1.06) & 3.12 (1.06)\\
$Education$ & 15.54 (2.09) & 15.57 (2.37) & 15.43 (2.14) \\
$Correct$  & 0.41 (0.49) & 0.46 (0.50)& 0.59 (0.49)  \\
\hline
\hline
\textbf{Outcome} & \textbf{Coef (s.d.)} & \textbf{Coef (s.d.)} & \textbf{Coef (s.d.)} \\
\hline
$\hat \beta_0$ & 2.88 (0.08) & 2.85 (0.08) & 2.84 (0.10) \\
$\hat \beta_{1}$ &  0.689 (0.13) & 0.552 (0.13) & 0.547 (0.14) \\
\hline
\end{tabular}
\caption{Summary Statistics for Survey Waves ($n = 316$)}
\label{tab:data}
\end{table}
\end{frame}

\begin{frame}{Prediction Analysis }

\begin{itemize}
\item Treatment allocation for waves with bonus payment:
\[ w(\bm X_i; \beta) = 1.45\cdot \beta_1 \cdot Correct_i \]
\end{itemize}
\begin{enumerate}
\item In-sample $R^2$ for naive RM, for sample without a bonus
\item Out-of-sample $R^2$ for naive RM, for a sample without a bonus
\item Out-of-sample $R^2$ for naive RM, for a sample with a targeted bonus
\item Out-of-sample $R^2$ for OT-DE step, for a sample with a targeted bonus
\end{enumerate}
\end{frame}

\begin{frame}{Experimental Step}

 \centering
    \begin{tabular}{| l |r r | r r |  r | }
    \hline
      & \textbf{Naive RM}  & \textbf{Gradient} & \textbf{RRM} & \textbf{ Gradient} & \textbf{ Step}  \\
      \hline
      $\hat \beta_0$ & 2.88 & -0.19 & 2.84 & 0.01 & 2.89\\
      $\hat \beta_1$ & 0.69 & -0.46 & 0.55 &  1.24 & 0.60\\
      \hline
    \end{tabular}

\end{frame}

\begin{frame}{Impact on $R^2$}
\begin{figure}[ht]
    \centering
    \includegraphics[width=0.7\textwidth]{figures/r2exp}
    \caption{$R^2$ of Prediction Rules for Different Settings ($n=300$ for each out-of-sample evaluation) }
    \label{fig:exp_mse}
\end{figure}

\end{frame}

\begin{frame}{Conclusion}
 \begin{itemize}
        \item Propose adaptive experiment for designing optimal and robust targeting rules (ex. classification functions, heterogeneous pricing and heterogeneous credit allocation)
        \item Theoretical, simulation-based and empirical evidence that this works well
    \end{itemize}
    Key takeaways
 \begin{enumerate}
 \item  Modeling incentives matters. CATE-based approaches that ignore endogeneity of covariates are sub-optimal.
  \item A dynamic approach is useful for solving the problem with minimal assumptions
 \item Estimating the optimal policy requires randomizing the dependence of treatments on observed characteristics.
  \item Combining the flexibility of statistical optimization approaches with economic models of incentives is useful for estimating robust policy
 \end{enumerate}
\end{frame}

\appendix

\begin{frame}[allowframebreaks]{References}
    \bibliography{sample}
\end{frame}
\end{document}

max_stars_repo_name: evanmunro/personalized-policy

max_issues_repo_name: evanmunro/personalized-policy

max_forks_repo_name: evanmunro/personalized-policy


text:
% Tento soubor nahraďte vlastním souborem s přílohami (nadpisy níže jsou pouze pro příklad)
% This file should be replaced with your file with an appendices (headings below are examples only)

% Umístění obsahu paměťového média do příloh je vhodné konzultovat s vedoucím
% Placing of table of contents of the memory media here should be consulted with a supervisor
%\chapter{Obsah přiloženého paměťového média}

\chapter{CD Content}
\label{CD Content}

\begin{itemize}
  \item \textbf{/maestro-java/*}\,---\,source code of Maestro from date \today
  \item \textbf{/iqa-topology-generator/*}\,---\,source code of Topology Generator from date \today
  \item \textbf{/doc/*}\,---\,Maestro documentation
  \item \textbf{/readme.txt}\,---\,readme with useful informations about Maestro build and start
  \item \textbf{/text/*}\,---\,source code of this thesis from date \today
  \item \textbf{/xstejs24-performance.pdf}\,---\,final version of this thesis from date \today
\end{itemize}

\chapter{The Maestro Protocol}
\label{AP:commands}
The following commands were updated according the Maestro 1.3.0 version\footnote{Original commands description for MPT is available at \url{https://github.com/orpiske/msg-perf-tool/tree/master/doc/maestro/protocol}}:

\section*{Requests Notes}
\begin{description}
  \setlength\itemsep{0em}
  \item \textbf{MAESTRO\_NOTE\_START\_RECEIVER}\,---\,note to the receiver, that it should start receiving data.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 0
    \item Payload: None
    \item Response: the peers respond to this note by sending a MAESTRO\_NOTE\_OK or MAESTRO\_NOTE\_INTERNAL\_ERROR
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_STOP\_RECEIVER}\,---\,note to the receiver, that it should stop receiving data.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 1
    \item Payload: None
    \item Response: the peers respond to this note by sending a MAESTRO\_NOTE\_OK or MAESTRO\_NOTE\_INTERNAL\_ERROR
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_START\_SENDER}\,---\,note to the sender, that it should start sending data.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 2
    \item Payload: None
    \item Response: the peers respond to this note by sending a MAESTRO\_NOTE\_OK or MAESTRO\_NOTE\_INTERNAL\_ERROR
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_STOP\_SENDER}\,---\,note to the sender, that it should stop sending data.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 3
    \item Payload: None
    \item Response: the peers respond to this note by sending a MAESTRO\_NOTE\_OK or MAESTRO\_NOTE\_INTERNAL\_ERROR
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_START\_INSPECTOR}\,---\,note to the inspector, that it should start inspecting the SUT.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 4
    \item Payload: None
    \item Response: the peers respond to this note by sending a MAESTRO\_NOTE\_OK or MAESTRO\_NOTE\_INTERNAL\_ERROR
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_STOP\_INSPECTOR}\,---\,note to the inspector, that it should stop inspecting the SUT.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 5
    \item Payload: None
    \item Response: the peers respond to this note by sending a MAESTRO\_NOTE\_OK or MAESTRO\_NOTE\_INTERNAL\_ERROR
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_FLUSH}\,---\,note to the any node to request it to flush test data to disk.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 6
    \item Payload: None
    \item Response: the peers respond to this note by sending a MAESTRO\_NOTE\_OK or MAESTRO\_NOTE\_INTERNAL\_ERROR
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_SET}\,---\,note to the any node to set the testing properties.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 7
    \item Payload: the test parameters such as TEST\_DURATION, PARALLEL\_COUNT, MESSAGE\_SIZE, RATE, etc.
    \item Response: the peers respond to this note by sending a MAESTRO\_NOTE\_OK or MAESTRO\_NOTE\_INTERNAL\_ERROR
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_STATS}\,---\,note to the any node to request the current performance statistics.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 8
    \item Payload: None
    \item Response: the peers respond to this note by sending a MAESTRO\_NOTE\_OK or MAESTRO\_NOTE\_INTERNAL\_ERROR
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_HALT}\,---\,note to the any node to request them to stop and exit cleanly.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 9
    \item Payload: None
    \item Response: the peers respond to this note by sending a MAESTRO\_NOTE\_OK or MAESTRO\_NOTE\_INTERNAL\_ERROR
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_PING}\,---\,note to the any node to verify which peers are alive in the cluster.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 10
    \item Payload: seconds or microseconds.
    \item Response: the peers respond to this note by sending a MAESTRO\_NOTE\_OK or MAESTRO\_NOTE\_INTERNAL\_ERROR
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_GET}\,---\,note to the peers to get informations about the test.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 17
    \item Payload: None
    \item Response:
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_START\_AGENT}\,---\,note to the agent, that it should start executing external handlers.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 18
    \item Payload: None
    \item Response: the peers respond to this note by sending a MAESTRO\_NOTE\_OK or MAESTRO\_NOTE\_INTERNAL\_ERROR
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_STOP\_AGENT}\,---\,note to the agent, that it should stop executing external handlers.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 19
    \item Payload: None
    \item Response: the peers respond to this note by sending a MAESTRO\_NOTE\_OK or MAESTRO\_NOTE\_INTERNAL\_ERROR
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_AGENT\_SOURCE}\,---\,note to the agent, that it should download external source defined in the payload.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 21
    \item Payload: URL for external git repository which the Agent will download.
    \item Response: the peers respond to this note by sending a MAESTRO\_NOTE\_OK or MAESTRO\_NOTE\_INTERNAL\_ERROR
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_USER\_COMMAND\_1}\,---\,note to the agent, that it should execute command specified in the payload. The command should be present in external git repository downloaded by MAESTRO\_NOTE\_AGENT\_SOURCE.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 30
    \item Payload: Command which will be executed in string format.
    \item Response: the peers respond to this note by sending a MAESTRO\_NOTE\_OK or MAESTRO\_NOTE\_INTERNAL\_ERROR
  \end{itemize}
\end{description}

\section*{Response Notes}
\begin{description}
  \setlength\itemsep{0em}
  \item \textbf{MAESTRO\_NOTE\_STATS}\,---\,is sent by a node as a response to a MAESTRO\_NOTE\_STATS request.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 8
    \item Payload: yes
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_PING}\,---\,is sent by the peers as a response to a MAESTRO\_NOTE\_PING request.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 10
    \item Payload: yes
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_OK}\,---\,is a generic response when the node complies with a request.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 11
    \item Payload: None
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_PROTOCOL\_ERROR}\,---\,is issued by any node whenever the protocol is malformed.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 12
    \item Payload: None
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_INTERNAL\_ERROR}\,---\,is issued by any node when it is unable to comply with a request.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 13
    \item Payload: None
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_ABNORMAL\_DISCONNECT}\,---\,is issued by any node as a last-will message.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 14
    \item Payload: None
  \end{itemize}
\end{description}

\section*{Notify Notes}
\begin{description}
  \setlength\itemsep{0em}
  \item \textbf{MAESTRO\_NOTE\_NOTIFY\_FAIL}\,---\,is issued by any node when the test failed.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 15
    \item Payload: yes
  \end{itemize}
  \item \textbf{MAESTRO\_NOTE\_NOTIFY\_SUCCESS}\,---\,is issued by any node when the test completed successfully.
  \begin{itemize}
    \setlength\itemsep{0em}
    \item Value: 16
    \item Payload: yes
  \end{itemize}
\end{description}

\chapter{Topology Generator} % Configuration filenechce

\section*{Inventory}
\label{AP:Inventory}
The following is an example of Inventory file used as an input for Topology Generator and Ansible deployment scripts. The inventory lists all the nodes and their role in the topology.

\begin{verbatim}
[clients]
sender ansible_host=10.0.0.1
receiver ansible_host=10.0.0.2

[routers]
router1 ansible_host=10.0.0.3
router2 ansible_host=10.0.0.4

[brokers]
broker1 ansible_host=10.0.0.5

[nodes:children]
brokers
clients
routers
\end{verbatim}

\section*{Graph Metadata}
\label{AP:Graph Metadata}
The example of graph metadata file for Topology Generator is as follows. For this case Generator will generate graph with two routers and three brokers, where routers are connected together and each broker is connected to one router.

\begin{verbatim}
---
directed: false
graph: {}
nodes:
- type: router						%node type
  id: router1						%node name
- type: router
  id: router2
- type: broker
  id: broker1
- type: broker
  id: broker2
links:
- source: router2					%source node for link
  target: router1					%target node for link
- source: router2
  target: broker2
- source: router1
  target: broker1
multigraph: false
\end{verbatim}

\section*{Topology Generator Output}
\label{AP:Topology Generator Output}
The example of Topology Generator output in YAML format. This output is for two directly connected routers.

\begin{verbatim}
---
confs:
- machine: router1
  router:
  - id: router1
    mode: standalone
  listener:
  - host: 0.0.0.0
    role: inter-router
    port: 6000
  - host: 0.0.0.0
    authenticatePeer: 'no'
    role: normal
    port: 5000
    saslMechanisms: ANONYMOUS
  connector:
  - host: router2
    role: inter-router
    port: 6001
  address:
  - prefix: closest
    distribution: closest
  - prefix: multicast
    distribution: multicast
  - prefix: unicast
    distribution: closest
- machine: router2
  router:
  - id: router2
    mode: standalone
  listener:
  - host: 0.0.0.0
    role: inter-router
    port: 6001
  - host: 0.0.0.0
    authenticatePeer: 'no'
    role: normal
    port: 5001
    saslMechanisms: ANONYMOUS
  connector:
  - host: router1
    role: inter-router
    port: 6000
  address:
  - prefix: closest
    distribution: closest
  - prefix: multicast
    distribution: multicast
  - prefix: unicast
    distribution: closest

\end{verbatim}

\section*{Qpid-Dispatch Configuration File Template}
\label{AP:Qpid-Dispatch Configuration File Template}
The template for configuration files for current version of Qpid-Dispatch is generated by \emph{qdrouter-jinja2} tool which is open-source and available at \url{https://github.com/rh-messaging-qe/qdrouter-jinja2}.

Since the template is file with approximately 600 lines, the model template for Qpid-Dispatch version 1.0.0 is available at \url{https://github.com/rh-messaging-qe/ansible-qpid-dispatch/blob/master/test/files/templates/qdrouterd-roland.conf.j2}.

\section*{Topology Generator Source Code}
\label{AP:Topology Generator Source Code}
The complete source code of Topology Generator is available at:
\begin{itemize}
  \item \url{https://github.com/rh-messaging-qe/iqa-topology-generator}
  \item \url{https://pypi.org/project/msg-topgen/#description}
\end{itemize}

\chapter{AMQP Inspector Data Sets}
\label{AMQP Inspector Data Sets}
The following represents headers for data files with AMQP Inspector collected data. The data file structure depends on the AMQP Inspector request.

\section*{General Info}
\begin{itemize}
  \setlength\itemsep{0em}
  \item \textbf{Timestamp}\,---\,timestamp when the data was collected.
  \item \textbf{Name}\,---\,name of the router.
  \item \textbf{Version}\,---\,version of the router.
  \item \textbf{LinkRoutes}\,---\,number of active link routes.
  \item \textbf{AutoLinks}\,---\,number of active auto links.
  \item \textbf{Links}\,---\,number of active links.
  \item \textbf{Nodes}\,---\,number of active neighbour nodes.
  \item \textbf{Addresses}\,---\,number of active addresses.
  \item \textbf{Connections}\,---\,number of active connections.
\end{itemize}

\section*{Memory Info}
\begin{itemize}
  \setlength\itemsep{0em}
  \item \textbf{Timestamp}\,---\,timestamp when the data was collected.
  \item \textbf{Name}\,---\,name of the memory space.
  \item \textbf{Size}\,---\,type size.
  \item \textbf{Batch}\,---\,transfer batch size.
  \item \textbf{Thread-max}\,---\,maximum allocated for thread.
  \item \textbf{Total}\,---\,totally allocated memory.
  \item \textbf{In-threads}\,---\,memory held by threads.
  \item \textbf{Rebal-in}\,---\,batches rebalanced to threads.
  \item \textbf{Rebal-out}\,---\,batches rebalanced to global.
  \item \textbf{totalFreeToHeap}\,---\,total free to heap.
  \item \textbf{globalFreeListMax}\,---\,global free list max.
\end{itemize}

\section*{RouteLink Info}
\begin{itemize}
  \setlength\itemsep{0em}
  \item \textbf{Timestamp}\,---\,timestamp when the data was collected.
  \item \textbf{Name}\,---\,name of the route link.
  \item \textbf{LinkDir}\,---\,intput link or output link.
  \item \textbf{OperStatus}\,---\,current status.
  \item \textbf{Identity}\,---\,identification.
  \item \textbf{DeliveryCount}\,---\,number of delivered messages.
  \item \textbf{UndeliveredCount}\,---\,number of undelivered messages.
  \item \textbf{PresettledCount}\,---\,number of presettled messages.
  \item \textbf{UnsettledCount}\,---\,number of unsettled messages.
  \item \textbf{ReleasedCount}\,---\,number of released messages.
  \item \textbf{ModifiedCount}\,---\,number of modified messages.
  \item \textbf{AcceptedCount}\,---\,number of accepted messages.
  \item \textbf{RejectedCount}\,---\,number of rejected messages.
  \item \textbf{Capacity}\,---\,route link capacity.
\end{itemize}

\chapter{Experimental Evaluation Additional Data}
\label{Experimental Evaluation Additional Data}

\section*{Throughput}
The Qpid-Dispatch need some time to evaluate the messages and send them to the receiver. In the Figure \ref{fig:router-single-routerLink} we can see the histogram of unsettled messages during the singlepoint throughput test. This charts shows the number off received messages, which are not yet evaluated. Note, that throughput is around 90,000 messages per second.

The flow-control mechanism mentioned in the Subsection \ref{Throughput} also affected the unsettled message count, which is multiple times higher than in the previous test case depicted in the Figure \ref{fig:router-single-routerLink}. The unsettled message count is depicted in the Figure \ref{fig:router-multipoint-routerLink}.

\begin{figure}[H]
	\centering
	\begin{minipage}{0.49\linewidth}
		\subfloat[Single router node.\label{fig:router-single-routerLink}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/singlepoint-router-throughput-routerLink.pdf}}
	\end{minipage}
	\begin{minipage}{0.49\linewidth}
		\subfloat[Line topology node.\label{fig:router-multipoint-routerLink}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/multipoint-router-only-throughput-routerLink.pdf}}
	\end{minipage}
	\caption[Examples of experimental topologies created for basic performance testing and experiments with Maestro.]{Examples of experimental topologies created for basic performance testing and experiments with Maestro.}
  \label{fig:routerLink-throughput}
\end{figure}

\section*{Latency}

Unsettled messages for the router available in the Figure \ref{fig:latency-router-routerLink}. From the Inspector outputs one can see, that the Broker handled 10,000,000 messages in more than 7\,minutes, but the router handled the same amount of messages much faster approximately in 2\,minutes and 20\,seconds.

Since the router applies the flow control during this measurement and the rate is setup to 80\,\% of maximum, the unsettled message count is here much lower than in the other cases as it is depicted in the Figure \ref{fig:latency-multiple-router-routerLink}.

\begin{figure}[H]
	\centering
	\begin{minipage}{0.49\linewidth}
		\subfloat[Single router node.\label{fig:latency-router-routerLink}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/singlepoint-router-latency-routerLink.pdf}}
	\end{minipage}
	\begin{minipage}{0.49\linewidth}
		\subfloat[Line topology node.\label{fig:latency-multiple-router-routerLink}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/multipoint-router-only-latency-routerLink.pdf}}
	\end{minipage}
	\caption[Examples of experimental topologies created for basic performance testing and experiments with Maestro.]{Examples of experimental topologies created for basic performance testing and experiments with Maestro.}\label{fig:routerLink-latency}
\end{figure}

\section*{Measurement With Redundant Router}

\begin{figure}[h]
	\centering
	\begin{minipage}{0.49\linewidth}
		\subfloat[Restart\label{fig:restart-redundant-agent-memory}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/restart-redundant-agent-memory.pdf}}
	\end{minipage}
	\begin{minipage}{0.49\linewidth}
		\subfloat[10 seconds shutdown\label{fig:shutdown_10-redundant-agent-memory}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/shutdown_10-redundant-agent-memory.pdf}}
	\end{minipage}
  \begin{minipage}{0.49\linewidth}
		\subfloat[60 seconds shutdown\label{fig:shutdown_60-redundant-agent-memory}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/shutdown_60-redundant-agent-memory.pdf}}
	\end{minipage}
	\begin{minipage}{0.49\linewidth}
		\subfloat[120 seconds shutdown\label{fig:shutdown_120-redundant-agent-memory}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/shutdown_120-redundant-agent-memory.pdf}}
	\end{minipage}
	\caption[Collected data about the memory allocation for the redundant router node during the Agent actions execution.]{Collected data about the memory allocation for the redundant router node during the Agent actions execution.}\label{fig:redundant-memory-info}
\end{figure}

\begin{figure}[h]
	\centering
	\begin{minipage}{0.49\linewidth}
		\subfloat[Restart\label{fig:restart-redundant-agent-routerLink}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/restart-redundant-agent-routerLink.pdf}}
	\end{minipage}
	\begin{minipage}{0.49\linewidth}
		\subfloat[10 seconds shutdown\label{fig:shutdown_10-redundant-agent-routerLink}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/shutdown_10-redundant-agent-routerLink.pdf}}
	\end{minipage}
  \begin{minipage}{0.49\linewidth}
		\subfloat[60 seconds shutdown\label{fig:shutdown_60-redundant-agent-routerLink}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/shutdown_60-redundant-agent-routerLink.pdf}}
	\end{minipage}
	\begin{minipage}{0.49\linewidth}
		\subfloat[120 seconds shutdown\label{fig:shutdown_120-redundant-agent-routerLink}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/shutdown_120-redundant-agent-routerLink.pdf}}
	\end{minipage}
	\caption[Collected data about the unsettled messages for the redundant router node during the Agent actions execution.]{Collected data about the unsettled messages for the redundant router node during the Agent actions execution.}\label{fig:routerLink-latency}
\end{figure}

\begin{figure}[h]
	\centering
	\begin{minipage}{0.49\linewidth}
		\subfloat[Restart\label{fig:restart-redundant-agent-delivered}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/restart-redundant-agent-delivered.pdf}}
	\end{minipage}
	\begin{minipage}{0.49\linewidth}
		\subfloat[10 seconds shutdown\label{fig:shutdown_10-redundant-agent-delivered}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/shutdown_10-redundant-agent-delivered.pdf}}
	\end{minipage}
  \begin{minipage}{0.49\linewidth}
		\subfloat[60 seconds shutdown\label{fig:shutdown_60-redundant-agent-delivered}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/shutdown_60-redundant-agent-delivered.pdf}}
	\end{minipage}
	\begin{minipage}{0.49\linewidth}
		\subfloat[120 seconds shutdown\label{fig:shutdown_120-redundant-agent-delivered}]{\includegraphics[width=\linewidth]{obrazky-figures/charts/shutdown_120-redundant-agent-delivered.pdf}}
	\end{minipage}
	\caption[Collected data about the delivered messages for the redundant router node during the Agent actions execution.]{Collected data about the delivered messages for the redundant router node during the Agent actions execution.}\label{fig:routerLink-latency}
\end{figure}

%\chapter{RelaxNG Schéma konfiguračního souboru} % Scheme of RelaxNG configuration file

%\chapter{Plakát} % poster

max_stars_repo_name: Frawless/Master-thesis

max_issues_repo_name: Frawless/Master-thesis

max_forks_repo_name: Frawless/Master-thesis


text:
% Acknowledgements

\pdfbookmark[1]{Acknowledgements}{Acknowledgements} % Bookmark name visible in a PDF viewer

\begin{flushright}{\slshape
We have seen that computer programming is an art, \\
because it applies accumulated knowledge to the world, \\
because it requires skill and ingenuity, and especially \\
because it produces objects of beauty.} \\ \medskip
--- \defcitealias{knuth:1974}{Donald E. Knuth}\citetalias{knuth:1974} \citep{knuth:1974}
\end{flushright}

\bigskip

%----------------------------------------------------------------------------------------

\begingroup

\let\clearpage\relax
\let\cleardoublepage\relax
\let\cleardoublepage\relax

\chapter*{Acknowledgements}

\noindent Put your acknowledgements here.\\

\noindent Many thanks to everybody who already sent me a postcard!\\

\noindent Regarding the typography and other help, many thanks go to Marco Kuhlmann, Philipp Lehman, Lothar Schlesier, Jim Young, Lorenzo Pantieri and Enrico Gregorio\footnote{Members of GuIT (Gruppo Italiano Utilizzatori di \TeX\ e \LaTeX )}, J\"org Sommer, Joachim K\"ostler, Daniel Gottschlag, Denis Aydin, Paride Legovini, Steffen Prochnow, Nicolas Repp, Hinrich Harms, Roland Winkler, and the whole \LaTeX-community for support, ideas and some great software.

\bigskip

\noindent\emph{Regarding \mLyX}: The \mLyX\ port was initially done by
\emph{Nicholas Mariette} in March 2009 and continued by
\emph{Ivo Pletikosi\'c} in 2011. Thank you very much for your work and the contributions to the original style.

\endgroup

max_stars_repo_name: pranav-ust/ir-heuristics

max_issues_repo_name: pranav-ust/ir-heuristics

max_forks_repo_name: pranav-ust/ir-heuristics