Ultra l1b extended spin voltage cull

[lacoak21]

Change Summary

Overview

Add low voltage flags to l1b goodtimes / extendedspin. Use this in l1c psets to reject events at spins dependent on energy.

This makes the current goodtimes configuration a little tricky because the code was only set up to really cull spins across all energies. To remedy this, I just added energy dependent flags to the goodtimes dataset without culling full spins. Then at l1c, we can toss out events at spins that are flagged if the flag is for the energy of the event.

The low voltage cull is only dependent on spins and not energy but I added the frame work for culling dependent on energy bins for future algorithms.

Bob specifically wants us to be able to cull bins of spins and energy configurable with constants.

closes #2709

FIle changes

See copilot below

Tests for new functions including validation test that uses bobs code

[demajistre]

I'm hoping that you see the comments that I left referencing the code

[Copilot]

Pull request overview

This pull request implements extended spin voltage culling for ULTRA L1B data processing. The changes introduce energy and spin-dependent event rejection based on quality flags, including low voltage detection, and integrate this functionality into the L1C pointing set calculation pipeline.

Changes:

• Added energy and spin-dependent culling functions to filter events based on voltage thresholds and energy bin flags
• Integrated status dataset processing into L1B extended spin calculations
• Updated L1C spacecraft and helio pointing set calculations to apply new rejection masks

Reviewed changes

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

Show a summary per file

File	Description
imap_processing/ultra/l1b/ultra_l1b_culling.py	Added functions for low voltage flagging, energy bin grouping, and energy/spin-dependent rejection masking
imap_processing/ultra/l1b/extendedspin.py	Integrated voltage quality flagging and energy bin flag calculations into extended spin processing
imap_processing/ultra/l1c/spacecraft_pset.py	Applied new rejection filters before calculating spacecraft pointing sets
imap_processing/ultra/l1c/helio_pset.py	Applied new rejection filters before calculating heliosphere pointing sets
imap_processing/ultra/l1b/goodtimes.py	Added quality_low_voltage, quality_high_energy, and quality_statistics fields to goodtimes dataset
imap_processing/ultra/l1b/ultra_l1b.py	Added status dataset requirement for extended spin calculations
imap_processing/ultra/utils/ultra_l1_utils.py	Added handling for energy_bin_flags with energy_bins_for_culling dimension
imap_processing/ultra/constants.py	Added culling parameters (voltage threshold, spin bin size, energy bin grouping)
imap_processing/ultra/l1c/l1c_lookup_utils.py	Removed informational logging statement from build_energy_bins
imap_processing/tests/ultra/unit/*.py	Updated tests to include status dataset and mock goodtimes dataset, added tests for new culling functions
imap_processing/tests/ultra/unit/conftest.py	Added mock_goodtimes_dataset fixture and status_dataset fixture

---

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

[subagonsouth]

Overall, this looks good. There is lots going on here and I am missing some high level context but I don't see anything glaring.

[subagonsouth]

I think that all of this could be made a bit more efficient by filtering the dataframe first then extracting the values.

spin_df = spin_df[spin_df.spin_number.isin(spins)]
spin_period = spin_df["spin_period_sec"].values
spin_starttime = spin_df["spin_start_met"].values
spin_phase_valid = spin_df["spin_phase_valid"].values
spin_period_valid = spin_df["spin_period_valid"].values

[subagonsouth]

I'm not sure if this matters here, but on Hi, I had an issue where there were small gaps or overlap of spins because I was using spin_start_met + spin_period to define a spin. That is never identically equal to the next spin_start_met. So, here, I think you could have a small gap in your final edge and what would be the next starting edge.