Reviewed top part, but needs updated file on s3 first

src/docs/part5/reconstruction_analysis.md

@@ -37,17 +37,21 @@ For the purpose of this tutorial we will use the S3 interface since it does not
 
 ## File structure of the full simulation reconstruction output
 
-Each reconstruction output file has essentially the same structure, defined by the EIC Data Model. This structure can be retrieved with `rootls`, e.g.
+Each reconstruction output file has essentially the same structure, defined by the EIC Data Model. This structure can be retrieved with `root` and `.ls` (or, for local files, with `rootls` as well), e.g.
 ```console
 root -l s3https://dtn01.sdcc.bnl.gov:9000/eictest/ATHENA/RECO/master/SINGLE/pi+/1GeV/45to135deg/pi+_1GeV_45to135deg.0001.root
 ```
+and
+```console
+.ls
+```
 which produces the following output, two trees:
 ```console
 events  metadata
 ```
-You may encounter some (or many) warnings when you run this on a regular ROOT installation, but the ROOT files are built in such a way that they only use basic ("plain old data") types that ROOT can interpret without any helper classes. There are helper classes available inside the ATHENA container.
+You may encounter some (or many) warnings when you run this on a regular ROOT installation, but the ROOT files are built in such a way that they only use basic ("plain old data") types that ROOT can interpret without any helper classes. There are helper classes available inside the `eic-shell` container.
 
-The `events` tree is of course what we are interested in. We can explore its top-level structure as follows. We first start a ROOT session:
+The `events` tree is what we are interested in. We can explore its top-level structure as follows. We start a ROOT session:
 ```console
 root -l s3https://dtn01.sdcc.bnl.gov:9000/eictest/ATHENA/RECO/master/SINGLE/pi+/1GeV/45to135deg/pi+_1GeV_45to135deg.0001.root
 ```
