makeplots.md 18.6 KB
Newer Older
Christian Bierlich's avatar
Christian Bierlich committed
1 2
# make-plots

Christian Bierlich's avatar
Christian Bierlich committed
3 4 5
The plots produced with `rivet-mkhtml` are really rendered with the command `make-plots`, which is called under the hood. The `make-plots` command can also be used to create figures from the simple .dat text format produced by `rivet-cmphistos` directly.
The `make-plots` script is quite powerful, and includes several options to modify plotting style, adding curves or fits and more. For use with Rivet, the syntax documented in this document should be provided in the .plot file.
Internally, `make-plots` the simple text format and converts them into PostScript or PDF files by creating a LaTeX file and running `latex`, `dvips`, and maybe `ps2pdf`.
Christian Bierlich's avatar
Christian Bierlich committed
6 7 8 9 10

## Usage

To run `make-plots` call

Christian Bierlich's avatar
Christian Bierlich committed
11
```
Christian Bierlich's avatar
Christian Bierlich committed
12
     make-plots [options] file.dat [file2.dat ...]
Christian Bierlich's avatar
Christian Bierlich committed
13
```
Christian Bierlich's avatar
Christian Bierlich committed
14 15 16

All available options can be listed by running

Christian Bierlich's avatar
Christian Bierlich committed
17
```
Christian Bierlich's avatar
Christian Bierlich committed
18
     make-plots --help
Christian Bierlich's avatar
Christian Bierlich committed
19
```
Christian Bierlich's avatar
Christian Bierlich committed
20 21 22 23 24 25 26 27

### Configuration files


`make-plots` typically takes the plotting instructions and settings from the input ascii files as described in the "Input Format" chapter. It is also possible though to pass a global configuration file to `make-plots` (cf. `--help`) which allows to specify/overwrite settings for certain plots or histograms in a plot on top of what the input files specify. This could be useful if the ascii files are generated automatically (e.g. with `rivet-mkhtml` or `compare-histos`) and you still want to apply custom plotting options.

An example for this looks like:

Christian Bierlich's avatar
Christian Bierlich committed
28
```
Christian Bierlich's avatar
Christian Bierlich committed
29 30 31 32 33 34
    # BEGIN PLOT figures/MC_WJETS/W_mass.dat
    XMin=60.0
    XMax=100.0
    LegendXPos=0.65
    # END PLOT

Christian Bierlich's avatar
Christian Bierlich committed
35
    .*myLOrun.yoda/D0_2008_S7554427/d01-x01-y01::Scale=1.0
Christian Bierlich's avatar
Christian Bierlich committed
36

Christian Bierlich's avatar
Christian Bierlich committed
37
```
Christian Bierlich's avatar
Christian Bierlich committed
38 39 40 41 42 43 44 45 46 47 48 49 50

Here first the options in the `PLOT` section of a specific ascii file are being amended/overwritten. The second part shows how to overwrite the `Scale` property of one specific histogram line using the ID of the histogram.

## Input Format

The ascii files which can be read by `make-plots` are divided into sections. There are four types of sections which are called `PLOT`, `HISTOGRAM`, `FUNCTION`, and `SPECIAL`. Every file must contain exactly one `PLOT` section and at least one section of the other three types. There may be multiple `HISTOGRAM`, `FUNCTION`, and `SPECIAL` sections.

Empty lines and lines starting with `#` are ignored, except for the section delimiters described below.

### PLOT

The `PLOT` section starts with

Christian Bierlich's avatar
Christian Bierlich committed
51
```
Christian Bierlich's avatar
Christian Bierlich committed
52 53
    # BEGIN PLOT

Christian Bierlich's avatar
Christian Bierlich committed
54
```
Christian Bierlich's avatar
Christian Bierlich committed
55 56 57
and ends with


Christian Bierlich's avatar
Christian Bierlich committed
58
```
Christian Bierlich's avatar
Christian Bierlich committed
59 60
    # END PLOT

Christian Bierlich's avatar
Christian Bierlich committed
61
```
Christian Bierlich's avatar
Christian Bierlich committed
62 63 64 65 66 67

Every file must have exactly one `PLOT` section. In this section global parameters are specified, like the axis labels, the plot title, size, … An empty `PLOT` section is perfectly legal, though.
In this section the following parameters can be set:

#### Titles, Labels

Christian Bierlich's avatar
Christian Bierlich committed
68
```
Christian Bierlich's avatar
Christian Bierlich committed
69 70
    Title=<title>

Christian Bierlich's avatar
Christian Bierlich committed
71
```
Christian Bierlich's avatar
Christian Bierlich committed
72 73
The title of the plot.

