Quick Start

Obtaining FCCAnalyses

From the Key4hep stack

As mentioned on the main page, one can obtain already compiled, ready to use, FCCAnalyses by sourcing the Key4hep stack:

source /cvmfs/sw.hsf.org/key4hep/setup.sh

From GitHub

If any adjustments are needed, one can compile it locally, first fork the project on GitHub and after that run the following commands:

git clone git@github.com:<your_github_handle>/FCCAnalyses.git
cd FCCAnalyses
git remote add upstream git@github.com:HEP-FCC/FCCAnalyses.git
git fetch upstream
source setup.sh
fccanalysis build -j 8

The setup.sh script can take command line options and allows to select different Key4hep stacks. Use source setup.sh -h to get the full list of the available options:

USAGE: source setup.sh [-h, -l, -n, -p, -b]
       -h/--help           Show this help and exit
       -l/--latest         Setup the latest release of the Key4hep stack
       -n/--nightlies      Setup the latest nightlies version of the Key4hep stack
       -p/--pinned         Setup the pinned version of the Key4hep stack
       -b/--from-build     Setup the version of the Key4hep stack used for the latest local build

The setup script defaults to using the pinned stack. If the pinned stack is not set,
the latest stable release is used instead.

Creating analysis script

The analysis creation involves writing a valid Python script, which contains a mandatory class called Analysis with several required methods. There can be several stages of the analysis and for each stage a separate analysis script needs to be written.

The first required method of the Analysis class, the __init__() method, initializes the analysis and controls its behavior, there are several required attributes and many optional ones. For the evolving list see the manual page: fccanalysis-script(7).

Second required method creates and manipulates the dataframe itself. It is called analyzers() and it is required to return the last version of the dataframe.

The final required method, output() is required to return list of columns which will be saved to the output ROOT file.

Together the skeleton of an analysis script looks similar to this:

class Analysis():
    def __init__(self, cmdline_args):
        ...


    def analyzers(self, dframe):
        dframe2 = (
            dframe
            # define the muon collection
            .Define("muons",
                    "ReconstructedParticle::get(Muon0, ReconstructedParticles)")
            ...
        )
        return dframe2


    def output(self):
        return ["muons", "muon_mass"]

Running the analysis

Running the analysis script can be done using fccanalysis run command:

fccanalysis run analysis_script.py

To have read access to the FCC centrally produced physics datasets, one needs to be subscribed to the following e-group (with owner approval) fcc-eos-access. The information regarding the available datasets can be found here.

Demos

Sourcing of the Key4hep stack and running of the example analysis:

Downloading of the FCCAnalyses from GitHub and building it locally: