Improve documentation for make_rgb_lupton

[astrofrog]

I tried using the make_rgb_lupton on a set of 2MASS images for the Galactic center:

import numpy as np
from astropy.visualization import make_lupton_rgb
from astropy.utils.data import get_pkg_data_filename
from astropy.io import fits

image_r = fits.getdata(get_pkg_data_filename('galactic_center/gc_2mass_k.fits'))
image_g = fits.getdata(get_pkg_data_filename('galactic_center/gc_2mass_h.fits'))
image_b = fits.getdata(get_pkg_data_filename('galactic_center/gc_2mass_j.fits'))

image = make_lupton_rgb(image_r, image_g, image_b, filename='galactic_center_default.png')

and get the following result:

That's... a lot of yellow....

I cannot figure out how to make this look like a normal star field, and the documentation doesn't explain how to tune the parameters to get a good result. It would be nice to have more extensive documentation to show the effect different parameters have.

@parejkoj - on a shorter timescale, can you explain how to optimize the example above so that I have a better idea how this work?

Where does the algorithm perform best - not so dense star fields?

Is the issue the minimum values and if so should we have better defaults? (for example percentile-based)

[parejkoj]

Can you post the images you used? Are they all on the same flux scale?

[astrofrog]

@parejkoj - yes they are on the same scale. The images are on http://data.astropy.org (just go there and download the three 2mass ones)

[parejkoj]

The background levels in those three images are quite different: j-band background is ~150, others are ~500. That's where the difference is coming from.

[astrofrog]

@parejkoj - would it make sense to default minimum to the actual minimum in the arrays rather than zero?

[parejkoj]

What does "actual minimum in the arrays" mean in this context? Setting minimum=147 doesn't help.

[parejkoj]

Also, are those images co-aligned?

[parejkoj]

Sorry, I just answered my own question: yes, they are co-aligned.

[astrofrog]

@parejkoj - yes the images are co-aligned. What I mean by minimum is we could set it to e.g. minimum=(np.min(r), np.min(g), np.min(b)) by default (but I don't feel strongly about it, just an idea). It helps a little but not perfect (maybe it's just not the kind of image that would benefit from this algorithm)

[parejkoj]

Given the different backgrounds and overall flux levels, combining those images is going to be tricky. I tried subtracting 300 from r and g (k and h), but that only helps a little.

[parejkoj]

That's not a terrible idea. Let me see what using an "all array minimum" looks like on my SDSS example data.

[astrofrog]

I think my main request (and probably there won't be time before 1.3, but maybe for 1.3.1) would be to have some narrative docs that explain these kinds of issues and mention how the best results can be obtained.

If we do the change in the minimum thing, maybe np.nanmin would be more sensible.

[parejkoj]

I've only ever used it on well-behaved--usually optical--data, where the backgrounds are similar, so the tricks for making it work on other things would have to be something we work out. I agree that having such docs would be handy.

[parejkoj]

Ok, I just tried putting in image minimums, and it definitely looks worse on well-behaved SDSS data.

[parejkoj]

(after giving up on the IPAC data interface and discovering the SDSS provides a better 2MASS image browser than 2MASS does...): It looks like SDSS made 3-color 2MASS images that are fairly reasonable. You can find them on skyserver: put ra=266.4 and dec=-28.933 in the boxes, and click the 2MASS button on top. That can be what we aim to reproduce.

[parejkoj]

Where did those galactic center 2mass data come from originally? I wonder if this is just a "feature" of 2mass data, or if there was something particular about how this data was processed?

[hamogu]

If going this route, np.nanmin is clearly better than np.min. I don't know any details of the lupton algorithm (so I don't know if it takes care of the following already through some means), but when making images, I generally have better results with np.percentile(1) and resetting all values below the 1-percentile to the new minimum. Sometimes images have hot pixels that are oversubtracted giving you a small number of pixels with very low (sometimes negative) values.

[eteq]

@astrofrog @parejkoj I want to reiterate my suggestion from #5570 : I think this function doesn't necessarily need a lot of narrative docs in astropy proper, but this is a perfect case to write a tutorial that promotes use of proper packages in the proper places. Photutils has a bunch of algorithms for estimating the background level of an image and subtracting it (https://photutils.readthedocs.io/en/stable/photutils/background.html). So my suggested workflow would be:

1. Download the image from somewhere, maybe using astroquery
2. reproject it onto a common frame using reproject
3. Use photutils to subtract off the background
4. Use make_lupton_rgb to generate the final RGB image

That sounds like a beautiful example of how the ecosystem works together flexibly, doesn't it? And then the narrative docs can reference that tutorial and stay lean-and-mean focused on just the final step.

[eteq]

Oh, but it probably does make sense to add at least a little bit along the lines of "make sure your backgrounds match". Maybe even use this specific example, with magic numbers chosen by @astrofrog to make it pretty, with a note that says "if you want to know how these numbers were chosen, see the fancy tutorial that includes feature-ful background subtraction"