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!