TFileService: a ROOT Object Storage Service

Purpose

TFileService is a CMSSW Framework Service that allows one to create ROOT objects in multiple modules and store those histograms in the same ROOT file.

Files are stored in different directories, each having the same name as the label of the module that called the service. In this way ROOT object name clashes are automatically avoided. The TFileService can be used in both the full framework with cmsRun and in FWLite. Details below/

Usage in the full framework

Configuring a job to use TFileService

The service is enabled and the output is set to a specified output path using the following directives in the configuration file:

  process.TFileService = cms.Service("TFileService", fileName = cms.string("histo.root") )
 

Since CMSSW_2_1_0 an additional untracked boolean parameter, closeFileFast can be specified, which is set to false per default. Setting this parameter to true will dramatically (!!) decrease the time to close the file if it contains many objects. This option is safe as long as the file doesn't contain multiple references to the same object, for example a histogram and a TCanvas containing that histogram. If that is not the case, configure the service as follows:

  process.TFileService = cms.Service("TFileService", 
      fileName = cms.string("histo.root"),
      closeFileFast = cms.untracked.bool(True)
  )

Accessing TFileService within a Module

To access the TFileService object in a framework module, The following call is needed:

  edm::Service<TFileService> fs;

The service header is included with:

#include "FWCore/ServiceRegistry/interface/Service.h"
#include "CommonTools/UtilAlgos/interface/TFileService.h"

The BuildFile.xml needs the following dependencies:

<use name="PhysicsTools/UtilAlgos"/>
<use name="FWCore/ServiceRegistry"/> # GF: Not sure whether really needed...

Creating Histograms

In the module's constructor, or beginJob method, histograms can be created using the function template make<...>:

  TH1F * h_pt = fs->make<TH1F>( "pt"  , "p_{t}", 100,  0., 100. );

Other ROOT objects can be constructed in a similar way by passing to make<...> the arguments to be passed at the object's constructor. Histograms will be created in the directory having the same name as the module that calls this instruction line.

Creating Subdirectories

If one wants to create subdirectories inside the main module's subdirectory, it is possible through the following interface:

  TFileDirectory subDir = fs->mkdir( "mySubDirectory" );
  TFileDirectory subSubDir = subDir.mkdir( "mySubSubDirectory" );

Within a subdirectory histograms are booked with the same syntax as for TFileService:

  TH1F * h_pt = subDir.make<TH1F>( "pt"  , "p_{t}", 100,  0., 100. );

Complete Example

class MyHistoAnalyzer : public edm::EDAnalyzer {
public:
  MyHistoAnalyzer( const edm::ParameterSet & );

private:
  void analyze( const edm::Event& , const edm::EventSetup& );

  edm::InputTag src_;
  TH1F * h_pt, * h_eta, * h_phi;
  double ptMax_;
};

MyHistoAnalyzer::MyHistoAnalyzer( const ParameterSet & cfg ) :
  src_( cfg.getUntrackedParameter<edm::InputTag>( "src" ) ),
  ptMax_( cfg.getUntrackedParameter<double>( "ptMax" ) ) {
  edm::Service<TFileService> fs;
  h_pt    = fs->make<TH1F>( "pt"  , "p_{t}", 100,  0., ptMax_ );
  h_eta   = fs->make<TH1F>( "eta" , "#eta" , 50, -3, 3 );
  h_phi   = fs->make<TH1F>( "phi" , "#phi" , 50, -M_PI, M_PI );
}

void MyHistoAnalyzer::analyze( const Event& evt, const EventSetup& ) {
  Handle<TrackCollection> tracks;
  evt.getByLabel( src_, tracks );
  for( TrackCollection::const_iterator t = tracks->begin(); t != tracks->end(); ++ t ) {
    double pt = t->pt(), eta = t->eta(), phi = t->phi();
    h_pt->Fill( pt );
    h_eta->Fill( eta );
    h_phi->Fill( phi );
  }
}

Usage in FWLite

In FWLite the TFileService gets initialized using the file name of the ROOT file. The further usage is identical to the full framework case.

#include "CMS.PhysicsTools/FWLite/interface/TFileService.h"

TFileService fs("output.root");
TH1F * h_pt = fs->make<TH1F>( "pt"  , "p_{t}", 100,  0., 100. );

Merging histogram output files

In the case you run multiple jobs to produce your histograms, you may need to merge the different output files by adding them.

This can be done with the utility:

• mergeTFileServiceHistograms

Optionally, a list of weights can be specified, if not all outputs should be added with the same weight.

The available options are specified below:

>mergeTFileServiceHistograms -h
mergeTFileServiceHistograms [options] data_file
Allowed options:
  -h [ --help ]                        produce help message
  -o [ --output-file ] arg (=out.root) output root file
  -w [ --weights ] arg                 list of weights (comma separates).
                                       default: weights are assumed to be 1
  -i [ --input-files ] arg             input root files

At the moment, histograms of the following types are supported:

• TH1F, TH1D, TH2F, TH2D

Review Status

Responsible: BenediktHegner
Last reviewed by: Reviewer