analysis/Collect/README.md

0001 # Collect
0002
0003 `Collect` is a Fun4All `SubsysReco` module for sPHENIX analyses. In a
0004 single pass over each event it writes out:
0005
0006 - a **track tree**, with per-track kinematics, quality flags, dE/dx
0007   (multiple estimators), and optional calorimeter-tower-energy-around-track
0008   grids, and
0009 - a **V0/decay tree**, built from `KFParticle` K-short / Lambda / anti-Lambda
0010   candidates, with full daughter-track linkage back to the track tree.
0011
0012 The tree written by Collect is intended to support both spectra and correlations
0013 analyses. Both whole-acceptance correlation functions, e.g. R2(dy,dphi), and
0014 femtoscopic correlation functions, e.g. C(Q), can be built for arbitrary pair
0015 species and charges from these trees. This is possible because the trees carry
0016 per-track tracking-hit bitmasks and cluster keys, which support sensitive
0017 identification and removal of split tracks — a single real particle mistakenly
0018 reconstructed as two separate tracks, which does real damage to C(Q) and R2
0019 near (dy,dphi)~(0,0).
0020
0021 Each tree row is one beam crossing that has a reconstructed vertex. Every track
0022 in that crossing that passes the track-quality floor (ntpc, nmvtx, nintt, pT) is
0023 written, whether or not the vertex finder attached it to the vertex; tracks that
0024 are daughters of a found V0 are always saved, even if they fail the floor.
0025 Collect applies NO DCA selection: each track carries its 3D DCA to the row's
0026 vertex (`dcaxy`, `dcaz`), and `primary==1` means only that the vertex finder
0027 attached it to that vertex. Choose any DCA cut downstream (e.g. Corral's
0028 AcceptTrack). Note the finder's attachment is loose, especially in z: in run
0029 81585, ~22% of attached tracks have |dca_z| > 1.5 cm.
0030
0031 V0s are reconstructed by KFParticle already quite cleanly, since KFP's own V0
0032 cuts are applied in the F4A macro itself. The mass windows intentionally leave
0033 enough room on either side of the peak to perform sideband subtraction and
0034 remove the backgrounds visible in the V0 invariant-mass plots.
0035
0036 A few extra things Collect does to keep the trees clean:
0037
0038 - **Duplicate-V0 cleanup**: if two reconstructed V0s in the same crossing
0039   share a daughter track, only the better-fit one (lower chi2/ndf) is kept.
0040 - **One-vertex-per-crossing**: when several reconstructed vertices land in
0041   the same beam crossing (real pileup, or a split-vertex artifact), Collect
0042   keeps only the "hottest" one — the vertex with the most attached tracks —
0043   so tracks and V0s are never double-counted across near-duplicate vertices.
0044   The row records `nvtxXing` (vertices found in that crossing) and `vtxntr2`
0045   (the runner-up vertex's attached-track count), so analyses that are
0046   confused by >1 collision per crossing (e.g. correlation functions) can skip
0047   rows with `nvtxXing>1`. (Not to be confused with `nvtx`, the vertex count of
0048   the whole trigger frame.)
0049 - **Split-track bookkeeping**: persisted per-track hit masks and cluster
0050   keys let downstream analysis recompute a STAR-style Splitting Level for
0051   any pair, sibling or mixed-event, to identify a split track — a single
0052   real particle mistakenly reconstructed twice — and remove the extra stub
0053   from the event.
0054
0055 ## How to Build
0056
0057 `Collect` is a standard sPHENIX autotools package (`configure.ac` /
0058 `Makefile.am`), meant to be built against an sPHENIX offline software
0059 environment.
0060
0061 ```sh
0062 # Inside an sPHENIX environment (OFFLINE_MAIN and MYINSTALL set, e.g. via
0063 # `source setup.sh <build>` from sPHENIX's cvmfs area or your own build):
0064
0065 git clone https://github.com/sPHENIX-Collaboration/analysis.git
0066 cd analysis/Collect
0067
0068 sh autogen.sh
0069 mkdir build && cd build
0070 ../configure --prefix="$MYINSTALL"
0071 make
0072 make install
0073 ```
0074
0075 This installs `libcollect.so` (and `Collect.h`) into `$MYINSTALL`. A
0076 `do_build.sh` convenience script wraps the same steps:
0077
0078 ```sh
0079 sh do_build.sh
0080 ```
0081
0082 ## How to Run
0083
0084 Load the library and register `Collect` as a `SubsysReco` in your Fun4All
0085 macro, after the tracking/KFParticle reconstruction chain and after
0086 calorimeter tower geometry has been loaded (`Collect::InitRun()` needs the
0087 tower geometry already on the node tree):
0088
0089 ```cpp
0090 #include <collect/Collect.h>
0091 R__LOAD_LIBRARY(libcollect.so)
0092
0093 ...
0094
0095 Collect *myCollect = new Collect("myCollect");
0096 myCollect->setVerbosity(0);
0097 myCollect->setSegment(segment);
0098 myCollect->setRequireXingZero(ReqXing0);
0099 myCollect->setAddTowersToTrackTree(collectAddTowersToTrackTree);
0100 myCollect->outfileName(collFile.c_str());
0101 se->registerSubsystem(myCollect);
0102 ```
0103
0104 - `setSegment()` records the input segment number in the output tree, for
0105   bookkeeping across batch jobs.
0106 - `setRequireXingZero()` restricts output to bunch-crossing-zero vertices.
0107 - `setAddTowersToTrackTree()` enables the calorimeter-tower-around-track
0108   energy grid on the track tree; when `false` (the default), extra dE/dx
0109   branches are booked instead and track-quality cuts are looser.