%-------------------------------------------------------------------------------
% Examples on how to make tables for ATLAS documents
% Responsible: Ian Brock (Ian.Brock@cern.ch)
%-------------------------------------------------------------------------------
% Specify where ATLAS LaTeX style files can be found.
\RequirePackage{../atlasdocpath}
%-------------------------------------------------------------------------------
\documentclass[REPORT=false, UKenglish]{atlasdoc}

\newcommand*{\AtlasTweakYear}{2020}

% Standard packages that can and should be used in ATLAS papers
\usepackage{atlaspackage}
\usepackage{atlasbiblatex}
\usepackage{authblk}
% \usepackage{verbatim}

\usepackage{atlasphysics}

\usepackage{atlas_doc-defs}
\usepackage{atlas_tables-defs}

% New definition of s column type (removed in TeX Live 2021 siunitx)
\usepackage{collcell}
\newcolumntype{s}{>{\collectcell\si}c<{\endcollectcell}}

% Files with references in BibTeX format
\addbibresource{../atlas_latex.bib}

\graphicspath{{../../logos/}}

%-------------------------------------------------------------------------------
% Generic document information
%-------------------------------------------------------------------------------

% Set author and title for the PDF file
\hypersetup{pdftitle={ATLAS tables guide},pdfauthor={Ian Brock}}

\AtlasTitle{Guide to formatting tables for ATLAS documents}

\author{Ian C. Brock}
\affil{University of Bonn}

\AtlasAbstract{%
  This document illustrates the preferred style for tables in ATLAS documents.
  It illustrates what the tables should look like and also provides guidelines on how to achieve this look.

  This document was generated using version \ATPackageVersion\ of the ATLAS \LaTeX\ package.
  % The \TeX\ Live version is set to \AtlasTeXLiveVersion.
  The main class is \KOMAScriptVersion.
  It uses the option \Option{atlasstyle}, which implies that the standard ATLAS preprint style is used.
}


%-------------------------------------------------------------------------------
\begin{document}

\maketitle

%-------------------------------------------------------------------------------
\section{General guidelines}
%-------------------------------------------------------------------------------

Tables should only contain as many lines as are needed for clarity.
\Cref{tab:yield:2dig} shows a good example that has been taken
from \enquote{Rounding --- ATLAS Recommendations}~\cite{atlas-rounding}.

\sisetup{retain-explicit-plus=true}
\begin{table}[htbp]
\begin{tcblisting}{}
  \sisetup{group-minimum-digits=4}
  \caption{Example event yields spread over several orders of magnitude.}%
  \label{tab:yield:2dig}
  \centering
    \begin{tabular}{%
      l
      r@{\(\,\pm\,\)}r
    }
    \toprule
    {Channel} & \multicolumn{2}{c}{Selected events} \\
    \midrule
    \(WW, WZ, ZZ\)               & \numRF[3]{943.045}  & \numRF[2]{94.3045} \\
    QCD multijets                & \numRF[2]{2838.39}  & \numRF[2]{1419.19} \\
    \(Wc\bar{c}, Wb\bar{b}, Wc\) & \numRF[2]{31178  }  & \numRF[2]{13094.8} \\
    \(W\) + jets                 & \numRF[3]{10584.5}  & \numRF[2]{4445.49} \\
    Single top \(Wt\)            & \numRF[3]{1699.75}  & \numRF[2]{152.977} \\
    \(Z\) + jets                 & \numRF[2]{2378.42}  & \numRF[2]{998.934} \\
    Single top \(s\)             & \numRF[3]{297.591}  & \numRF[2]{12.4988} \\
    Single top \(t\)             & \numRF[3]{3936.98}  & \numRF[2]{165.353} \\
    \(t\bar{t}\)                 & \numRF[3]{9386.28}  & \numRF[2]{901.083} \\
    \midrule
    Expected                     & \numRF[2]{63243}    & \numRF[2]{13968.5} \\
    Data                         & \multicolumn{2}{l}{\num{73062}} \\
    \bottomrule
  \end{tabular}
\end{tcblisting}
\end{table}

The \Package{booktabs} package provides the macros
\Macro{toprule}, \Macro{midrule}, \Macro{bottomrule} which are to be preferred over \Macro{hline},
as, among other things, they introduce some extra spacing around the lines, which is useful.

