Clarify documentation of orbital_parameters metadata

[sfinkens]

Clarify documentation of orbital_parameters metadata, as discussed in #922. I also checked the altitude units in abi_l1b, ahi_hsd, goes_imager*, hrit_jma, seviri_l1b* and electrol_hrit. Except for abi_l1b which is in km, they are all in meters. So I changed the units to meters in abi_l1b. Not sure how many users would be affected by this change. If a lot, I could instead add a user warning that the units will be changed in the next release or so.

• Closes Clarify orbital_parameters metadata #922
• Tests added and test suite added to parent suite
• Tests passed
• Passes flake8 satpy
• Fully documented

[djhoese]

Nice job. Commented on a few typos but otherwise I have one main question/point:

I just merged the AMI reader where I made satellite_actual_altitude to be in kilometers. This is likely because I was matching ABI's reader. From what I could tell though this needed to be this way for pyorbital to work correctly in the composites (for generating angles). Could you merge with master (if you don't already have the AMI reader) and fix the kilometer conversion? Could you also verify that pyorbital's angle generation code in the compositors doesn't need kilometers?

[coveralls]

Coverage increased (+0.1%) to 86.06% when pulling 294be54 on sfinkens:doc-orbital-parameters into e40961e on pytroll:master.

[codecov]

Codecov Report

Merging #950 into master will increase coverage by 0.12%.
The diff coverage is 97.1%.

@@            Coverage Diff             @@
##           master     #950      +/-   ##
==========================================
+ Coverage   85.92%   86.05%   +0.12%     
==========================================
  Files         174      174              
  Lines       26452    26520      +68     
==========================================
+ Hits        22730    22822      +92     
+ Misses       3722     3698      -24

Impacted Files	Coverage Δ
satpy/composites/__init__.py	78.4% <ø> (+3.31%)	⬆️
satpy/readers/abi_l1b.py	98.3% <ø> (ø)	⬆️
satpy/tests/reader_tests/test_ami_l1b.py	94.73% <ø> (ø)	⬆️
satpy/tests/reader_tests/test_abi_l1b.py	96.36% <ø> (ø)	⬆️
satpy/readers/ami_l1b.py	97.32% <ø> (ø)	⬆️
satpy/tests/compositor_tests/__init__.py	99.57% <100%> (+0.02%)	⬆️
satpy/composites/viirs.py	83.78% <100%> (+0.07%)	⬆️
satpy/tests/compositor_tests/test_viirs.py	98.71% <92.3%> (-0.59%)	⬇️
satpy/scene.py	90.35% <0%> (-0.18%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e40961e...294be54. Read the comment docs.

[sfinkens]

@djhoese @martin I updated the AMI reader and the compositors. Two things I'm not sure about:

• The VIIRS compositor uses attrs['satellite_altitude'], but none of the VIIRS readers defines that attribute.
• I don't have much experience with the LEO readers. Do they usually provide altitude in meters or kilometers?

[djhoese]

1. Which VIIRS compositor?
2. I've never needed to use the orbit parameters for a polar instrument since they typically provide the angles in their data files (and that's all I have ever needed).

[sfinkens]

Sorry not very precise. I meant satpy.composites.viirs.ReflectanceCorrector.get_angles

[djhoese]

I think this was copied from the older version of the pyspectral rayleigh corrector. I think this class is meant as an option for VIIRS/MODIS rayleigh correction (it is what my Polar2Grid project uses), but we also played around with it for ABI/AHI (as a test for my Geo2Grid software). So the get_angles there should match whatever ABI/AHI would have. In normal cases get_angles should not be called when processing VIIRS or MODIS data.

Only other thing I could think of would be the VIIRS compact reader if they don't include the angles in the data files.

[sfinkens]

@djhoese Ok, thanks for the explanation! I've updated viirs.ReflectanceCorrector.get_angles to match ABI/AHI, i.e. expect meters and convert them to kilometers in the get_observer_look call. Could you please try with real ABI data and see if the results are correct?

[sfinkens]

Nevermind, I'll do that. Then I learn something about composites.

[sfinkens]

Ok, I checked the true_color_crefl ABI composite before/after and they are identical 🙂

[mraspaud]

Just one more line :)