HepData Submissions

Why, what and how

HepData is a repository for publication-related High Enery Physics data. It is used as “an open-access repository for scattering data from experimental particle physics”. It can be used also in the re-analysis of data. In addition, it can be used to prepare Rivet plugins, which are useful for the tuning of generators for better simulation. For these reasons, the incorporation of LHCb results within HepData is necessary. This page acts as a first primer on the preparation of HepData submissions using tools developed to help automate the work for you.

These tools can be found in The HepDataExtractor repository. The package can be installed using pip directly from GitLab:

pip install git+https://gitlab.cern.ch/lhcb-simulation/hepdataextractor.git

It is also available from LbConda:

lb-conda Simulation/parameter-tuning gethepdata

Preparation of Tables from LaTeX source

There are three major parts of the tool from HepDataExtractor: First is extract_tables which extracts from LaTeX source files the necessary tables to make the datafiles for HepData submission, then tex_to_yaml is responsible for conversion of these files into appropriate HepData data YAML files for submission. Finally, these are grouped together into one submission by prepare_submission which takes the outputted YAML files and writes the final submission. An added functionality would be to automatically zip the directory for HepData submission.

If you have the LaTeX source files of the tables you want to submit, it is enough to run the extract_tables command using each individual .tex file with a table as input. Otherwise, you can first run

gethepdata extract_tables --file /path/to/main.tex

This will extract the necessary tables from the file main.tex and make new independent .tex files with names taken from the label field of the table. The script is recursive, meaning any included .tex files in the main.tex file will also be considered. If you only want one table contained in one file, that single file can be passed.

Preparation of HepData YAML files from tables

Once you have the individual tables in a .tex format (either from above or individually formatted), it is enough to use the command tex_to_yaml to re-express the tables as YAML suitable for HepData submission.

This tool is able to interpret both tabulated results as well as correlation/covariance matrices. Find below some examples as taken from LHCb-PAPER-2020-018 and LHCb-PAPER-2018-050 and is used as integration tests within the HepDataExtractor repository.

Preparation of submission file

Once you have the necessary tables converted to YAML format, pass these to prepare_submission

gethepdata prepare_submission -f *.yaml

this script needs to be run in the same place as the YAML files. Additionally, there are some FIXMEs within the submission file, such as the name of the table (e.g. Table 4) as well as a link to the public LHCb result.

Checking of files for submission

HepData has its own validator, called hepdata-validator which can be used to ensure that the submission has the minimal correct format. This can be used then on the directory with the submission.yaml as well as YAML files from the previous steps.

hepdata-validate -d ./

If everything looks good, then go ahead and submit!