%!TEX root = istgame-doc.tex %\begin{document} \setcounter{section}{-1} \section{Changes and remarks} \subsection{Changes in version 2.1} \label{ssec:changes2.1} Version 2.1 of the \pkg{istgame} package introduces a starred version of the \env{istgame} environment, some new macros, and some examples added to the documentation. \paragraph {The starred version of \env{istgame} environment:} The \emph{new} starred version of the \env{istgame} environment is essentially the same as the \env{tikzpicture} environment. \begin{itemize} \item The standard version of \env{istgame} environment checks the existence of \Tikz\ scaling and the arrow option |->|, and uses the collected information to automatically get the best results. (See Section~\ref{ssec:envistgame} on page~\pageref{ssec:envistgame} for more details.) \item |\begin{istgame}*| may be slightly faster than |\begin{istgame}| as it does not collect this information. \item However, using |\begin{istgame}*| may require some manual work to get desired results, especially for asymmetric \Tikz\ scaling (i.e. when |xscale| is not the same as |yscale|). \item With |\begin{istgame}*|: \begin{itemize} \item |\xtxscale|, |\xtyscale|, and |\xtscale| have no effect. \item |\xtcureslopedlabelsNS| and |\xtcureslopedlabelsEW| do nothing. \item The oval type information sets |\xtInfosetO|, |\xtCIfnosetO|, and |\cntmAInfosetO| may be distorted. \item |\setistgamefontsize| and |\setistgameshorten| have no effect. \item The initial \Tikz\ arrow style (but not |>=stealth|) is used. \end{itemize} %\end{istgame} %\end{tikzpicture} %\end{istgame} %\end{istgame} %\end{istgame} \end{itemize} It is recommended to use the standard \env{istgame} environment, when you use the oval type information sets and sloped labels with \Tikz\ scaling. \emph{In all other cases}, |\begin{istgame}*| and |\begin{istgame}| will give you the \emph{same results} in drawing tree structures (except for the default arrow style). \xbigskip1 Here are some examples to show that the \env{istgame} environment can automatically achieve the best results. \begin{doccode}{.3} % asymmetric scaling: distorted oval information sets \begin{istgame}*[xscale=1.5,yscale=.9] % starred \setistgrowdirection'{south east} \istroot(0) \istb \istb* \endist \istroot(1)(0-1){2} \istb* \istb* \endist \xtInfosetO[fill=red!20,ellipse](0)(0-2){1} \xtInfosetO(1)(1) \xtInfosetO[fill=blue!40,opacity=.5] (1-1)(1-2){3}(1.5em) \end{istgame} \end{doccode} \begin{doccode}{.3} % Oval information sets do not depend on scaling \begin{istgame}[xscale=1.5,yscale=.9] \setistgrowdirection'{south east} \istroot(0) \istb \istb* \endist \istroot(1)(0-1){2} \istb* \istb* \endist \xtInfosetO[fill=red!20,ellipse](0)(0-2){1} \xtInfosetO(1)(1) \xtInfosetO[fill=blue!40,opacity=.5] (1-1)(1-2){3}(1.5em) \end{istgame} \end{doccode} The \Tikz's |tree| library does not seem to deal with the sloped labels correctly in the case of asymmetric scaling. (See page~\pageref{page:slopedlabels-warning} for more details.) \begin{doccode}{.3} % tikz tree's sloped labels problem: \begin{istgame}*[xscale=2,font=\footnotesize] % starred \xtcureslopedlabelsNS % does nothing \istroot(0) \istb[dashed,thick]{Left}[above,sloped] \istb[->]{Center}[above,sloped] \istb[draw=blue,thick]{Right}[above,sloped] \endist \end{istgame} \end{doccode} The macro |\xtcureslopedlabelsNS| solves this problem only when you use the standard version of \env{istgame}. \begin{doccode}{.3} % tikz tree's sloped labels problem: solved \begin{istgame}[xscale=2,font=\footnotesize] \xtcureslopedlabelsNS \istroot(0) \istb[dashed,thick]{Left}[above,sloped] \istb[->]{Center}[above,sloped] \istb[draw=blue,thick]{Right}[above,sloped] \endist \end{istgame} \end{doccode} \paragraph{New macros to set the default node sizes:} In order to change the size of basic nodes, new macros \icmd{\setistsolidnodesize}, \icmd{\setisthollownodesize}, \icmd{\setistellipsenodesize}, and \icmd{\setistrectanglenodesize} are introduced. You can use these macros outside of the \env{istgame} environment (or in the preamble) to change the default node size globally. In the following example you can see the effect of |\setistsolidnodesize{.5\pgflinewidth}|. The default size of a |solid| node is |2.4pt|. \begin{doccode}[text above listing] % \setistsolidnodesize \begin{istgame} \istroot(0)(0,0) \istb* \istb* \istb* \endist \istroot(c)(0-3) \istb* \istb* \endist \setistsolidnodesize{.5\pgflinewidth} % solid node size changed \istroot(0)(6,0) \istb* \istb* \istb* \endist \istroot(c)(0-3) \istb* \istb* \endist \end{istgame} \end{doccode} \paragraph{Some more:} The update to version 2.1 includes a few bug fixes and minor changes. (See the version history on page~\pageref{version-history}.) The \Tikz\ libraries |arrows.meta| and |bending| are added to the the list of preloaded |tikz| libraries. You can see some examples of arrow tips from |arrows.meta| in Section~\ref{ssec:setxtarrowtips} on page~\pageref{ssec:setxtarrowtips}. \subsection{Changes in version 2.0} Some macros have been \textsc{changed} and \textsc{removed} in version 2.0. Those who have used these changed and removed macros may want to \textsc{find} and \textsc{replace} the followings: %\begin{center} %\begin{tabu} {X[l1.5]X[l1.5]} \toprule %to .5\linewidth %\makecell[l]{\textbf{ver. 1.0}} & \makecell[l]{\textbf{ver. 2.0 or later}} \\\midrule %|\istb.| & |\istbt| \\\tabucline- %|\xtInfoset'| & |\xtInfoset| \\\tabucline- %|\xtInfosetO'| & |\xtInfosetO| \\\tabucline- %|\setistgrowkey| & |\setxtgrowkey| \\\tabucline- %\end{tabu} %\end{center} \begin{center} \begin{tabular} {lll} \toprule \makecell[l]{\textbf{ver. 1.0}} & \makecell[l]{\textbf{ver. 2.0 or later}} \\\midrule |\istb.| & |\istbt| \\\cline{1-2} |\xtInfoset'| & |\xtInfoset| \\\cline{1-2} |\xtInfosetO'| & |\xtInfosetO| \\\cline{1-2} |\setistgrowkey| & |\setxtgrowkey| \\\cline{1-2} \end{tabular} \end{center} \paragraph{Changed and removed macros} \begin{itemize}\tightlist \item The macro name |\istb.|(terminal version) has been changed to |\istbt| (terminal version). \begin{itemize} \item This is the opportunity cost of having a new macro |\istB| (dual action label version). \end{itemize} \item The two (unsatisfactory) macros |\xtInfoset'| and |\xtInfosetO'| have been removed. \begin{itemize} \item The macro |\xtInfosetO| is completely redesigned, so that we do not need the macro |\xtInfosetO'| any more. \item No reasons could be found to keep (even for the backward compatibility) the swap versions |\xtInfoset'| and |\xtInfosetO'|, except for the inconvenience to do `find and replace.' \end{itemize} \item|\setistgrowkey| is renamed to |\setxtgrowkey| for consistency in macro naming. \end{itemize} \paragraph{Redesigned macros and the environment} \begin{itemize}\firmlist \item |\xtInfosetO| is completely redefined to improve its function: \begin{itemize} \item Now a \emph{sloped} information set is possible. \item It connects two nodes like |\xtInfosetO(coor1)(coor2)|, but if the two coordinates are identical it represents a \emph{singleton information set} by a \emph{circle} by default. \item This change does not seem to cause much harm, but be aware that the swap version |\xtInfosetO'| has been removed and replaced by |\xtInfosetO|. \item Be aware also that the way to change the \emph{height} (|1em| by new default) of an information set has been \emph{changed}, though you might not see much difference if you have only used the default information sets. \item With \emph{new macros} |\xtCInfoset| and |\xtCInfosetO|, a curved (even skewed curved) information set is now possible. \end{itemize} \item \env{istgame} environment: (internal change) \begin{itemize} \item Now the each value of the option of |xscale| and |yscale|, if exists, is extracted and saved at |\xtxscale| and |\xtyscale|, respectively. The value of |scale| is also saved at |\xtscale| only when it is used without |xscale| nor |yscale|. These values are internally used to get the best outputs of trees in many ways. \item If the \Tikz\ arrow option |->| exists in the option list of an \env{istgame} environment, you can globally control the arrow-end-shorten value (by default, |shorten >=0pt|) by using a new macro |\setistgameshorten|. This is to get a better result of branches with arrows. \end{itemize} \item Some changes that you might not notice have been made, including: \begin{itemize} \item The core macros |\istroot|, |\istb|, and |\endist| have literally been redefined for some purposes, but this makes no difference to users. \item The options |thin| and |solid| have been added to the definitions of basic node styles. \item Some default values have been slightly changed. \end{itemize} \end{itemize} \subsection{What's new in version 2.0} \paragraph{Some new functions} \begin{itemize}\tightlist \item \emph{input mode changer} (math or text) for important labels: owners, action labels, and payoffs \begin{itemize}\tightlist \item |\setistmathTF| as an input mode changer for the important labels \item |\setistmathTF*| having additional functions as a \emph{text font style changer} \end{itemize} \item \emph{curved} (even \emph{skewed}) \emph{information sets} \begin{itemize}\tightlist \item |\xtCInfoset| for curved information sets \item |\xtCInfosetO| for curved bubble type information sets \end{itemize} \item enhanced \emph{continuum of branches} (making |\istcntm| and |\istcntmarc| obsolete) \begin{itemize}\tightlist \item |\istrootcntm| for a continuum triangle \item |\istrootcntmA| for a continuum arc (with |\istbA|) \item |\cntmAInfoset| and |\cntmAInfosetO| for information sets for a continuum of branches \end{itemize} \item \emph{arrows} and \emph{middle arrows} on branches \begin{itemize}\tightlist \item controllable arrow option |->-| with |\setxtarrowtips| and middle arrow tip styles \item |\xtShowMidArrows| and |\xtShowArrows| \end{itemize} \item and some more \begin{itemize} \item |\istB| for dual action labels \item |\xtTimeLineH|, |\xtTimeLineV|, |\xtCommentTo|, |\xtCommentFrom|, etc. \end{itemize} \end{itemize} \paragraph{List of new macros} \begin{itemize}\tightlist \item |\istbt(*)|: terminal version of |\istb(*)| (replacement of the removed macro |\istb.(*)|) \item |\istB(*)|: dual action label version of |\istb(*)| \item |\istBt(*)|: terminal version of |\istB(*)| \item |\istbA(*)|: alternative version of |\istb(*)| (intended to work with a continuum arc) \item |\istbAt(*)|: terminal version of |\istbA(*)| % \listdivider \item |\setistmathTF|: input mode changer (math or text) for owners, action labels, and payoffs % \begin{itemize}\tightlist % \item |\istownermathtrue|, |\istactionlabelmathtrue|, |\istpayoffmathtrue|: math mode % \item |\istownermathfalse|, |\istactionlabelmathfalse|, |\istpayoffmathfalse|: text mode % \end{itemize} \item |\setistmathTF*|: input mode and font style changer for owners, action labels, and payoffs % \begin{itemize}\tightlist % \item |\istownertextfont|, |\istactionlabeltextfont|, |\istpayofftextfont| % \end{itemize} % \listdivider \item |\xtCInfoset|: (curved version) curved information set \item |\xtCInfosetO|: (curved oval version) curved oval type information set \item |\xtCInfosetOTurnX|: turns |X| circles of |\xtCInfosetO| (to use it just in case) % \listdivider \item |\xtInfoset*|: prints owners according to the input mode as set by |\setistmathTF(*)| \item |\xtInfosetO*|: prints owners according to the input mode as set by |\setistmathTF(*)| \item |\xtCInfoset*|: prints owners according to the input mode as set by |\setistmathTF(*)| \item |\xtCInfosetO*|: prints owners according to the input mode as set by |\setistmathTF(*)| \item |\xtOwner*|: prints owners according to the input mode as set by |\setistmathTF(*)| \item |\xtActionLabel*|: prints action labels according to the input mode set by |\setistmathTF(*)| \item |\xtPayoff*|: prints payoffs according to the input mode as set by |\setistmathTF(*)| \item |\xtInfosetOwner*|: prints owners according to the input mode set by |\setistmathTF(*)| % \listdivider \item |\setxtinfosetstyle|: changes line the style (line style, fill, etc.) for all information sets \item |\setxtinfosetlayer|: changes the layer of information sets \item |\setxtsubgamelayer|: changes the layer of |\xtSubgameBox| and |\xtSubgameOval| \item |\setistgameshorten|: value of the key |shorten >| in \env{istgame} environment option list % \listdivider \item |\cntmdistance|: analogous to |\xtdistance|, for a continuum of branches \item |\cntmdistance*|: incorporates |\cntmdistance| with |\xtdistance| %\item |\cntmactsibdist|: sibling distance for action branches from |\istrootcntm| and its variants \item |\istrootcntm|: |\istroot| |+| |cntm|, printing a continuum of branches \item |\istrootcntm'|: swap version of |\istrootcntm| \item |\istrootocntm|: (oval version) |\istrooto| |+| |cntm|, printing a continuum triangle \item |\istrootocntm'|: swap version of |\istrootocntm| \item |\cntmpreset|: controls a continuum of branches (line style, color, size, fill color) \item |\cntmpreset*|: controls a simple triangle continuum of branches with no background color \item |\cntmistb|: similar to |\istb| for the outermost branches of a continuum triangle \item |\cntmistb*|: draws |solid node|s at the ends of the continuum outermost branches \item |\istrootcntmA|: |\istroot| |+| |cntmA|, printing a continuum arc \item |\istrootcntmA'|: swap version of |\istrootcntmA| \item |\istrootocntmA|: (oval version) |\istrooto| |+| |cntmA|, printing a continuum arc \item |\istrootocntmA'|: swap version of |\istrootocntmA| \item |\cntmApreset|: controls the features of a continuum arc \item |\cntmAlayerpreset|: sets the layer of a continuum wedge (with fill color) \item |\cntmAistb|: similar to |\istb| for the outermost branches of a continuum arc \item |\cntmAistb*|: draws |solid node|s at the ends of the continuum arc outermost branches \item |\cntmAInfoset|: prints an information set for a continuum arc \item |\cntmAInfosetO|: oval version of |\cntmAInfoset| \item |\xtShowEndPoints*|: shows additionally the outermost endpoints of a continuum of branches \item |\xtHideEndPoints*|: turns off only the endpoints of a continuum of branches \item |\cntmAexpostShowEndPoints|: shows the two endpoints of a continuum arc % \listdivider \item |\setxtarrowtips|: works through |->-| to control the features of middle arrow tips \item |\xtShowMidArrows|: shows arrows in the middle of branches \item |\xtHideMidArrows|: hides middle arrows drawn by |\xtShowMidArrows| \item |\setxtshowmidarrows|: controls the middle arrows on branches in a simple tree \item |\xtShowArrows|: shows arrows at the ends of branches with endpoints \item |\xtHideArrows|: hides arrows drawn by |\xtShowArrows| \item |\xtHideArrows*|: hides arrows but with endpoints remained \item |\setxtshowarrows|: controls the features of the arrows shown by |\xtShowArrows| % \listdivider \item |\xtTimeLineH|: a horizontal time-line \item |\xtTimeLineH'|: a horizontal time-line with a label at the other end \item |\xtTimeLineV|: a vertical time-line \item |\xtTimeLineV'|: a vertical time-line with a label at the other end \item |\xtCommentTo|: to leave a comment |to| a node |from| a \emph{relative} coordinate \item |\xtCommentFrom|: to leave a comment |from| an \emph{absolute} coordinate |to| a node % \listdivider \item |\xtcureslopedlabelsNS|: cures the \TikZ\ issue of sloped labels with asymmetric scales \item |\xtcureslopedlabelsEW|: same, for a tree growing eastwards or westwards\par The last two macros are for only temporary use and could be removed at any time. \end{itemize} \paragraph{List of new arrow styles} \begin{itemize}\tightlist \item |->-|: (controllable) middle arrow tip, taking one optional argument \item |->>-|: double middle arrow tip \item |->>>-|: triple middle arrow tip \item |-o-|: circle middle arrow tip \item |-x-|: cross middle arrow tip \end{itemize} \subsection{How to read this document} %First of all, since this package is just an application of \Tikz\ to draw game trees, not for learning \Tikz, you should have basic knowledge of using \Tikz\ to take a full advantage of this package. As a \Tikz\ user, if this is your first read of this manual, \emph{all you need to read} is Section~\ref{sec:gettingstarted} entitled ``\emph{Getting started}." That's only \emph{four} pages long. (You can find a little secret at the first part of Section~\ref{sec:desperateusers} entitled ``\emph{Complete examples for desperate users}.") Every example in this document is provided with its complete codes you can copy to use. Now you can go to Section~\ref{sec:gettingstarted} to get started! If you are not urgent, you can continue to read sections on \emph{core macros} up to Section~\ref{sec:istb}. That's about \emph{twenty} pages total. Still more time? Then read Section~\ref{sec:corelabels} (entitled ``\emph{Important labels: players, action labels, and payoffs}") and Section~\ref{sec:setistmathTF} (entitled ``\emph{Input mode and text font style changer}"). That's about \emph{thirty} pages all total. Throughout the manual, just disregard the parts with marks including ``\emph{fine-tuning}" or ``\emph{not for most users}," if you are not an experienced user of this package. Just reading first part of each section will suffice most users to draw game trees in almost all cases, hopefully. If you you are an experienced user of the \pkg{istgame} package, enjoy every detail of the package. %\clearpage \subsection{Remarks} \paragraph{Rules of thumb for the usage of delimiters} Though the rules are not strictly observed, it might be useful to go over the rules of thumb for the usage of delimiters. \begin{itemize}\tightlist \item |{ }|: contents, texts, important dimensions (mandatory or optional) \item |[ ]|: usual options, positions or directions, node types, fill color \item |( )|: coordinate related arguments, dimension as the last optional argument, special purposes \item |< >|: angles (or directions), special purposes (mostly used right before |{ }|) \item |+ .. +|: only for the local change of level and sibling distances with |\istroot| and its friends \item |! !|: |midpoint factor| only for curved information sets \end{itemize} As for the order of delimiters, the (somewhat loose) rules are as follows: \begin{itemize}\tightlist \item Generally, all macros are designed to avoid leaving an empty argument like |[][blue]|, as possible as they can do. (This is \emph{input minimalism} for lazy users including myself!) \item |< >| is used just before |{ }|, except for |\istb| and its friends. \item |( )| as the last optional argument is for dimensions, like |(1em)| or |(3pt)|. \item The order mostly looks like |<>{}[]| or |<>{}[]()|, especially after a mandatory argument. \end{itemize} \paragraph{Optional versions of macros} Some macros have a starred(|*|) version or a swap(|'|) version, for example, |\istb*| or \cmd{\istroot'}. \begin{itemize}\tightlist \item |* version|: just another version with different functions (in some cases, it's quite different) \item |' version|: clockwise arrangement of branches or its related version \end{itemize} \paragraph{Global macros} Some macros have global effects, so you can use them outside of the \env{istgame} environment or even in the preamble of your document, but \emph{with very great caution}. The following macros, all prefixed by |\setist...|, can be used outside of the \env{istgame} environment, to change the default values of the options: \begin{itemize}\tightlist \item \icmd{\setistgamefontsize}|{}| \hfill (default: |\normalsize|) \item \icmd{\setistgameshorten}|{}| \hfill (default: |0pt|) \begin{itemize} \item This works only when |->| exists in the option list of the \env{istgame} environment. \end{itemize} \end{itemize} Though it is not recommended, you can use all the macros prefixed by |\setist...| inside or outside of the \env{istgame} environment to change the default values. \begin{itemize}\tightlist \item \icmd{\setistmathTF}, \icmd{\setistmathTF*} \hfill (initially: |011|) \item \icmd{\setistdefaultnodeinnersep} \hfill (default: |1pt|) \item \icmd{\setistdefaultnodeoutersep} \hfill (default: |0pt|) \item \icmd{\setistdefaultnodedrawcolor} \hfill (default: |black|) \item \icmd{\setistdefaultnodefillcolor} \hfill (default: |white|) \item \icmd{\setist<...>NodeStyle} \item \icmd{\setistgrowdirection}, \icmd{\setistgrowdirection'} \hfill (default: |south|): \begin{itemize} \item You may not want to use (but still can use) this outside of an \env{istgame} environment. \end{itemize} \end{itemize} %You can also use (from the version 2.1): % %\begin{itemize}\tightlist %\item \icmd{\setistsolidnodesize} \hfill (default: |2.4pt|) %\item \icmd{\setisthollownodesize} \hfill (default: |2.8pt|) %\item \icmd{\setistellipsenodesize} \hfill (default: |4.8pt|) %\item \icmd{\setistrectanglenodesize} \hfill (default: |4pt|) %\end{itemize} So, for example, you can do, in the preamble of your document, like: \begin{verbatim} \usepackage{istgame} \setistgamefontsize{\normalsize} \setistdefaultnodedrawcolor{black} \setistsolidnodesize{2.4pt} % (new in version 2.1) \setistellipsenodesize{2.8pt} % (new in version 2.1) \setistgameshorten{.3pt} \setistmathTF011 \end{verbatim} The node styles such as |ellipse node| and |rectangle node| has |white| as the default background color. This means that if the paper color of your document is not white, say, |blue!16|, you might not satisfy the results because the nodes have |white| background. In this case you can resolve the conflict by adding the following two lines at the very first of your document: \begin{verbatim} \papercolor{blue!16} \setistdefaultnodefillcolor{blue!16} \end{verbatim} %The background color of the TeXShop preview in the dark mode of |macOS| |Mojave| is very similar to |black!16|. \paragraph{Known problem with the \pkg{tikz-qtree} package} It seems that \pkg{tikz-qtree} changes node anchors. So, with the \pkg{tikz-qtree} package uploaded, you will get unexpected results when you draw a game tree by using the native |tree| library in \TikZ. Since the \pkg{istgame} package is based on the |tree| library, it is also affected by \pkg{tikz-qtree}, resulting in unexpected outputs. The best way to resolve this problem is that you DO NOT LOAD \pkg{tikz-qtree} when you draw game trees with \TikZ. If, for some reason, you need to load \pkg{tikz-qtree} when you draw a game tree by using the \pkg{istgame} package, a temporary solution to resolve the conflict is to add the \TikZ\ option |edge from parent path| in the option list of \env{istgame} environment as follows: \xbigskip1 \begin{docplain} % tikz-qtree conflict resolution (only with \usepackage{tikz-qtree}) [ edge from parent path={(\tikzparentnode) -- (\tikzchildnode)} ] \end{docplain} %\begin{docsty} %\begin{istgame}% % [ % tikz-qtree conflict resolution (only with \usepackage{tikz-qtree}) % edge from parent path={(\tikzparentnode) -- (\tikzchildnode)} % ] % < istgame codes > %\end{istgame} %\end{docsty} %\tmpclearpage \subsection{Previous changes (up to version 1.0)} A considerable number of macro names have been changed in the version 0.8 (Jan.\@ 17, 2017) of this package.\footnote{The \pkg{istgame} package of the version older than ver.\@ 1.0 had been distributed via the KTUG (Korean TeX Users Group) Private Repository.} The following old macro names in any previously written documents using codes in \pkg{istgame} ver.\@ 0.7 or before, should be replaced by the new names, accordingly. Also, |\istroot*|, |\istcntm*|, and |\xtInfoset*| must be replaced by |\istrooto|, |\istcntmarc|, and |\xtInfosetO|, respectively, in the version 1.0 or later. %\begin{center} %\begin{tabu} {X[l4]X[l3]X[l2]} \toprule % to\linewidth %\makecell[l]{\textbf{ver.\@ 0.7 or before}} & \makecell[l]{\textbf{ver.\@ 0.8 or later}} & \makecell[l]{\textbf{ver.\@ 1.0 or later}}\\\midrule %|\xdistance| & |\xtdistance| & \\\tabucline- %|\xDot| &|\xtNode| & \\\tabucline- %|\xInfoset| &|\xtInfoset| & \\\tabucline- %|\xInfoset*| &|\xtInfoset*| & |\xtInfosetO| \\\tabucline- %|\xInfosetOwner| &|\xtInfosetOwner| & \\\tabucline- %|\xActionLabel| &|\xtActionLabel| & \\\tabucline- %|\xPayoff| &|\xtPayoff| & \\\tabucline- %|\ShowTerminalNodes| &|\xtShowTerminalNodes| & \\\tabucline- %|\HideTerminalNodes| &|\xtHideTerminalNodes| & \\\tabucline- %|\levdist| &|\xtlevdist| & \\\tabucline- %|\sibdist| &|\xtsibdist| & \\\tabucline- %|\setistactionlabelshift| & ~ & |\xtALPush| \\\tabucline- %|\setistactionlabelposition| & ~ & |\xtALShift| \\\tabucline- %|\istroot*| & & |\istrooto| \\\tabucline- %|\istcntm*| & & |\istcntmarc| \\\tabucline- %\end{tabu} %\end{center} \begin{center} \begin{tabular} {lll} \toprule % to\linewidth \makecell[l]{\textbf{ver.\@ 0.7 or before}} & \makecell[l]{\textbf{ver.\@ 0.8 or later}} & \makecell[l]{\textbf{ver.\@ 1.0 or later}}\\\midrule |\xdistance| & |\xtdistance| & \\\cline{1-3} |\xDot| &|\xtNode| & \\\cline{1-3} |\xInfoset| &|\xtInfoset| & \\\cline{1-3} |\xInfoset*| &|\xtInfoset*| & |\xtInfosetO| \\\cline{1-3} |\xInfosetOwner| &|\xtInfosetOwner| & \\\cline{1-3} |\xActionLabel| &|\xtActionLabel| & \\\cline{1-3} |\xPayoff| &|\xtPayoff| & \\\cline{1-3} |\ShowTerminalNodes| &|\xtShowTerminalNodes| & \\\cline{1-3} |\HideTerminalNodes| &|\xtHideTerminalNodes| & \\\cline{1-3} |\levdist| &|\xtlevdist| & \\\cline{1-3} |\sibdist| &|\xtsibdist| & \\\cline{1-3} |\setistactionlabelshift| & ~ & |\xtALPush| \\\cline{1-3} |\setistactionlabelposition| & ~ & |\xtALShift| \\\cline{1-3} |\istroot*| & & |\istrooto| \\\cline{1-3} |\istcntm*| & & |\istcntmarc| \\\cline{1-3} \end{tabular} \end{center} \clearpage \section{Getting started} \label{sec:gettingstarted} The package \ipkg{istgame} provides macros built on \TikZ\ to draw game trees. The core macros provided with this package are \icmd{\istroot}, \icmd{\istb}, and \icmd{\endist}. |\istroot| pins down the root of a tree or a subtree, |\istb| represents a branch, and |\endist| indicates the end of drawing a simple tree. Without |\endist|, the tree is NOT actually drawn, with no error messages produced. A tree drawn by the sequence of |\istroot-||\istb-||\endist| is a \ixsw{simple tree}. You can draw a whole game tree by repeatedly connecting these \emph{simple tree structures}. Here, the prefix `|ist|' stands for `it's a simple tree.' You can also read it as `insung's simple tree' if you would like. The package \pkg{istgame} depends on the packages \ipkg{tikz}, \ipkg{xparse}, and \ipkg{expl3}. To use the \pkg{istgame} package you must load the package in the preamble of your document: \begin{verbatim} \usepackage{istgame} \end{verbatim} The package preloads the following \TikZ\ libraries: \begin{verbatim} trees,calc,arrows,shapes,positioning,backgrounds,fit,decorations.markings, arrows.meta,bending, \end{verbatim} and also preloads |patterns| and |intersections| for additional use. \subsection{Getting-started example: a simple tree} Let us get started with a simple self-explanatory example: \begin{doccode}{.3} %% \usepackage{istgame} % Example: a simple tree \begin{istgame} \istroot(0)(0,0) % names the root as (0) at (0,0) \istb % endpoint will be (0-1), automatically \istb % endpoint will be (0-2), automatically \istb % endpoint will be (0-3), automatically \endist % end of simple (parent-child) structure \end{istgame} \end{doccode} The resulting tree has the \emph{height} of |15mm| and the \emph{distance between two neighbor endpoints} (not shown) is also |15mm| by default. In \TikZ, the height is called the \ixw{level distance} and the distance between two neighbor endpoints is called the \ixw{sibling distance}. If the second parenthesis argument of |\istroot| is omitted, it is regarded as |(0,0)| by default, otherwise it is necessary to specify the coordinate from which a simple tree starts. \subsection{Connecting simple tree structures} Basically, in order to draw a whole game tree, we just repeat the simple |\istroot-\istb-\endist| structure. \begin{doccode}{.3} % Example: connecting simple trees \begin{istgame} \istroot(0) % names the root (0) at (0,0) \istb % endpoint will be (0-1), automatically \istb % endpoint will be (0-2) \istb % endpoint will be (0-3) \endist % end of simple (parent-child) structure \istroot(c)(0-3) % names the subroot (c) at (0-3) \istb % endpoint will be (c-1) \istb % endpoint will be (c-2) \endist \end{istgame} \end{doccode} In the above example, the simple \emph{subtree} is rooted at |(0-3)|, names the subroot |(c)|, and has two branches whose endpoints are automatically named |(c-1)| and |(c-2)|, respectively. Note that the user-defined names of the (sub)roots and the names of endpoints are arranged \xw{counterclockwise} (from left to right) by \TikZ\ at the endpoints of branches, which can be used as coordinates in the usual \TikZ\ way. \subsection{Complete examples for desperate users} \label{sec:desperateusers} Basically, |\istroot| designates a \emph{decision node} and its \emph{owner} (or a \emph{player}), |\istb| prints a \emph{branch} coming out from the decision node with \emph{action labels} and \emph{payoffs}, and |\endist| actually draws the tree structures. (One secret is that I almost always use only the basic features of the \pkg{istgame} package, discussed in this subsection.) \subsubsection{How to put a decision node and its owner} \begin{docstx} \istroot()(){} \end{docstx} The only \emph{mandatory} argument of \icmd{\istroot} is |()| and all others are \emph{optional}. If the |()| where the \emph{\isw{root}} or a \emph{decision node} is placed is omitted, it is regarded as |(0,0)| by default. The position of an \isw{owner} (or a \isw{player}) is || (or equivalently, |<90>| degree) by default. The \emph{owner} of a node is printed in \emph{text mode} by default. \begin{doccode}{.3} % Example: first try \begin{istgame} \xtdistance{15mm}{30mm} \istroot(0)(0,0){Child} \istb \istb \endist \istroot(1)(0-2)<30>{Parent} \istb \istb \endist \end{istgame} \end{doccode} In fact, |\istroot| and its variants have much more functions than these. Later, you can look into Section~\ref{sec:istroot} on page~\pageref{sec:istroot} for more details. \subsubsection{How to print branches with action labels and payoffs} \begin{docstx} \istb{}[]{}[] \end{docstx} With the macro \icmd{\istb}, you can draw a \emph{\isw{branch}} and put an \emph{\isw{action}} label and \emph{\isw{payoff}}s as optional arguments. \begin{doccode}{.3} % Example: first try \begin{istgame} \xtdistance{15mm}{30mm} \istroot(0){Child} \istb{Good}[above left]{(0,2)} \istb{Bad}[above right] \endist \istroot(1)(0-2)<30>{Parent} \istb{Forgive}[al]{(1,1)} \istb{Punish}[ar]{(-1,-1)} \endist \end{istgame} \end{doccode} The positions of an action label and payoffs are specified as options right after each of the two. When you omit the position of payoffs, the package prints them naturally, but still you can change the location using an option like |[left]| or |[above left]|. For the positions of action labels and payoffs, you can use an abbreviation |[al]| for |[above left]| and similarly |[ar]|, |[bl]|, and |[br]|. The abbreviations |[a]|, |[b]|, |[l]|, and |[r]| are also available. Both of the \emph{action labels} and \emph{payoffs} are printed in \emph{math mode} by default. (You can change the input mode for owners, action labels, and payoffs using a very useful macro |\setistmathTF|, documented in Section~\ref{sec:setistmathTF} on page~\pageref{sec:setistmathTF}.) In fact, |\istb| and its variants have much more functions than these. For more details, see Section~\ref{sec:istb}, on page~\pageref{sec:istb}. If this is your first read of this manual, however, you don't need to bother about all the details at the moment. Following three sections are about an information set, a continuum of branches, and changing the direction of tree growing. If you do not need to use them now, the core macros |\istroot|, |\istb|, and |\endist| are \emph{all you need to know about} drawing game trees of any size, small or big. Just connect simple trees to complete a whole tree. \subsubsection{How to put information sets} The macro \icmd{\xtInfoset} connects two nodes with a densely dotted line, by default, representing an information set. \begin{docstx} \xtInfoset()(){}[] \end{docstx} The two node coordinates are \emph{mandatory}. You can put the owner of an information set as an optional argument. An owner is printed above (by default) the line in \emph{text mode}, which can be changed. For more details about |\xtInfoset|, see Section~\ref{sec:infoset} on page~\pageref{sec:infoset}. In the example below, the macro |\xtInfoset| is used to show an \isw{information set}. \begin{doccode}{.35} % Example: information set \begin{istgame} %\setistgrowdirection'{east} \xtdistance{15mm}{30mm} \istroot(0){Alice} \istb{A}[al]{(2,2)} \istb{D}[ar] \endist \istroot(1)(0-2){Alice} \istb{L}[al] \istb{R}[ar] \endist \xtdistance{10mm}{20mm} \istroot(2)(1-1) \istb{\ell}[al]{(4,2)} \istb{r}[ar]{(1,1)} \endist \istroot(3)(1-2) \istb{\ell}[al]{(3,2)} \istb{r}[ar]{(0,3)} \endist \xtInfoset(2)(3){Elaine} \end{istgame} \end{doccode} The package also provides the macro |\xtInfosetO| to draw a bubble type information set. Just replace |\xtInfoset| with |\xtInfosetO| (see Section~\ref{ssec:xtInfosetO} on page~\pageref{ssec:xtInfosetO}). You can also draw a curved information by using |\xtCInfoset| (Section~\ref{ssec:xtCInfoset}) and even a curved bubble type by using |\xtCInfosetO| (Section~\ref{ssec:xtCInfosetO}). You can try now. \subsubsection{How to put a continuum of branches} Just use |\istrootcntm| (|\istroot + cntm|), instead of |\istroot|, to draw a \isw{continuum} of branches. \begin{docstx} \istrootcntm()(){} \end{docstx} The macro \icmd{\istrootcntm} works just like |\istroot|, but it prints a background triangle in |black!25|, by default, representing a continuum of branches. \begin{doccode}{.35} % Example: continuum of branches \begin{istgame}[font=\scriptsize] \istrootcntm(0){1} \istb{x}[r] \istbm \endist \xtdistance{10mm}{20mm} \istroot(1)(0-1)<120>{2} \istb{Y}[al]{x,1-x} \istb{N}[ar]{0,0} \endist \end{istgame} \end{doccode} Here, |\istbm| represents a missing (or an invisible) branch (see page~\pageref{page:istbm}). You can also change the color and size of the triangle representing a continuum of branches. For more details on |\istrootcntm| see Section~\ref{ssec:istrootcntm}, on page~\pageref{ssec:istrootcntm}. The package also provides the macro |\istrootcntmA| to draw an arc to represent a continuum of branches. You can just replace |\istrootcntm| by |\istrootcntmA| to do that, but let us not try this now. (If you really want to try this now, you should change the first |\istb| to |\istbA| and then take out |\istbm| in the above example. It is said not to try this now.) For more details on |\istrootcntmA| see Section~\ref{ssec:istrootcntmA}, on page~\pageref{ssec:istrootcntmA}. You can use every options and macros you can use for the \env{tikzpicture} environment with the \env{istgame} environment. In the above example, |font=\scriptsize| is used as an option. \subsubsection{How to change the growing direction of a tree} With |\setistgrowdirection| or \cmd{\setistgrowdirection'}, you can easily change the \isw{direction} (|south| by default) to which a game tree grows, as shown in the example below. \begin{doccode}{.35} % Example: \setistgrowdirection(') \begin{istgame}[scale=1.2] \setistgrowdirection'{east} \istroot(0)<180>{1} \istb{a}[al] \istb{b}[a] \istb{c}[bl] \endist \xtdistance{10mm}{20mm} \istroot(1)(0-2)<135>{2} \istb{Y}[al]{x,1-x} \istb{N}[bl]{0,0} % \endist \end{istgame} \end{doccode} All you need to do is just to specify the direction you want, like |\setistgrowdirection{west}|, \cmd{\setistgrowdirection'}|{east}|, or \cmd{\setistgrowdirection'}|{-45}|. The prime version (|'|) is just to arrange branches \xw{clockwise} (by default \xw{counterclockwise}). In the above example, if you use |\setistgrowdirection| without the prime, the branches will be arranged \xw{counterclockwise}, like $a$, $b$, and $c$ \emph{from bottom to top}. When changing the direction of a tree, you may want to relocate the owner and action labels. For more details, see Sections~\ref{sec:growing} (on page~\pageref{sec:growing}) and~\ref{sec:payoffdirection} (on page~\pageref{sec:payoffdirection}). Now you are ready to draw any standard game trees such as all game trees in Osborne's book. \section{Important distances: \protect\CMD{\xtdistance}} \label{sec:xtdistance} The length and direction of branches in a simple tree can be controlled by the macro \icmd{\xtdistance}. Here, the prefix `|xt|' stands for \ixsw{extensive tree}. \begin{docstx} % syntax: \xtdistance \xtdistance[]{}{} % defaults: [1]{15mm}{15mm} \end{docstx} The macro |\xtdistance| sets or resets the \xw{level distance} and the \xw{sibling distance}, respectively. Note also that internally, for example, |\xtdistance{20mm}{30mm}| assigns |20mm| to \icmd{\xtlevdist} and |30mm| to \icmd{\xtsibdist}, which renew the default distances. It is effective until you change the distances by using another |\xtdistance|. \begin{center} \begin{istgame}[scale=2] \istroot(0) \istb* \istb* \istb* \endist \coordinate (A) at ([xshift=-10pt]0-|0-1) ; \coordinate (B) at ([xshift=-10pt]0-1) ; \coordinate (C) at ([yshift=-10pt]0-1) ; \coordinate (D) at ([yshift=-10pt]0-2) ; \begin{scope}[blue] \draw [|<->|] (A) -- (B) ; \draw [|<->|] (C) -- (D) ; \node at ($(A)!.5!(B)$) [left] {\makecell[c]{level distance\\\xw{\xtlevdist}}} ; \node at ($(C)!.5!(D)$) [below] {\makecell[c]{sibling distance\\\xw{\xtsibdist}}} ; \end{scope} \end{istgame} \end{center} You can use |\xtdistance| at any time you want to change the length and the directions of branches. Since we are dealing with simple \emph{parent-child} tree structures, || is |1| by default. (The level depth number other than |1| is not expected to be used.) \begin{doccode}{.3} % \xtdistance \begin{istgame} \xtdistance{15mm} % default \istroot(0) \istb \istb \istb \endist \xtdistance{15mm}{30mm} % changes sibling dist \istroot(a)(0-1) \istb \istb \endist \endist \end{istgame} \end{doccode} \remark \begin{itemize} \item Since |\xtlevdist| and |\xtsibdist| are assigned values by |\xtdistance|, you can use these values to do some calculation like, for example, |1.2*\xtlevdist| or |1.5*\xtsibdist|. \item The starred version \icmd{\cntmdistance*} is provided to deal with a continuum of branches and |\xtdistance| together, which is not documented at the moment. See Section~\ref{sec:xtdistance*}, on page~\pageref{sec:xtdistance*}, for more details about |\cntmdistance*|. \end{itemize} In fact, the core macros are much more powerful. |\istroot| controls the direction to which a simple parent-child tree grows, node styles, the node owner and its position, the height and sibling distance of a current simple tree, etc. |\istb| specifies the growing direction of an individual branch, branch line styles, branch color, action labels, and payoffs and their position. Below we will see in more details on how the core macros and others work. \section{The \env{istgame} environment and node styles} \subsection{The \env{istgame} environment} \label{ssec:envistgame} The package provides the \ienv{istgame} environment, which is basically the sum of the \ienv{tikzpicture} environment plus some additional functions and different initial values. So it accepts all the options and macros that can be used for the \env{tikzpicture} environment. (Note that most of the macros provided by the package work also in the \env{tikzpicture} environment, but some works only in the \env{istgame} environment.) \begin{docsty} % istgame environment % \def\istgame@default@fontsize{\normalsize} \begin{istgame}[ ] < istgame contents > < tikzpicture contents > \end{istgame} % default options: [ font=\normalsize , >=stealth ] \end{docsty} The default font size is set as |font=\normalsize|. You can globally change the default font size by using \icmd{\setistgamefontsize}, like |\setistgamefontsize{\scriptsize}|. Since the environment \env{istgame} is basically the same as \env{tikzpicture}, you can also locally change the font size by using the |font| option key, like |\begin{istgame}[font=\scriptsize]...\end{istgame}|. \remark \textbf{(Not for most users)} What the \env{istgame} environment \emph{internally} does includes: \begin{itemize} \item The \env{istgame} environment internally checks and extracts the optional values of |xscale| and |yscale| and, if exist, saves the values (|1.0| by default) at \icmd{\xtxscale} and \icmd{\xtyscale}, respectively. And if the optional value of |scale| exists, it is saved at \icmd{\xtscale} only when neither |xscale| nor |yscale| exists. You can use these values to calculate something you want, like |5*1/\xtscale|. The extracted values are internally used to get the best results of the shapes of bubble type information sets. \item The \env{istgame} environment also checks if the arrow option |[->]| exists in the option list of the environment. If it exists the \env{istgame} adds |shorten >=| (by default |0pt|) to the list as the first option together with |[->]|. You can change the arrow shortening default value, like |\setistgameshorten{1.3pt}|. (Though this is \emph{not for most users}, you can see some more details, in Section~\ref{sec:setistgamearrowendshorten}.) \end{itemize} \paragraph{Starred version \xw{\begin\{istgame\}*}:} The \emph{starred version} of \env{istgame} environment is essentially the same as the \env{tikzpicture} environment. It means that if you start with |\begin{istgame}*|, the environment does not check what is said in the description above. (See the discussion on page~\pageref{ssec:changes2.1} for more details on what happens in this case.) \subsection{Node styles} \label{sec:nodestyles} \subsubsection{Basic node styles} The |tikzstyle|'s of the six basic node styles are predefined. \begin{itemize}\tightlist \item \ixw{plain node}: draws nothing \hfill (default: |inner sep=1pt|) \item \ixw{null node}: \begin{istgame}\istroot(0)[null node]\endist\end{istgame} (very small node) \hfill (default: |minimum size=0.2pt|) \item \ixw{solid node}: \begin{istgame}\istroot(0)[solid node]\endist\end{istgame} (default node style) \hfill (default: |minimum size=2.4pt|) \item \ixw{hollow node}: \begin{istgame}\istroot(0)[hollow node]\endist\end{istgame} \hfill (default: |minimum size=2.8pt|) \item \ixw{rectangle node}: \begin{istgame}\istroot(0)[rectangle node]\endist\end{istgame} \hfill (defaults: |inner sep=2pt|, |minimum size=4pt|) \item \ixw{ellipse node}: \begin{istgame}\istroot(0)[ellipse node]\endist\end{istgame} \hfill (defaults: |inner sep=1.5pt|, |minimum size=4.8pt|) \end{itemize} In some special cases, you may want to change some node styles, including the minimum size. This can be done by \icmd{\setist<...>NodeStyle}, all of whose arguments are optional. \begin{verbatim} syntax: \setistPlainNodeStyle{}{} \setistNullNodeStyle[]{}[][] \setistSolidNodeStyle[]{}[][] \setistHollowNodeStyle[]{}[][] \setistRectangleNodeStyle[]{}[][] \setistEllipseNodeStyle[]{}[][] \end{verbatim} \begin{doccode}{.1} % Examples: \begin{istgame}\setistSolidNodeStyle[blue]{10pt} \istroot(0)[solid node]\endist\end{istgame}\\[1ex] \begin{istgame}\setistHollowNodeStyle[blue]{10pt}[yellow] \istroot(0)[hollow node]\endist\end{istgame}\\[1ex] \begin{istgame}\setistRectangleNodeStyle{10pt}[red][.5] \istroot(0)[rectangle node]\endist\end{istgame}\\[1ex] \begin{istgame}\setistEllipseNodeStyle[blue]{10pt}[green] \istroot(0)[ellipse node]\endist\end{istgame}\\[1ex] \begin{istgame}\setistNullNodeStyle[blue!20]{10pt} \istroot(0)[null node]\endist\end{istgame} \end{doccode} These basic node styles have their aliases, for convenience, for those who are familiar with game theoretic terminology. \begin{docsty} % aliases for game theorists \tikzset{decision node/.style=solid node} % decision nodes \tikzset{terminal node/.style=solid node} % terminal nodes \tikzset{initial node/.style=hollow node} \tikzset{chance node/.style=hollow node} \end{docsty} The set of all nodes of a game tree can be partitioned into the set of \ixw{decision nodes} and that of \ixw{terminal nodes}. You can use \ixw{initial node} to distinguish the \ixsw{root} (or the |initial node|) of a game tree from decision nodes. You can also use \ixw{chance node} to represent a chance node of a game tree. %You can also change the node styles, like |\setistDecisionNodeStyle[blue]{3pt}|. Additional convenient node aliases are also provided: \ixw{box node}, \ixw{square node}, and \ixw{oval node}. \begin{docsty} % some more aliases \tikzset{box node/.style=rectangle node} \tikzset{square node/.style=rectangle node} \tikzset{oval node/.style=ellipse node} \end{docsty} For aliases, you can also change the node styles, like |\setistDecisionNodeStyle[blue]{3pt}| or |\setistBoxNodeStyle{3pt}[green][.5]|. \subsubsection{Your own node styles: \protect\CMD{\setistNewNodeStyle}} You can create your own node style by \icmd{\setistNewNodeStyle}. \begin{docstx} % \setistNewNodeStyle % syntax: \setistNewNodeStyle{