feat: add Truthiness datatype for Monte Carlo comparisons (#128)

### Briefly, what does this PR introduce?
This PR adds a datatype to record the
"[truthiness](https://en.wikipedia.org/wiki/Truthiness)" (as
mathematically defined...) for a reconstructed event; where truthiness
is the "quality of seeming or being felt to be true, even if not
necessarily true," or in this case also "the amount of confidently
proclaiming the wrong thing to be true."

Mathematically, truthiness is a non-negative value that is zero only for
perfectly reconstructed events (positive-definite), and is radially
increasing in the error of the reconstruction (greater error leads to
greater truthiness).

It is possible to define truthiness in multiple ways, but we will
typically use some combination of the following components:
- a &chi;<sup>2</sup> measure on associated reconstructed and generated
particles, with normalization given by the determined uncertainty in the
reconstruction (if available) or 1 GeV otherwise,
- a positive penalty term for discrete reconstruction errors, such as
PID mis-identification (where weighting can be used to penalize some
mis-identification more than others),
- a positive penalty term for generated particles that should have been
reconstructed, but weren't,
- a positive penalty term for reconstructed particles that were not part
of the original event record.

There are non-reconstruction reasons why the truthiness will be non-zero
in realistic scenarios:
- multiple-scattering effects will cause the event to lose momentum
starting from the true value, deviating both in direction and magnitude
in a consistent direction,
- secondary particles will be generated in materials or along bent
trajectories, leading to additional reconstructed particles
corresponding to e.g. hard bremsstrahlung gammas in the electromagnetic
calorimeters,
- primary particles (in particular are low energies) may be absorbed in
support structures, leading to their absence in the reconstructed event.

Nevertheless, the decrease of the overall average event truthiness for
the same geometry and input hit collections is intended to indicate an
improved reconstruction, and converse.

### What kind of change does this PR introduce?
- [ ] Bug fix (issue #__)
- [x] New feature (issue: store truthiness for event reconstruction)
- [ ] Documentation update
- [ ] Other: __

### Please check if this PR fulfills the following:
- [ ] Tests for the changes have been added
- [ ] Documentation has been added / updated
- [ ] Changes have been communicated to collaborators

### Does this PR introduce breaking changes? What changes might users
need to make to their code?
No.

### Does this PR change default behavior?
No.

---------

Co-authored-by: Dmitry Kalinkin <[email protected]>
Co-authored-by: Markus Diefenthaler <[email protected]>

Author: 3 people

CMakeLists.txt

@@ -7,7 +7,7 @@ project(EDM4EIC
   LANGUAGES CXX)
 
 SET( ${PROJECT_NAME}_VERSION_MAJOR 8 )
-SET( ${PROJECT_NAME}_VERSION_MINOR 4 )
+SET( ${PROJECT_NAME}_VERSION_MINOR 5 )
 SET( ${PROJECT_NAME}_VERSION_PATCH 0 )
 SET( ${PROJECT_NAME}_VERSION  "${${PROJECT_NAME}_VERSION_MAJOR}.${${PROJECT_NAME}_VERSION_MINOR}.${${PROJECT_NAME}_VERSION_PATCH}" )
 

edm4eic.yaml

@@ -9,7 +9,7 @@
 ## If there are schema version changes that can be evolved, see the podio documentation
 ## for an example: https://github.com/AIDASoft/podio/tree/master/tests/schema_evolution
 ##
-schema_version: 840
+schema_version: 850
 
 options :
   # should getters / setters be prefixed with get / set?
@@ -200,6 +200,13 @@ components:
       - bool     TOTInProgress      // Flag which indicates if TOT calculation is ongoing, ADC value may be corrupted if this is true
       - bool     TOTComplete        // Flag which indicates if a TOT calculation is complete and TOT value is valid
 
+  ## Event-level truthiness information
+  edm4eic::TruthinessContribution:
+    Members:
+      - float pid                 // Contribution of PID matching to truthiness
+      - float energy              // Contribution of energy matching to truthiness
+      - float momentum            // Contribution of momentum matching to truthiness
+
 datatypes:
 
   edm4eic::Tensor:
@@ -540,7 +547,7 @@ datatypes:
       - edm4eic::ReconstructedParticle hadrons // Reconstructed hadrons used in calculation
 
   ## ==========================================================================
-  ## Data-Montecarlo relations
+  ## Data-Monte Carlo relations
   ## ==========================================================================
 
   edm4eic::MCRecoParticleAssociation:
@@ -623,6 +630,27 @@ datatypes:
       - edm4eic::Track        from   // reference to the track
       - edm4eic::ProtoCluster to     // reference to the protocluster
 
+  ## ==========================================================================
+  ## Data-Monte Carlo comparisons
+  ## ==========================================================================
+
+  edm4eic::Truthiness:
+    Description: "Positive-definite convex norm of how confidently wrong the reconstruction is,
+                  with non-negative contributions from various aspects of the reconstruction,
+                  where a zero value indicates a perfect reconstruction."
+    Author: "W. Deconinck, S. Colbert"
+    Members:
+       - float truthiness                                         // Overall truthiness of the entire event
+       - edm4eic::TruthinessContribution associationContribution  // Contribution from all associated particles
+       - float unassociatedMCParticlesContribution                // Contribution from unassociated MC particles
+       - float unassociatedRecoParticlesContribution              // Contribution from unassociated reconstructed particles
+    VectorMembers:
+      - edm4eic::TruthinessContribution associationContributions  // Contribution from associated particles
+    OneToManyRelations:
+       - edm4eic::MCRecoParticleAssociation associations          // Reference to the associated particles
+       - edm4hep::MCParticle unassociatedMCParticles              // Reference to the unassociated MC particles
+       - edm4eic::ReconstructedParticle unassociatedRecoParticles // Reference to the unassociated reconstructed particles
+
 links:
   edm4eic::TrackProtoClusterLink:
     Description: "Link between a ProtoCluster and a Track"