Skip to content

Improvements to Cluster State Residuals QA#4147

Merged
osbornjd merged 3 commits intosPHENIX-Collaboration:masterfrom
rosstom2232:TPOTQA
Feb 2, 2026
Merged

Improvements to Cluster State Residuals QA#4147
osbornjd merged 3 commits intosPHENIX-Collaboration:masterfrom
rosstom2232:TPOTQA

Conversation

@rosstom2232
Copy link
Contributor

@rosstom2232 rosstom2232 commented Jan 30, 2026 •
edited by coderabbitai bot
Loading

comment: Adds ability to make plots in terms of local or global coordinate residuals, also adds 2D histograms showing residuals as a function of layer number, eta, and phi (Please tell us something about this pull request)

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work for users)
  • Requiring change in macros repository (Please provide links to the macros pull request in the last section)
  • I am a member of GitHub organization of sPHENIX Collaboration, EIC, or ECCE (contact Chris Pinkenburg to join)

What kind of change does this PR introduce? (Bug fix, feature, ...)

TODOs (if applicable)

Links to other PRs in macros and calibration repositories (if applicable)

Cluster State Residuals QA — Enhanced Residual Analysis

Motivation / context

  • Improve tracking QA by allowing residual plots in detector-local coordinates (sensor r-phi / z) in addition to existing global Cartesian (x/y/z) coordinates, and by adding 2D residual-vs-(layer, eta, phi) histograms to aid diagnostic and alignment studies.

Key changes

  • API & config
    • Added ResidualHistConfig fields for local (rphi_local_lower/upper, z_local_lower/upper) and global (x/y/z lower/upper) ranges.
    • New setter methods: setXRange(), setYRange(), setZRange(), setLocalRphiRange(), setLocalZRange(), and setUseLocalCoords().
    • Added m_use_local_coords flag to toggle local vs global plotting.
    • Removed previous m_xrange/m_yrange/m_zrange pair members.
  • Histograms
    • Added TH2-based histogram containers for residual correlations:
      • m_histograms_layer_{x,y,z}, m_histograms_phi_{x,y,z}, m_histograms_eta_{x,y,z}
    • createHistos() now registers either a local-coordinate histogram suite (local_rphi/local_z 1D + corresponding 2D correlations) or the global-coordinate suite (x/y/z 1D + 2D correlations) depending on m_use_local_coords.
    • Added include for TH2F.
  • Processing/robustness
    • process_event() now performs early null-checks for cluster retrieval and skips entries without clusters.
    • Residual filling split into two paths:
      • Local mode: compute residuals using state local coords and geometry.getLocalCoords(); fill local_rphi/local_z and their layer/phi/eta 2D histograms.
      • Global mode: compute residuals using state global x/y/z and geometry.getGlobalPosition(); fill x/y/z and their layer/phi/eta 2D histograms.
  • Miscellaneous
    • ~+182/-27 lines in .cc and +57/-3 in .h; no exported API removals beyond internal member changes.

Potential risk areas

  • IO / storage: increased histogram count and 2D TH2s will raise ROOT output size and memory usage during runs.
  • Reconstruction/behavior: residuals rely on geometry local/global transforms (getLocalCoords/getGlobalPosition); any geometry inaccuracies propagate to QA plots.
  • Thread-safety / concurrency: additional histogram vectors and branching increase code paths that must be safe under the framework’s threading model — confirm histo booking and fills follow framework thread-safety conventions.
  • Performance: more histograms and 2D fills may increase CPU and memory pressure for high-statistics jobs.
  • Backward-compatibility: default m_use_local_coords = false preserves previous behavior, but downstream macros or analysis expecting the old set of histo names will need updates.
  • Note of caution: AI-produced summaries can be imperfect — verify histogram types/names and coordinate transform usage in a manual code review.

Possible future improvements

  • Make bin counts and histogram selection configurable (e.g., enable/disable 2D correlations).
  • Refactor duplicate histogram creation into helper/template utilities to reduce maintenance burden.
  • Add consistency checks that selected coordinate mode matches available histograms at InitRun.
  • Consider memory-efficient histogram types (profiles or lightweight summaries) for large-scale jobs.
  • Add unit/regression tests validating local vs global residual consistency for sample events.

Note: AI-generated summaries can contain mistakes; please review code changes (histogram names/types and coordinate-transform calls) carefully before merging.

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Jan 30, 2026 •
edited
Loading

📝 Walkthrough

Walkthrough

Adds optional local-coordinate support to StateClusterResidualsQA: new m_use_local_coords flag, local rphi/z ranges, TH2 histograms, and branching in createHistos/process_event to compute and fill either local (rphi,z) or global (x,y,z) residuals; also adds cluster null-checks.

Changes

Cohort / File(s) Summary
StateClusterResidualsQA implementation
offline/QA/Tracking/StateClusterResidualsQA.cc		 Introduces branching to compute/fill residuals in local (rphi, z) vs global (x, y, z) coordinates; adds null-checks for cluster retrieval; creates and fills new TH2 histograms for local layer/phi/eta vs residuals.
StateClusterResidualsQA header
offline/QA/Tracking/StateClusterResidualsQA.h		 Adds class TH2 forward-decl, new local-range fields in ResidualHistConfig, setter methods (setX/Y/ZRange, setLocalRphi/ZRange, setUseLocalCoords), removes m_{x,y,z}range pairs, adds m_use_local_coords flag and multiple std::vector<TH2*> histogram containers for layer/phi/eta vs residuals.

Possibly related PRs

✨ Finishing touches
  • 📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

coderabbitai[bot]
coderabbitai bot reviewed Jan 30, 2026
View reviewed changes
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

@sphenix-jenkins-ci
Copy link

sphenix-jenkins-ci bot commented Jan 30, 2026

Build & test report

Report for commit 3e0b412f214ee53556cc089696ca9a543b261f64:
Jenkins on fire

Automatically generated by sPHENIX Jenkins continuous integration
sPHENIX             jenkins.io

@sphenix-jenkins-ci
Copy link

sphenix-jenkins-ci bot commented Jan 31, 2026

Build & test report

Report for commit 18821af5218bafe61ebabdf447fc29defec31d1f:
Jenkins on fire

Automatically generated by sPHENIX Jenkins continuous integration
sPHENIX             jenkins.io

@osbornjd
Copy link
Contributor

osbornjd commented Feb 2, 2026

None of these errors are related to this PR

@osbornjd osbornjd merged commit d5aeeca into sPHENIX-Collaboration:master Feb 2, 2026
19 of 22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@coderabbitai coderabbitai[bot] coderabbitai[bot] left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@rosstom2232 @osbornjd