Christian Bierlich's avatar
Christian Bierlich committed
74
```
Christian Bierlich's avatar
Christian Bierlich committed
75 76 77 78
    XLabel=<label>
    YLabel=<label>
    ZLabel=<label>

Christian Bierlich's avatar
Christian Bierlich committed
79
```
Christian Bierlich's avatar
Christian Bierlich committed
80 81 82
Axis labels for the x-, y-, and z-axis.


Christian Bierlich's avatar
Christian Bierlich committed
83
```
Christian Bierlich's avatar
Christian Bierlich committed
84 85 86 87
    XLabelSep=<distance>
    YLabelSep=<distance>
    ZLabelSep=<distance>

Christian Bierlich's avatar
Christian Bierlich committed
88
```
Christian Bierlich's avatar
Christian Bierlich committed
89 90
Distance between the axis label and the plot in units of `\labelsep`.

Christian Bierlich's avatar
Christian Bierlich committed
91
```
Christian Bierlich's avatar
Christian Bierlich committed
92 93 94 95 96 97
    XMajorTickMarks=<last_digit>
    YMajorTickMarks=<last_digit>
    ZMajorTickMarks=<last_digit>
    XMinorTickMarks=<nticks>
    YMinorTickMarks=<nticks>
    ZMinorTickMarks=<nticks>
Christian Bierlich's avatar
Christian Bierlich committed
98
```
Christian Bierlich's avatar
Christian Bierlich committed
99 100 101

`make-plots` tries to guess the distance between tickmarks automatically. If you are not satisfied with its result, you can override this by setting `<last_digit>` to 1, 2, 5, or 10, and `<nticks>` to the number of minor ticks you like. _Note_: These options are not available for logarithmic axes.

Christian Bierlich's avatar
Christian Bierlich committed
102
```
Christian Bierlich's avatar
Christian Bierlich committed
103 104 105
    XTwosidedTicks=<0|1>
    YTwosidedTicks=<0|1>

Christian Bierlich's avatar
Christian Bierlich committed
106
```
Christian Bierlich's avatar
Christian Bierlich committed
107 108
Draw tickmarks also on the upper and/or right side of the plot.

Christian Bierlich's avatar
Christian Bierlich committed
109
```
Christian Bierlich's avatar
Christian Bierlich committed
110 111 112 113
    XCustomMajorTicks=<list>
    YCustomMajorTicks=<list>
    ZCustomMajorTicks=<list>

Christian Bierlich's avatar
Christian Bierlich committed
114
```
Christian Bierlich's avatar
Christian Bierlich committed
115 116 117 118

To specify major ticks at arbitrary positions and/or with arbitrary labels. `<list>` is a whitespace-separated list of format `value1 <spaces_or_tabs> label1 <spaces_or_tabs> value2 <spaces_or_tabs> label2 ...`.


