Madanalysis5 - A package for event file analysis and recasting of LHC results

Overview

Welcome to MadAnalysis 5

PAD TUTO FAQ

Python v3.8 C++

Outline

What is MadAnalysis 5?

MadAnalysis 5 is a framework for phenomenological investigations at particle colliders. Based on a C++ kernel, this program allows to efficiently perform, in a straightforward and user-friendly fashion, sophisticated physics analyses of event files such as those generated by a large class of Monte Carlo event generators.

The first running mode (Normal Mode) of the program, easier to handle, uses the strengths of a powerful Python interface in order to implement physics analyses by means of a set of intuitive commands.

The second running mode (Expert Mode) requires to implement the analyses in the C++ programming language, directly within the core of the analysis framework. This opens unlimited possibilities concerning the level of complexity that can be reached, the latter being only limited by the programming skills and the originality of the user.

More details can be found on the MadAnalysis 5 website.

Requirements

MadAnalysis 5 requires several external libraries in order to properly run:

  • Python 3.6 or a more recent version that can be downloaded from this website In order to check the installed version of Python on a system, it is sufficient to issue in a shell $ python --version.

  • Either the GNU GCC compiler, or the Apple clang compiler. MadAnalysis 5 has been validated:

    • with the versions 4.3.X and 4.4.X of the GCC compiler. The GCC compiler can be downloaded from this website.
    • with the version 12.0.5 (clang-1205.0.22.9) of the clang compiler.

To benefit from all options coming with the MadAnalysis 5 program, the following (optional) libraries have to be installed on the system:

  • Zlib headers and libraries that can be downloaded from this website which can also be downloaded by by typing ma5> install zlib through MadAnalysis interface.
  • The FastJet package version 3.3, or a more recent version, that can be downloaded from this link. This package can also be installed by typing ma5> install fastjet in MadAnalysis.
  • LaTeX and pdflatex compilers for report rendering.

Downloading and installing the MadAnalysis 5 package

We are moving from our previous location in Launchpad but the latest MadAnalysis 5 version can still be downloaded through here until the release of v1.10. Note that future versions will only be available through GitHub.

If you satisfy the requirements mentioned above the only thing that you need to do is download the latest release from here and start playing;

$ cd madanalysis5
$ ./bin/ma5

During your first execution MadAnalysis 5 will build the entire workspace automatically. Note that release versions are always the stable ones the main repository will be under constant development.

Usage of MadAnalysis 5

Syntax: ./bin/ma5 [options] [scripts]

[options]
This optional argument allows to select the running mode of MadAnalysis 5 appropriate 
to the type of event files to analyze. If absent, the parton-level mode is selected. 
Warning: the different modes are self-excluding each other and only one choice has to be made.

List of available options :
 -P or --partonlevel  : parton-level mode
 -H or --hadronlevel  : hadron-level mode
 -R or --recolevel    : detector-level mode
 -e or -E or --expert : entering expert mode
 -v or --version
    or --release      : display the version number of MadAnalysis
 -b or --build        : rebuild the SampleAnalyzer static library
 -f or --forced       : do not ask for confirmation when MA5 removes a directory or overwrites an object
 -s or --script       : quit automatically MA5 when the script is loaded
 -h or --help         : dump this help
 -i or --installcard  : produce the default installation card in installation_card.dat
 -d or --debug        : debug mode
 -q or --qmode        : developper mode only for MA5 developpers

[scripts]
This optional argument is a list of filenames containing a set of MadAnalysis 5 commands. 
The file name are handled as concatenated, and the commands are applied sequentially.

Description of the package

The directory structure of the MadAnalysis 5 package can be summarized as follows:

   +  bin                | This directory contains the executable file 'ma5'.
   +  madanalysis        | This directory contains all the source files of
                         |   MadAnalysis 5.
      +   configuration  | This directory contains functions related to the
                         |   configuration of the dependencie such as FastJet.
      +   core           | This directory contains the core of the Python
                         |   interface.
      +   dataset        | This directory contains the functions related to the
                         |   handling of Monte Carlo event files in MadAnalysis
                         |   5.
      +   enumeration    | This directory contains the definition of the
                         |   keywords used by within the Python source files. 
      +   input          | This directory contains the lists of (multi)particles
                         |   to be loaded at the start-up of MadAnalysis 5.
      +   IOinterface    | This directory contains routines related to
                         |   input/output flows.
      +   interpreter    | This directory contains all the commands available
                         |   within the Python interface of MadAnalysis 5.
      +   job            | This directory contains the routines necessary for
                         |   the creation and execution of C++ jobs.
      +   layout         | This directory contains all the functions necessary
                         |   for handling the layout of the figures and reports
                         |   produced by MadAnalysis 5. 
      +   multiparticle  | This directory contains the functions related to the
                         |   handling of multiparticle and particle collections.
      +   observable     | This directory contains the list of observables
                         |   supported within MadAnalysis 5.
      +   selection      | This directory contains the routines necessary for
                         |   producing histograms and applying event selection
                         |   cuts.
   +  tools              | This directory contains the packages that are used
                         |   by MadAnalysis 5.
      +   SampleAnalyzer | This directory contains the C++ kernel of
                         |   MadAnalysis, dubbed SampleAnalyzer (see below).
      +   Glue           | This directory contains the glues allowing to use
                         |   showering programs (not supported yet).
  (+) samples            | This optional directory is dedicated to event sample
                         |   storage. 

