CPSClusterChunk -- contains information on single layer and 3D clusters found in the central preshower detector The output of CPSReco for a given event is stored in a container class called CPSClusterChunk. The two main data items are the SLCVec, defined in a typedef as "std::vector," and the GlobalClusterList, defined in a typedef as "std::list." The clusters that have been reconstructed for this event are stored in these containers. The CPSCluster objects have information on the full single layer clusters (see below) and the CPS3DCluster objects have information on the global (3D) clusters (see below). Single layer clusters consist of contiguous strips that are above an energy threshold. 3D clusters contain information from all three layers of the detector and have phi and z coordinates assigned to them. The information below is excerpted from the CPSReco documentation, D0 note 4014. The complete document can be found on the web at http://kuhep4.phsx.ukans.edu/~baringer/cps/CPSReco.htm CPSCluster, the class that holds the single layer cluster data The class CPSCluster holds the data on the single layer clusters. A vector of these CPSCluster objects is preserved in the CPSClusterChunk. The data that are stored for a CPSCluster are the integer cluster ID, the ClusterMap (std::map) that gives the energies and CPSCellID's of the strips that form the cluster, the total cluster energy, the energy-weighted centroid (in units of strip number), and the rms error on the centroid (also in units of strip number). The accessor methods for the data are: -- int ClusID() gives the cluster ID number -- float energy() gives the total cluster energy in GeV -- float Centroid() gives the cluster centroid in units of strip number -- float RMSerror() gives the rms error on the centroid position in units of strip number (another method, float RMSwidth(), is synonymous with float RMSerror()) -- ClusterMap StripMap() returns the map of strip energies indexed by their CPSCellID -- int layer() gives the layer number of the cluster (1=axial, 2=u stereo, 3=v stereo) In addition to the accessor methods, CPSCluster has some other useful methods. The == and != methods test whether two CPSCluster objects are the same. Two CPSCluster objects are considered to be the same if their ClusterMaps are identical. The method "int saturated()" gives the number of strips in the cluster having energies that saturated the CPS readout electronics. (Such strips are flagged in the ClusterMap by having negative energies.) The method "void cenrmsE2(float& cent, float& var)" returns centroid and error weighted by the square of the strip energy, and "float WidthE2()" returns an alternative calculation of the strip width for the linearly weighted centroid. (WidthE2() was the width calculation prior to February 2000 when a mistake was found in the code for the rms calculation.) The class for the thumbnail object, CPSTmbObj, is a friend class of CPSCluster. CPSCluster has a constructor that unpacks from CPSTmbObj for a selected layer number. (CPSTmbObj is formed from a 3D cluster and has information on the SLC's that make up the 3D cluster.) The code for the CPSCluster class can be found in the cvs module cps_evt. CPSHitPosition, the class that stores the cluster position The geometry methods store information on the D0 coordinates and errors on the coordinates in a simple container class called CPSHitPosition. The following access methods are provided for the ten private data elements: -- float r(), float phi(), float z() give, respectively, the r, phi , and z D0 coordinates of the object. Values of r and z are given in cm and phi is given in radians. -- float error(int i1, int i2) gives elements of the symmetric position error matrix from the CPSHitPosition object. The nine elements are accessed through the integers i1 and i2. 1=r, 2=phi, 3=z, so error(1,1) yields sigma**2_rr, error(1,3)=error(3,1) and yields sigma**2_rz, etc. In the current implementation of the CPS geometry classes, only the diagonal elements are non-zero. The sigma**2_rr value is assigned a fixed value of 0.16 cm**2, which takes the uncertainty in radius as the thickness of a CPS layer. -- float matchquality() gives the matchquality variable calculated by the geometry method uvxmatch. This quantity is the absolute value of the difference between the axial layer and u-v phi positions divided by the uncertainty in that difference. Two other methods, "float phi(const float x, const float y, const float z)" and "float eta(const float x, const float y, const float z)," give the phi and eta coordinates of the cluster relative to an input primary vertex position. The input x, y, and z coordinates of the primary vertex should be specified in centimeters. The CPSHitPosition code can be found in the cvs module cps_util. CPS3DCluster, the class that holds the 3D cluster data The class CPS3DCluster holds the data on the 3D (global) clusters. A list of these CPS3DCluster objects is preserved in the CPSClusterChunk. Each CPS3DCluster has in its data a CPSHitPosition object. As described above, the CPSHitPosition class holds information on the position of the cluster in D0 coordinates and the uncertainty on that position. Other information stored in the CPS3DCluster class includes the cluster ID, cluster energy, and information from the subclusters used to construct the 3D cluster. The accessor methods for the data are: -- int ClusID() gives the cluster ID number. -- float ClusEnergy() gives the total 3D cluster energy in GeV. -- float xSLCEnergy(), float uSLCEnergy(), float vSLCEnergy() gives the energy in GeV of the subcluster in the x, u, and v layers, respectively. ClusEnergy reports the sum of these three layer energies. -- float delEnergy() gives the uncertainty in the total cluster energy in GeV. This is taken to be the square root of the ClusEnergy divided by 1000 times the parameter npeMeV. This parameter is set in CPSReco.rcp and represents the number of photoelectrons yielded by a one MeV energy deposit. The current default value for npeMeV is 17.0. -- CPSHitPosition HitPosition() gives the whole CPSHitPosition object associated with the 3D cluster. -- float r(), float phi(), float z() give the r, phi, and z coordinates, respectively, from the CPSHitPosition object. In other words, these are the D0 coordinates of the 3D cluster. Values of r and z are given in cm and phi is given in radians. -- float error(int i1, int i2) gives elements of the position error matrix from the CPSHitPosition object. The nine elements are accessed through the integers i1 and i2 in the same manner as for the CPSHitPosition object (1=r, 2=phi , 3=z). -- float rphiwidth() gives the uncertainty in phi times the mean radius of the detector (in cm). This can also be calculated from r() times the square root of error(2, 2). -- float zwidth() gives the uncertainty in the z coordinate (in cm). This can also be obtained from the square root of error(3, 3). -- float matchquality() gives the matchquality variable from the CPSHitPosition object. -- CellList StripList() returns a list of CPSCellID's that identify the strips used in the three subclusters that formed the 3D cluster. (CellList is defined in a public typedef as std::list.) -- int xCluster(), int uCluster(), int vCluster() give the ClusID's for the x, u, and v layers, respectively, from the CPSCluster objects of the full SLC's associated with the 3D cluster. In the case of a merged cluster, the ClusID's of the two SLC's involved is a packed into an integer that equals -(1000*id1 + id2). In addition to the accessor methods, CPS3DCluster has some other useful methods. The == and != methods test whether two CPS3DCluster objects are the same. Two CPS3DCluster objects are considered to be the same if ClusterTags for each of the three layers are identical. The methods "float phi(const float x, const float y, const float z)" and "float eta(const float x, const float y, const float z)" give the phi and eta coordinates of the cluster relative to an input primary vertex position (using the corresponding CPSHitPosition methods) . A pseudo-chisquare that measures the degree of energy matching between the layers is returned by the method "float Ematchqual() const". This quantity and the matchquality position-matching variable are used in the deghosting process. The formula for Ematchqual can be found in D0 Note 4014. For CPS3Dclusters that are stored in the CPSClusterChunk, you can get the pointers to the CPSCluster objects in the chunk for the constituent SLC's in a given layer (the full SLC's, that is, not the subclusters) from the methods "const CPSCluster* ptr_xSLC/ ptr_uSLC/ ptr_vSLC(vec_SLC_ptrs* pexcess) const." For merged clusters there is more than one pointer for a given layer, and the full set of pointers is returned through the vector in the argument. The 0th element in the vector is returned as the CPSCluster* object. The method "const std::vector ptr_SLC (int clusterID) const" gives the pointer to the SLC's that are identified by the ID given as input in the argument. (The method ptr_xSLC uses this method with the xClusterTag as the argument, and similarly for ptr_uSLC and ptr_vSLC.) The method "float rootSLCEnergy(int slcID)" returns the energy of the full SLC for the constituent SLC with the ID given as input. (For merged clusters you get the sum of the energies of the full SLC's.) To get the full SLC energies for the three individual layers without use of the ID, use the methods float xSLCEnergyFull(), uSLCEnergyFull(), and vSLCEnergyFull().(The method xSLCEnergyFull uses the rootSLCEnergy method with the xClusterTag as the argument, and similarly for uSLCEnergyFull() and vSLCEnergyFull().) The sum of the three full SLC energies is returned by the method float ClusEnergyFull(). The class for the thumbnail object, CPSTmbObj, is a friend class of CPS3DCluster. CPS3DCluster has a method, CPSTmbObj getThumbnail() const, that makes a thumbnail object for the 3D cluster and its constituent SLC's. There is also a method, "void unpThumbNail(const CPSTmbObj* tmbptr)," that unpacks the CPS3DCluster data from the CPSTmbObj. A set of standard LinkIndex methods ("edm::LinkIndex index() const;" "void setLinkIndex(edm::ChunkID cid, int indx) const;" "void completeLinks(const edm::AbsChunk* c) const") is also provided in the class. The code for the CPS3DCluster class can be found in the cvs module cps_evt. Methods of the CPSClusterChunk class The CPSClusterChunk class is set up as an event data model (edm) chunk that is made persistent in the event record using D0OM. (CPSClusterChunk inherits from edm::AbsChunk.) The CPSClusterChunk class has methods that give it an interface like an STL container. (Thanks to Jim Kowalkowski for the useful design ideas!) Methods are provided that allow one to iterate through the data in the chunk, much as one would iterate through an STL container. To access the CPS3DClusters in the GlobalClusterList, one can get the starting iterator from either the method "GlobalClusterList::iterator begin()" or method "GlobalClusterList::const_iterator begin() const". For reverse iteration, these methods are available: "GlobalClusterList::reverse_iterator rbegin()" and "GlobalClusterList::const_reverse_iterator rbegin() const". One can get the end iterator from the method "GlobalClusterList::iterator end()" or method "GlobalClusterList::const_iterator end() const". The method "bool empty()" will tell you whether the GlobalClusterList is empty and the method "int size()" will report the size of the GlobalClusterList. If you know the integer index of the CPS3DCluster you want, you can retrieve it from the GlobalClusterList using either the vector-like access method "const CPS3DCluster&; operator[](int index) const" or either of the synonymous methods "const CPS3DCluster& at(int index) const" and "const CPS3DCluster& getGlobalCluster(int index) const". The equivalent STL-like access methods for the CPSCluster objects in the SLCVec are: "SLCVec:: iterator beginCluster()" or "SLCVec:: const_iterator beginCluster() const" (for begin()), "SLCVec:: iterator endCluster()" or "SLCVec:: const_iterator endCluster() const" (for end()), "bool emptySLC()" (for empty()), "int sizeSLC()" (for size()), and "const CPSCluster& getSLC(int index) const" (for getting an SLC by its index). Another useful CPSClusterChunk method is "eCone", written by Yimei Huang. This calculates the energy deposited in the central preshower detector within a specified cone. The inputs for the method "float CPSClusterChunk::eCone(const SpaceVector& Zprim, float eta, float phi, float detR) const" are: Zprim, the x, y, and z coordinates of the primary vertex; the cone direction, specified by eta and phi; and the cone size as specified by detR. The method identifies the 3D clusters that lie within the cone, then adds up the energy of the full single layer clusters associated with those 3D clusters. The method "float CPSClusterChunk::eCone(const std::vector< edm::LinkIndex >* m) const" performs the same energy summation for an input set of CPS3DCluster objects (specified by their Link Indices). A single layer cluster profile is provided by the method "const Profile getProfile(int ID)" where a Profile is defined in a typedef as a "std::map." The Profile returned for the CPSCluster object specified by its ID (the ClusID stored in the object) places the strip energies in order from the highest energy strip to the lowest. The index of the highest energy strip is zero. If you have Profiles from two SLC's and want a combined profile (say, because the two SLC's were from a merged CPS3DCluster), the method "const Profile merge2Profiles(const Profile& p1, const Profile& p2)" will provide it. The lists of chunk history variables, EnvID, RCPID and ChunkID, are also stored in the chunk. Access methods are provided for these lists. The standard edm method "void printChunk(ostream& out)" is provided for printing the chunk. A set of LinkIndex methods is also provided with the chunk. In particular, a vector of links to the CPS3DCluster objects, in the same order as the GlobalClusterList, can be obtained from either of two methods: "void cpslinks(std::vector>& links) const", or "const std::vector> & get_cpslinks() const". If the links have not been previously set up, the use of either of these methods will perform the setup. The code for CPSClusterChunk can be found in the cvs module cps_evt. The thumbnail version We have described above the full data record. The CPSClusterChunk can also be built from a vector of thumbnail objects (CPSTmbObj) using a constructor that takes this vector and the RCPID's and ChunkID's as input. Each CPSTmbObj has data for a CPS3DCluster object and its constituent SLC's. A CPSClusterChunk built from the thumbnail data will have a GlobalClusterList with one rebuilt CPS3DCluster object for each CPSTmbObj and an SLCVec with three CPSCluster objects (one from each layer) for each CPSTmbObj. The rebuilt objects contain a subset of the information contained in the full data record. We describe in detail below what information is available in CPS3DCluster and CPSCluster objects that have been rebuilt from the thumbnail. The most significant item of missing information is the list of strips used in the 3D cluster. Fewer bits are used to store the variables that are retained, so there is some loss of precision. The standard CPS3DCluster access methods will yield the following information: -- int ClusID() gives a cluster ID number assigned during the thumbnail unpacking. -- float ClusEnergy() gives the total 3D cluster energy in GeV, stored in the thumbnail using 16 bits. -- float xSLCEnergy(), float uSLCEnergy(), float vSLCEnergy() gives the energy in GeV of the subcluster in the x, u, and v layers, respectively. These were stored in the thumbnail as 16 bit fractions of the total ClusEnergy. -- float delEnergy() gives the uncertainty in the total cluster energy in GeV. This is not stored in the thumbnail, but is recalculated in the unpacking. It is taken to be the square root of the ClusEnergy divided by 1000 times the parameter npeMeV, which is hardwired to the current default value of 17.0. -- CPSHitPosition HitPosition() gives the whole CPSHitPosition object associated with the 3D cluster. The CPSHitPosition object is recreated in the unpacking. -- float r(), float phi(), float z() give the r, phi, and z D0 coordinates of the cluster, respectively. These were stored using 16 bits and are used to rebuild the CPSHitPosition object. Values of r and z are given in cm and the value of phi is given in radians. -- float error(int i1, int i2) gives elements of the position error matrix from the CPSHitPosition object. The nine elements are accessed through the integers i1 and i2 in the same manner as for the CPSHitPosition object (1=r, 2=phi, 3=z). The CPSHitPosition matrix is rebuilt from the stored variables, r, rphiwidth and zwidth, which are stored using 16 bits. The rebuilt error matrix has zero for all off-diagonal elements, the (1,1) element is hardwired to be 0.16, the (2,2) element is calculated from rphiwidth and r, and the (3,3) element is calculated from zwidth. -- float rphiwidth() gives the uncertainty in phi times the mean radius of the detector (in cm), stored in the thumbnail using 16 bits. -- float zwidth() gives the uncertainty in the z coordinate (in cm), stored in the thumbnail using 16 bits. -- float matchquality() gives the matchquality variable from the CPSHitPosition object, stored in the thumbnail using 8 bits. --CellList StripList() returns a dummy list of CPSCellID's. The size of the list gives the correct number of strips, but otherwise the information is dummy. The cell IDs used in the CPS3DCluster are not preserved in the thumbnail. (CellList is defined in a public typedef as std::list.) -- int xCluster(), int uCluster(), int vCluster() gives the ClusID for the x, u, and v layer, respectively, from the CPSCluster object of the full SLC associated with the 3D cluster. These ID's are assigned as the CPSClusterChunk is built from the vector of CPSTmbObj's. In the thumbnail, CPSCluster information is saved only for the SLC's that form the preserved CPS3DCluster objects. The standard CPSCluster access methods will yield the following information: -- int ClusID() gives the cluster ID number (a new one assigned in the rebuilt CPSClusterChunk). -- int layer() gives the layer number of the cluster (1=axial, 2=u stereo, 3=v stereo), which is reconstructed in the unpacking of the thumbnail object. -- float energy() gives the total cluster energy in GeV, stored in the thumbnail using 16 bits. -- float Centroid() gives the cluster centroid in units of strip number, stored in the thumbnail using 16 bits. -- float RMSerror() gives the rms error on the centroid position in units of strip number, stored in the thumbnail using 8 bits. -- ClusterMap StripMap() returns the map of strip energies indexed by their CPSCellID. This map is only partially preserved in the thumbnail. The strip number of the most energetic strip is stored in the thumbnail using 12 bits, 8 bits are used to store the number of strips, 8 bits each are used to store the fraction of the cluster energy in the highest energy strip and the nearest neighbors of that strip. So when reconstructed, the ClusterMap will report the correct number of strips and the correct energies and Cell ID's for the central three strips. The remaining strips in the map have dummy CPSCellID's and zero energy. (These strips are put in the map so that its size method returns the correct number of strips in the original SLC.) The code for the thumbnail class, CPSTmbObj, can be found in the cvs module cps_evt.