The \Package{siunitx} package contains powerful macros for formatting tables
and is highly recommended.
\Cref{tab:example0a,tab:example0b} show simple examples that make use of the
\Option{table-format} and \Option{table-number-alignment} options.
\Option{table-number-alignment} is particularly useful if the column header is wider then the content.
it is better to include space for the sign, if the numbers in the table are signed.
Have a close look at \enquote{Tabular material} section
(Section 4.12 in the 2022 version of the \Package{siunitx} manual)
for more details on exactly what can be steered and how.

\begin{table}[htbp]
\begin{tcblisting}{}
  \caption{Simple table using \Option{S} column.}
  \label{tab:example0a}
  \centering
  \begin{tabular}{
    S[table-format=2.2, table-number-alignment=center]
    S[table-format=2.2, table-number-alignment=right]
  }
    \toprule
    {Align Centre} & {Align Right} \\
    \midrule
    0.76 & 0.76 \\
    83.1 & 83.1 \\
    \bottomrule
  \end{tabular}
\end{tcblisting}
\end{table}

\begin{table}[htbp]
\begin{tcblisting}{}
  \caption{Simple table for numbers with signs using \Option{S} column.
    Vertical lines are included to show alignment (problems) --
    see the first column.}
  \label{tab:example0b}
  \centering
  \begin{tabular}{
    |S[table-format=2.2]
    |S[table-format=-2.2]
    |S[table-format=-2.2, table-number-alignment=center]
    |S[table-format=+2.2, table-number-alignment=left]|
  }
    \toprule
    {W/o} & {With} & {Align centre} & {Align left} \\
    \midrule
    0.76  & 0.76  & -0.76 & +0.76 \\
    82.0  & 82.0  &  82.0 &  82.0 \\
    +83.1 & +83.1 & -83.1 & +83.1 \\
    -84.2 & -84.2 & +84.2 & +84.2 \\
    \bottomrule
  \end{tabular}
\end{tcblisting}
\end{table}

An example of a wider and somewhat more complicated table is shown in \cref{tab:intro:presentlimits}.

\begin{table}[htbp]
\begin{tcblisting}{}
  \caption[Present FCNC top quark decays experimental limits]{Present experimental limits at \qty{95}{\%} confidence level
  on the branching fractions of the FCNC top quark decay channels established by experiments of the LEP, HERA, Tevatron and LHC accelerators.}%
  \label{tab:intro:presentlimits}
  \centering
  \begin{tabular}{lllll}
    \toprule
    Coupling & \multicolumn{2}{c}{LEP} & \multicolumn{2}{c}{HERA} \\
    \midrule
    \(\BR(t\to q\gamma)\) & \num{2.4E-2} &                          & \num{6.4E-3} & (\(tu\gamma\))\\
    \(\BR(t\to qZ)\)      & \num{7.8E-2} &                          & \num{49E-2} & (\(tuZ\))\\
    \(\BR(t\to qg)\)      & \num{17E-2}  &                          & \num{13E-2} & \\
    \bottomrule
    Coupling & \multicolumn{2}{c}{Tevatron}                         & \multicolumn{2}{c}{LHC} \\
    \midrule
    \(\BR(t\to q\gamma)\) & \num{3.2E-2} &                          & \multicolumn{1}{c}{---} \\
    \(\BR(t\to qZ)\)      & \num{3.2E-2} &                          & \num{7.0E-4}\\
    \(\BR(t\to qg)\)      & \num{2.0E-4} & (\(tug\)), \((2 \to 2)\) & \multicolumn{1}{c}{---} \\
                          & \num{3.9E-3} & (\(tcg\)), \((2 \to 2)\) & \multicolumn{1}{c}{---} \\
                          & \num{3.9E-4} & (\(tug\)), \((2 \to 1)\) & \num{5.7E-5} & (\(tug\)), \((2 \to 1)\)\\
                          & \num{5.7E-3} & (\(tcg\)), \((2 \to 1)\) & \num{2.7E-4} & (\(tcg\)), \((2 \to 1)\)\\
    \bottomrule
  \end{tabular}
