[Bug]: NISAR GSLC: wavelength not auto-detected, and NISAR_L_FREQUENCY constant is incorrect

[Dani-Lindsay]

Checked for duplicates

Yes - I've already checked

Describe the bug

When processing NISAR GSLC files without manually setting wavelength in input_options, dolphin silently outputs displacement in radians instead of metres. The existing auto-detection in model_post_init only handles OPERA-S1 (via get_burst_id). NISAR filenames don't match that pattern so it falls through with no warning.

There is also a related bug in constants.py: NISAR_L_FREQUENCY = 1.25e9 is a rounded value that gives a wavelength of 0.23983 m, whereas the correct NISAR L-band centre frequency gives ~0.23840 m (~1.4 mm error, ~0.6%). Note that UAVSAR_WAVELENGTH = 0.238403545 in the same file is already correct — NISAR and UAVSAR share the same L-band frequency.

NISAR GSLC HDF5 files store the mission and radar band under:
science/LSAR/identification/missionId -> b'NISAR'
science/LSAR/identification/radarBand -> b'L'

These fields are present in all tested GSLC products. Since h5py is already a dolphin dependency, a fix requires no new requirements.

Proposed addition to model_post_init in dolphin/workflows/config/_displacement.py, after the existing S1 block:

if self.input_options.wavelength is None and self.cslc_file_list:
    try:
        import h5py

        with h5py.File(self.cslc_file_list[0], "r") as hf:
            ident = hf.get("science/LSAR/identification")
            if ident is not None:
                mission = ident.get("missionId")
                band = ident.get("radarBand")
                if mission is not None and band is not None:
                    mission_str = mission[()].decode().upper()
                    band_str = band[()].decode().upper()
                    if mission_str == "NISAR":
                        if band_str == "L":
                            self.input_options.wavelength = constants.NISAR_L_WAVELENGTH
                        elif band_str == "S":
                            self.input_options.wavelength = constants.NISAR_S_WAVELENGTH
    except Exception:
        pass

And in dolphin/constants.py:

# change from:
NISAR_L_FREQUENCY = 1.25e9

# to:
NISAR_L_FREQUENCY = 1_257_476_312  # actual L-band centre frequency (same as UAVSAR)

Happy to put up a PR for both if useful — the changes are small and self-contained.

What did you expect?

I expected Dolphin to auto-detect the NISAR L-band wavelength from the file metadata and output displacement in metres, consistent with the behaviour for OPERA-S1.

Reproducible steps

1. Download any NISAR GSLC product (tested on v1.4.0 beta, productSpecificationVersion 1.4.0)
2. Run `dolphin config` without setting `--wavelength`
3. Run `dolphin run` — timeseries outputs are in radians, not metres

Environment

dolphin version: 0.42.5

Python deps:
        h5py: 3.16.0
         jax: 0.7.1
       numba: 0.64.0
       numpy: 1.26.4
 opera-utils: 0.25.6
    pydantic: 2.12.5
      pyproj: 3.7.2
    rasterio: 1.5.0
 ruamel_yaml: None
       scipy: 1.12.0
      snaphu: 0.4.1
threadpoolctl: 3.6.0
        tqdm: 4.67.3
        tyro: 1.0.10
  osgeo.gdal: 3.12.2

System:
      python: 3.12.13 | packaged by conda-forge
  executable: /Users/dlindsay/miniforge3/envs/dolphin-env/bin/python
     machine: macOS-26.3.1-arm64-arm-64bit

Unwrapping packages:
      snaphu: 0.4.1
       isce3: 0.25.8

[scottstanie]

Thanks for the report!

• agreed that wavelength should be updated to be exact
• the current "sniff test" for the opera CSLC S1 uses filenames rather than opening/checking the hdf5 structure:

        if self.input_options.wavelength is None and self.cslc_file_list:
            # Try to infer the wavelength from filenames
            try:
                get_burst_id(self.cslc_file_list[-1])
                # The Burst ID was recognized for OPERA-S1 SLCs: use S1 wavelength
                self.input_options.wavelength = constants.SENTINEL_1_WAVELENGTH
            except ValueError:
                pass

so maybe we could do a similar regex for NISAR L band files using the opera-utils logic, which was updated more recently.

(does the S-band data have distinct filenaming? or was the check for the band just for the datasets that have both L and S?)

[EJFielding]

Note that the NISAR center frequency will be different for different modes. The NISAR L-band 20+5 MHz and 40+5 MHz modes have different center frequencies, so you should get the wavelength from the metadata, as the PR above does.

[s-sasaki-earthsea-wizard]

I went and measured this against real products, because both proposals on the table are testable and I had the Earthdata access set up anyway.

@Dani-Lindsay — you offered to put up a PR for this back in May; I don't want to step on that. If you're still on it, everything below is yours to use. If you've moved on, I'm happy to take it.

What I did

I took the NISAR_L2_GSLC_BETA_V1 collection (~23k granules) and picked one granule per distinct (mode, polarization) configuration in it — 13 granules, 22 frequency sub-bands. For each I read /science/LSAR/GSLC/grids/frequency{A,B}/centerFrequency and derived c / centerFrequency.

