feat: fully support Iguana and add documentation webpage

[c-dilks]

🦎 Iguana Integration

RunRoot/Ex11_Iguana.C provides a full example how to use Iguana algorithms with Clas12root; the comments within explain everything. Here are resulting plots for run 6658:

clas12root RunRoot/Ex11_Iguana.C+ --in=/cache/clas12/rg-a/production/recon/spring2019/torus-1/pass2/dst/train/nSidis/nSidis_006658.hipo

Details

clas12reader now has the function
clas12reader::SetReadAction(std::function<bool(clas12reader*)>), which takes a lambda expression of the form

[](clas12reader* reader) -> bool {
  // iguana run functions here
}

• this function is called directly after the HIPO banks are read for an event, but before Clas12root does anything else with them, such as building region_particle objects
• the clas12reader* pointer argument provides access to the state of the clas12reader instance at that time, and its bank accessors therefore provide access to the banks before Clas12root does anything else with them
• it is within this lambda expression that the user can call Iguana's Run functions to:
  • filter banks (e.g., with fiducial cuts)
  • transform banks (e.g., with momentum corrections)
  • create new banks (e.g., calculate inclusive kinematics)
• the bool return value can be used to decide whether or not to further process the event; returning false means the event will be skipped and clas12reader will proceed to the next event
• the lambda expression's capture variables can be used to pass in/out
  • Iguana algorithm instances
  • bank instances, namely those created by Iguana algorithms
  • any other custom data structures
• Requires Iguana 1.0.0 or newer (specifically, feat!: Run function enhancements iguana#364)

region_particle is equipped to handle hipo::bank filters

• Iguana filter algorithms use hipo::bank::rowlist::filter to filter bank rows
• region_particle now contains members to track whether or not the particle was filtered
• region_particle accessors in clas12reader also now can handle such filtering results

📖 Documentation

• CI job now runs Doxygen
• I've started populating various docstrings, especially for the stuff this PR touches
• Doxygen webpage will be deployed whenever a commit is pushed to the master branch
  • Ideally, whenever a PR is merged
  • You will need to allow this behavior in your settings: go to Settings -> Pages -> Build and Development -> Change "source" to "GitHub Actions"
  • This will deploy to https://jeffersonlab.github.io/clas12root (which will return 404 until the first successful deployment); I've added a link to this page in the main README.md

Here's a screenshot of the webpage for clas12reader (click to enlarge):

[dglazier]

Hi Chris,
Thanks, I got it all to run and tested a few examples and saw no ill-effects.
One thing that we need to think about a bit more is the behaviour of RECFT based particles. clas12root is set up so the user just sets a flag so RECFT is used if exists, and REC is used if not. For the iguana algorithms is looks like they now have to write explicitly which bank, as well as set the useFT flag. Also these 2 banks share some common items (which the FT cannot change). Do you have any ideas how best to handle this ? One possibility might be to change cr->getRECParticle() to cr->getParticle(), with some care needed as these are different class objects. Another possibility might be to handle this in iguana with a transform alogorithm overwriting the REC::PARTICLE items with RECFT when appropriate. i.e. do we need a clas12root or iguana solution for this.
Cheers
Derek

[c-dilks]

One thing that we need to think about a bit more is the behaviour of RECFT based particles. clas12root is set up so the user just sets a flag so RECFT is used if exists, and REC is used if not. For the iguana algorithms is looks like they now have to write explicitly which bank, as well as set the useFT flag.

Iguana's Run functions indeed need the user to choose the correct bank. Iguana algorithms which read particle banks (REC::Particle, RECFT::Particle, MC::Particle, etc.) should be reasonably generalized to support all of them, where appropriate; I've done some work in the past few weeks to make sure that's true for all existing algorithms.

If I understand correctly, the user should call clas12reader::useFTBased if they want to use FT-based PID. In the current design, however, the user still needs to manually choose which particle bank to feed into iguana algorithms, which I think is reasonable, but we can do better. I propose another method getParticleBank; see the diff here and let me know what you think. It could be extended to return other particle-like banks if we want.

Also these 2 banks share some common items (which the FT cannot change).

getParticleBank returns the base class hipo::bank& reference, and the user could downcast if needed; alternatively we could return std::variant, but that may be less user-friendly. getRECParticle and getRECFTParticle should remain as they are, for consistency and transparent access.

Another possibility might be to handle this in iguana with a transform alogorithm overwriting the REC::PARTICLE items with RECFT when appropriate.

That's possible too.

[dglazier]

I made a comment in the branch pull request. I will copy it here

"I think there may be an issue with this method. RECFT is not a fully complete record, it shares some banks with REC. So a filter or iguana algorithm may require a combination of RECFT and REC information and any filters applied would need to be synchronised with both."

I think having iguana create a combined bank on the fly, might be the way to go. The procedure would be well defined. :
If useFT && RECFT.size()>0 => use RECFT banks + REC banks (which don't have a RECFT equivalent)
if useFT && RECFT.size()== 0 => use all REC
if !useFT => use all REC

This is essentially what clas12root currently does.

It my also be the getParticleBank works in practise, just not clear to me yet.
Cheers
Derek

[c-dilks]

I think having iguana create a combined bank on the fly, might be the way to go. The procedure would be well defined. :
If useFT && RECFT.size()>0 => use RECFT banks + REC banks (which don't have a RECFT equivalent)
if useFT && RECFT.size()== 0 => use all REC
if !useFT => use all REC

Sure, I can take care of this in the iguana repo. Since we want to maintain independence of clas12root on iguana, and clas12root already does this sort of thing, this is a feature for iguana users only; in other words, clas12root shouldn't be refactored to use the new combined bank this iguana algo would create, unless we could do so without introducing build-dependency on iguana.

This is out of scope of this PR though, being more of an iguana issue, so I'll work on it as a separate task there.

It my also be the getParticleBank works in practise, just not clear to me yet.

getParticleBank is more meant to just be "sugar", to help automate the choice between getRECParticle and getRECFTParticle.