@@ -59,83 +63,33 @@ This will display a large number of branches (and their size):
 ```console
 ******************************************************************************
 *Tree    :events    : Events tree                                            *
-*Entries :     1002 : Total =        44146720 bytes  File  Size =   14534550 *
-*        :          : Tree compression factor =   3.01                       *
+*Entries :   125002 : Total =       259721864 bytes  File  Size =   58678900 *
+*        :          : Tree compression factor =   4.43                       *
 ******************************************************************************
-branch: mcparticles2            117074
-branch: TrackerBarrelHits2      352204
-branch: ReconstructedParticles      3763
-branch: EcalBarrelHitsSimpleDigi    132444
-branch: EcalBarrelHitsSimpleReco    162677
-branch: EcalEndcapNHitsDigi      53267
-branch: EcalEndcapNHitsReco      18557
-branch: EcalEndcapNProtoClusters      2247
-branch: EcalEndcapNClusters       5389
-branch: outputInfoCollection      2744
-branch: EcalEndcapPHitsDigi      79927
-branch: EcalEndcapPHitsReco      57765
-branch: EcalEndcapPHitsRecoXY     53667
-branch: EcalEndcapPProtoClusters      2439
-branch: EcalEndcapPClusters       5508
-branch: EcalEndcapPClustersInfo      2833
-branch: EcalBarrelHitsDigi      130174
-branch: EcalBarrelHitsReco      297904
-branch: EcalBarrelProtoClusters      3416
-branch: EcalBarrelLayers          8672
-branch: EcalBarrelClusters        9396
-branch: EcalBarrelClustersInfo      5286
-branch: EcalBarrelScFiHitsDigi   5345203
-branch: EcalBarrelScFiHitsReco   5554064
-branch: EcalBarrelScFiGridReco   1328000
-branch: EcalBarrelScFiProtoClusters     67285
-branch: EcalBarrelScFiClusters     36508
-branch: EcalBarrelScFiClustersInfo     19039
-branch: HcalBarrelHitsDigi       54355
-branch: HcalBarrelHitsReco       44131
-branch: HcalBarrelHitsRecoXY     36646
-branch: HcalBarrelProtoClusters      1935
-branch: HcalBarrelClusters        4251
-branch: HcalBarrelClustersInfo      2269
-branch: HcalEndcapNHitsDigi      11722
-branch: HcalEndcapNHitsReco      13786
-branch: HcalEndcapNHitsRecoXY     11962
-branch: HcalEndcapNProtoClusters      1903
-branch: HcalEndcapNClusters       4115
-branch: HcalEndcapNClustersInfo      2215
-branch: HcalEndcapPHitsDigi       7388
-branch: HcalEndcapPHitsReco       8158
-branch: HcalEndcapPHitsRecoXY      7660
-branch: HcalEndcapPProtoClusters      1903
-branch: HcalEndcapPClusters       4115
-branch: HcalEndcapPClustersInfo      2215
-branch: TrackerBarrelRawHits     51559
-branch: TrackerEndcapRawHits      3664
-branch: VertexBarrelRawHits      27933
-branch: VertexEndcapRawHits       2283
-branch: TrackerBarrelRecHits    148096
-branch: TrackerEndcapRecHits      7560
-branch: VertexBarrelRecHits      61902
-branch: VertexEndcapRecHits       3984
-branch: ReconstructedParticlesInitFromTruth      3277
-branch: outputTrackParameters      3519
-branch: DRICHHits2                8688
-branch: DRICHHitsDigi             1998
-branch: DRICHHitsReco             3525
-branch: EcalEndcapNHits           3717
-branch: EcalEndcapPHits           3717
-branch: EcalBarrelHits            3701
-branch: EcalBarrelScFiHits        3760
-branch: HcalBarrelHits            3701
-branch: HcalEndcapPHits           3717
-branch: HcalEndcapNHits           3717
-branch: TrackerEndcapHits         4372
-branch: TrackerBarrelHits         4372
-branch: VertexBarrelHits          4352
-branch: VertexEndcapHits          4352
-branch: DRICHHits                 4217
+branch: mcparticles2          19076202
+branch: GeneratedParticles     8870182
+branch: DummyReconstructedParticleRelations   3145028
+branch: EcalEndcapNClusters     420775
+branch: EcalEndcapNClusterInfo    278320
+branch: EcalEndcapPClusters     353052
+branch: EcalEndcapPClustersInfo    244860
+branch: EcalBarrelImagingLayers    513560
+branch: EcalBarrelImagingClusters    573919
+branch: EcalBarrelImagingClustersInfo    391666
+branch: EcalBarrelScFiClusters   4455990
+branch: EcalBarrelScFiClustersInfo   2532135
+branch: HcalBarrelClusters      249597
+branch: HcalBarrelClustersInfo    193490
+branch: HcalEndcapPClusters     243298
+branch: HcalEndcapPClustersInfo    190510
+branch: HcalEndcapNClusters     246231
+branch: HcalEndcapNClustersInfo    191962
+branch: outputTrackParameters   7543335
+branch: ReconstructedParticles   6195172
+branch: ReconstructedParticleRelations   2689346
 ```
 
-During the development of the reconstruction, there are more branches enabled here than are strictly necessary (e.g. simulated and digitized hits, intermediate reconstruction parameters). These are all available for analysis (with fixed interfaces). In this tutorial we will focus on a few branches in particular:
+During the development of the reconstruction, there are often more branches enabled here than are strictly necessary (e.g. simulated and digitized hits, intermediate reconstruction parameters). These are all available for analysis (with fixed interfaces). In this tutorial we will focus on a few branches in particular:
 - ReconstructedParticles: contains the results from track finding and fitting,
 - EcalBarrelImagingClusters: contains the results from the barrel Imaging Ecal cluster finding,
 - EcalBarrelScFiClusters: contains the results from the barrel ScFi Ecal cluster finding.
