```eval_rst .. _plotting-format: ``` Plotting format =============== A *plotting file* defines a set of options that are used for analysis and representation purposes, particularly to determine how datasets should be represented in plots and how they should be grouped together according to various criteria. The plotting files should be considered part of the implementation of the dataset, and should be read by various tools that want to sensibly represent the data. ## Naming convention Plotting files are located in the `commondata` folder (`nnpdfcpp/data/commondata`). For a dataset labeled ``, the corresponding file name is `PLOTTING_.yaml` or `PLOTTING_.yml` For example, given the dataset "HERA1CCEP", the corresponding plotting file name is: ```` PLOTTING_HERA1CCEP.yaml ```` Additionally, the configuration is loaded from a per-process-type file called: ``` PLOTTINGTYPE_.yaml ``` See [kinematic labels](#kinematic-labels) below for a list of defined types. When a key is present both in the dataset-specific and the per-process-type file, the dataset-specific one always takes precedence. ## Format The plotting file specifies the variable in which the data is to be plotted (in the *x* axis) as well as the variables in which the data will be split in different lines in the same figure or in different figures. The possible variables ('*kinematic labels*') are described below. The format also allows the control of several plotting properties, such as whether to use log scale, or the axes labels. ### Data label A key called `dataset_label` can be used to specify a nice plotting and display label for each dataset. LaTeX math is allowed between dollar signs. See the [example](#example) plotting file for usage. ### Kinematic labels The default kinematic variables are inferred from the *process type* declared in the commondata files (more specifically from a substring). Currently they are: ``` 'DIS': ('$x$', '$Q^2 (GeV^2)$', '$y$'), 'DYP': ('$y$', '$M^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'EWJ_JPT': ('$p_T (GeV)$', '$M^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'EWJ_JRAP': ('$\\eta/y$', '$M^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'EWJ_MLL': ('$M_{ll} (GeV)$', '$M_{ll}^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'EWJ_PT': ('$p_T (GeV)$', '$M^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'EWJ_PTRAP': ('$\\eta/y$', '$p_T^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'EWJ_RAP': ('$\\eta/y$', '$M^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'EWK_MLL': ('$M_{ll} (GeV)$', '$M_{ll}^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'EWK_PT': ('$p_T$ (GeV)', '$M^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'EWK_PTRAP': ('$\\eta/y$', '$p_T^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'EWK_RAP': ('$\\eta/y$', '$M^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'HIG_RAP': ('$y$', '$M_H^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'HQP_MQQ': ('$M^{QQ} (GeV)$', '$\\mu^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'HQP_PTQ': ('$p_T^Q (GeV)$', '$\\mu^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'HQP_PTQQ': ('$p_T^{QQ} (GeV)$', '$\\mu^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'HQP_YQ': ('$y^Q$', '$\\mu^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'HQP_YQQ': ('$y^{QQ} (GeV)$', '$\\mu^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'INC': ('$0$', '$\\mu^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'JET': ('$\\eta$', '$p_T^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'PHT': ('$\\eta_\\gamma$', '$E_{T,\\gamma}^2 (GeV^2)$', '$\\sqrt{s} (GeV)$'), 'SIA': ('$z$', '$Q^2 (GeV^2)$', '$y$') ``` This mapping is declared as `validphys.commondataparser.KINLABEL_LATEX` in the python code. The three kinematic variables are referred to as `k1`, `k2` and `k3` in the plotting files. For example, for DIS processes, `k1` refers to `x`, `k2` to `Q`, and `k3` to `y`. These kinematic values can be overridden by some transformation of them. For that purpose, it is possible to define a `kinematics_override` key. The value must be a class defined in: `validphys2/src/validphys/plotoptions/kintransforms.py` The class must have a `__call__` method that takes three parameters: `(k1, k2 k3)` as defined in the dataset implementation, and returns three new values `('k1', 'k2', k3')` which are the "transformed" kinematical variables, which will be used for plotting purposes every time the kinematic variables `k1`, `k2` and `k3` are referred to. Additionally, the class must implement a `new_labels` method, that takes the old labels and returns the new ones, and an `xq2map` function that takes the kinematic variables and returns a tuple of (x, Q²) with some approximate values. An example of such transform is: ````python class dis_sqrt_scale: def __call__(self, k1, k2, k3): ecm = sqrt(k2/(k1*k3)) return k1, sqrt(k2), ceil(ecm) def new_labels(self, *old_labels): return ('$x$', '$Q$ (GeV)', r'$\sqrt{s} (GeV)$') def xq2map(self, k1, k2, k3, **extra_labels): return k1, k2*k2 ```` Additional labels can be specified by declaring an **extra_labels** key in the plotting file, and specifying for each new label a value for each point in the dataset. For example: ```` extra_labels: idat2bin: [0, 0, 0, 0, 0, 0, 0, 0, 100, 100, 100, 100, 100, 200, 200, 200, 300, 300, 300, 400, 400, 400, 500, 500, 600, 600, 700, 700, 800, 800, 900, 1000, 1000, 1100] ```` defines one label where the values for each of the datapoints are given in the list. Note that the name of the extra_label (in this case `idat2bin` is completely arbitrary, and will be used for plotting purposes (LaTeX math syntax is allowed as well). However, adding labels manually for each point can be tedious. This should only be reserved for information that cannot be recovered from the kinematics as defined in the CommonData file. Instead, new labels can be generated programmatically: every function defined in `validphys2/src/validphys/plotoptions/labelers.py` is a valid label. These functions take as keyword arguments the (possibly transformed) kinematical variables, as well as any extra label declared in the plotting file. For example, one might declare: ```` def high_xq(k1, k2, k3, **kwargs): return k1 > 1e-2 and k2 > 1000 ```` Note that it is convenient to always declare the `**kwargs` parameter so that the code doesn't crash when the function is called with extra arguments. Similarly to the kinematics transforms, it is possible to decorate them with a `@label` describing a nicer latex label than the function name. For example: ```` @label(r"$I(x>10^{-2})\times I(Q > 1000 GeV)$") def high_xq(k1, k2, k3, **kwargs): return (k1 > 1e-2) & (k2 > 1000) ```` ### Plotting and grouping The variable in which the data is plotted is simply declared as ```` x: