mvtx/MvtxHotPixel/README.md

0001 # MVTX Calibration
0002
0003 ## Building the package
0004
0005 A package should be built before running the scripts, or remove any mention of these packages in the Fun4All macros so you can just process the data.
0006
0007 There is an included script called `setup-condor.sh` will create condor files to submit jobs in `$pwd/condor`. This is an example of how to run the script:
0008
0009 ```bash
0010 export $MYINSTALL=<your install directory path>
0011 source setup-condor.sh $MYINSTALL
0012 ```
0013 Help can be found by running `setup-condor.sh` with the `-h` flag.
0014 ```bash
0015 source setup-condor.sh -h
0016 ```
0017
0018 ## What is in the package?
0019
0020 These modules are located in the `calibration/mvtx` directory. The modules are:
0021
0022 1. `mvtxcalib`
0023         - Contains classes and subsystem modules for doing a Fake hit rate analysis on raw `.prdf` files.
0024
0025 #### Required `coresoftware` dependencies:
0026
0027 These modules are located in the `offline/packages/mvtx` directory. The modules are:
0028
0029 - `MvtxPixelDefs`
0030         - Contains definitions and methods for creating pixel keys for each pixel in the MVTX detector. The pixel key is a 64-bit integer that uniquely identifies each pixel in the detector.
0031 - `MvtxPixelMask`
0032         - Class which loads pixel masks from the conditions database and provides methods for masking pixels in hitmaps.
0033 - `MvtxHitMap`
0034         - Class which creates hitmaps from raw data files. Hitmap is a vector of pairs of pixel keys and the number of hits in that pixel.
0035
0036
0037 ### `mvtxcalib` module
0038
0039 This module contains classes and subsystem modules for doing a Fake hit rate analysis on raw `.prdf` files. The module contains classes for loading pixel masks from the conditions database, creating hitmaps from raw data, and calculating the fake hit rate.
0040
0041 - `MvtxFakeHitRate`
0042         - Main class for calculating the fake hit rate. Creates hitmaps from raw data files, masks pixels, and calculates the fake hit rate.
0043         - `SetOutputfile(std::string outputfile)`
0044                 - Sets the output file for the fake hit rate analysis. The output file will contain the fake hit rate and the optimized pixel mask.
0045         - `SetMaxMaskedPixels(int max_masked_pixels)`
0046                 - Sets the maximum number of pixels to mask in the optimization. The optimization will mask the `max_masked_pixels` pixels with the most hits in the hitmap.
0047
0048 - `MvtxHitMapWriter`
0049         - Writes the hitmap to a root file. The hitmap is a vector of pairs of pixel keys and the number of hits in that pixel. The hitmap is written to a root file with the name `mvtx_hit_map.root` by default. The root file contains a TTree with the hitmap data.
0050         - `SetOutputfile(std::string outputfile)`
0051                 - Sets the output file for the hitmap analysis. The output file will contain the hitmap data.
0052
0053 ## Running the Fake Hit Rate Analysis
0054
0055 The fake hit rate analysis is run using the `Fun4All_MvtxFHR.C` macro in the`<SPHENIXMACROS>/calibrations/mvtx` directory. This macro will run the fake hit rate analysis on raw MVTX data files and save the results to an output file. The macro takes the following arguments:
0056
0057 - `nEvents` : Number of events to process
0058 - `run_number` : Run number of the data
0059 - `trigger_rate_kHz` : Trigger rate in kHz
0060 - `output_name` : Output file name
0061 - `selected_layer` : Selected layer to analyze (optional, -1 for all layers)
0062 - `trigger_guard_output_name` : Output file name for trigger guard analysis (optional)
0063
0064 The macro can be run using the following command:
0065
0066 ```bash
0067 root -l -b -q 'Fun4All_MvtxFHR.C(10000, 42641, 44, "output.root", "-1", "trigger_guard_output.root")'
0068 ```
0069
0070 The macro will initialze a Fun4All server,  then load raw MVTX data files for the given run number using the `RawDataManager` class. The macro will then create a `MvtxFakeHitRate` object and set the output file name and the maximum number of pixels to mask. The macro will then run the fake hit rate analysis and save the results to the output file. The output file will contain the fake hit rate and the optimized pixel mask.
0071
0072 ## Generating Pixel Masks
0073
0074 To generate a json file with the pixel mask, you can use the `MakeJsonHotPixelMap.C` macro in the `<SPHENIXMACROS>/calibrations/mvtx` directory. This macro will read the output file from the fake hit rate analysis and generate a json file with the pixel mask. The macro takes the following arguments:
0075
0076 - `calibration_file` : Output file from the fake hit rate analysis
0077 - `target_threshold` : Target threshold for fake hit rate
0078
0079 The macro can be run using the following command:
0080
0081 ```bash
0082 root -l -b -q 'MakeJsonHotPixelMap.C("output.root", 10e-8)'
0083 ```
0084
0085 The macro will read the output file from the fake hit rate analysis and generate a json file with the pixel mask. The json file will contain the pixel mask and the fake hit rate for each pixel. The macro will also print the number of pixels masked and the fake hit rate threshold.
0086
0087
0088 ## Questions
0089
0090 This is a work in progress and likely has some bugs. If you have any questions or need help, please contact me at
0091 ` <tmengel@bnl.gov>`.
0092 ```
0093
0094
0095