\end{tcblisting}
\end{table}

A typical table containing Monte Carlo samples is given in \cref{tab:mcsamples}.

\begin{table}[htbp]
\begin{tcblisting}{}
  \caption{Top quark event MC samples used for this analysis. The cross-section column includes \(k\)-factors and branching ratios.}%
  \label{tab:mcsamples}
  \centering
  \renewcommand{\arraystretch}{1.2}
  \scriptsize
  \begin{tabular}{lSlS[table-format=9.0]SS[table-format=6.0]}
    \toprule
      & {\(\sigma\) [\unit{\pb}]} & Generator
      & \multicolumn{1}{c}{\(N_{MC}\)} & \multicolumn{1}{c}{\(k\)-factor} & \multicolumn{1}{c}{Dataset ID}\\
    \midrule
    \(Wt\) all decays                   &  22  & \POWHEG + \PYTHIA &   1000000  & 1.09 & 110140\\
    \(t\)-channel (lepton+jets) top     &  18  & \POWHEG + \PYTHIA &   5000000  & 1.05 & 110090\\
    \(s\)-channel (lepton+jets) antitop &  1.8 & \POWHEG + \PYTHIA &   5000000  & 1.06 & 110091\\
    \(t\bar{t}\) no fully hadronic      & 114  & \POWHEG + \PYTHIA & 100000000  & 1.12 & 117050\\
    \bottomrule
  \end{tabular}
\end{tcblisting}
\end{table}

\Cref{tab:example1} shows the use of \(\pm\) as the intercolumn
character for alignment. An alternative, as shown in
\cref{tab:example2}, is to use \verb+\phantom+ to put in extra
space equal to the width of a number if you have different numbers of
decimal places in the table.


\begin{table}[htbp]
\begin{tcblisting}{}
  \caption[Monte Carlo purities in the single lepton sample]{%
    Monte Carlo estimates of the fraction of each process in the single
    lepton data sample. This table uses \enquote{S} format from \texttt{siunitx} and
    \enquote{\(\,\pm\,\)} as the intercolumn separator.}%
  \label{tab:example1}
  \centering
  \begin{tabular}{l S[table-format=2.1]@{\(\;\pm\;\)}S[table-format=1.1]@{\,}l
    S[table-format=3.1]@{\,}l}
    \toprule
    Category             & \multicolumn{3}{c}{\(\mu\)} & \multicolumn{2}{c}{\(e\)}\\
    \midrule
    \(b \to \ell\)       &     65.2 & 0.4 & \%   &  79.3 & \% \\
    \(b \to c \to \ell\) &      7.8 & 0.3 & \%   &   5.4 & \% \\
    Total                &     73.0 & 0.2 & \%   &   9.1 & \% \\
    \bottomrule
  \end{tabular}
\end{tcblisting}
\end{table}

\begin{table}[htbp]
\begin{tcblisting}{}
  \caption{Monte Carlo estimates of the fraction of each process in
  the single lepton data sample.
  This table uses \texttt{\textbackslash phantom}.}%
  \label{tab:example2}
  \centering
  \begin{tabular}{lcc}
    \toprule
    Category             & \multicolumn{1}{c}{\(\mu\)} & \multicolumn{1}{c}{\(e\)}\\
    \midrule
    \(b \to \ell\)       & \(    65.2 \pm 0.4\,\%\)   &     79.3\,\% \\
    \(b \to c \to \ell\) & \(\pho 7.8 \pm 0.3\,\%\)   & \pho 5.4\,\% \\
    Total                & \(    73.0 \pm 0.2\,\%\)   & \pho 9.1\,\% \\
    \bottomrule
  \end{tabular}
\end{tcblisting}
\end{table}


%-------------------------------------------------------------------------------
\section{\LaTeX\ packages for tables}
%-------------------------------------------------------------------------------