The main file of the package is also the only one which is supposed to be run on a system:

$ ./bin/ma5

In addition, several text files are dedicated to specific information:

  • README: this file,
  • COPYING: the description of the software license,
  • version.txt: general information about the installed release,
  • madanalysis/UpdateNotes.txt: the update notes.

The C++ kernel of MadAnalysis is stored in the directory tools/SampleAnalyzer This directory has the following structure:

   + tools
     + SampleAnalyzer
       + Analyzer         | This directory contains the skeleton for the
                          |   analysis class as well as for the merging plots.
       + Core             | This directory contains the main routines.
       + Counter          | This directory contains routines related to
                          |   histogram and cut referencing.
       + DataFormat       | This directory contains the implementation of the
                          |   employed data format for handling event samples
                          |   and the related information.
       + Filter           | This directory contains routines for applying event
                          |   filtering (to be developped in the future).
       + JetClustering    | This directory contains routines dedicated to jet
                          |   clustering algorithms.
       + Lib              | This directory store the SampleAnalyzer library,
                          |   once compiled.
       + Plot             | This directory contains all the methods related to
                          |   histogram generation.
       + Reader           | This directory contains the definition of classes
                          |   dedicated to the reading of the event files. 
       + Service          | This directory contains services (logger, physics
                          |   tools, ...)
       + Writer           | This directory contains the definition of classes
                          |   dedicated to the writing of event files and
                          | result files.
     + newAnalyzer.py     | This script allows to create a blank analysis.
     + newFilter.py       | This script allows to create a blank filter.

The Glue directory contains routines dedicated to future developments and are thus neither supporter, nor documented.

The associated Doxygen documentation can be found on the MadAnalysis 5 wiki.

Very first steps with MadAnalysis 5

To start MadAnalysis 5, it is enough to type in a shell ./bin/ma5

In a first step, the program checks all the dependencies and provide warning and/or error messages if necessary. Next, the SampleAnalyzer C++ kernel library is generated. This is performed once and for all at the first run of MadAnalysis

  • Let us however note that if the system configuration changes, this is detected by MadAnalysis 5 and the library is regenerated.

If everything is going as smoothly as it should, a Python command line interface with a ma5> prompt appears. To learn how to use MadAnalysis 5 and to get an overview of its functionalities, we refer in particular to Section 3 of the manual that can be found here.

Troubleshootings and bug reports

Any public release of MadAnalysis 5 has been automatically and intensely validated. However, especially due to the variety of possible system configurations and the large number of functionalities included in the program, it is not impossible that some bugs are found. In this case, is is strongly suggested to create a report on GitHub Issues.

In this way, you also participate to the improvement of MadAnalysis 5 and the authors thank you for this.

Authors

MadAnalysis 5 is openly developed by the core dev team consisting of:

Our famous last words

The development team of MadAnalysis 5 hopes that the package will meet the expectations of the users and help particle physicists in their phenomenological investigations.

That's all folks!

Credits

If you use MadAnalysis 5, please cite:

Issues
  • Simplified likelihood calculation raises `RuntimeWarning` and sets 1-CLs value to `NaN`

    Simplified likelihood calculation raises `RuntimeWarning` and sets 1-CLs value to `NaN`

    System Settings

    • OS independent
    • Python 3.8.9
    • GCC: NA
    • ma5 v1.9.60

    Describe the bug

    Simplified likelihood calculation raises a RuntimeWarning while calculating CLs value and sets 1-CLs to NaN.

    To Reproduce

    Recalculate global CLs with the attached file for cms_exo_20_004.

    mass2000002_1250.0_mass57_5.0_xs_0.0006211.tar.gz

    Expected behaviour

    The 1-CLs value should be set to zero or one for such cases.

    Log files

    ~/madanalysis5/madanalysis/misc/simplified_likelihood.py:926: RuntimeWarning: invalid value encountered in double_scalars
      CLs = CLsb/CLb
    

    Code does not crash.

    Additional information

    No response

    bug PAD 
    opened by jackaraz 0
  • minor fix to avoid NaN in CLs_output following issue #3

    minor fix to avoid NaN in CLs_output following issue #3

    Context: Minor fix in the simplified likelihoods workflow.

    Description of the Change: prevent zero division.

    Benefits: In the case of zero division sets CLs to 1. This prevents NaN in the CLs_output.dat

    Related GitHub Issues: see issue #3

    bug PAD 
    opened by jackaraz 0
  • Full likelihoods

    Full likelihoods

    Description of the Change: add the ability to include CRs and VRs in the full likelihoods.

    Benefits:

    • In general, ATLAS analyses are designed such that the signal contamination of CRs is max 10%. So recasting only the SRs but not the CRs/VRs is a good approximation in most cases (as long as the signal hypothesis is not very different from the one the analysis has been designed for).
    • Some analyses do a combined fit to signal and control regions; others don't. If they do, removing the CRs altogether is wrong. If they don't, it makes no difference whether or not the CRs are kept.

    New options: Option introduced in the .info file of the analysis e.g.

      <pyhf id="RegionC">
        <name>atlas_susy_2018_31_SRC.json</name>
        <regions>
          <channel name="CRtt_cuts"> </channel>
          <channel name="SR_metsigST">
          SRC_22
          SRC_24
          SRC_26
          SRC_28
          </channel>
          <channel name="VRzAlt_cuts" is_included="True"> </channel>
          <channel name="CRz_cuts" is_included="True"> </channel>
          <channel name="VRtt_cuts"> </channel>
          <channel name="VRz_cuts"> </channel>
        </regions>
      </pyhf>
    

    If there is no data present in the channel code will look for the is_included tag, which can be "True", "yes", "1". If true, the channel will be included in the likelihood calculation; if not, it will be removed. If is_included is not present, and the channel does not have any data, it will be removed by default.

    enhancement PAD 
    opened by jackaraz 0
  • Interest in Docker image and associated CI?

    Interest in Docker image and associated CI?

    Feature details

    :wave: Hi and welcome to GitHub MadAnalysis 5 team! :rocket:

    I was wondering if you had any interest in having a Dockerfile for your project that would build a minimal "base" Docker image for others to build upon. This type of Docker image is useful to have in CI as well for both testing the build and then running tests against the build (c.f. https://github.com/scailfin/MadGraph5_aMC-NLO for an example of what I mean).

    If so, I have one I wrote quickly on my fork and an associated CI workflow that builds and runs a very simple example as a test. If this is of any interest I'm happy to contribute a PR where we can refine this to your liking.

    Implementation

    Yes. I already have this done on my fork https://github.com/matthewfeickert/madanalysis5. If you want to see what it would look like roughly before code review for a PR I'd open just pull down the Docker image I made in CI and have on my fork's GitHub Container Registry

    docker pull ghcr.io/matthewfeickert/madanalysis5:v1.9.60
    

    and if you want to see it run the differential cross-section plot example from http://madanalysis.irmp.ucl.ac.be/wiki/FAQNormalMode as a sanity check

    docker run --rm ghcr.io/matthewfeickert/madanalysis5:v1.9.60 'ma5 --version && cat $(find /root/ -iname "differential_xsec_plot.ma5") | ma5'
    

    and then check inside of the differential_xsec_example it spits out.

    How important would you say this feature is?

    1: Not important. Would be nice to have.

    Additional information

    No response

    enhancement 
    opened by matthewfeickert 2
Releases(v1.9.60)
  • v1.9.60(Jan 12, 2022)

    • Adding support for LLP also in the SFS.
    • Particle propagation module.
    • PYHF/simplified likelihood interface.
    • TACO methods are available.
    • Python3 support.
    • Connection of the PAD to the MA5 dataverse + reorganisation of how it works.
    • Many minor bug fixes.
    • Update to newer Delphes/Root versions
    Source code(tar.gz)
    Source code(zip)
Owner
MadAnalysis
A package for event file analysis and recasting of LHC results
MadAnalysis
Code to reproduce the results in the paper "Tensor Component Analysis for Interpreting the Latent Space of GANs".

Tensor Component Analysis for Interpreting the Latent Space of GANs [ paper | project page ] Code to reproduce the results in the paper "Tensor Compon

James Oldfield 3 Nov 25, 2021
Code and model benchmarks for "SEVIR : A Storm Event Imagery Dataset for Deep Learning Applications in Radar and Satellite Meteorology"

NeurIPS 2020 SEVIR Code for paper: SEVIR : A Storm Event Imagery Dataset for Deep Learning Applications in Radar and Satellite Meteorology Requirement

USAF - MIT Artificial Intelligence Accelerator 33 Dec 30, 2021
Code for the ECCV2020 paper "A Differentiable Recurrent Surface for Asynchronous Event-Based Data"

A Differentiable Recurrent Surface for Asynchronous Event-Based Data Code for the ECCV2020 paper "A Differentiable Recurrent Surface for Asynchronous

Marco Cannici 17 Oct 12, 2021
Scalable, event-driven, deep-learning-friendly backtesting library

...Minimizing the mean square error on future experience. - Richard S. Sutton BTGym Scalable event-driven RL-friendly backtesting library. Build on

Andrew 870 Jan 17, 2022
Python Implementation of the CoronaWarnApp (CWA) Event Registration

Python implementation of the Corona-Warn-App (CWA) Event Registration This is an implementation of the Protocol used to generate event and location QR

MaZderMind 17 Oct 28, 2021
Code for the paper "Unsupervised Contrastive Learning of Sound Event Representations", ICASSP 2021.

Unsupervised Contrastive Learning of Sound Event Representations This repository contains the code for the following paper. If you use this code or pa

Eduardo Fonseca 77 Jan 4, 2022
Repo for "Event-Stream Representation for Human Gaits Identification Using Deep Neural Networks"

Summary This is the code for the paper Event-Stream Representation for Human Gaits Identification Using Deep Neural Networks by Yanxiang Wang, Xian Zh

zhangxian 45 Dec 14, 2021
Cross-media Structured Common Space for Multimedia Event Extraction (ACL2020)

Cross-media Structured Common Space for Multimedia Event Extraction Table of Contents Overview Requirements Data Quickstart Citation Overview The code

Manling Li 32 Nov 22, 2021
CVPRW 2021: How to calibrate your event camera

E2Calib: How to Calibrate Your Event Camera This repository contains code that implements video reconstruction from event data for calibration as desc

Robotics and Perception Group 77 Jan 6, 2022
Repository relating to the CVPR21 paper TimeLens: Event-based Video Frame Interpolation

TimeLens: Event-based Video Frame Interpolation This repository is about the High Speed Event and RGB (HS-ERGB) dataset, used in the 2021 CVPR paper T

Robotics and Perception Group 456 Jan 6, 2022
An implementation for `Text2Event: Controllable Sequence-to-Structure Generation for End-to-end Event Extraction`

Text2Event An implementation for Text2Event: Controllable Sequence-to-Structure Generation for End-to-end Event Extraction Please contact Yaojie Lu (@

Roger 70 Jan 4, 2022
Official PyTorch implementation of N-ImageNet: Towards Robust, Fine-Grained Object Recognition with Event Cameras (ICCV 2021)

N-ImageNet: Towards Robust, Fine-Grained Object Recognition with Event Cameras Official PyTorch implementation of N-ImageNet: Towards Robust, Fine-Gra

null 9 Jan 7, 2022
SurvITE: Learning Heterogeneous Treatment Effects from Time-to-Event Data

SurvITE: Learning Heterogeneous Treatment Effects from Time-to-Event Data SurvITE: Learning Heterogeneous Treatment Effects from Time-to-Event Data Au

null 8 Jan 11, 2022
Weakly Supervised Dense Event Captioning in Videos, i.e. generating multiple sentence descriptions for a video in a weakly-supervised manner.

WSDEC This is the official repo for our NeurIPS paper Weakly Supervised Dense Event Captioning in Videos. Description Repo directories ./: global conf

Melon(Xuguang Duan) 91 Oct 27, 2021
A toolkit for document-level event extraction, containing some SOTA model implementations

❤️ A Toolkit for Document-level Event Extraction with & without Triggers Hi, there ?? . Thanks for your stay in this repo. This project aims at buildi

Tong Zhu(朱桐) 51 Jan 14, 2022
How to Learn a Domain Adaptive Event Simulator? ACM MM, 2021

LETGAN How to Learn a Domain Adaptive Event Simulator? ACM MM 2021 Running Environment: pytorch=1.4, 1 NVIDIA-1080TI. More details can be found in pap

CVTEAM 1 Dec 27, 2021
Space-event-trace - Tracing service for spaceteam events

space-event-trace Tracing service for TU Wien Spaceteam events. This service is

TU Wien Space Team 2 Jan 4, 2022
A scientific and useful toolbox, which contains practical and effective long-tail related tricks with extensive experimental results

Bag of tricks for long-tailed visual recognition with deep convolutional neural networks This repository is the official PyTorch implementation of AAA

Yong-Shun Zhang 105 Jan 10, 2022