Analyses¶

HEPData provides some level of integration for eleven analysis frameworks: Rivet, MadAnalysis 5, SModelS, CheckMATE, HackAnalysis, GAMBIT, Combine, pyhf, HS3, SimpleAnalysis and NUISANCE. For Rivet, MadAnalysis 5, SModelS, CheckMATE, HackAnalysis, GAMBIT and Combine, the analysis code is hosted externally, while for pyhf, HS3 and NUISANCE, files are stored as additional resources in HEPData itself (attached to a whole submission, not to individual data tables). For SimpleAnalysis, some files are stored in HEPData itself, while links are also made to external analysis code.

In each case, links are made from relevant HEPData records under “View Analyses”. Badges are also added to search results and to the publication information of a record shown in the left panel.

Externally hosted analyses are exposed to HEPData via an analyses JSON file. For these, a bulk subscription feature means that analysis framework authors can receive automatic HEPData record update notifications if they desire. Contact info@hepdata.net to request bulk subscription, giving the email address of the HEPData account that you wish notifications to be sent to.

Analyses tools ¶

Rivet ¶

HEPData can export data in the YODA format for use in a Rivet analysis. The list of Rivet analyses (in JSON format) is parsed nightly. A search query analysis:rivet can be used to find HEPData records that have an associated Rivet analysis.

A link to a Rivet analysis can manually be added to a record at the upload stage via the additional_resources of the first document of the submission.yaml file if the Rivet analysis is already released, for example,

additional_resources:
- {location: 'http://rivet.hepforge.org/analyses/ATLAS_2016_I1424838', description: 'Rivet analysis'}

But this should not be necessary and it is not recommended, since the Rivet analysis will anyway be picked up by the nightly harvesting after the HEPData record has been made public.

If a HEPData record has an associated Rivet analysis, then the Rivet analysis name (for example, ATLAS_2016_I1424838) will appear in the YODA download. Otherwise, if the HEPData record has an attached INSPIRE ID, a guess is made for the Rivet analysis name using the collaboration name (“ATLAS”), the creation year of the INSPIRE record (“2016”), and the INSPIRE ID (“1424838”). If the HEPData record has neither an associated Rivet analysis or an INSPIRE ID, a placeholder RIVET_ANALYSIS_NAME will be written in the YODA download. It is possible to override the automatic Rivet analysis name by passing an extra URL argument for the YODA download. This can be done for either of the two download URL formats:

Copy the download link and append the Rivet analysis name (/ATLAS_2016_I1424838) at the end after /yoda, e.g. https://www.hepdata.net/download/submission/ins1424838/1/yoda/ATLAS_2016_I1424838
Add ?format=yoda&rivet=ATLAS_2016_I1424838 to the normal record URL, e.g. https://www.hepdata.net/record/ins1424838?format=yoda&rivet=ATLAS_2016_I1424838

Similarly, an explicit Rivet analysis name can be passed when downloading individual tables in the YODA format.

The Rivet identifier (e.g. d01-x01-y01) written in the path of the YODA file is generated from the table number (d01) and the index of the dependent variable within a table (y01), while x01 always takes the same value. The Rivet analysis should preferably be written using the same numbering scheme, but if this is not possible, a custom Rivet identifier can be specified as a qualifier for a particular dependent variable and subsequently used in the YODA conversion:

qualifiers:
- {name: 'Custom Rivet identifier', value: 'd01-x01-y01'}

MadAnalysis 5 ¶

Similarly to the Rivet case, a list of MadAnalysis 5 analyses (as JSON) is parsed nightly. A search query analysis:MadAnalysis can be used to find HEPData records that have an associated MadAnalysis 5 analysis.

SModelS ¶

Similarly to the Rivet and MadAnalysis 5 cases, a list of SModelS analyses (as JSON) is parsed nightly. A search query analysis:SModelS can be used to find HEPData records that have an associated SModelS analysis.

CheckMATE ¶

Similarly to the Rivet, MadAnalysis 5 and SModelS cases, a list of CheckMATE analyses (in JSON format) is parsed nightly. A search query analysis:CheckMATE can be used to find HEPData records that have an associated CheckMATE analysis.

HackAnalysis ¶

Similarly to the Rivet, MadAnalysis 5, SModelS and CheckMATE cases, a list of HackAnalysis analyses (in JSON format) is parsed nightly. A search query analysis:HackAnalysis can be used to find HEPData records that have an associated HackAnalysis analysis.

GAMBIT ¶

Similarly to the Rivet, MadAnalysis 5, SModelS, CheckMATE and HackAnalysis cases, a list of GAMBIT analyses (in the new JSON format) is parsed nightly. A search query analysis:GAMBIT can be used to find HEPData records that have an associated GAMBIT analysis.

Combine ¶

Similarly to the Rivet, MadAnalysis 5, SModelS, CheckMATE, HackAnalysis and GAMBIT cases, a list of CMS statistical models in the Combine format is parsed nightly via a simplified JSON file. A search query analysis:Combine can be used to find HEPData records that have associated statistical models in the Combine format.

pyhf ¶

