Installation

Normal HEPData users and data submitters should not need to install this package, since it is automatically invoked when uploading a single text file with extension .oldhepdata to the hepdata.net submission system, or when requesting one of the alternative output formats via the web interface.

To install this package locally, you first need to install YODA and ROOT (including PyROOT). Check that you can import yoda and import ROOT from Python. You might want to install into a dedicated virtual environment:

$ python3 -m venv hepdata-converter
$ source hepdata-converter/bin/activate
(hepdata-converter)$ pip install hepdata-converter

This will install the latest released version from PyPI.

Developers

Developers might want to instead install the project directly from GitHub in editable mode:

$ git clone https://github.com/HEPData/hepdata-converter
$ cd hepdata-converter
$ python3 -m venv venv
$ source venv/bin/activate
(venv)$ pip install -e '.[tests]'

Developers can then run the tests with the following command:

python -m unittest discover hepdata_converter/testsuite 'test_*'

The documentation can be built locally in the virtual environment using Sphinx:

(venv)$ pip install -e '.[docs]'
(venv)$ cd docs
(venv)$ make html

Then view the output by opening a web browser at _build/html/index.html. Developers should also check that they can successfully build other formats using make latexpdf and make epub. All three formats will be built by Read the Docs for the main branch on GitHub.

Docker

Alternatively, a Docker image is available (see the hepdata-converter-docker repository) containing the dependencies such as YODA and ROOT, but not the hepdata-converter package itself.

$ docker pull hepdata/hepdata-converter
$ docker run --rm -it hepdata/hepdata-converter /bin/bash

The hepdata-converter package can be installed inside the Docker container:

root@617be04cbab5:/# pip install hepdata-converter
root@617be04cbab5:/# hepdata-converter -h
root@617be04cbab5:/# python -c 'import hepdata_converter'

Note that the Docker container will be automatically removed when it exits (if running with the --rm option). The Python module or CLI can then be used as described in Usage. Input and output files can be moved between the local filesystem and the running Docker container using the docker cp command, for example,

$ docker cp sample.oldhepdata 617be04cbab5:/
root@617be04cbab5:/# hepdata-converter -i oldhepdata sample.oldhepdata SampleYAML
$ docker cp 617be04cbab5:/SampleYAML .

where the prompt $ indicates a terminal corresponding to the local filesystem and the prompt root@617be04cbab5:/# indicates another terminal corresponding to the running Docker container.

Alternatively, developers can install from GitHub and mount the current directory of the local filesystem when running the Docker container:

$ git clone https://github.com/HEPData/hepdata-converter
$ cd hepdata-converter
$ docker run -v $PWD:$PWD -w $PWD --rm -it hepdata/hepdata-converter /bin/bash
root@2c22e88402d2:/hepdata-converter# pip install -e '.[tests]'
root@2c22e88402d2:/hepdata-converter# hepdata-converter -h
root@2c22e88402d2:/hepdata-converter# python -c 'import hepdata_converter'
root@2c22e88402d2:/hepdata-converter# python -m unittest discover hepdata_converter/testsuite 'test_*'