**** MULTIPLOT LAYOUT HELPER SCRIPT ****

Motivation:
-----------

The built-in layout option for gnuplot's multiplot style is a highly
useful tool for many purposes. However, setting nicely aligned layouts
for scientific figures is still painful. The easiest way to make
panels with margin-free fitting subframes is to set all margins to
zero and write the labels outside the canvas. This may work often, but
may fail even more often, e.g. due to hard-coded clipping of objects
to the canvas boundary.

Description and usage:
----------------------

This script provides an easy way to specify well-aligned multiplot
panels by using the absolute margin syntax ("set *margin screen
<value>"; see the gnuplot guide for details). The script calculates
the absolute margin positions depending on the number of rows and
columns of subframes, as well as on the subframe aspect ratio and any
required margin fraction for labels. Furthermore, it allows to place
axis labels to those frame borders at the outer border if the whole
panel, thus avoiding labels breaking up the panel layout or writing
labels inside neighbouring frames.

The user specifies the number of columns (ncols) and rows (nrows), the
subframe aspect ratio (qratio = height/width of the subframe), the
width and height of the graph or plotting canvas (i.e. the part of the
canvas that is occupied by the panel of graphs), and the decimal
fraction of the full gnuplot canvas that should be reserved for axis
labels, colorbox etc.  The script then calculates the full canvas
dimensions xcanvas, ycanvas (which you can then apply to the terminal
setting) and the absolute margins of the subframes.

Before setting the multiplot style, the base script mplayout_base.gp
has to be called with given ncols, nrows, xpcanv, ypcanv, and
qratio. Before each plot command within the multiplot environment, the
frame-setting script mplayout_frame.gp is called with given column
index c (1...ncols) and row index r (1...nrows), as well as given text
strings xlabeltext and ylabeltext, and label switches flgxlabel,
flgylabel, unless the user wishes to set the axis labels manually.

Issues: For now, there is no safe way to estimate the required margins
for labels. Such a function, which would require information about the
font type and size, may be implemented in a future version. For now,
the required margins have to be estimated and transferred to the script
by the variables lmgadd, rmgadd, tmgadd, and bmgadd. These are treated
as additional margins around the graph canvas. In addition, margins can
be defined for the individual frames via the variables lmgsub, rmgsub,
tmgsub, and bmgsub. They are, for now, equally set for all subframes.

The script has been tested with the gnuplot 4.4 and the development version.
However, it probably also works fine with version 4.2.

License info:
-------------

I am not sure whether these scripts are of sufficient complexity to be
subject to copyright law. However, in case it does I am providing these scripts

mplayout_base.gp
mplayout_frame.gp
testframes.gp

under the FreeBSD License license:

--------------------------------------------------------------------------------------------
LICENCE TERMS

Copyright (c) 2010-2011 by Ingo Thies

Redistribution and use in source and binary forms, with or without modification, are
permitted provided that the following conditions are met:

   1. Redistributions of source code must retain the above copyright notice, this list of
      conditions and the following disclaimer.

   2. Redistributions in binary form must reproduce the above copyright notice, this list
      of conditions and the following disclaimer in the documentation and/or other materials
      provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are those of the
authors and should not be interpreted as representing official policies, either expressed
or implied, of the copyright holder.
--------------------------------------------------------------------------------------------