Nothing was downloaded: these are ~22 GB each, but HDF5 byte-range reads over HTTPS pull only the metadata, a couple of minutes for the whole run. I deliberately went through opera_utils._remote.open_h5 — the same call dolphin.io._core.read_nisar_grid_metadata already uses for remote NISAR HDF5 — so this measures what dolphin itself would see.

What's in the products

Collapsed by mode (the full 22-row table, the granule IDs, and a make validate that reproduces it are linked at the bottom):

mode	frequencyA	frequencyB
0005	absent	1221.5 MHz → 0.245429765 m
0505	1221.5 MHz → 0.245429765 m	1236.5 MHz → 0.242452453 m
2005	1229.0 MHz → 0.243932024 m	1293.5 MHz → 0.231768425 m
4005	1239.0 MHz → 0.241963243 m	1293.5 MHz → 0.231768425 m
7700	1257.5 MHz → 0.238403545 m	absent

Six distinct centre frequencies. Wavelengths span 0.2318–0.2454 m — a spread of 13.7 mm, about 5.9% of a wavelength. @EJFielding's point holds, and it's bigger than the ~1.4 mm the issue was originally about.

Three things follow:

The constant fix doesn't survive contact with the data. UAVSAR_WAVELENGTH (0.238403545 m) is exact for exactly 1 of the 22 sub-bands — mode 7700 frequencyA. Everywhere else it's off by up to 7.0 mm. That's worse than the current 1.25e9 for several configurations (e.g. 4005 frequencyA: current constant is off by 2.1 mm, the UAVSAR value by 3.6 mm). So changing the constant would fix the stated 1.4 mm error in one mode and regress others — I'd suggest dropping that half of the proposal.

The filename regex can't get there either — though not for the reason I first assumed. The mode field is in the SDS granule name, and within this sample each mode does map to a consistent pair of centre frequencies, so a mode-keyed table isn't nonsense on its face. But most products carry both frequencyA and frequencyB with different centre frequencies in the same file, and which one applies is decided by dolphin's subdataset setting, not by anything in the filename. A regex can at best tell you the pair; it can't tell you which half you're reading. It would also mean hardcoding an undocumented mapping that has to track SDS changes, to approximate a number the product already states exactly.

frequencyA can't be assumed to exist. Mode 0005 ships frequencyB only. identification/listOfFrequencies is the authoritative list.

What I'd propose instead

Read centerFrequency from the same frequency group the configured subdataset points at, and set input_options.wavelength from it.

The nice part is that dolphin already does exactly this shape of thing: read_nisar_grid_metadata opens the GSLC with h5py and reads siblings of the subdataset's parent group (xCoordinates, yCoordinateSpacing, the grid_mapping attr…). centerFrequency is one more sibling in that same group, so this rides on machinery that's already there rather than adding a new concept. It's exact for every mode, present and future, and needs no new dependency.

Falling back to the existing behaviour (leave wavelength as None, i.e. radians) if the field is missing keeps it conservative.

Two things I'd want your call on before writing it:

1. What happens to NISAR_L_FREQUENCY / NISAR_S_FREQUENCY? They're currently unreferenced anywhere in src/. Delete them, or keep them as a last-resort fallback? Given the measurements I lean toward deleting — a constant that's wrong in every observed configuration seems worse than no constant — but that's a judgement call about your users.
2. Where should the read live? model_post_init in _displacement.py (mirroring the S1 block) is the obvious spot, but it would mean config validation opens an HDF5 file, which it doesn't do today. Happy to put it wherever you'd rather have it.

If this direction looks right, I'm glad to put up the PR.

Reproducing

Harness, full 22-row table, and the granule list, pinned at the commit that produced these numbers:

• report: https://github.com/s-sasaki-earthsea-wizard/dolphin-nisar-sample/blob/3cc28a7b9835c7d2197b924143b1ca6ca1746650/reports/center_frequency.md
• granule list + selection rule: https://github.com/s-sasaki-earthsea-wizard/dolphin-nisar-sample/blob/3cc28a7b9835c7d2197b924143b1ca6ca1746650/granules.json
• repo: https://github.com/s-sasaki-earthsea-wizard/dolphin-nisar-sample/tree/3cc28a7b9835c7d2197b924143b1ca6ca1746650

make validate PYTHON=/path/to/your/dolphin-env/bin/python re-runs the measurements against your own environment (needs Earthdata Login in ~/.netrc, mode 0600 — Python's netrc module silently refuses anything more permissive, which curl doesn't care about). make render rebuilds the table from the saved JSON with no network and no credentials at all.

Measured with opera-utils 0.25.8, h5py 3.16.0, Python 3.12.3.

[Dani-Lindsay]

@s-sasaki-earthsea-wizard you go for it! :)

[scottstanie]

@s-sasaki-earthsea-wizard you might want to check how it's handled/if it makes more sense to adapt https://github.com/opera-adt/opera-utils/ , which already holds a lot of the logic for interpreting/parsing metadata for S1 and NISAR

[s-sasaki-earthsea-wizard]

Good call — I went through opera-utils (0.25.8, and current main) before writing anything. Summary of what's there and what isn't:

