search

robintw / Py6S

A Python interface to the 6S Radiative Transfer Model
GNU Lesser General Public License v3.0
186 stars 105 forks source link

Typo in description of apparent reflectance (?) #95

Closed AserMata closed 2 years ago

AserMata commented 2 years ago

It has been a few years since the last time I used Py6S and now that I revisited, I was trying to remember the difference between "apparent_reflectance" and "pixel_reflectance". Looking at the code to find an answer I read: https://github.com/robintw/Py6S/blob/cf263682836b5f1371564b2814be97db174326da/Py6S/outputs.py#L168

Surely if it is reflectance should be adimensional? The line just before is "apparent_radiance" so I guess this is a typo.

robintw commented 2 years ago

Thanks for raising this, but actually this isn't a mistake - it's just a legacy design choice that makes it look incorrect.

This big dictionary defines how to extract information from the 6S output file (it doesn't define what these outputs are - that's defined by 6S - just where to find them). The key of the dictionary is the text to search for in the output file, and the value of the dictionary (a tuple) gives information on how to extract the value (whether it is on the same line as the text to search for or not, what to call it, what type to convert it to etc). You can't have multiple entries in a dictionary with the same key, so when we want to extract two entries from the same line, we have to give slightly different strings to search for. You can see this a few lines later where we search for "rad at satel. level" and then "rad at satel. level (w/m2/". They will both find the same line, and then the configuration in the tuple explains how to extract the data from that line.

Therefore, the two lines that you were looking at say to search for "appar. rad.(w/m2/sr/mic)" and extract the 2nd entry in the line, and store it as apparent_reflectance, and then search for basically the same text "appar. rad." and extract the 5th entry in the line and store it as apparent_radiance.

Yes, it would have been more easily understandable to be searching for the term apparent reflectance in the one for reflectance - but in the end it finds the same line so it works. There may have been a reason for doing it this way (maybe the term apparent reflectance appears elsewhere in the file and could find the wrong line?) or I may have just done it weirdly for some strange reason many years ago.

Hope that makes sense.

AserMata commented 2 years ago

Hi Robin,

Thanks for looking into this. I was not sure what was the best way to raise this issue so I hope opening the issue in github was a good idea (and not bothersome for the lack of a better word).

I understand then. No problem with the settings chosen for the python dictionary and how the outputs are extracted. I was mostly trying to understand the physics of the outputs. I thought the apparent reflectance in the outputs should give the Top Of Atmosphere reflectance but not entirely sure what is the pixel reflectance. I was doing some tests with apparent reflectance and different AOT and angles for a given ground reflectance and the outputs seem to match nicely the ground reflectance making me think it was modelling instead the BOA reflectance? Let me know if this makes sense and happy to discuss somewhere else if you prefer.

robintw commented 2 years ago

apparent_reflectance should be the TOA reflectance, and I think pixel_reflectance is the reflectance of the pixel in question, without irradiance reflected in from adjacent areas (eg. if you use the HeterogeneousLambertian ground reflectance profile). The full equations are in the 6S manual.

AserMata commented 2 years ago

Thanks Robin. I was indeed looking at the manual and the equations. That is fine, no problem there so I thought I was missing something in the code and that is why I went over the documentation and opened this issue.

My bad is that I was simplifying my inputs as much as possible with all angles 0, (lat,lon=0,0) and using a given in situ ground reflectance (GR) as HomogeneousLambertian(GR) and introducing maritime aero profile and AOT550. I was surprised that apparent_reflectance was matching nicely the GR but pixel_reflectance was the same shape but only a fraction (which now with your latest comment I understand my bad). Very sorry that I dragged this a bit too much.