Getting Started

Why VISPA Desktop Edition?

The VISPA Desktop Edition provides an easy way to design and run physics analyses. The philosophy is to offer a fast start for newcomers while maintaining all the flexibility that advanced users need for their analysis.

VISPA GUI and plugins

VISPA offers a common GUI for several plugins which are closely linked to VISPA. This guide mainly deals with the features provided by the Analysis Designer and Analysis Browser plugins. For a full list of available plugins, look at the feature list. VISPA also provides the ability to create own GUI plugins, see the API Reference for more details.

How to install

Download VISPA for your platform and follow the instructions. To be able to use plugins for designing physics analyses or browse data, be sure to also include PXL in your installation, which is the default for most platforms. We recommend to install VISPA using the pre-compiled tar balls. A detailed guide for the VISPA installation from source code with a UNIX system can be found here. Experts may have a look at the Quick Installation Guide.

For Windows see the recommended steps for proper installation using the binary packages here.

Browse examples

VISPA comes with a set of handy examples.

The Analysis Designer Plugin

The Analysis Designer is the main plugin for designing a physics analysis and is based on the PXL toolkit. It provides all the ingredients to design and execute a high-energy physics analysis and can be extended for other applications.

Analysis Flow

The analysis designer is based on a serial analysis flow. Starting from data input or data generation, a set of data is processed serially by a chain of modules which can implement logical operations.

Create an analysis

Once you start VISPA, the start dialogue is shown.

VISPA Desktop Edition Startup

From here, choose New physics analysis to start designing a physics analysis from scratch, or open an existing analysis on the left-hand side, e.g. from the delivered [examples], to start from an already existing analysis.

 

Data input or data generation

There are two options for data input: Either use a PXL data file via a File Input module, or create data using a PyGenerator module. Both modules will start the execution of the module chain by passing a basic data entity (a Serializable) to the next module. After a chain is executed, the module will continue with a new Serializable until either there is no more data present in the input file, or the stop condition of the generator module is fulfilled.

VISPA Desktop input module

In case more than one module is present, the execution of the analysis will stop when all input modules fail to deliver more data. As default, data will be delivered in turns. To force the execution of different input modules one after the other, the runIndex can be set to different integer values for each module. Then, modules will be executed from lowest to highest runIndex.

If you want to convert data from a dedicated experiment into the PXL I/O format, you may want to have a look at the following examples:

  • the EASYROOTPLOT modules are a collection of plotting modules (using ROOT) and a text file parser that reads text files in the Comma Separated Value (CSV) format.
  • the LHE Input Module allows VISPA to read the Les Houches Event File format and to convert it into the PXL I/O format.
  • the PAT2PXLIO filler allows to read data from the CMS Experiment software CMSSW.

 

Pass data to the next module

After the execution of each module, the data will be passed to the next module if a connection line is drawn. Modules can be connected in the GUI from a source of one module to a sink of another module. Sources are always located on the right-hand side of a module and sinks on the left-hand side such that the data flow is from the left to the right.

Modules can have more than one source, and the logic in the module code determines to which source the data is passed. If the data is passed to a source which is not connected to a sink, the execution of the analysis for this piece of data stops. The same is true if a module has no source.

 

Analyse data

In each module, arbitrary operations on the input data can be performed. This can mean gathering of information like counting the number of passed objects, adding of additional information, e.g. the calculation of variables using the input data and storing these in the data, dropping parts of the data, or modification of the passed data, e.g. by running dedicated algorithms.

To get started, insert a PyAnalyse module by choosing this on the left-hand side of the VISPA window and then by double-clicking in the main window. Point the mouse to the module and choose Create skeleton from the menu appearing on top of the module. This asks you to save a skeleton module on your file system. You can instead also select a script, e.g. from the delivered examples, by choosing Select script. Then, the module code itself can be changed to perform any operation. For more details on what you can do with PXL modules, see the PXL documentation.

VISPA Desktop Edition analysis

 

Logical operations

The analysis designer has a set of basic Python modules to allow to graphically represent logical operations. In principal, any logical operation is allowed and can be implemented with the set of basic logic modules and the general Python or C++ module with an arbitrary number of sinks and sources. The only limit is that it is not possible to divide a set of data. There is no principal veto of using a module twice in a chain; however, this should be used with great care to prevent infinite loops, and is generally not recommended.

 

Pass

The simplest logical operation is the absence of any operation, the Pass. This is represented by the PyAnalyse module. In modules of this type, the data is processed and passed to the next module, given a connection exists.

 

Decide

VISPA Desktop Edition decide

 

Switch

VISPA Desktop Edition switch

Create a new Module

PXL offers two possibilities to write modules, either in Python, or in C++.
For a list of example modules, see Examples. Skeletons for python modules can be created directly via the VISPA graphical user interface.

BatchSystemPlugin

The example for the batch system plugin can be found here: Batch System Plugin.

Further information