Christian Bierlich's avatar
Christian Bierlich committed
119
[//]: # TODO: allow use of YAML-style list syntax to clarify delimiters?
Christian Bierlich's avatar
Christian Bierlich committed
120

Christian Bierlich's avatar
Christian Bierlich committed
121
```
Christian Bierlich's avatar
Christian Bierlich committed
122 123 124
    XCustomMinorTicks=<list>
    YCustomMinorTicks=<list>
    ZCustomMinorTicks=<list>
Christian Bierlich's avatar
Christian Bierlich committed
125
```
Christian Bierlich's avatar
Christian Bierlich committed
126 127
To specify minor ticks at arbitrary positions. `<list>` is a tab separated list of format `value1 <tab> value2 <tab> value3 ...`.

Christian Bierlich's avatar
Christian Bierlich committed
128
```
Christian Bierlich's avatar
Christian Bierlich committed
129 130 131
    PlotXTickLabels=<0|1>
    RatioPlotTickLabels=<0|1>

Christian Bierlich's avatar
Christian Bierlich committed
132
```
Christian Bierlich's avatar
Christian Bierlich committed
133 134 135 136 137
Disable/enable plotting of the tick labels in the plot and ratio plot (useful if multiple plots are to be combined manually later).


#### Axes

Christian Bierlich's avatar
Christian Bierlich committed
138
```
Christian Bierlich's avatar
Christian Bierlich committed
139 140 141 142
    LogX=<0|1>
    LogY=<0|1>
    LogZ=<0|1>

Christian Bierlich's avatar
Christian Bierlich committed
143
```
Christian Bierlich's avatar
Christian Bierlich committed
144 145
Use a logarithmic x-, y-, or z-axis. Default is linear.

Christian Bierlich's avatar
Christian Bierlich committed
146
```
Christian Bierlich's avatar
Christian Bierlich committed
147 148 149 150 151 152 153 154 155
    XMin=<value>
    XMax=<value>
    YMin=<value>
    YMax=<value>
    ZMin=<value>
    ZMax=<value>
    FullRange=<0|1>
    ShowZero=<0|1>

Christian Bierlich's avatar
Christian Bierlich committed
156
```
Christian Bierlich's avatar
Christian Bierlich committed
157 158 159 160
Specify the plot range. By default the range is chosen such that all data is visible in linear plots, and the zero is visible. `ShowZero=0` suppresses plotting the zero in linear plots and thus zooms into the actual y-value range of the distribution. In logarithmic plots the automatic choice of `YMin` is limited to be not smaller than 2e-4*`YMax`, but manually you can specify any value. `FullRange=1` also overrides the 2e-4*`YMax` limit and plots the full range in y.

#### Normalization, Rebinning

Christian Bierlich's avatar
Christian Bierlich committed
161
```
Christian Bierlich's avatar
Christian Bierlich committed
162 163 164
    NormalizeToIntegral=<1|0>
    NormalizeToSum=<1|0>
    Scale=<factor>
Christian Bierlich's avatar
Christian Bierlich committed
165
```
Christian Bierlich's avatar
Christian Bierlich committed
166 167
Normalize all histograms to their integral, to their sum of entries, or scale them by some arbitrary factor. Normalization and scale options in the `PLOT` section override the corresponding option in the `HISTOGRAM` section. The scale factor is applied after normalization.

Christian Bierlich's avatar
Christian Bierlich committed
168
```
Christian Bierlich's avatar
Christian Bierlich committed
169
    Rebin=<nbins>
Christian Bierlich's avatar
Christian Bierlich committed
170
```
Christian Bierlich's avatar
Christian Bierlich committed
171 172 173 174
Rebin all histograms in this plot. Syntax and functionality is the same as for the Rebin option in the `HISTOGRAM` section.

#### Sizes and Margins

Christian Bierlich's avatar
Christian Bierlich committed
175 176 177
```
     PlotSize=<xsize,ysize>
```
Christian Bierlich's avatar
Christian Bierlich committed
178 179
Size in x and y direction of the plot. This can be specified in any unit LaTeX understands.

Christian Bierlich's avatar
Christian Bierlich committed
180
```
Christian Bierlich's avatar
Christian Bierlich committed
181 182 183 184
    LeftMargin=<size>
    RightMargin=<size>
    TopMargin=<size>
    BottomMargin=<size>
Christian Bierlich's avatar
Christian Bierlich committed
185
```
Christian Bierlich's avatar
Christian Bierlich committed
186 187 188

Distance between the plot and the paper edge.

Christian Bierlich's avatar
Christian Bierlich committed
189
```
Christian Bierlich's avatar
Christian Bierlich committed
190
    FrameColor=<color>
Christian Bierlich's avatar
Christian Bierlich committed
191
```
Christian Bierlich's avatar
Christian Bierlich committed
192 193 194 195
Background color for the margin around the plot.

#### Legends

Christian Bierlich's avatar
Christian Bierlich committed
196
```
Christian Bierlich's avatar
Christian Bierlich committed
197
    Legend=<0|1>
Christian Bierlich's avatar
Christian Bierlich committed
198
```
Christian Bierlich's avatar
Christian Bierlich committed
199 200
Display a legend in the plot.

Christian Bierlich's avatar
Christian Bierlich committed
201
```
Christian Bierlich's avatar
Christian Bierlich committed
202
    CustomLegend=<text>
Christian Bierlich's avatar
Christian Bierlich committed
203
```
Christian Bierlich's avatar
Christian Bierlich committed
204 205 206

Custom text that is added to the legend.

Christian Bierlich's avatar
Christian Bierlich committed
207
```
Christian Bierlich's avatar
Christian Bierlich committed
208 209
    LegendXPos=<pos>
    LegendYPos=<pos>
Christian Bierlich's avatar
Christian Bierlich committed
210
```
Christian Bierlich's avatar
Christian Bierlich committed
211 212
Position of the legend within the plot. Anchor point is the top left corner of the legend, so units typically range between 0.0 and 1.0.

Christian Bierlich's avatar
Christian Bierlich committed
213
```
Christian Bierlich's avatar
Christian Bierlich committed
214
    LegendAlign=<align>
Christian Bierlich's avatar
Christian Bierlich committed
215
```
Christian Bierlich's avatar
Christian Bierlich committed
216 217
Horizontal alignment of the legend: `LegendAlign=l` is the default and will create a left-aligned legend, while `LegendAlign=r` is right-aligned with the keys on the right hand side.

Christian Bierlich's avatar
Christian Bierlich committed
218
```
Christian Bierlich's avatar
Christian Bierlich committed
219
    LegendOnly=<list>
Christian Bierlich's avatar
Christian Bierlich committed
220
```
Christian Bierlich's avatar
Christian Bierlich committed
221 222 223 224 225
Whitespace separated list of IDs. These can be histograms or functions. The legend is only shown for the listed objects. Without this option, all plotted objects which have a title enter the legend. The legend titles are plotted in the given order, so there are cases in which it makes sense to use `LegendOnly` together with all histogram IDs. It is also possible to specify the legend order on an entry-by-entry basis using the `LegendOrder=<int>` setting for each histogram or function.


#### Plotting Options

Christian Bierlich's avatar
Christian Bierlich committed
226
```
Christian Bierlich's avatar
Christian Bierlich committed
227
    DrawOnly=<list>
Christian Bierlich's avatar
Christian Bierlich committed
228
```
Christian Bierlich's avatar
Christian Bierlich committed
229 230 231

Whitespace separated list of histogram IDs. Only the histograms in this list are plotted, even if there are more histograms defined in the file. The histograms are plotted in the given order, so there are cases in which it makes sense to use `DrawOnly` together with all histogram IDs. This is especially useful for the `Stack` option. It is also possible to specify the plotting order on a histogram-by-histogram basis using the `PlotOrder=<int>` setting for each histogram.

Christian Bierlich's avatar
Christian Bierlich committed
232
```
Christian Bierlich's avatar
Christian Bierlich committed
233
    Stack=<list>
Christian Bierlich's avatar
Christian Bierlich committed
234
```
Christian Bierlich's avatar
Christian Bierlich committed
235 236
Whitespace separated list of histogram IDs. The histograms will be added on top of each other. This is useful for example to compare data with background if the background has contributions from several histograms.

Christian Bierlich's avatar
Christian Bierlich committed
237
```
Christian Bierlich's avatar
Christian Bierlich committed
238 239
    DrawSpecialFirst=<0|1>
    DrawFunctionFirst=<0|1>
Christian Bierlich's avatar
Christian Bierlich committed
240
```
Christian Bierlich's avatar
Christian Bierlich committed
241 242
By default the `SPECIAL` and `FUNCTION` sections are plotted after the histograms. With these options you can override that behaviour.

Christian Bierlich's avatar
Christian Bierlich committed
243
```
Christian Bierlich's avatar
Christian Bierlich committed
244
    ConnectGaps=<0|1>
Christian Bierlich's avatar
Christian Bierlich committed
245
```
Christian Bierlich's avatar
Christian Bierlich committed
246 247 248 249 250 251 252
If error bars are disabled and you want to bridge gaps in a histogram, you can set this parameter. By default it is off. Setting it in the `PLOT` section affects all histograms, but you can also set it in the `HISTOGRAM` section for individual histograms. The local setting overrides the global setting.


#### Comparison Plots

With the

Christian Bierlich's avatar
Christian Bierlich committed
253
```
Christian Bierlich's avatar
Christian Bierlich committed
254 255
    RatioPlot=1
    RatioPlotReference=<histogram_ID>
Christian Bierlich's avatar
Christian Bierlich committed
256
```
Christian Bierlich's avatar
Christian Bierlich committed
257
options you can create ratio plots for two or more histograms. Note that you must specify your reference data ID. This option is used by the `compare-histos` script.
Christian Bierlich's avatar
Christian Bierlich committed
258

Christian Bierlich's avatar
Christian Bierlich committed
259
```
Christian Bierlich's avatar
Christian Bierlich committed
260
    RatioPlotMode=<default|deviation|datamc>
Christian Bierlich's avatar
Christian Bierlich committed
261
```
Christian Bierlich's avatar
Christian Bierlich committed
262 263 264 265 266

By default, the ratio plot displays MC/Data. You can switch to (MC-data)/uncertainty (`deviation`) or Data/MC (`datamc`) with this option.

In ratio plots the following additional options are available and work in a similar way as their regular counterparts:

Christian Bierlich's avatar
Christian Bierlich committed
267
```
Christian Bierlich's avatar
Christian Bierlich committed
268 269 270 271 272
    RatioPlotYLabel=<label>
    RatioPlotYMin=<value>
    RatioPlotYMax=<value>
    RatioPlotYSize=<size>
    RatioPlotErrorBandColor=<color>
Christian Bierlich's avatar
Christian Bierlich committed
273
```
Christian Bierlich's avatar
Christian Bierlich committed
274 275 276

By default, the reference data is plotted using a yellow error band around the central value of the ratio plot. If you would rather have it plotted in the same style as in the main plot (e.g. with black errorbars), you can specify:

Christian Bierlich's avatar
Christian Bierlich committed
277
```
Christian Bierlich's avatar
Christian Bierlich committed
278
    RatioPlotSameStyle=1
Christian Bierlich's avatar
Christian Bierlich committed
279
```
Christian Bierlich's avatar
Christian Bierlich committed
280 281 282

If you only want the ratio plot without showing the actual data distribution, you can switch off the main plot. This option implies `RatioPlot=1`:

Christian Bierlich's avatar
Christian Bierlich committed
283
```
Christian Bierlich's avatar
Christian Bierlich committed
284
    MainPlot=0
Christian Bierlich's avatar
Christian Bierlich committed
285
```
Christian Bierlich's avatar
Christian Bierlich committed
286 287 288 289 290 291 292

#### Goodness of Fit


`make-plots` can calculate the goodness of fit between histograms and display the result in the legend. It is also possible to change the color of the margin around the plot depending on the GoF. This is useful to provide a quick overview when looking at many plots.


Christian Bierlich's avatar
Christian Bierlich committed
293
```
Christian Bierlich's avatar
Christian Bierlich committed
294
    GofType=chi2
Christian Bierlich's avatar
Christian Bierlich committed
295
```
Christian Bierlich's avatar
Christian Bierlich committed
296 297 298 299

The type of GoF. The default is `chi2` and currently that’s the only option.


Christian Bierlich's avatar
Christian Bierlich committed
300
```
Christian Bierlich's avatar
Christian Bierlich committed
301
    GofReference=<histogram_ID>
Christian Bierlich's avatar
Christian Bierlich committed
302
```
Christian Bierlich's avatar
Christian Bierlich committed
303 304 305 306 307 308

specifies the reference histogram to be used for the GoF calculation. If this option is omitted, the fallback is `RatioPlotReference`.


The GoF calculation is activated by two options:

Christian Bierlich's avatar
Christian Bierlich committed
309
```
Christian Bierlich's avatar
Christian Bierlich committed
310 311
    GofLegend=<0|1>
    GofFrame=<histogram_ID>
Christian Bierlich's avatar
Christian Bierlich committed
312
```
Christian Bierlich's avatar
Christian Bierlich committed
313 314 315

`GofLegend` calculates the GoF for all histograms and displays the results in the legend. With `GofFrame` you can specify a single histogram for which the GoF result will be shown in the legend and used to assign a color to the plot margins. Note that `FrameColor` overrides the color choice for the margin. You can use

Christian Bierlich's avatar
Christian Bierlich committed
316
```
Christian Bierlich's avatar
Christian Bierlich committed
317 318
    GofFrameColor=<colorthresholds>

Christian Bierlich's avatar
Christian Bierlich committed
319
```
Christian Bierlich's avatar
Christian Bierlich committed
320 321 322 323 324 325 326

to specify the thresholds for the frame color. This option takes a list of `<threshold>:<color>` pairs, separated by whitespace. The default is `GofFrameColor=0:green 3:yellow 6:red!70`. Again, if you use `FrameColor`, this option is disabled.

#### Color Palettes for 2-dim Plots

With the option `ColorSeries` you can define a custom color palette for 2-dimensional plots. The syntax is the same as for the `\definecolorseries` command in the `xcolor` LaTeX package after the color series name, i.e. `{core-model}{method}[begin-model]{begin-spec}[end-model]{end-spec}`. For more information you can consult the [xcolor documentation](http://www.ctan.org/tex-archive/macros/latex/contrib/xcolor/xcolor.pdf). Here is an example:

Christian Bierlich's avatar
Christian Bierlich committed
327
```
Christian Bierlich's avatar
Christian Bierlich committed
328
    ColorSeries={rgb}{last}[rgb]{1,0.97,0.94}[rgb]{0.6,0.0,0.05}
Christian Bierlich's avatar
Christian Bierlich committed
329
```
Christian Bierlich's avatar
Christian Bierlich committed
330 331 332 333
### HISTOGRAM

The `HISTOGRAM` section starts with

Christian Bierlich's avatar
Christian Bierlich committed
334
```
Christian Bierlich's avatar
Christian Bierlich committed
335
    # BEGIN HISTOGRAM <ID>
Christian Bierlich's avatar
Christian Bierlich committed
336
```
Christian Bierlich's avatar
Christian Bierlich committed
337 338 339

and ends with

Christian Bierlich's avatar
Christian Bierlich committed
340
```
Christian Bierlich's avatar
Christian Bierlich committed
341
    # END HISTOGRAM
Christian Bierlich's avatar
Christian Bierlich committed
342
```
Christian Bierlich's avatar
Christian Bierlich committed
343 344 345 346 347 348 349

There can be more than one `HISTOGRAM` section in a file. Histograms are identified by `<ID>` which can be any string _not_ containing whitespace.

#### Data Format

Lines starting with a number (positive or negative) are interpreted as data. Each line specifies one bin. The fields in each line must be separated by tabs, not spaces (this needs to be fixes some day). For 1-dimensional histograms the format can be

Christian Bierlich's avatar
Christian Bierlich committed
350
```
Christian Bierlich's avatar
Christian Bierlich committed
351 352
    <lowerbinedge>  <upperbinedge>  <value>  <error>
    <lowerbinedge>  <upperbinedge>  <value>  <minuserror>  <pluserror>
Christian Bierlich's avatar
Christian Bierlich committed
353
```
Christian Bierlich's avatar
Christian Bierlich committed
354 355 356

2-dimensional histograms are supported, too. They are plotted as colormap (errors are ignored) and specified as

Christian Bierlich's avatar
Christian Bierlich committed
357
```
Christian Bierlich's avatar
Christian Bierlich committed
358
    <lowerxbinedge>  <upperxbinedge>  <lowerybinedge>  <upperybinedge>  <value>  <error>
Christian Bierlich's avatar
Christian Bierlich committed
359
```
Christian Bierlich's avatar
Christian Bierlich committed
360 361 362

#### Titles

Christian Bierlich's avatar
Christian Bierlich committed
363
```
Christian Bierlich's avatar
Christian Bierlich committed
364
    Title=<title>
Christian Bierlich's avatar
Christian Bierlich committed
365
```
Christian Bierlich's avatar
Christian Bierlich committed
366 367 368 369 370

Title of the histogram. This is used for the legend.

#### Linestyles

Christian Bierlich's avatar
Christian Bierlich committed
371
```
Christian Bierlich's avatar
Christian Bierlich committed
372
    LineStyle=<style>
Christian Bierlich's avatar
Christian Bierlich committed
373
```
Christian Bierlich's avatar
Christian Bierlich committed
374 375 376

Any linestyle that is understood by the LaTeX pstricks package, e.g. `solid`, `dotted`, `dashed`, `none`, as well as a special `dashdotted` (or `dotdashed`) linestyle which does what you might expect.

Christian Bierlich's avatar
Christian Bierlich committed
377
```
Christian Bierlich's avatar
Christian Bierlich committed
378
    LineColor=<color>
Christian Bierlich's avatar
Christian Bierlich committed
379
```
Christian Bierlich's avatar
Christian Bierlich committed
380 381
Color of the line. Default is black, but any color that pstricks understands can be used, including constructions like `red!70!blue!20` (for mixing colors), `{[rgb]{0.8,0,0.7}}` (for RGB-colors), `{[wave]{580}}` (for wavelengths in nm), `LineColor={[cmyk]{1,1,0,0}}` for CMYK-colors, or `[hsb]{0.5,1,1}` for HSB-colors.

Christian Bierlich's avatar
Christian Bierlich committed
382
```
Christian Bierlich's avatar
Christian Bierlich committed
383
    LineOpacity=<opacity>
Christian Bierlich's avatar
Christian Bierlich committed
384
```
Christian Bierlich's avatar
Christian Bierlich committed
385 386 387

Set the opacity of the line. Default is 1.0\. This might not work for ps output.

Christian Bierlich's avatar
Christian Bierlich committed
388
```
Christian Bierlich's avatar
Christian Bierlich committed
389
    LineWidth=<width>
Christian Bierlich's avatar
Christian Bierlich committed
390
```
Christian Bierlich's avatar
Christian Bierlich committed
391 392 393

Width of the line.

Christian Bierlich's avatar
Christian Bierlich committed
394
```
Christian Bierlich's avatar
Christian Bierlich committed
395
    LineDash=<dashstyle>
Christian Bierlich's avatar
Christian Bierlich committed
396
```
Christian Bierlich's avatar
Christian Bierlich committed
397 398 399

If `LineStyle` is set to `dashed`, you can specify the dash style with this option. Anything that is understood by pstrick’s `dash=...` option is valid. An example for a dash-dotted line is `LineDash=3pt 3pt .8pt 3pt`. You can use `LineStyle=dashdotted` or `LineStyle=dotdashed` as an abbreviation for `LineStyle=dashed` with `LineDash=3pt 3pt .8pt 3pt`.

Christian Bierlich's avatar
Christian Bierlich committed
400
```
Christian Bierlich's avatar
Christian Bierlich committed
401
    ConnectBins=<0|1>
Christian Bierlich's avatar
Christian Bierlich committed
402
```
Christian Bierlich's avatar
Christian Bierlich committed
403 404 405

Choose whether to connect adjacent bins' horizontal lines together by a vertical line on the bin edge. This is enabled by default, but you may wish to disable it when plotting reference data with error bars and point markers.

Christian Bierlich's avatar
Christian Bierlich committed
406
```
Christian Bierlich's avatar
Christian Bierlich committed
407
    ConnectGaps=<0|1>
Christian Bierlich's avatar
Christian Bierlich committed
408
```
Christian Bierlich's avatar
Christian Bierlich committed
409 410 411

If ConnectBins is enabled and you want to bridge gaps in a histogram, you can set this parameter. By default it is off. Setting it in the `PLOT` section affects all histograms, but you can also set it in the `HISTOGRAM` section for individual histograms. The local setting overrides the global setting.

Christian Bierlich's avatar
Christian Bierlich committed
412
```
Christian Bierlich's avatar
Christian Bierlich committed
413
    SmoothLine=<0|1>
Christian Bierlich's avatar
Christian Bierlich committed
414
```
Christian Bierlich's avatar
Christian Bierlich committed
415 416 417 418 419

Draw a smooth curve rather than a histogram

#### Fillstyles

Christian Bierlich's avatar
Christian Bierlich committed
420
```
Christian Bierlich's avatar
Christian Bierlich committed
421 422
    FillStyle=<style>
    FillColor=<color>
Christian Bierlich's avatar
Christian Bierlich committed
423
```
Christian Bierlich's avatar
Christian Bierlich committed
424 425 426

To fill the area below a histogram, set `FillStyle` and `FillColor` to something pstricks understands. Examples for the style are `solid` or `vlines`. See `LineColor` for examples of color definitions.

Christian Bierlich's avatar
Christian Bierlich committed
427
```
Christian Bierlich's avatar
Christian Bierlich committed
428
    FillOpacity=<opacity>
Christian Bierlich's avatar
Christian Bierlich committed
429
```
Christian Bierlich's avatar
Christian Bierlich committed
430 431 432

Set the opacity of the solid fillcolor. Default is 1.0\. This might not work for ps output.

Christian Bierlich's avatar
Christian Bierlich committed
433
```
Christian Bierlich's avatar
Christian Bierlich committed
434
    HatchColor=<color>
Christian Bierlich's avatar
Christian Bierlich committed
435
```
Christian Bierlich's avatar
Christian Bierlich committed
436 437 438 439 440

The color of a hatch pattern used for filling the area below a histogram. This is used for example when you use `vlines` as style.

#### Data Points

Christian Bierlich's avatar
Christian Bierlich committed
441
```
Christian Bierlich's avatar
Christian Bierlich committed
442
    ErrorBars=<0|1>
Christian Bierlich's avatar
Christian Bierlich committed
443
```
Christian Bierlich's avatar
Christian Bierlich committed
444 445 446

Turn on error bars.

Christian Bierlich's avatar
Christian Bierlich committed
447
```
Christian Bierlich's avatar
Christian Bierlich committed
448 449
    ErrorBands=<0|1>
    ErrorBandColor=<color>
Christian Bierlich's avatar
Christian Bierlich committed
450
```
Christian Bierlich's avatar
Christian Bierlich committed
451 452
Turn on error bands and set their color (see `LineColor` for a description of color definitions).

Christian Bierlich's avatar
Christian Bierlich committed
453
```
Christian Bierlich's avatar
Christian Bierlich committed
454
    ErrorBandOpacity=<opacity>
Christian Bierlich's avatar
Christian Bierlich committed
455
```
Christian Bierlich's avatar
Christian Bierlich committed
456 457 458

Set the opacity of the error band. Default is 1.0\. This might not work for ps output.

Christian Bierlich's avatar
Christian Bierlich committed
459
```
Christian Bierlich's avatar
Christian Bierlich committed
460
    PolyMarker=<dotstyle>
Christian Bierlich's avatar
Christian Bierlich committed
461
```
Christian Bierlich's avatar
Christian Bierlich committed
462 463 464

The marker style of the points. Any dot style which is understood by pstricks is valid, e.g. `*`, `o`, `triangle`, `diamond`, …

Christian Bierlich's avatar
Christian Bierlich committed
465
```
Christian Bierlich's avatar
Christian Bierlich committed
466 467
    DotSize=<size>
    DotScale=<factor>
Christian Bierlich's avatar
Christian Bierlich committed
468
```
Christian Bierlich's avatar
Christian Bierlich committed
469 470 471 472 473

The size of the markers. With `DotSize` you can specify the absolute size, e.g. in units of `pt`, while `DotScale` is a relative measure with respect to the default size.

#### Normalization, Rebinning

Christian Bierlich's avatar
Christian Bierlich committed
474
```
Christian Bierlich's avatar
Christian Bierlich committed
475 476 477
    NormalizeToIntegral=<1|0>
    NormalizeToSum=<1|0>
    Scale=<factor>
Christian Bierlich's avatar
Christian Bierlich committed
478
```
Christian Bierlich's avatar
Christian Bierlich committed
479 480 481

Normalize the histogram to the integral, to the sum of entries, or scale it by some arbitrary factor. If normalization and a scale factor are given, the scale factor is applied after normalization. This is useful for stacking histograms when the ratios are known.

Christian Bierlich's avatar
Christian Bierlich committed
482
```
Christian Bierlich's avatar
Christian Bierlich committed
483 484
    Rebin=<nbins>
    ErrorType=<stat|env>
Christian Bierlich's avatar
Christian Bierlich committed
485
```
Christian Bierlich's avatar
Christian Bierlich committed
486

487
Rebin the histogram. Starting with the lowest bin `<nbins>` bins are combined into a new bin. If the number of bins in the histogram is not a multiple of `<nbins>`, the remaining bins at the upper histogram end are silently ignored (i.e. if the original histogram has 10 bins and `<nbins>` is 3, the plotted histogram shows three bins combining the bins 1—9 of the original histogram). The treatment of the errors is determined by the given ErrorType: `stat` (default) assumes the errors are of statistical nature and combines them in quadrature sum, while `env` allows to treat errors as envelope of various uncertainty runs which are combined linearly.
Christian Bierlich's avatar
Christian Bierlich committed
488 489 490 491 492

### FUNCTION

`make-plots` can draw arbitrary functions. These functions are defined as python code sniplets which are evaluated by `make-plots`. The code sniplet must come after all other options in a `FUNCTION` section and are preceded by `Code=` on a single line. An example `FUNCTION` section might look like this:

Christian Bierlich's avatar
Christian Bierlich committed
493
```
Christian Bierlich's avatar
Christian Bierlich committed
494 495 496 497 498 499 500 501 502 503 504 505 506
    # BEGIN FUNCTION f_cc
    LineColor=red
    Code=
    p0=16.4
    p1=1.25
    p2=0.9832
    from scipy.special import erf
    x-=0.5
    if x<=0:
        return 0
    else:
        return .5*p2*(1.+erf( (x-p0)/sqrt(x*p1) ))
    # END FUNCTION
Christian Bierlich's avatar
Christian Bierlich committed
507
```
Christian Bierlich's avatar
Christian Bierlich committed
508 509 510 511 512

#### Common Options with HISTOGRAM

The following options have the same meaning as in the `HISTOGRAM` section:

Christian Bierlich's avatar
Christian Bierlich committed
513
```
Christian Bierlich's avatar
Christian Bierlich committed
514 515 516 517 518 519 520 521
    Title=<title>
    LineStyle=<style>
    LineColor=<color>
    LineWidth=<width>
    LineDash=<dashstyle>
    FillStyle=<style>
    FillColor=<color>
    HatchColor=<color>
Christian Bierlich's avatar
Christian Bierlich committed
522
```
Christian Bierlich's avatar
Christian Bierlich committed
523 524 525 526 527

#### Function Range

You can limit the plot range of functions by specifying

Christian Bierlich's avatar
Christian Bierlich committed
528
```
Christian Bierlich's avatar
Christian Bierlich committed
529 530
    XMin=<value>
    XMax=<value>
Christian Bierlich's avatar
Christian Bierlich committed
531
```
Christian Bierlich's avatar
Christian Bierlich committed
532 533 534 535 536

### SPECIAL

The `SPECIAL` sections are used to include any custom pstricks code. This is useful for drawing arrows and lines, put text at any position into the plot, etc. The default coordinate system is defined to be `(0,0)` at the lower left and `(1,1)` at the upper right corner of the plot. By putting the `\physicscoor` command in front of a coordinate pair, these coordinates are interpreted not in the pstricks coordinate system, but in the physics coordinate system of the plot, which is useful e.g. for marking cut values in a plot. Similar `\physicsxcoor` and `\physicsycoor` commands exist which will only treat the x or y coordinate respectively as being in physics units.

Christian Bierlich's avatar
Christian Bierlich committed
537
*Hint:* If you want to clip your `SPECIAL` code to the plot area, you can use
Christian Bierlich's avatar
Christian Bierlich committed
538

Christian Bierlich's avatar
Christian Bierlich committed
539
```
Christian Bierlich's avatar
Christian Bierlich committed
540 541 542
    \psclip{\psframe[linewidth=0, linestyle=none](0,0)(1,1)}
       ...
    \endpsclip
Christian Bierlich's avatar
Christian Bierlich committed
543
```
Christian Bierlich's avatar
Christian Bierlich committed
544 545 546

An example of a `SPECIAL` section might look like this:

Christian Bierlich's avatar
Christian Bierlich committed
547
```
Christian Bierlich's avatar
Christian Bierlich committed
548 549 550 551 552 553 554 555
    # BEGIN SPECIAL
    \psclip{\psframe[linewidth=0, linestyle=none](0,0)(1,1)}
    \psline[linewidth=1.2pt,linecolor=red]{<-}\physicscoor(2.83,2)\physicscoor(2.83,18)
    \uput{4pt}[180]{0}\physicscoor(2.83,12){observed}
    \psline[linewidth=0.8pt,linecolor=red,linestyle=dashed]\physicscoor( 3.17,0)\physicscoor( 3.17,28.14)
    \psline[linewidth=0.8pt,linecolor=red,linestyle=dashed]\physicscoor(-3.59,0)\physicscoor(-3.59,28.14)
    \endpsclip
    # END SPECIAL
Christian Bierlich's avatar
Christian Bierlich committed
556
```