ULTRA l1b High Energy (SEP) culling

[lacoak21]

Change Summary

closes #2711

Overview

This PR adds a quality flag array to the ULTRA L1B extended spin and goodtimes CDF. The new quality flag array indicates spins and energy ranges that should be removed due to high energy events.
First, valid events are selected based on other flags and criteria at each energy range. Then, using the selected "culling energy channel" — the channel with the highest energy events, identified by the ULTRA IT team — entire groups of spins are flagged. The culling energy channel is shown to be correlated with SEPs in other channels, so it can be used to cull contaminated spins. Each energy channel has its own threshold, also provided by the ULTRA IT team. The counts at each spin bin for the culling channel are calculated, and then for each energy bin, if the counts exceed the energy threshold, that spin bin is flagged at that energy range.

These flags will be used to cull spins at l1c.

File changes

• imap_processing/ultra/constants.py
  • Add necessary culling constants
• imap_processing/ultra/l1b/extendedspin.py
  • Remove low voltage events from the DE dataset and then calculate the high energy quality flags
• imap_processing/ultra/l1b/ultra_l1b_culling.py
  • Add function to flag high energy events
  • Add function to get valid events for each energy range

Testing

Add basic testing and a validation test. The validation files were computed using Bob Demajistre's code.

[Copilot]

Pull request overview

This PR adds high energy (SEP) culling functionality to the ULTRA L1B extended spin processing. The implementation identifies spins contaminated by Solar Energetic Particles (SEPs) by monitoring counts in a designated "culling energy channel" and flagging entire spin groups when counts exceed energy-specific thresholds. The quality flags are stored in the L1B CDF files for use in L1C processing.

Changes:

• Added high energy culling constants (thresholds, culling channel) to constants.py
• Implemented flag_high_energy and get_valid_events_per_energy_range functions in ultra_l1b_culling.py
• Integrated high energy flagging into extendedspin.py with voltage-based event filtering
• Added comprehensive unit tests and validation tests

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 8 comments.

File	Description
imap_processing/ultra/constants.py	Added HIGH_ENERGY_CULL_THRESHOLDS and HIGH_ENERGY_CULL_CHANNEL constants
imap_processing/ultra/l1b/ultra_l1b_culling.py	Implemented high energy event flagging logic and valid event filtering; renamed get_binned_energy_range_flags to get_energy_range_flags
imap_processing/ultra/l1b/extendedspin.py	Integrated high energy flagging with low voltage filtering
imap_processing/tests/ultra/unit/test_ultra_l1b_culling.py	Added unit tests and validation test for high energy culling

---

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

[subagonsouth]

I had a hard time finding anything to comment on. This all looks good to me!