fix(event-display,app): make "Color Options → Color by" work for tracks and document the full event data format

guides/developers/event_data_format.md

@@ -41,12 +41,12 @@ The format is the following.
 
 Where:
 
-* `event number` and `run number` are hopefully obvious,
+* `event number` (or `eventNumber`) and `run number` (or `runNumber`) are hopefully obvious,
 * `OBJECT_TYPE` is one of the supported types that will be mentioned [below](#supported-object-types),
 * `COLLECTION_NAME` is an arbitrary name used to label this particular collection (you can have as many collections of each `OBJECT_TYPE` as you like).
-* `...` can be any other optional key/value pairs. Phoenix understands by default the following keys which will be used in the event Metadata panel, valuse being free strings :
+* `...` can be any other optional key/value pairs. Phoenix understands by default the following keys which will be used in the event Metadata panel, values being free strings :
   * `ls` will be printed for `LS` entry
-  * `lumiblock` will be printed for `LumiBlock` entry
+  * `lumiBlock` will be printed for `LumiBlock` entry
   * `time` : will be printed for `Data recorded` entry
 
 
@@ -63,26 +63,34 @@ Currently Phoenix supports the following physics objects:
 * Tracks - the trajectory of a charged particle (usually in a magnetic field)
 * Jets - cones of activity within the detector
 * Hits - individual measurements, which can either be points, lines, or boxes
-* CaloClusters - cluters of deposits in a calorimeter
-* [Planar]CaloCells - deposits of energy in a calorimeter (planar and cylindrical are supported).
+* CaloClusters - clusters of deposits in a calorimeter
+* [Planar/Irregular]CaloCells - deposits of energy in a calorimeter (cylindrical, planar and irregular geometries are supported).
 * Vertices - optionally linked to tracks
 * MissingEnergy
-* Compound objects which link 'Tracks' and 'Clusters' :
+* Compound objects which link 'Tracks' and 'CaloClusters' :
   * Muons 
   * Photons
   * Electrons
 
 (other shapes may be supported in the future)
 
-What follows in the detailed format of each object type. Any extra entry is considered as decoration and will not be interpreted by phoenix, although it will be visible by the user. E.g. a Track can have `dof` attribute on top of `pos`, `color`, ...
+What follows is the detailed format of each object type. Any extra entry is considered as decoration and will not be interpreted by phoenix, although it will be visible by the user.
 In all the descriptions, `opt` means that the attribute described is optional.
 
+Some attributes are used to build cut sliders in the collection's `Cut Options` menu folder. A cut is only shown if the attribute exists on the first object of the collection.
+
 #### 'Tracks'
-Tracks is a list of Track objects with the following attrbutes :
-* `pos` - list of positions along the track, each  given as a triplet [x, y, z]
+Tracks is a list of Track objects with the following attributes :
+* `pos` - list of positions along the track, each given as a triplet [x, y, z]
+* `dparams` (opt) - perigee parameters of the track: 5 floats matching [d0, z0, phi, theta, qOverP]. If `pos` is missing or has fewer than 3 positions, the track is extrapolated from `dparams` using a Runge-Kutta propagator
 * `color` (opt) - Hexadecimal string representing the color to draw the track.
-* `dparams` (opt) - parameters of the tracks. 5 floats matching d0, z0, phi, theta, qOverP
-* `d0`, `z0`, `phi`, `eta`, `qOverP`  (opt) - parameters of the tracks, taking precedence over `dparams`
+* `linewidth` (opt) - width of the track line (default 2)
+* `phi`, `eta`, `d0`, `z0` (opt) - parameters of the track, used for cuts. If not given, they are derived from `dparams` (or, for `phi`/`eta`, from the first two positions of `pos`)
+* `dca`, `angle` (opt) - distance of closest approach and polar angle in degrees, used for cuts. If not given, they are derived from the parameters above
+* `chi2`, `dof`, `pT` (opt) - used for cuts
+* `charge`, `mom` (opt) - charge and momentum, used by the `Color by` options (see below). Not needed if `dparams` is given, since then both are derived from the qOverP component
+
+Available cuts: `phi`, `eta`, `chi2`, `dof`, `pT`, `z0`, `d0`, `dca`, `angle`.
 
 #### 'Jets'
 Jets are a list of Jet objects with the following attributes :
@@ -92,32 +100,46 @@ Jets are a list of Jet objects with the following attributes :
 * `energy`, `et` (opt) - energy of the Jets, used to set its length
 * `coneR` (opt) - the radius of the jet cone. If not given, radius is 10% of the length
 * `color` (opt) - Hexadecimal string representing the color to draw the jet.
+* `origin_X`, `origin_Y`, `origin_Z` (opt) - origin of the jet (defaults to [0, 0, 0])
+
+Available cuts: `phi`, `eta`, `energy`.
 
 #### 'Hits'
 Hits can be defined in 2 ways. Either as an array of positions or as an array of Hit objects.
 
-In case aray of positions is used, Hits have format [ [x,y,z], [x,y,z], [x,y,z], ... ] i.e. an array of 3-dim arrays containing Cartesian coordinate.
+In case array of positions is used, Hits have format [ [x,y,z], [x,y,z], [x,y,z], ... ] i.e. an array of 3-dim arrays containing Cartesian coordinates.
 These will be rendered as points.
 
 In case of array of Hit objects, format is [ hit, hit, hit ] where the hit object has the following attributes :
-* `type` (opt) - type of Hit. One of `Point`, `Line` or `Box`. Defaults to Point
-* `pos` - an array of number describing the hit
-  * for `Point` type, it should have 3 coordinates : [x, y, z]
+* `type` (opt) - type of Hit. One of `Point`, `CircularPoint`, `Line` or `Box`. Defaults to Point
+* `pos` - an array of numbers describing the hit
+  * for `Point` and `CircularPoint` types, it should have 3 coordinates : [x, y, z]
   * for `Line` type, it should have 6 coordinates : [x0, y0, z0, x1, y1, z1]
   * for `Box` type, it should have 6 coordinates : [x, y, z, length in x, width in y, height in z]
 * `color` (opt) - Hexadecimal string representing the color to draw the hit.
-Note that all hit objects in a given Hits collection have to be of the same type.
+* `size` (opt) - size of the drawn point (`CircularPoint` type only, default 10)
+
+Note that all hit objects in a given Hits collection have to be of the same type, and that `type`, `color` and `size` are read from the first hit of the collection and applied to the whole collection.
 
 #### 'CaloClusters' and 'CaloCells'
-We are talking here of cylindrical calorimeters, the deposits will be displayed as boxes with fixed square base and length matching the energy. The orientation of the boxes is radial.
+We are talking here of cylindrical calorimeters, the deposits will be displayed as boxes with a square base, oriented radially, positioned at a default barrel radius of 1800 (CaloClusters) or 1700 (CaloCells) and a default z of 3600 (CaloClusters) or 2000 (CaloCells).
 'CaloClusters' and 'CaloCells' are lists of CaloCluster and CaloCell objects respectively. These have the same set of attributes :
-* `energy` - energy of the cluster or deposit, converted to length of the displayed box
+* `energy` - energy of the cluster or deposit. For CaloClusters it is converted to the length of the displayed box (unless `length` is given); for CaloCells it is only used for cuts
 * `phi` - phi direction
 * `eta` - eta direction
-
+* `theta` (opt) - if given, used instead of `eta` to position the box
+* `radius` (opt) - cylindrical radius at which to draw the box, overriding the default
+* `z` (opt) - z position at which to draw the box, overriding the default
+* `side` (opt) - transverse size of the box (default 40 for CaloClusters, 30 for CaloCells)
+* `length` (opt) - length of the box, overriding the energy-derived length (CaloCells default to 30)
+* `color` (opt) - Hexadecimal string representing the color to draw the box.
+* `opacity` (opt) - opacity of the box from 0 to 1 (CaloClusters only)
+
+Available cuts: `phi`, `eta`, `energy`.
+
 #### 'PlanarCaloCells'
 We are talking here of planar calorimeters, the deposits will be displayed as boxes with square base of cellSize and length matching the energy.
-These boxes will be positions on a given plane (the plane pf the calorimeter) at the specified coordinates in this plane.
+These boxes will be positioned on a given plane (the plane of the calorimeter) at the specified coordinates in this plane.
 
 PlanarCaloCells is an object with the following attributes :
 * `plane` - the Calorimeter plane, defined as 4 numbers, giving a direction (normal to the plane) and a distance to the origin : [dx, dy, dz, length]
@@ -127,14 +149,46 @@ PlanarCaloCells is an object with the following attributes :
   * `pos` - position of the cell within the calo plane given as a pair [x, y]
   * `color` (opt) - Hexadecimal string representing the color to draw the cell.
 
-#### 'Vertices
-'Vertices are a list of Vertex objects with the following attributes :
-* `color` (opt) - Hexadecimal string representing the color to draw the vertex.
+Available cuts: `energy`.
+
+#### 'IrregularCaloCells'
+Calorimeter cells with arbitrary polyhedron-type geometry. 
+Each cell is represented by 8 (x,y,z) vertices connected using a convex hull from the [ConvexGeometry](https://threejs.org/docs/#examples/en/geometries/ConvexGeometry) class.
+
+IrregularCaloCells is a list of objects with the following attributes :
+* `layer` - the Calorimeter layer, used for cuts
+* `vtx` - a flattened list of 8 vertex coordinates (24 floats)
+* `color` - an integer list of [R,G,B] values (note: not a hexadecimal string)
+* `opacity` - value from 0 to 1
+
+Available cuts: `layer`, `energy`.
+
+#### 'Vertices'
+Vertices are a list of Vertex objects with the following attributes :
 * one of the 2 following sets of attributes 
   * `x`, `y`, `z` : describing the position of the vertex
   * `pos` : array of 3 numbers (x, y, z) describing the position of the vertex
+* `color` (opt) - Hexadecimal string representing the color to draw the vertex.
+* `size` (opt) - radius of the displayed sphere (default 3)
+* `vertexType` (opt) - type of the vertex, used for cuts
+* `linkedTracks` (opt) - list of indices of the tracks associated with this vertex
+* `linkedTrackCollection` (opt) - name of the Tracks collection the `linkedTracks` indices refer to
 
-#### MissingEnergy
+If `linkedTracks` and `linkedTrackCollection` are given, the linked Tracks collection gets a `Color by` → `Vertex` option which colors each vertex and its associated tracks with a distinct color.
+
+Available cuts: `vertexType`.
+
+#### 'MissingEnergy'
 This is a list of objects, displayed as dashed lines starting from 0 and staying in the plane z=0. Each object has the following attributes :
 * `etx`, `ety` : describing the direction of the line
 * `color` (opt) - Hexadecimal string representing the color to draw the line.
+
+#### 'Muons', 'Electrons' and 'Photons'
+These are compound objects which link to existing 'Tracks' and 'CaloClusters' objects of the event. Each object has the following attributes :
+* `LinkedTracks` (opt) - list of strings of the form `"COLLECTION_NAME:INDEX"` (e.g. `"GSFTrackParticles:12"`), each identifying a track in a Tracks collection of the event (Muons and Electrons)
+* `LinkedClusters` (opt) - list of strings of the form `"COLLECTION_NAME:INDEX"`, each identifying a cluster in a CaloClusters collection of the event
+* `energy`, `eta`, `phi` (opt) - if no `LinkedClusters` are given, used to draw a cluster for Photons
+* `eta`, `phi`, `pt` (opt) - if no `LinkedTracks` are given, used to extrapolate a track for Muons and Electrons
+* `pdgId` (opt) - PDG ID of the particle, used to determine the charge of the extrapolated track
+
+Available cuts: `phi`, `eta`, `energy`, `pT`.

guides/users.md

@@ -12,10 +12,7 @@
   * [Labels](#labels)
   * [URL options](#url-options)
 * [Using Phoenix with your own data](#using-phoenix-with-your-own-data)
-  * [Event data](#event-data)
-    * [Format](#format)
-    * [Supported object types](#supported-object-types)
-  * [Geometry](#geometry)
+  * [Geometry Data](#geometry-data)
 
 ## Getting started
 
@@ -182,71 +179,7 @@ http://localhost:4200/#/atlas?file=assets/event_data/data.json&type=json
 
 ## Using Phoenix with your own data
 
-For details on the Phoenix event data format, please see [Phoenix Event Data Format](developers/event_data_format.md)
-
-#### 'Jets'
-Jets are a list of Jet objects with the following attributes :
-* `eta` - eta direction
-* `phi`- phi direction
-* `theta` (opt) - if not given, eta is used to calculate theta
-* `energy`, `et` (opt) - energy of the Jets, used to set its length
-* `coneR` (opt) - the radius of the jet cone. If not given, radius is 10% of the length
-* `color` (opt) - Hexadecimal string representing the color to draw the jet.
-* `origin_X`, `origin_Y`, `origin_Z` (opt) - Origin of the jet
-
-#### 'Hits'
-Hits can be defined in 2 ways. Either as an array of positions or as an array of Hit objects.
-
-In case aray of positions is used, Hits have format [ [x,y,z], [x,y,z], [x,y,z], ... ] i.e. an array of 3-dim arrays containing Cartesian coordinate.
-These will be rendered as points.
-
-In case of array of Hit objects, format is [ hit, hit, hit ] where the hit object has the following attributes :
-* `type` (opt) - type of Hit. One of `Point`, `Line` or `Box`. Defaults to Point
-* `pos` - an array of number describing the hit
-  * for `Point` type, it should have 3 coordinates : [x, y, z]
-  * for `Line` type, it should have 6 coordinates : [x0, y0, z0, x1, y1, z1]
-  * for `Box` type, it should have 6 coordinates : [x, y, z, length in x, width in y, height in z]
-* `color` (opt) - Hexadecimal string representing the color to draw the hit.
-Note that all hit objects in a given Hits collection have to be of the same type.
-
-#### 'CaloClusters' and 'CaloCells'
-We are talking here of cylindrical calorimeters, the deposits will be displayed as boxes with fixed square base and length matching the energy. The orientation of the boxes is radial.
-'CaloClusters' and 'CaloCells' are lists of CaloCluster and CaloCell objects respectively. These have the same set of attributes :
-* `energy` - energy of the cluster or deposit, converted to length of the displayed box
-* `phi` - phi direction
-* `eta` - eta direction
-
-#### 'PlanarCaloCells'
-We are talking here of planar calorimeters, the deposits will be displayed as boxes with square base of cellSize and length matching the energy.
-These boxes will be positions on a given plane (the plane pf the calorimeter) at the specified coordinates in this plane.
-
-PlanarCaloCells is an object with the following attributes :
-* `plane` - the Calorimeter plane, defined as 4 numbers, giving a direction (normal to the plane) and a distance to the origin : [dx, dy, dz, length]
-* `cells` - a list of Cell objects with the following attributes:
-  * `cellSize` - size of the Calorimeter cell which fired
-  * `energy` - energy of the deposit, converted to length of the displayed box
-  * `pos` - position of the cell within the calo plane given as a pair [x, y]
-  * `color` (opt) - Hexadecimal string representing the color to draw the cell.
-
-#### 'IrregularCaloCells'
-Calorimeter cells with arbitrary polyhedron-type geometry. 
-Each cell is represented by 8 (x,y,z) vertices connected using a convex hull from the [ConvexGeometry](https://threejs.org/docs/#examples/en/geometries/ConvexGeometry) class.
-
-IrregularCaloCells is a list of objects with the following attributes :
-   * `layer` - the Calorimeter layer
-   * `vtx` - a flattened list of 8 vertex coordinates (24 floats)
-   * `color` - an integer list of [R,G,B] values
-   * `opacity` - value from 0 to 1
-
-#### 'Vertices
-'Vertices are a list of Vertex objects with the following attributes :
-* `x`, `y`, `z` : describing the position of the vertex
-* `color` (opt) - Hexadecimal string representing the color to draw the vertex.
-
-#### MissingEnergy
-This is a list of objects, displayed as dashed lines starting from 0 and staying in the plane z=0. Each object has the following attributes :
-* `etx`, `ety` : describing the direction of the line
-* `color` (opt) - Hexadecimal string representing the color to draw the line.
+For details on the Phoenix event data format, including all supported object types and their attributes, please see [Phoenix Event Data Format](developers/event_data_format.md)
 
 ### Geometry Data
 

packages/phoenix-event-display/src/lib/types/event-data.ts

@@ -193,6 +193,10 @@ export interface VertexParams {
   vertexType?: number;
   /** Color for rendering. */
   color?: string | number;
+  /** Indices of the tracks associated with this vertex, used to color tracks by vertex. */
+  linkedTracks?: number[];
+  /** Name of the track collection the linked track indices refer to. */
+  linkedTrackCollection?: string;
   /** UUID assigned after object creation. Set internally. */
   uuid?: string;
   /** Extra experiment-specific properties. */

packages/phoenix-event-display/src/loaders/jivexml-loader.ts

@@ -160,6 +160,17 @@ export class JiveXMLLoader extends PhoenixLoader {
     return [false, 0, 0, 0];
   }
 
+  /**
+   * Get a track collection name which does not clash with an event data type.
+   * We have problems if the name of the collection is a type, so a collection
+   * named `Tracks` is renamed to `Tracks_`.
+   * @param collectionName Name (storeGateKey) of the track collection.
+   * @returns The (possibly renamed) collection name.
+   */
+  private getSafeTrackCollectionName(collectionName: string): string {
+    return collectionName === 'Tracks' ? 'Tracks_' : collectionName;
+  }
+
   /**
    * Extract Tracks from the JiveXML data format and process them.
    * @param firstEvent First "Event" element in the XML DOM of the JiveXML data format.
@@ -174,11 +185,9 @@ export class JiveXMLLoader extends PhoenixLoader {
     const badTracks: { [key: string]: any } = {};
 
     for (const collection of trackCollections) {
-      let trackCollectionName =
-        collection.getAttribute('storeGateKey') ?? 'Unknown';
-      if (trackCollectionName === 'Tracks') {
-        trackCollectionName = 'Tracks_'; //We have problems if the name of the collection is a type
-      }
+      const trackCollectionName = this.getSafeTrackCollectionName(
+        collection.getAttribute('storeGateKey') ?? 'Unknown',
+      );
 
       let thickTracks = false;
       if (
@@ -271,6 +280,7 @@ export class JiveXMLLoader extends PhoenixLoader {
         let storeTrack = true; // Need to do this because we need to retrieve all info so counters don't go wrong.
         const debugTrack = false;
         const track = {
+          index: i, // Original index in the JiveXML collection, needed to e.g. match vertex track links when bad tracks are dropped.
           chi2: 0.0,
           dof: 0.0,
           pT: 0.0,
@@ -923,7 +933,9 @@ export class JiveXMLLoader extends PhoenixLoader {
           primVxCand: primVxCand[i],
           vertexType: vertexType[i],
           linkedTracks: thisTrackIndices,
-          linkedTrackCollection: sgkeyOfTracks[i],
+          linkedTrackCollection: sgkeyOfTracks[i]
+            ? this.getSafeTrackCollectionName(sgkeyOfTracks[i])
+            : sgkeyOfTracks[i],
         });
       }
       const key = vertexColl.getAttribute('storeGateKey');