v492 dev8 xg boost

[GernotMaier]

This is the first step to add a simple interface to machine learning methods to calculate direction, energy, or gamma/hadron separation indicators. This PR adds a new method to calculate the direction reconstruction.

Methods

Add XGBoost regression trees methods for training and reconstruction to calculate the gamma-ray arrival direction in camera coordinates. Uses DispBDT, intersection methods, plus image parameters to calculate Xoff/Yoff. Allows to take better into account edge cases like truncated images in comparison with the averaging over all DispBDT directions applied in previous methods.

Two new scripts:

• python/trainXGBoostforDirection.py
• python/applyXGBoostforDirection.py

Angular resolution

Moderate box cuts; 20 deg, 0.5 deg offset, noise 400: red is dispBDT, blue the updated XGB method

Moderate box cuts; 20 deg, 1.75 deg offset, noise 400: red is dispBDT, blue the updated XGB method

Moderate box cuts; 60 deg, 0.5 deg offset, noise 400: red is dispBDT, blue the updated XGB method

Moderate box cuts; 60 deg, 1.5 deg offset, noise 400: red is dispBDT, blue the updated XGB method

Crab rates

• +<5% Crab rates for 0.5 deg offsets (variable zenith angles): 2.38 vs 2.48 (xgb) g/min (hard box cuts)
• +10% higher with XGB for 0.7 - 1.5 deg offsets: 2.18 vs 2.38 (xgb) g/min (hard box cuts)

Interface

Both script use uproot to read the parameters from the mscw files, the preferred access interface for any new methods.

Both scripts writes a simple root file with a tree with the same number of entries as the data tree generated by the mscw stage. In this PR, we added Dir_Xoff and Dir_Yoff. Several changes are applied to read those tree in the analysis and in the IRF production without big changes in the workflow.

Related PRs

• Xgb Eventdisplay_AnalysisScripts_VTS#124
• v492.0 dev3 xgb Eventdisplay_AnalysisFiles_VTS#86

Todos

• 3tel IRF production

[Copilot]

Pull request overview

This PR introduces XGBoost-based machine learning methods for gamma-ray arrival direction reconstruction in camera coordinates. The implementation adds a new pipeline using DispBDT, intersection methods, and image parameters to predict Xoff/Yoff positions, particularly improving handling of edge cases like truncated images compared to previous averaging methods.

Key Changes:

• New Python scripts for training (trainXGBoostforDirection.py) and applying (applyXGBoostforDirection.py) XGBoost multi-target regression models for direction reconstruction
• C++ infrastructure to read XGBoost predictions from friend trees and integrate them into the analysis workflow via new getter methods in CData
• Refactored derotation angle calculation into a standalone utility function to eliminate code duplication

Reviewed changes

Copilot reviewed 27 out of 28 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
python/trainXGBoostforDirection.py	New script for training XGBoost models per telescope multiplicity (2, 3, 4 tel) using mscw file parameters
python/applyXGBoostforDirection.py	New script for applying trained models and writing Dir_Xoff/Dir_Yoff predictions to ROOT files
src/CData.cpp	Adds friend tree support for XGB results with new getter methods (get_Xoff, get_Yoff, get_XYoff_derot)
inc/CData.h	Declares friend tree members and new getter methods with method parameter for selecting reconstruction type
src/VStereoAnalysis.cpp	Opens XGB files and passes trees to CData constructor for analysis
src/makeEffectiveArea.cpp	Loads XGB files for effective area calculations
src/VSkyCoordinatesUtilities.cpp	Adds getDerotationAngleFromGroundCoordinates utility to simplify derotation calculations
inc/VSkyCoordinatesUtilities.h	Declares new derotation utility function
src/VTableLookupDataHandler.cpp	Removes getArrayPointingDeRotationAngle (replaced by new utility), adds fpointing_dx/dy branches
inc/VTableLookupDataHandler.h	Removes getArrayPointingDeRotationAngle declaration
src/VRadialAcceptance.cpp	Updates to use new CData getter methods instead of direct member access
src/VInstrumentResponseFunctionData.cpp	Updates to use get_Xoff/get_Yoff getter methods
src/VInstrumentResponseFunctionRunParameter.cpp	Adds fXGB_file_suffix parameter for XGB file configuration
inc/VInstrumentResponseFunctionRunParameter.h	Declares fXGB_file_suffix and increments ClassDef version to 19
src/VGammaHadronCuts.cpp	Updates to use get_Xoff/get_Yoff getter methods with explicit method parameter
src/VEffectiveAreaCalculator.cpp	Updates validation check to use new getter methods
src/VDispAnalyzer.cpp	Minor formatting fix (whitespace)
src/VDataMCComparision.cpp	Updates to use get_XYoff_derot() for derotated coordinates
inc/VDataMCComparision.h	Adds utility header include
src/VAnaSumRunParameter.cpp	Adds fXGB_file_suffix parameter handling and printing
inc/VAnaSumRunParameter.h	Declares fXGB_file_suffix and increments ClassDef version to 19
src/VAnaSum.cpp	Fixes spelling in comment (sequentiell → sequential)
inc/VRadialAcceptance.h	Adds utility header include
src/trainTMVAforGammaHadronSeparation.cpp	Adds clarifying comment about derotated coordinates
environment.yml	New conda environment file with Python 3.13 and ML dependencies
.pre-commit-config.yaml	Updates pre-commit hooks (adds Ruff, updates versions)
Makefile	Adds dependencies for new executables that now use CData and related classes

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.