HEPData provides similar highlighting of additional resource files corresponding to statistical models provided in the HistFactory JSON (pyhf) format. Multiple HistFactory JSON files should preferably be packaged in an archive file (.zip, .tar, .tar.gz, .tgz, .tar.xz) together with an explanatory README file. However, a single .json file can also be uploaded. Originally, HistFactory JSON files were identified by the description of the additional resource file containing one of a number of case-insensitive trigger words (histfactory, pyhf, likelihoods, workspaces). However, this method is ambiguous and is now phased out (as of 17th October 2025). To avoid relying on trigger words, a type: HistFactory field (case-insensitive) should be added to the additional_resources of the first document of the submission.yaml file, for example,

additional_resources:
- location: "Likelihoods.tar.gz"
  description: "Archive of full likelihoods in the HistFactory JSON format"
  type: "HistFactory"  # to allow HistFactory JSON (pyhf) files to be highlighted

If using the hepdata_lib package, pass file_type = "HistFactory" to the add_additional_resource function. Links are made from relevant HEPData records (after finalisation) with attached HistFactory JSON files under “View Analyses”. A search query analysis:HistFactory can be used to find HEPData records that have associated HistFactory JSON files. Note that HistFactory JSON files attached to individual data tables are not currently highlighted in this way, only resource files attached to the whole HEPData record.

HEPData makes no checks of the formatting of the HistFactory JSON files. In case of questions, please contact either experts within your experiment or the pyhf developers.

HS3 ¶

Similar highlighting is provided for additional resource files in the HEP Statistics Serialization Standard (HS3) format. A type: HS3 field (case-insensitive) should be added to the relevant resource file metadata in the additional_resources of a whole HEPData record. HS3 files will also be automatically identified by the presence of the trigger word HS3 in the description, but it is still recommended to add the explicit type: HS3 field. If using the hepdata_lib package, pass file_type = "HS3" to the add_additional_resource function. A search query analysis:HS3 can be used to find HEPData records that have associated HS3 files. Note that HS3 files attached to individual data tables are not currently highlighted in this way, only resource files attached to the whole HEPData record.

SimpleAnalysis ¶

Similar highlighting is provided for code snippets given as additional resource files in the Simplified ATLAS SUSY analysis framework (SimpleAnalysis) format. A type: SimpleAnalysis field (case-insensitive) should be added to the relevant resource file metadata in the additional_resources of a whole HEPData record. SimpleAnalysis files will also be automatically identified by the presence of the trigger word SimpleAnalysis in the description, but it is still recommended to add the explicit type: SimpleAnalysis field. If using the hepdata_lib package, pass file_type = "SimpleAnalysis" to the add_additional_resource function. A search query analysis:SimpleAnalysis can be used to find HEPData records that have associated SimpleAnalysis files. Note that SimpleAnalysis files attached to individual data tables are not currently highlighted in this way, only resource files attached to the whole HEPData record.

Links are also made to SimpleAnalysis files hosted in a CERN GitLab repository specified via a SimpleAnalysis JSON file.

NUISANCE ¶

NUISANCE is a framework for event generators in neutrino physics that plays a similar role to Rivet in collider physics. Analysis code provided as C++ snippets in the ProSelecta format can be attached to HEPData records as additional_resources with type: ProSelecta, for example,

additional_resources:
- location: analysis.cxx
  description: "Selection and projection function examples. Can be executed in the ProSelecta environment v1.0."
  type: ProSelecta

If using the hepdata_lib package, pass file_type = "ProSelecta" to the add_additional_resource function. Links are made from relevant HEPData records (after finalisation) with attached ProSelecta C++ files under “View Analyses”. A search query analysis:NUISANCE (no results yet) can be used to find HEPData records that have associated ProSelecta C++ snippets for use with NUISANCE. Note that ProSelecta files attached to individual data tables are not currently highlighted in this way, only resource files attached to the whole HEPData record.

Analyses JSON schema ¶

A JSON format was defined which is used by reinterpretation tools to communicate to HEPData which analyses are implemented in that tool and where to find the implementations such that this information is Findable on HEPData. The current standard is version 1.0.0, usage of the previous standard is deprecated at this point.

The goals of v1.0.0 are

Self-descriptiveness: the JSON format includes information about the tool and tool version it’s valid for as well as basic information of the analyses implemented in the tool. It also allows tools to include very rough human-readable information instead of just bare identifiers.
Standardisation: a common standard for everyone ensures easy exchange and Findability of information.
Future-proofness: the standard aims to foresee future needs such that it doesn’t require frequent updates.
Redundancy reduction: the JSON format allows to codify URLs such that the URL stem doesn’t have to be repeated. This makes it more compact, better human-readable and better maintainable.

A JSON file exposed by a tool to HEPData could look as follows

{
   "schema_version": "1.0.0",
   "tool": "SModelS",
   "version": "3.0.0",
   "date_created": "2018-11-13T20:20:39+00:00",
   "implementations_description": "SModelS analysis",
   "url_templates": {
      "main_url": "https://github.com/SModelS/smodels-database-release/tree/main/{name}"
   },
   "analyses": [
      {
         "inspire_id": 1795076,
         "implementations": [
            {
               "name": "ATLAS-EXOT-2018-48",
            }
         ]
      }
   ]
}

License information can be added if it differs from the default CC0 license mentioned in the HEPData Terms of Use. For more details on the standard, see the HEPData repository! Contact info@hepdata.net to request being added to the list of supported tools.