@@ -145,38 +99,50 @@ We can inspect each of these three branches in more detail (some information rem
 root [14] events->Print("ReconstructedParticles*")
 ******************************************************************************
 *Tree    :events    : Events tree                                            *
-*Entries :     1002 : Total =        44146720 bytes  File  Size =   14534550 *
-*        :          : Tree compression factor =   3.01                       *
+*Entries :   125002 : Total =       259721864 bytes  File  Size =   58678900 *
+*        :          : Tree compression factor =   4.43                       *
 ******************************************************************************
 *Br    0 :ReconstructedParticles : Int_t ReconstructedParticles_             *
-*Br    1 :ReconstructedParticles.ID.value : Int_t value[ReconstructedParticles_]                             *
-*Br    2 :ReconstructedParticles.p.x : Float_t x[ReconstructedParticles_]    *
-*Br    3 :ReconstructedParticles.p.y : Float_t y[ReconstructedParticles_]    *
-*Br    4 :ReconstructedParticles.p.z : Float_t z[ReconstructedParticles_]    *
-*Br    5 :ReconstructedParticles.v.x : Float_t x[ReconstructedParticles_]    *
-*Br    6 :ReconstructedParticles.v.y : Float_t y[ReconstructedParticles_]    *
-*Br    7 :ReconstructedParticles.v.z : Float_t z[ReconstructedParticles_]    *
-*Br    8 :ReconstructedParticles.time : Float_t time[ReconstructedParticles_]*
-*Br    9 :ReconstructedParticles.pid : Int_t pid[ReconstructedParticles_]    *
-*Br   10 :ReconstructedParticles.status : Short_t status[ReconstructedParticles_]                          *
-*Br   11 :ReconstructedParticles.charge : Short_t charge[ReconstructedParticles_]                          *
-*Br   12 :ReconstructedParticles.momentum : Float_t momentum[ReconstructedParticles_]                        *
-*Br   13 :ReconstructedParticles.energy : Float_t energy[ReconstructedParticles_]                          *
-*Br   14 :ReconstructedParticles.mass : Float_t mass[ReconstructedParticles_]*
-*Br   15 :ReconstructedParticles.weight.value :                              *
+*Br    1 :ReconstructedParticles.ID.value :                                  *
+*         | Int_t value[ReconstructedParticles_]                             *
+*Br    2 :ReconstructedParticles.ID.source :                                 *
+*         | Int_t source[ReconstructedParticles_]                            *
+*Br    3 :ReconstructedParticles.p.x : Float_t x[ReconstructedParticles_]    *
+*Br    4 :ReconstructedParticles.p.y : Float_t y[ReconstructedParticles_]    *
+*Br    5 :ReconstructedParticles.p.z : Float_t z[ReconstructedParticles_]    *
+*Br    6 :ReconstructedParticles.v.x : Float_t x[ReconstructedParticles_]    *
+*Br    7 :ReconstructedParticles.v.y : Float_t y[ReconstructedParticles_]    *
+*Br    8 :ReconstructedParticles.v.z : Float_t z[ReconstructedParticles_]    *
+*Br    9 :ReconstructedParticles.time : Float_t time[ReconstructedParticles_]*
+*Br   10 :ReconstructedParticles.pid : Int_t pid[ReconstructedParticles_]    *
+*Br   11 :ReconstructedParticles.status :                                    *
+*         | Short_t status[ReconstructedParticles_]                          *
+*Br   12 :ReconstructedParticles.charge :                                    *
+*         | Short_t charge[ReconstructedParticles_]                          *
+*Br   13 :ReconstructedParticles.weight.value :                              *
 *         | Float_t value[ReconstructedParticles_]                           *
+*Br   14 :ReconstructedParticles.direction.theta :                           *
+*         | Float_t theta[ReconstructedParticles_]                           *
+*Br   15 :ReconstructedParticles.direction.phi :                             *
+*         | Float_t phi[ReconstructedParticles_]                             *
+*Br   16 :ReconstructedParticles.momentum :                                  *
+*         | Float_t momentum[ReconstructedParticles_]                        *
+*Br   17 :ReconstructedParticles.energy :                                    *
+*         | Float_t energy[ReconstructedParticles_]                          *
+*Br   18 :ReconstructedParticles.mass : Float_t mass[ReconstructedParticles_]*
 *............................................................................*
 
 root [6] events->Print("EcalBarrelScFiClusters*")
 ******************************************************************************
 *Tree    :events    : Events tree                                            *
-*Entries :     1002 : Total =        44146720 bytes  File  Size =   14534550 *
-*        :          : Tree compression factor =   3.01                       *
+*Entries :   125002 : Total =       259721864 bytes  File  Size =   58678900 *
+*        :          : Tree compression factor =   4.43                       *
 ******************************************************************************
 *Br    0 :EcalBarrelScFiClusters : Int_t EcalBarrelScFiClusters_             *
 *Br    1 :EcalBarrelScFiClusters.ID.value :                                  *
 *         | Int_t value[EcalBarrelScFiClusters_]                             *
-*Br    2 :EcalBarrelScFiClusters.type : Int_t type[EcalBarrelScFiClusters_]  *
+*Br    2 :EcalBarrelScFiClusters.ID.source :                                 *
+*         | Int_t source[EcalBarrelScFiClusters_]                            *
 *Br    3 :EcalBarrelScFiClusters.energy :                                    *
 *         | Float_t energy[EcalBarrelScFiClusters_]                          *
 *Br    4 :EcalBarrelScFiClusters.energyError :                               *
@@ -209,13 +175,15 @@ root [6] events->Print("EcalBarrelScFiClusters*")
 *Br   18 :EcalBarrelScFiClustersInfo : Int_t EcalBarrelScFiClustersInfo_     *
 *Br   19 :EcalBarrelScFiClustersInfo.clusterID.value :                       *
 *         | Int_t value[EcalBarrelScFiClustersInfo_]                         *
-*Br   20 :EcalBarrelScFiClustersInfo.polar.r :                               *
+*Br   20 :EcalBarrelScFiClustersInfo.clusterID.source :                      *
+*         | Int_t source[EcalBarrelScFiClustersInfo_]                        *
+*Br   21 :EcalBarrelScFiClustersInfo.polar.r :                               *
 *         | Float_t r[EcalBarrelScFiClustersInfo_]                           *
-*Br   21 :EcalBarrelScFiClustersInfo.polar.theta :                           *
+*Br   22 :EcalBarrelScFiClustersInfo.polar.theta :                           *
 *         | Float_t theta[EcalBarrelScFiClustersInfo_]                       *
-*Br   22 :EcalBarrelScFiClustersInfo.polar.phi :                             *
+*Br   23 :EcalBarrelScFiClustersInfo.polar.phi :                             *
 *         | Float_t phi[EcalBarrelScFiClustersInfo_]                         *
-*Br   23 :EcalBarrelScFiClustersInfo.eta :                                   *
+*Br   24 :EcalBarrelScFiClustersInfo.eta :                                   *
 *         | Float_t eta[EcalBarrelScFiClustersInfo_]                         *
 *............................................................................*
 ```
@@ -244,7 +212,7 @@ These types of plots will likely be limited to simple data inspection.
 
 For a more advanced analysis, you can take advantage of the RDataFrame features, such as in this (shortened) DIS example. The [original](https://eicweb.phy.anl.gov/EIC/benchmarks/physics_benchmarks/-/blob/master/benchmarks/dis/analysis/dis_electrons.cxx) is used in our CI system and determines DIS parameters for every change to the detector geometry, simulation, digitization, or reconstruction.
 ```console
-auto momenta_from_reconstruction(const std::vector<eic::ReconstructedParticleData>& parts) {
+auto momenta_from_reconstruction(const std::vector<eicd::ReconstructedParticleData>& parts) {
   std::vector<ROOT::Math::PxPyPzEVector> momenta{parts.size()};
   std::transform(parts.begin(), parts.end(), momenta.begin(), [](const auto& part) {
     return ROOT::Math::PxPyPzEVector{part.p.x, part.p.y, part.p.z, part.energy};