The \LaTeX\ package \Package{booktabs} gives a number of guidelines on how tables should be formatted.
These are followed to a large extent in this document.
The following packages related to tables are included by default when you load the package \Package{atlaspackage}:
\begin{description}
\item[booktabs] useful tools for formatting tables;
\item[siunitx] tools for rounding and also for helping to format and align numbers in tables;
\end{description}
Further packages related to the formatting of tables are:
\begin{description}
\item[multirow] construction for table cells that span more than one row of the table;
\item[longtable] the most actively developed package that spread over more than one page;
\item[xtab] an alternative package for long tables;
\item[supertabular] yet another alternative package for long tables;
\item[dcolumn] can be used as an alternative to \Package{siunitx} to align numbers in tables.
\end{description}
\Package{longtable} is included if you load \Package{atlaspackage} with the option \Option{full}.
You may also need to rotate a big table.
The \Package{rotating} package can be used for this.

In order to shorten commands when doing rounding in tables, it is useful to define a few extra macros.
Typical definitions can be found in the file \File{../atlas\_doc-defs.sty}.

If you use \Package{siunitx} to format your numbers,
you may have to adjust the option \Option{group-minimum-digits}.
The default value of \Option{group-minimum-digits} is set to 5.
Hence \num{1234} will not have a space after the thousands digit,
whereas \num{12345} will have.
This is fine in text, but in tables, you probably want to use the option
\verb|\siseteup{group-minimum-digits=4}|,
see \crefrange{tab:minimum-digits1}{tab:minimum-digits2}.

\begin{table}[htbp]
\begin{tcblisting}{}
  \caption{Tables comparing different \Option{group-minimum-digits} values
  for the package \Package{siunitx}.}
  \label{tab:minimum-digits}
  \centering
  \subfloat[Table with \Option{group-minimum-digits=4}.]{%
  \sisetup{group-minimum-digits=4}
  \begin{tabular}{lS[table-format=5.2]}
    Quantity & \multicolumn{1}{c}{Value}\\
    \midrule
    Value1 & 1234.56\\
    Value2 & 98765.43
  \end{tabular}
  \label{tab:minimum-digits1}
  }
  \qquad
  \subfloat[Table with \Option{group-minimum-digits=5}.]{%
  \sisetup{group-minimum-digits=5}
  \begin{tabular}{lS[table-format=5.2]}
    Quantity & \multicolumn{1}{c}{Value}\\
    \midrule
    Value1 & 1234.56\\
    Value2 & 98765.43
  \end{tabular}
  \label{tab:minimum-digits2}
  }
\end{tcblisting}
\end{table}

\clearpage

%------------------------------------------------------------------------------
\section{Rounding and numbers with asymmetric errors}%
\label{sec:tips:pmerr}\index{asymmetric errors}\index{errors!asymmetric}
%------------------------------------------------------------------------------

Two things that are currently not built into the \Package{siunitx} package
are separate statistical and  systematic errors and asymmetric errors.
In addition it may be desirable to round the numbers.
From the author I got some suggestions on how to define such things.
Such macros are included in the \Package{atlasmisc} package.
Several new macros are defined there:
\begin{itemize}
  \item \Macro{numR}, \Macro{numRF} and  \Macro{numRP}
    for rounding numbers.
    \Macro{numRF} uses a fixed number of digits,
    whose value can be  given as an optional argument.
    \Macro{numRP} does the same, but with a fixed number of decimal places.
    For \Macro{numR} you specify the rounding mode (and any other options)
    using \Macro{sisetup} before calling it.
  \item \Macro{numpmerr} can be used to pass the rounding precision
    as the first optional argument and the mode as the second optional argument.
  \item \Macro{numerrt}, \Macro{numpmerrx} and \Macro{numpmerrt}
    can be used to write errors with a description,
    which are asymmetric and both, respectively.
    Any \Package{sisetup} options can be passed as the first (optional) argument.
  \item The corresponding macros for values and errors are
    \Macro{qtypmerr}, \Macro{qtyerrt}, \Macro{qtypmerrx} and \Macro{qtypmerrt}. For the macros
    whose names end with \enquote{\texttt{t}}, you also have to provide
    the descriptive text.
  \item If you have two errors then use \Macro{qtyerrtt}
    or \Macro{qtypmerrtt}, which have one or two more arguments, respectively.
  \item For the standard case of statistical and systematic
    errors, you can use the macros \Macro{qtyerrs} and
    \Macro{qtypmerrs}.
