(RSLC) RFI tone-rank: Variable group names hinder programmatic access

Overview

PR #257 introduced a new RFI diagnostic output group in the RSLC HDF5 product at /science/LSAR/RSLC/metadata/RFI/. This output is only generated when using the tone-rank RFI mitigation algorithm.

The new RFI HDF5 group is then further broken down, following the format /science/LSAR/RSLC/metadata/RFI/frequency<freq>/<pol>/rawXXXXX/..
For example: /science/LSAR/RSLC/metadata/RFI/frequencyA/HH/raw82226/..

The new datasets include:

• ../rawXXXXX/nativeDopplerTime - Raw data slow-time midpoint of each analysis block (seconds)
• ../rawXXXXX/slantRange - Raw data slant range midpoint of each analysis block (meters)
• ../rawXXXXX/frequency - Frequency axis for hitCount (Hz)
• ../rawXXXXX/signalMean - Estimated mean signal power per block (DN²)
• ../rawXXXXX/hitCount - Fraction of pulses with detected RFI at each frequency bin (0-1)
• ../rawXXXXX/interferenceSignalRatio - Interference-to-signal ratio (DN²/DN²)

I wasn't involved in the original review nor discussions about this feature, and have some questions about the design and long-term maintainability of this structure, particularly around group naming conventions, programmatic discoverability, and product specifications.

Questions and Observations

1. Algorithm-Specific Diagnostic Output

Observation: The RFI diagnostic group is only created when using the tone-rank algorithm. It is not generated for other RFI mitigation options (st-evd or fdnf).

Code Reference: focus.py:2096-2098

# Only write rich HDF5 for tone-rank
(rfi_results_h5.require_group(f"raw{raw_times[0]:05.0f}")
    if using_tone_rank else None),

Questions:

• Was this choice intentional to provide richer diagnostics specifically for tone-rank, or is this a temporary implementation with plans to add similar diagnostics for other algorithms?
• Is the algorithm-specific presence (and absence) of groups acceptable from a spec perspective, or should we aim for a more uniform structure across algorithms?

2. Variable Group Names Based on Pulse Time

Observation: The group name uses a variable naming convention (e.g., raw82226, raw12345) where the number represents (please confirm!) the first pulse time in seconds since epoch, formatted as a 5-digit integer with zero-padding.

Code Reference: focus.py:2097

rfi_results_h5.require_group(f"raw{raw_times[0]:05.0f}")

Where raw_times[0] is the first element of the pulse time array (in seconds since orbit/grid epoch) for the current processing block after slicing to the processing window.

Concrete examples showing variable group names across products:

Example 1: NISAR_L1_PR_RSLC_012_097_D_106_2005_DHDH_A_20260208T225030_20260208T225100_X05016_N_F_J_001.h5

• Contains: /science/LSAR/RSLC/metadata/RFI/frequencyA/HH/raw82226/

Example 2: NISAR_L1_PR_RSLC_009_148_A_024_2005_DHDH_M_20260107T105830_20260107T105839_X05016_P_P_J_001.h5

• Contains: /science/LSAR/RSLC/metadata/RFI/frequencyA/HH/raw39506/
• And also: /science/LSAR/RSLC/metadata/RFI/frequencyA/HH/raw39508/

Each product has different group names, and products with multiple L0B inputs have multiple groups.

Questions:

• What motivated encoding the pulse time directly in the group name? Is there a specific use case this design serves?
• Was this intended as a temporary solution or the long-term approach?
• For users building automated tools (trending, validation, etc.), what's the recommended way to discover and parse these variable group names?
• Are there recommendations for comparing single source vs. mixed mode granules?

3. Product Specification Documentation

Observation: The new HDF5 groups and metadata introduced in PR #257 are not yet documented in the PIX XML specifications.

Questions:

• Are there plans to add these groups to the PIX specs?
• If so, what is the timeline in mind?
• Are there spec considerations we should be thinking about (e.g., optional vs. required groups, variably-named groups)?

4. Discoverability and User Experience

Observation: The current naming convention of rawXXXXX is variable and undocumented for new users.

Questions:

• What's the recommended way for users to understand what 82226 represents? Should this be documented in group attributes or external documentation?
• For users building tools or doing analysis, how should they discover these groups? Should they scan (regex) for all groups matching the raw***** pattern?
• Are there use cases where having the pulse time in the group name is particularly valuable?
• Is there an alternative where the group name could be fixed (like rrsd_000 and rrsd_001, or l0b_000 etc.) with pulse time stored as an attribute?
  • Or, does the current approach have advantages that aren't immediately apparent to me?

Questions for working with RSLCs with multiple input L0Bs:

• For trending or comparison across products, how should a user approach e.g. comparing an RSLC with multiple input L0Bs vs. an RSLC with one single-source input L0B?
• In granules with multiple raw* groups, should these groups be concatenated, analyzed separately, or aggregated in some other way?
• Would it be valuable to have a single aggregated group per polarization that combines data from all raw sources, with an additional dimension or dataset to track the source/timing?
• Is there metadata we could add (as attributes) to help tools understand the relationship between multiple raw* groups in the same product?

Summary

PR #257 included important RFI diagnostic capabilities for the tone-rank algorithm; the questions raised here focus on ensuring these outputs can be effectively utilized by downstream systems and meet product specification requirements. These questions aim to clarify the design intent and identify any areas where additional documentation, standardization, or tooling guidance might be beneficial.

Key areas for discussion:

• Group naming conventions and their implications for programmatic access
• Product specification documentation and compliance
• Guidance for developers building validation, trending, or analysis tools
• Whether the current implementation represents the intended long-term design

cc: @hfattahi @bhawkins @hb6688 @Tyler-g-hudson @rad-eng-59