7.1.2.1 2D histogram as a table for plotting ¶

When called with the --histogram=table option, Statistics will output a table file with three columns that have the information of every box as a column. If you asked for --numbins=N and --numbins2=M, all three columns will have \(M\times N\) rows (one row for every box/pixel of the 2D histogram). The first and second columns are the position of the box along the first and second dimensions. The third column has the number of input points that fall within that box/pixel.

For example, you can make high-quality plots within your paper (using the same LaTeX engine, thus blending very nicely with your text) using PGFPlots. Below you can see one such minimal example, using your favorite text editor, save it into a file, make the two small corrections in it, then run the commands shown at the top. This assumes that you have LaTeX installed, if not the steps to install a minimally sufficient LaTeX package on your system, see the respective section in Bootstrapping dependencies.

The two parts that need to be corrected are marked with ’%% <--’: the first one (XXXXXXXXX) should be replaced by the value to the --numbins option which is the number of bins along the first dimension. The second one (FILE.txt) should be replaced with the name of the file generated by Statistics.

%% Replace 'XXXXXXXXX' with your selected number of bins in the first
%% dimension.
%%
%% Then run these commands to build the plot in a LaTeX command.
%%    mkdir tikz
%%    pdflatex --shell-escape --halt-on-error report.tex
\documentclass{article}

%% Load PGFPlots and set it to build the figure separately in a 'tikz'
%% directory (which has to exist before LaTeX is run). This
%% "externalization" is very useful to include the commands of multiple
%% plots in the middle of your paper/report, but also have the plots
%% separately to use in slides or other scenarios.
\usepackage{pgfplots}
\usetikzlibrary{external}
\tikzexternalize
\tikzsetexternalprefix{tikz/}

%% Define colormap for the PGFPlots 2D histogram
\pgfplotsset{
 /pgfplots/colormap={hsvwhitestart}{
   rgb255(0cm)=(255,255,255)
   rgb255(0.10cm)=(128,0,128)
   rgb255(0.5cm)=(0,0,230)
   rgb255(1.cm)=(0,255,255)
   rgb255(2.5cm)=(0,255,0)
   rgb255(3.5cm)=(255,255,0)
   rgb255(6cm)=(255,0,0)
 }
}

%% Start the prinable document
\begin{document}

  You can write a full paper here and include many figures!
  Describe what the two axes are, and how you measured them.
  Also, do not forget to explain what it shows and how to interpret it.
  You also have separate PDFs for every figure in the `tikz' directory.
  Feel free to change this text.

  %% Draw the plot.
  \begin{tikzpicture}
    \small
    \begin{axis}[
      width=\linewidth,
      view={0}{90},
      colorbar horizontal,
      xlabel=X axis,
      ylabel=Y axis,
      ylabel shift=-0.1cm,
      colorbar style={at={(0,1.01)}, anchor=south west,
                      xticklabel pos=upper},
    ]
      \addplot3[
        surf,
        shader=flat corner,
        mesh/ordering=rowwise,
        mesh/cols=XXXXXXXXX,     %% <-- Number of bins in 1st column.
      ] file {FILE.txt};         %% <-- Name of aststatistics output.

  \end{axis}
\end{tikzpicture}

%% End the printable document.
\end{document}

Let’s assume you have put the LaTeX source above, into a plain-text file called report.tex. The PGFPlots call above is configured to build the plots as separate PDF files in a tikz/ directory¹⁹⁴. This allows you to directly load those PDFs in your slides or other reports. Therefore, before building the PDF report, you should first make a tikz/ directory:

$ mkdir tikz

To build the final PDF, you should run pdflatex with the --shell-escape option, so it can build the separate PDF(s) separately. We are also adding the --halt-on-error so it immediately aborts in the case of an error (in the case of an error, by default LaTeX will not abort, it will stop and ask for your input to temporarily change things and try fixing the error, but it has a special interface which can be hard to master).

$ pdflatex --shell-escape --halt-on-error report.tex

You can now open report.pdf to see your very high quality 2D histogram within your text. And if you need the plots separately (for example, for slides), you can take the PDF inside the tikz/ directory.