\end{itemize}
For all the macros except \Macro{numRF}, \Macro{numRP}
\Macro{numpmerr} and \Macro{qtypmerr}
the first (optional) argument can be used to pass any options you like to
the \Macro{num} command.

\ADOCnew{15.0} Backwards incompatible changes were made to the
\Macro{numR}, \Macro{numRF}, \Macro{numRP} and \Macro{numpmerr} macros.
The precision is now an optional argument for \Macro{numR}, \Macro{numRF} and \Macro{numRP}.
The precision and rounding mode are optional arguments for \Macro{numpmerr}.
The macros \Macro{numpmRF} and \Macro{numpmRP} have been removed,
as \Macro{numpmerr} can easily be used instead.
For most flexibility, the \Macro{numpmerrx} can be used to set the precision and rounding options and more.
You can use the previous versions by passing the option \Option{version=14} to \Package{atlasdoc}.

\clearpage

Examples of the rounding macros' usage are:
\begin{tcblisting}{}
\sisetup{round-precision=3}
\begin{tabular}{ll}
  \numR{1234.5678}\\
  \numRF{1234.5678} & \numRF[2]{1234.5678}\\
  \numRP{1234.5678} & \numRP[2]{1234.5678}\\
\end{tabular}
\end{tcblisting}

Examples of the asymmetric error macros are:
\begin{tcblisting}{}
\renewcommand{\arraystretch}{1.4}
\begin{equation*}
\begin{array}{lll}
  \numpmerr{+0.1234}{-0.4567} & \numpmerr[2][places]{+0.1234}{-0.4567} &
  \numpmerrx[round-mode=places, round-precision=2]{+0.1235}{-0.4568}\\
  \numpmerrt{+0.1234}{-0.4567}{stat.} & \numpmerr[2]{+0.1236}{-0.4569}\,\text{(stat.)} &
  \numpmerrt[round-mode=places, round-precision=2]{+0.1237}{-0.4560}{sys.}\\
\end{array}
\end{equation*}
\end{tcblisting}

Examples of the quantities macros are:
\begin{tcblisting}{}
\begin{align*}
  \sigma & = \qtyerrs{3.42}{0.46}{0.32}{\pico\barn} & \Macro{qtyerrs}\\
  \sigma & = \qtyerrs[round-mode=places, round-precision=1]{3.43}{0.46}{0.32}{\pico\barn} & \Macro{qtyerrs}\\
  \sigma & = \qtyerrt[round-mode=places, round-precision=2]{3.43}{0.46}{stat.}{\pico\barn} & \Macro{qtyerrt}\\
  \sigma & = \qtyerrtt{3.43}{0.46}{stat.}{0.32}{sys.}{\pico\barn} & \Macro{qtyerrtt}\\
  \sigma & = \qtypmerr{3.44}{+0.46}{-0.32}{\pico\barn} & \Macro{qtypmerr}\\
  \sigma & = \qtypmerr[2][figures]{3.45}{+0.46}{-0.32}{\pico\barn} & \Macro{qtypmerr}\\
  \sigma & = \qtypmerrx[round-mode=figures, round-precision=2]{3.46}{+0.46}{-0.32}{\pico\barn} & \Macro{qtypmerrs}\\
  \sigma & = \qtypmerrt{3.47}{+0.46}{-0.32}{stat.}{\pico\barn} & \Macro{qtypmerrt}\\
  \sigma & = \qtypmerrs{3.48}{+0.46}{-0.32}{+0.06}{-0.04}{\pico\barn} & \Macro{qtypmerrs}\\
  \sigma & = \qtypmerrtt{3.49}{+0.46}{-0.32}{stat.}{+0.06}{-0.04}{sys.}{\pico\barn} & \Macro{qtypmerrtt}
\end{align*}
\end{tcblisting}
The last two examples use \Macro{qtypmerrs} and \Macro{qtypmerrtt} just
to show that they can both give the same output. If you need even more
complicated combinations of errors, or more errors, have a look at the
definitions, e.g.
\begin{tcblisting}{}
\begin{equation*}
  \sigma_{t\bar{t}} = (\num{164.6}%
  \valuesep\numerrt{8.7}{stat.}%
  \valuesep\numpmerrt{+6.4}{-5.3}{sys.}%
  \valuesep\numerrt{8.2}{lumi.})%
  \valuesep\unit{\pico\barn}
