get_satpos documentation contradicts implementation

[gerritholl]

Describe the bug

The documentation for satpy.utils.get_satpos contradicts its implementation. The documentation states:

Get satellite position from dataset attributes.

Preferences are:

• Longitude & Latitude: Nadir, actual, nominal, projection
• Altitude: Actual, nominal, projection

A warning is issued when projection values have to be used because nothing else is available.

Returns:
Geodetic longitude, latitude, altitude

Looking at the sourcecode:

satpy/satpy/utils.py

Lines 334 to 346 in 85656a8

	try:
	orb_params = dataset.attrs['orbital_parameters']
	alt = _get_sat_altitude(orb_params)
	lon, lat = _get_sat_lonlat(orb_params)
	except KeyError:
	# Legacy
	lon = dataset.attrs['satellite_longitude']
	lat = dataset.attrs['satellite_latitude']
	alt = dataset.attrs['satellite_altitude']
	return lon, lat, alt

Contradictions include:

• Documentation promises a look at the projection; this would be from the AreaDefinition? No such lookup takes place.
• Documentation promises to issue a warning if projection values are used; no warning is issued.

To Reproduce

Comparing the docstring to the implementation in the source code is perhaps enough of a "reproduction". I don't know if get_satpos is supposed to work in this example:

from satpy import Scene
from satpy.utils import get_satpos

files_nwc = ["/media/nas/x21308/scratch/NWCSAF/20211130/CTTH/S_NWC_CTTH_MSG4_MSG-N-VISIR_20211130T121500Z.nc"]
sc = Scene(filenames=files_nwc, reader="nwcsaf-geo")
sc.load(['ctth_alti'])
get_satpos(sc["ctth_alti"])

Expected behavior

I expect that documentation is consistent with implementation. Therefore, for the MCVE I would perhaps expect a warning if projection values are used. Even better would be success, but that may require a change in the nwcsaf-geo reader.

Actual results

Traceback (most recent call last):
  File "/data/gholl/checkouts/satpy/satpy/utils.py", line 335, in get_satpos
    orb_params = dataset.attrs['orbital_parameters']
KeyError: 'orbital_parameters'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/data/gholl/checkouts/protocode/mwe/no-satpos.py", line 7, in <module>
    get_satpos(sc["ctth_alti"])
  File "/data/gholl/checkouts/satpy/satpy/utils.py", line 342, in get_satpos
    lon = dataset.attrs['satellite_longitude']
KeyError: 'satellite_longitude'

Environment Info:

• OS: openSUSE 15.3
• Satpy Version: v0.31.0-156-g1b38fb86

Additional context

Ran into this when testing the parallax correction being implemented in #1904, because this needs the satellite position, which appears unavailable in NWCSAF-GEO, but — unlike the implied promise by the documentation — isn't taken from the projection either.

[sfinkens]

Thanks for reporting @gerritholl ! The satellite position is obtained from the orbital_parameters dictionary in the dataset attributes, see https://satpy.readthedocs.io/en/stable/readers.html#metadata. If the reader provides that information, you should see the warnings. As for the bad error reporting, this is fixed by #1925 .