• opera_utils.nisar.GslcProduct already has most of the machinery: _open() goes through _remote.open_h5, which transparently handles local paths and HTTPS/S3 URLs, and get_available_frequencies() / get_available_polarizations() already probe the grids/frequency{A,B} groups.
• But nothing reads centerFrequency (zero hits package-wide). The only wavelength reader, get_radar_wavelength, is hardwired to the OPERA CSLC-S1 layout (/metadata/processing_information/input_burst_metadata/wavelength) and raises KeyError on a NISAR GSLC.
• constants.SPEED_OF_LIGHT is defined but currently unreferenced — so the wavelength derivation slots in naturally.
• The filename side can't help: NISAR_SDS_FILE_REGEX captures the bandwidth/configuration code (4005 etc.), but that code is not itself a center frequency — consistent with what I measured (six distinct center frequencies across configurations, and the two sub-bands differing within one file).

So I'd propose splitting this into two small PRs:

opera-utils: add the reader to the opera_utils.nisar package — something like get_nisar_wavelength(filename, subdataset) (naming yours to call), which resolves the grids/frequency{A|B} group from the subdataset path, reads centerFrequency, and returns the wavelength via SPEED_OF_LIGHT, plus a thin delegating method on GslcProduct. Keeping the frequency-group interpretation inside opera-utils seems like the point of consolidating there. Pure addition, no existing API touched; works for local files and remote URLs alike since it rides on open_h5 / _open().

dolphin: in model_post_init, after the existing S1 block, call that function for NISAR inputs. One nice property: dolphin's input_options.subdataset is the full dataset path (/science/LSAR/GSLC/grids/frequencyA/HH), so it already names exactly which frequency group applies — the A/B ambiguity I raised above disappears entirely. A user-supplied wavelength always wins and skips the file read, as today.

Two design points I'd like your read on:

1. Failure behavior. The current S1 sniff falls through silently, and my first instinct was to mirror that (leave wavelength = None → radians). But the original report here is precisely "silent radians output", so for files we've already identified as NISAR GSLC, I lean toward raising a contextual ValueError when centerFrequency is missing or invalid (non-scalar, non-finite, ≤ 0) rather than quietly reverting to radians — catching those specific cases, not a blanket except. Happy to go either way — it's your users' workflows that would see the error.

2. Stack consistency. The center frequency varies by acquisition configuration, so using the first file's value assumes the whole stack shares one. Options, roughly in order of cost: (a) read the scalar from every file at config time — exact, but unappealing for large remote stacks; (b) compare the filename configuration codes across the stack (free, no I/O) and read the metadata from one representative file — though this is conservative: e.g. codes 2005 and 4005 share the same frequencyB center frequency (1293.5 MHz), so a mixed stack can be physically consistent yet fail the filename check; (c) use the first file, document the single-configuration assumption, and leave validation to a follow-up issue. I don't have a strong preference — which fits dolphin's config-time philosophy best?

On my earlier question about NISAR_L_FREQUENCY / NISAR_S_FREQUENCY: since they're importable from dolphin.constants, I'd now simply leave them in place for compatibility and stop using them for auto-detection; whether to deprecate/remove them can be handled separately.

Sequencing: opera-utils PR first; once it's merged/released, the dolphin PR bumps the opera-utils>= floor and wires it up. Test matrix I have in mind: local + remote (mocked/cassette-based — no live Earthdata dependency in CI), frequencyA/B, the B-only mode-0005 product, explicit-wavelength precedence, bad subdataset, missing/invalid centerFrequency.

If that split sounds right I'll open the opera-utils PR first.

Disclosure: These investigations were assisted by AI agents - Claude Opus 4.8, Fable 5 (Anthropic), GPT-5.6 Sol (OpenAI).

[s-sasaki-earthsea-wizard]

Opened opera-adt/opera-utils#225, which adds the reader we discussed:
get_nisar_wavelength(filename, subdataset) plus a
GslcProduct.get_wavelength(frequency=...) convenience method.

One thing that pushed me away from the filename-regex approach: I probed the
real products, and a filename/constant lookup can't be made exact. Across the
NISAR_L2_GSLC_BETA_V1 collection there are six distinct centerFrequency
values (1221.5, 1229.0, 1236.5, 1239.0, 1257.5, 1293.5 MHz — a ~13.7 mm
wavelength spread), and many granules carry both frequencyA and
frequencyB with two different center frequencies in one file. So the reader
reads centerFrequency out of the frequency group named by the subdataset
being processed, which also makes it exact for whichever sub-band is actually in
use. Measurements (reproducible, remote byte-range reads, no bulk download):
https://github.com/s-sasaki-earthsea-wizard/dolphin-nisar-sample/blob/3e3d025958448ff8ce646338426973666d64d1a6/reports/wavelength_validation.md

On your S-band question: since the group is located from the subdataset path
(.../LSAR/... vs .../SSAR/...), the reader never has to infer the band from
the filename at all — it's band-agnostic by construction.

One open API-policy question is noted in the PR description (raise vs. return
None when a requested sub-band is genuinely absent); happy to take direction
there either on the PR or here.