\end{equation*}
\end{tcblisting}

Rounding is very nice and works well, but can slow down compilation considerably,
especially in big INT notes.

Details of the arguments for all the macros can be found in \cref{tab:numerr,tab:qtyerr}.

\begin{table}[htbp]
  \caption{Arguments of error macros.
  \enquote{prec} is short for the \Option{rounding-precision},
  \enquote{mode} for the \Option{rounding-mode}.
  Columns that start with \enquote{m} mean mandatory arguments.}
  \label{tab:numerr}
  \begin{tabular}{lllll}
    Macro & Options & m1 & m2 & m3 \\
    \Macro{numR}      & [sisetup]   & value & error \\
    \Macro{numRF}     & [prec] & value & error \\
    \Macro{numRP}     & [prec] & value & error \\
    \Macro{numpmerr}  & [prec] [mode] & value & err+ & err-\\
    \Macro{numpmerrx} & [siunitx] & value & err+ & err-\\
  \end{tabular}
\end{table}

\begin{table}[htbp]
  \caption{Arguments of quantity macros.
  \enquote{prec} is short for the \Option{rounding-precision},
  \enquote{mode} for the \Option{rounding-mode},
  \enquote{desc} is short for the description of what the error is,
  \enquote{stat.} is short for statistical error,
  \enquote{sys.} is short for systematic error/
  Columns that start with \enquote{m} mean mandatory arguments.}
  \label{tab:qtyerr}
  \begin{tabular}{ll lllllll l}
    Macro & Options & m1 & m2 & m3 & m4 & m5 & m6 & m7 & m8\\
    \Macro{qtypmerr} & [prec] [mode] & value & err+ & err- & unit\\
    \Macro{qtypmerrx} & [sisetup] & value & +err & err- & unit\\
    \Macro{qtyerrt} & [sisetup] & value & error & desc & unit\\
    \Macro{qtyerrtt} & [sisetup] & value & error & desc
      & error & desc & unit\\
    \Macro{qtypmerrt} & [sisetup] & value & err+ & err- & desc & unit\\
    \Macro{qtypmerrtt} & [sisetup] & value & err+ & err- & desc
      & err+ & err- & desc & unit\\
      \Macro{qtyerrs} & [sisetup] & value & stat. & sys. & unit\\
      \Macro{qtypmerrs} & [sisetup] & value & stat.+ & stat.- & sys.+ & sys- & unit\\
    \end{tabular}
\end{table}

%-------------------------------------------------------------------------------
\subsection{Asymmetric uncertainties}
%-------------------------------------------------------------------------------

Those of you with sharp eyes may spot that the width of \enquote{\(+\)} and \enquote{\(-\)}
are different in the default font used by ATLAS (\Package{newtx}).
This leads to the numbers in the subscripts and superscripts not being aligned.
For some examples see \cref{tab:asym}.

The option \Option{numpmcorr} in the \Package{atlasphysics} package
can be used to make the superscript and the subscript
have the same width.
% This is needed as in some fonts \enquote{\(+\)} and \enquote{\(-\)} have a different width.
This option is enabled by default as pdf\LaTeX\ has this problem
with the default ATLAS font, \Package{newtx}.
It is not needed (and slows things down) for Lua\LaTeX\ and Xe\LaTeX.
A macro \Macro{supsub} has been defined that ensures that the width
of the boxes for subscripts and superscripts is the same.
For example, if the \Option{numpmcorr} option is set,
the macro \Macro{numpmerr} uses \Macro{supsub} with two optional arguments:
the first one specifies the rounding precision, while the second the rounding mode
(\Option{places} or \Option{figures}).

\begin{table}[htbp]
\begin{tcblisting}{}
  \caption{Numbers with asymmetric uncertainties.}%
  \label{tab:asym}
  \centering
  \renewcommand{\arraystretch}{1.4}
  \begin{tabular}{cc}
    \toprule
    No macro & \Macro{numpmerr} \\
    \midrule
    \(^{\num{+0.223}}_{\num{-0.123}}\) & \numpmerr{+0.223}{-0.123} \\
    \(^{\num{+0.281}}_{\num{-0.215}}\) & \numpmerrx[round-precision=2]{+0.281}{-0.215}
  \end{tabular}
