treewide: use podio:output_collections instead of deprecated podio:ou…

…tput_include_collections (#1578)

### Briefly, what does this PR introduce?

This is a follow up on #1466 with focus on docs and use examples in
general.

### What kind of change does this PR introduce?
- [x] Bug fix (issue #__)
- [ ] New feature (issue #__)
- [ ] 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

.github/workflows/linux-eic-shell.yml

@@ -496,7 +496,7 @@ jobs:
           export DETECTOR_CONFIG=${DETECTOR}_${{ matrix.detector_config }}
           export LD_LIBRARY_PATH=$PWD/install/lib:$LD_LIBRARY_PATH
           export JANA_PLUGIN_PATH=$PWD/install/lib/EICrecon/plugins${JANA_PLUGIN_PATH:+:${JANA_PLUGIN_PATH}}
-          $PWD/install/bin/eicrecon $JANA_OPTIONS -Ppodio:output_include_collections=EventHeader,MCParticles,EcalBarrelScFiRawHits,EcalBarrelImagingRawHits -Ppodio:output_file=two_stage_raw_${{ matrix.particle }}_1GeV_20GeV_${{ matrix.detector_config }}.edm4eic.root sim_${{ matrix.particle }}_1GeV_20GeV_${{ matrix.detector_config }}.edm4hep.root -Pplugins=dump_flags,janadot -Pdump_flags:json=${{ matrix.particle }}_${{ matrix.detector_config }}_flags.json
+          $PWD/install/bin/eicrecon $JANA_OPTIONS -Ppodio:output_collections=EventHeader,MCParticles,EcalBarrelScFiRawHits,EcalBarrelImagingRawHits -Ppodio:output_file=two_stage_raw_${{ matrix.particle }}_1GeV_20GeV_${{ matrix.detector_config }}.edm4eic.root sim_${{ matrix.particle }}_1GeV_20GeV_${{ matrix.detector_config }}.edm4hep.root -Pplugins=dump_flags,janadot -Pdump_flags:json=${{ matrix.particle }}_${{ matrix.detector_config }}_flags.json
     - name: Upload digitization output
       uses: actions/upload-artifact@v4
       with:
@@ -512,7 +512,7 @@ jobs:
           export DETECTOR_CONFIG=${DETECTOR}_${{ matrix.detector_config }}
           export LD_LIBRARY_PATH=$PWD/install/lib:$LD_LIBRARY_PATH
           export JANA_PLUGIN_PATH=$PWD/install/lib/EICrecon/plugins${JANA_PLUGIN_PATH:+:${JANA_PLUGIN_PATH}}
-          $PWD/install/bin/eicrecon $JANA_OPTIONS -Ppodio:output_include_collections=EcalBarrelClusters,EcalBarrelClusterAssociations -Ppodio:output_file=two_stage_rec_${{ matrix.particle }}_1GeV_20GeV_${{ matrix.detector_config }}.edm4eic.root two_stage_raw_${{ matrix.particle }}_1GeV_20GeV_${{ matrix.detector_config }}.edm4eic.root -Pplugins=dump_flags,janadot -Pdump_flags:json=${{ matrix.particle }}_${{ matrix.detector_config }}_flags.json
+          $PWD/install/bin/eicrecon $JANA_OPTIONS -Ppodio:output_collections=EcalBarrelClusters,EcalBarrelClusterAssociations -Ppodio:output_file=two_stage_rec_${{ matrix.particle }}_1GeV_20GeV_${{ matrix.detector_config }}.edm4eic.root two_stage_raw_${{ matrix.particle }}_1GeV_20GeV_${{ matrix.detector_config }}.edm4eic.root -Pplugins=dump_flags,janadot -Pdump_flags:json=${{ matrix.particle }}_${{ matrix.detector_config }}_flags.json
     - name: Upload reconstruction output
       uses: actions/upload-artifact@v4
       with:
@@ -809,7 +809,7 @@ jobs:
           export DETECTOR_CONFIG=${DETECTOR}_${{ matrix.detector_config }}
           export LD_LIBRARY_PATH=$PWD/install/lib:$LD_LIBRARY_PATH
           export JANA_PLUGIN_PATH=$PWD/install/lib/EICrecon/plugins:/usr/local/plugins
-          $PWD/install/bin/eicrecon $JANA_OPTIONS -Ppodio:output_file=rec_${{ matrix.particle }}_EcalLumiSpec_${{ matrix.detector_config }}.edm4eic.root sim_${{ matrix.particle }}_EcalLumiSpec_${{ matrix.detector_config }}.edm4hep.root -Ppodio:output_include_collections=EcalLumiSpecRawHits,EcalLumiSpecRecHits,EcalLumiSpecClusters,EcalLumiSpecClusterAssociations -PLUMISPECCAL:EcalLumiSpecIslandProtoClusters:splitCluster=1 -Pplugins=dump_flags,janadot,janatop $(<${{ github.workspace }}/.github/janadot.groups) -Pdump_flags:json=${{ matrix.particle }}_${{ matrix.detector_config }}_flags.json
+          $PWD/install/bin/eicrecon $JANA_OPTIONS -Ppodio:output_file=rec_${{ matrix.particle }}_EcalLumiSpec_${{ matrix.detector_config }}.edm4eic.root sim_${{ matrix.particle }}_EcalLumiSpec_${{ matrix.detector_config }}.edm4hep.root -Ppodio:output_collections=EcalLumiSpecRawHits,EcalLumiSpecRecHits,EcalLumiSpecClusters,EcalLumiSpecClusterAssociations -PLUMISPECCAL:EcalLumiSpecIslandProtoClusters:splitCluster=1 -Pplugins=dump_flags,janadot,janatop $(<${{ github.workspace }}/.github/janadot.groups) -Pdump_flags:json=${{ matrix.particle }}_${{ matrix.detector_config }}_flags.json
     - uses: actions/upload-artifact@v4
       with:
         name: rec_${{ matrix.particle }}_EcalLumiSpec_${{ matrix.detector_config }}.edm4eic.root

docs/howto/visualize_callgraph.md

@@ -48,20 +48,20 @@ By default `eicrecon` activates the full reconstruction. This will
 result in a very busy callgraph that can be hard to read if you
 are only interested in one detector. (See [here](https://eic.github.io/EICrecon/howto/callgraphs/all.png).)
 To activate for a specific factory, you can specify the relevant output
-collection using the `podio:output_include_collections` parameter.
+collection using the `podio:output_collections` parameter.
 Here is an example for the *EcalEndcapN*:
 
 ~~~bash
 eicrecon -Pplugins=janadot \
-   -Ppodio:output_include_collections=EcalEndcapNMergedClusters \
+   -Ppodio:output_collections=EcalEndcapNMergedClusters \
    sim_file.edm4hep.root
 ~~~
 
 The above will produce something like the following:
 ![EcalEndcapNMergedClusters](callgraphs/EcalEndcapNMergedClusters.png)
 
 In the plot, the oval at the top is the JEventProcessor making the
-initial request for objects. (This is where the *podio:output_include_collections*
+initial request for objects. (This is where the *podio:output_collections*
 parameter is used). The rectangles in the middle represent factories (i.e. algorithms).
 The green trapezoid at the bottom is the object read from the input file.
 This is representative of the flow JANA implements. Namely, the requests for

docs/tutorial/02-work-environment.md

@@ -137,11 +137,11 @@ eicrecon 2022-09-26_ncdis10x100_minq2-1_100ev.edm4hep.root
 
 ## Generating a podio output file
 To write reconstructed values to an output file, you need to tell *eicrecon* what to write.
-There are several options available, but the mosrt useful one is *podio:output_include_collections*.
+There are several options available, but the mosrt useful one is *podio:output_collections*.
 This is a comma separated list of colelctions to write to the output file. For example:
 
 ```console
-eicrecon -Ppodio:output_include_collections=ReconstructedParticles 2022-09-26_ncdis10x100_minq2-1_100ev.edm4hep.root
+eicrecon -Ppodio:output_collections=ReconstructedParticles 2022-09-26_ncdis10x100_minq2-1_100ev.edm4hep.root
 ```
 
 To see a list of possible collections, run *eicrecon -L* .

docs/tutorial/04-factory.md

@@ -287,7 +287,7 @@ extern "C" {
 Finally, we go ahead and trigger the factory (remember, factories won't do anything unless activated by a JEventProcessor). You can open the
 
 ~~~ bash
-eicrecon in.root -Ppodio:output_file=out.root -Ppodio:output_include_collections=EcalEndcapNIslandClusters -Pjana:nevents=10
+eicrecon in.root -Ppodio:output_file=out.root -Ppodio:output_collections=EcalEndcapNIslandClusters -Pjana:nevents=10
 ~~~
 
 

src/benchmarks/reconstruction/tof_efficiency/README.md

@@ -65,7 +65,7 @@ export DETECTOR_PATH="/path/to/dd4hep/epic/"
 export DETECTOR="epic_tracking_only"
 
 # This makes tracking output data and input MC particles to be written to the output
--Ppodio:output_include_collections="ReconstructedParticles,TrackParameters,MCParticles"
+-Ppodio:output_collections="ReconstructedParticles,TrackParameters,MCParticles"
 
 # There is a centralized file where plugins can save their histograms:
 -Phistsfile=/home/romanov/work/data/eicrecon_test/tracking_test_gun.ana.root
@@ -82,7 +82,7 @@ defining a list of objects and the output file name:
 
 ```bash
 # This makes tracking output data and input MC particles to be written to the output
--Ppodio:output_include_collections="ReconstructedParticles,TrackParameters,MCParticles"
+-Ppodio:output_collections="ReconstructedParticles,TrackParameters,MCParticles"
 
 # This sets file path containing output tree
 -Ppodio:output_file=/home/romanov/work/data/eicrecon_test/tracking_test_gun.edm4eic.root

src/benchmarks/reconstruction/tracking_efficiency/README.md

@@ -67,7 +67,7 @@ export DETECTOR_PATH="/path/to/dd4hep/epic/"
 export DETECTOR="epic_tracking_only"
 
 # This makes tracking output data and input MC particles to be written to the output
--Ppodio:output_include_collections="ReconstructedParticles,TrackParameters,MCParticles"
+-Ppodio:output_collections="ReconstructedParticles,TrackParameters,MCParticles"
 
 # There is a centralized file where plugins can save their histograms:
 -Phistsfile=/home/romanov/work/data/eicrecon_test/tracking_test_gun.ana.root
@@ -84,7 +84,7 @@ defining a list of objects and the output file name:
 
 ```bash
 # This makes tracking output data and input MC particles to be written to the output
--Ppodio:output_include_collections="ReconstructedParticles,TrackParameters,MCParticles"
+-Ppodio:output_collections="ReconstructedParticles,TrackParameters,MCParticles"
 
 # This sets file path containing output tree
 -Ppodio:output_file=/home/romanov/work/data/eicrecon_test/tracking_test_gun.edm4eic.root

src/detectors/LUMISPECCAL/README.md

@@ -67,7 +67,7 @@ export DETECTOR_PATH="/path/to/dd4hep/epic/"
 export DETECTOR="epic_tracking_only"
 
 # This makes tracking output data and input MC particles to be written to the output
--Ppodio:output_include_collections="ReconstructedParticles,TrackParameters,MCParticles"
+-Ppodio:output_collections="ReconstructedParticles,TrackParameters,MCParticles"
 
 # There is a centralized file where plugins can save their histograms:
 -Phistsfile=/home/romanov/work/data/eicrecon_test/tracking_test_gun.ana.root
@@ -84,7 +84,7 @@ defining a list of objects and the output file name:
 
 ```bash
 # This makes tracking output data and input MC particles to be written to the output
--Ppodio:output_include_collections="ReconstructedParticles,TrackParameters,MCParticles"
+-Ppodio:output_collections="ReconstructedParticles,TrackParameters,MCParticles"
 
 # This sets file path containing output tree
 -Ppodio:output_file=/home/romanov/work/data/eicrecon_test/tracking_test_gun.edm4eic.root

src/services/io/podio/README.md

@@ -106,7 +106,7 @@ You may specify both an include list and an exclude list.
 
 
 Similar to the input, you may also specify which collections to write out using the
-_podio:output_include_collections_ and _podio:output_exclude_collections_ configuration
+_podio:output_collections_ and _podio:output_exclude_collections_ configuration
 parameters.
 
 ### Testing