\end{tcblisting}
\end{table}

%-------------------------------------------------------------------------------
\section{Tables and rounding}
%-------------------------------------------------------------------------------

Further examples of tables can be found in the note discussing the ATLAS recommendations on rounding~\cite{atlas-rounding}.
A selection of those tables are also reproduced here.
The \LaTeX\ code for the examples given below can be found in \cref{sec:raw-data}.

The tables shown earlier in this document were also created with \Package{siunitx}.
A few more examples of how to steer the formatting are given here.
\Cref{tab:rounding:xsect} compares two different approaches
to how this can be done  in \Package{siunitx}, even for asymmetric errors.  Note that although these
tables look almost identical, the syntax used to create them is different (see \cref{sec:raw-data}).
While the form may appear to be a bit clumsy at first, it is easy enough to get a
program to write out the lines. In the left-hand table
\Macro{numRP} is used in column 3, while the full syntax of \Macro{num}
in shown in column 4 for illustration purposes only.
The syntax
to change the precision of a single number is shown in the first line of
the left-hand part of the table.
This is seen to be rather trivial,
but the alignment on the decimal point is now no longer perfect.
While this is probably OK for internal notes etc., papers
(should) have more stringent requirements.
Another way of achieving
the same thing and avoiding the use of \Option{round-mode} and
\Option{round-precision} is shown in the code for the right-hand table.
Note the
use of options for the \Option{S} format and the use of \Macro{num} enclosed
in braces to format the row that requires a different precision.
The macro \Macro{tablenum} is available to achieve alignment in complicated situations,
such as within a \Macro{multicolumn} or \Macro{multirow}.
It is, in effect, a macro version of the \Option{S} option.
See the \Package{siunitx}~\cite{siunitx} manual for more details.

\begin{table}[htbp]
  \caption{A selection of cross-section measurements. Note that
    for numbers with asymmetric errors, the option
    \Option{\Macro{sisetup}\{retain-explicit-plus\}} is used to stop
    \Package{siunitx} from dropping the plus signs on the positive
    errors. (Although these tables look almost identical, the syntax used to
    create them is different --- see \cref{sec:raw-data}).}
  \label{tab:rounding:xsect}

  \input{cross-sections_charm-eta1}
  \quad
  \input{cross-sections_charm-eta2}
\end{table}

Cross-sections vs.\ \(\eta\) are usually not so difficult to
format, as the magnitudes of the numbers do not change much from one
bin to the next. The situation is different for cross-sections as a
function of \ET\ or \(x\).
\Cref{tab:xsect-ET,tab:xsect-x} show examples of such tables.

\begin{table}[htbp]
  \caption{Cross-section vs.\ \ET.}
  \label{tab:xsect-ET}
  \centering
  \renewcommand{\arraystretch}{1.4}
  \subfloat[No special formatting and \Option{round-mode=figures}.
    This is the starting point for more refined formatting.]{%
    \input{cross-sections_charm-ET1}
    \label{tab:xsect-ET1}%
  }
  \qquad
  \subfloat[Numbers adjusted according to the recommendations.
    \Option{round-mode=places} is used for asymmetric errors (except the first row).
    Some judicious use of \Macro{phantom} is applied to get improved, but not yet perfect, alignment.]{%
    \input{cross-sections_charm-ET2}
    \label{tab:xsect-ET2}%
  }
\end{table}

\Option{round-mode=figures} is in general best for cross-sections and their errors.
A precision of 2 digits for the uncertainties is a good
starting point, but will then have to be reduced to 1 digit in some cases.
For the cross-section values, more digits (typically 3) probably have to
be specified and the precision of some values will again have to be adjusted by hand.
In \cref{tab:xsect-ET2} some of the rounding
is adjusted by hand so that the numbers conform to the rules.
For the asymmetric errors, \Option{round-mode=places} is used
and the precision of each asymmetric uncertainty is then set by hand.
This works well if the cross-sections should all be shown with decimal
points, but does not work if used to round a number such as
\num{182}. Hence the first row uses \Option{round-mode=figures}.
Even with the tools offered by \Macro{siunitx} getting things exactly right
is non-trivial.

\begin{table}[htb]
  \caption{Cross-section vs.\ \(x\).}
  \label{tab:xsect-x}
  \centering
  \renewcommand{\arraystretch}{1.4}
  \subfloat[No special formatting or rounding. Option
    \textsf{scientific-notation=fixed} used.]{%
    \label{tab:xsect-x1}%
    \input{cross-sections_charm-x1}
  }
  \quad
  \subfloat[Several fixes including rescaled cross-section. Quite a
    lot of \Macro{phantom} commands are applied to get alignment correct.]{%
    \label{tab:xsect-x2}%
    \input{cross-sections_charm-x2}
  }
\end{table}

\Cref{tab:xsect-x} is probably the most challenging to format
correctly, as the bin boundaries also vary by several orders of magnitude.
\Cref{tab:xsect-x1} gives the numbers with the option
\Option{scientific-notation=fixed} to illustrate the problem of what
the table would look like if the cross-sections are output in \unit{\pb}.
In \cref{tab:xsect-x2} the exponential format of
numbers is used to rescale the cross-section from \unit{\pb} to \unit{\nb}.
\Macro{phantom} had to be used in more places than we
really like in order to get the final alignment correct.
It may be possible to use the \Macro{tablenum} instead,
but this has not been tested.

%-------------------------------------------------------------------------------
\clearpage
\section*{History}
%-------------------------------------------------------------------------------

\begin{description}
\item[2014-11-25: Ian Brock] First version of the document released.
\item[2018-02-15: Ian Brock] Moved table captions above tables to follow common convention.
\item[2020-08-03: Ian Brock] Removed code for \TeX\ Live version older than 2013.
  More use of listings with \Package{tcolorbox}.
  Added a bit of information on the use of \Macro{tablenum} macro.
\item[202-12-09: Ian Brock] Added some examples of the usage of \Option{table-number-alignment}.
  Add macros for equal width subscripts and superscripts.
\end{description}


%-------------------------------------------------------------------------------
% Print the bibliography.
\printbibliography
%-------------------------------------------------------------------------------

\clearpage
\appendix
\section{\LaTeX\ code for tables}
\label{sec:raw-data}

This appendix gives the \LaTeX\ code including the raw data used for
\cref{tab:rounding:xsect,tab:xsect-ET,tab:xsect-x}.
These files can be found in the \texttt{doc/atlas\_tables} directory
of the \texttt{atlaslatex} package.
% The options given here correspond to those that are need for \TeX\ Live 2012 and later.

%------------------------------------------------------------------------------
\subsection{Table~\protect\ref{tab:rounding:xsect}}

The files are: \texttt{cross-sections\_charm-eta1.tex} and
\texttt{cross-sections\_charm-eta2.tex}:

\tcbinputlisting{listing file=cross-sections_charm-eta1, listing only,
  listing options={basicstyle=\ttfamily\scriptsize}}

\tcbinputlisting{listing file=cross-sections_charm-eta2, listing only,
  listing options={basicstyle=\ttfamily\scriptsize}}


%------------------------------------------------------------------------------
\clearpage
\subsection{Table~\protect\ref{tab:xsect-ET}}

The files are: \texttt{cross-sections\_charm-ET1.tex} and
\texttt{cross-sections\_charm-ET2.tex}:

\tcbinputlisting{listing file=cross-sections_charm-ET1, listing only,
  listing options={basicstyle=\ttfamily\scriptsize}}

\tcbinputlisting{listing file=cross-sections_charm-ET2, listing only,
  listing options={basicstyle=\ttfamily\scriptsize}}

%------------------------------------------------------------------------------
\clearpage
\subsection{Table~\protect\ref{tab:xsect-x}}

The files are: \texttt{cross-sections\_charm-x1.tex} and
\texttt{cross\_sections-charm-x2.tex}:

\tcbinputlisting{listing file=cross-sections_charm-x1, listing only,
  listing options={basicstyle=\ttfamily\scriptsize}}

\tcbinputlisting{listing file=cross-sections_charm-x2, listing only,
  listing options={basicstyle=\ttfamily\scriptsize}}

\end{document}
