PSF image representation in NDData/CCDData by parejkoj · Pull Request #13743 · astropy/astropy

parejkoj · 2022-09-23T00:20:35Z

Description

This pull request adds a simple PSF image to NDData/CCDData, to support the Rubin Observatory LSST Prompt Processing alert distribution system. The LSST alert packet image cutouts will be sent as astropy CCDData objects, and the only thing we see as missing from that format is the PSF. For our purposes for these image cutouts, all we need is a realization of the PSF image at the image center, not a generic parameterized or model PSF.

TODO:

Are any further tests or functionality necessary?
Does this serialize to the various astropy outputs, or do I need to add code for that?
Document how to make use of this PSF representation (but I'm not sure where such documentation would go).
Document how to use the astropy flux-preserving warping code to move the PSF around within the image?

Checklist for package maintainer(s)

This checklist is meant to remind the package maintainer(s) who will review this pull request of some common things to look for. This list is not exhaustive.

pllim · 2022-09-27T22:39:34Z

    meta = MetaData(doc=_meta_doc, copy=False)

-    def __init__(self, data, uncertainty=None, mask=None, wcs=None,
+    def __init__(self, data, uncertainty=None, mask=None, wcs=None, psf=None,


Is it safer to put new keyword in the end in case people been passing in keywords as pos args?

While adding this, I wondered if we shouldn't modify this API to make everything after data be keyword-only, since there's a lot of them? So it would look like: __init__(self, data, *, uncertainty=None, ...).

Depends on who you ask. It would definitely break someone's code but if you ask @Cadair , he would be like 🔥 🔥 🔥

While adding this, I wondered if we shouldn't modify this API to make everything after data be keyword-only, since there's a lot of them?

I don't think we want to do this in minor version bump; there may be issues also with the @use_nddata decorator but I don't recall the details of that.

pllim · 2022-09-27T22:41:04Z

Thanks! Definitely need a change log.

Maybe a What's New too but I'll let others decide on that one.

mwcraig

@parejkoj -- this looks good. Can you please add an example in the narrative documentation?

It also needs a changelog, and I think it warrants a "What's new" entry too.

One question: why not just shove the PSF into the metadata?

parejkoj · 2022-10-11T00:04:16Z

One question: why not just shove the PSF into the metadata?

That is one of the things I was wondering about: I think it hinges on the question of how much structure you want to have in the CCDData object. Having a dedicated name for the PSF makes it readily discoverable, and we can enforce the type of the object. LSST's equivalent to CCDData (afw.Exposure) is a C++ object underneath, so it needs to have a pretty rigid structure and contain explicit types and names for all that "metadata".

I can think of a handful of other things one might add as named objects on CCDData (e.g. an LSF for spectra), but none of them are as broadly useful as the PSF, to my mind. Eventually extending this PSF to include model representations seems like a future next step, but we don't need it for our purposes, and there's not really any way to generically represent a model PSF. I think the question is "what, besides WCS, should be a first-class named parameter?" I think the PSF is the next thing. An object representing the photometric calibration isn't as broadly applicable as the WCS and PSF are, otherwise it would be my next suggestion.

mwcraig · 2022-10-17T20:36:59Z

@parejkoj -- it is best to mention me in replies -- my github notifications are a train wreck because of conda-forge (I know I could fix that, but) (and still my bad for not checking back sooner).

Having a dedicated name for the PSF makes it readily discoverable, and we can enforce the type of the object. LSST's equivalent to CCDData (afw.Exposure) is a C++ object underneath, so it needs to have a pretty rigid structure and contain explicit types and names for all that "metadata".

That makes sense -- I'm fine with adding it at a fairly high level.

Do you have time to do the changelog and some basics documentation this week?

parejkoj · 2022-10-20T20:52:28Z

@mwcraig :

Do you have time to do the changelog and some basics documentation this week?

I'm trying to finish it up now.

One of the difficulties I've had is figuring out exactly where I should put all the necessary functionality and tests. I'm fixing the one line I missed that the coverage test pointed out, but I don't really know where else I need to add code. Suggestions very welcome there.

parejkoj · 2022-10-20T23:48:43Z

@mwcraig : Ok, I believe I've added working FITS write/read support and a test that demonstrates it, there's a note in the changelog and what's new, and I've added some notes to the narrative docs (though I'm not sure what else should go there). Further comments very welcome.

dhomeier

Some comments from a relatively outsider point of view.
To elaborate a bit more on the requirements a PSF image has to fulfil, all the docs mention it should be 'normalized', but that does not seem to be checked on input anywhere – at least the somewhat pathological np.random.normal(size=[20, 20]) used in the tests generally is not (where by 'normalized' I'd understand that convolution with such a PSF will be automatically flux-preserving; if something else is meant, that should probably be pointed out in the docs as well).

mwcraig

This is close to ready to go. One last big question: how should PSF's be handled in arithmetic operations? My inclination is to treat it like metadata, where I think we punt to the user to decide what the resulting metadata should be. The logic for several of the other properties is here: https://github.com/astropy/astropy/blob/main/astropy/nddata/mixins/ndarithmetic.py#L231

parejkoj · 2022-10-24T23:47:29Z

@mwcraig : The PSF should definitely not be modified during arithmetic operations. This sort of question is one of the reasons the LSST CCDData-like object (afw.Exposure) does not have any arithmetic operations itself, only the "image array" class does (afw.MaskedImage, which includes the mask and variance planes and which are properly handled during arithmetic operations).

Co-authored-by: Derek Homeier <dhomeie@gwdg.de>

mwcraig · 2022-10-27T12:49:39Z

pre-commit.ci autofix

for more information, see https://pre-commit.ci

mwcraig

Assuming the CI passes I am ok with merging this. Thanks for getting this going @parejkoj!

@dhomeier -- thanks for your detailed review! I think all of your comments have been addressed, and I've opened an issue about improving the documentation landing page with the intent of fixing it for 6.0.

pllim · 2022-10-27T14:40:20Z

@dhomeier requested changes -- does he want to re-review?

pllim · 2022-10-27T14:42:07Z

Do the commits need squashing? 😸

dhomeier · 2022-10-27T14:55:54Z

Thanks for opening the issue on documentation!

mwcraig · 2022-10-27T14:57:12Z

Do the commits need squashing? 😸

@pllim -- I can do the squash if you want (I don't have strong feelings either way)

pllim · 2022-10-27T14:44:21Z

        Parameters
        ----------
-        hdu_mask, hdu_uncertainty, hdu_flags : str or None, optional
+        hdu_mask, hdu_uncertainty, hdu_flags, hdu_psf: str or None, optional


Suggested change

hdu_mask, hdu_uncertainty, hdu_flags, hdu_psf: str or None, optional

hdu_mask, hdu_uncertainty, hdu_flags, hdu_psf : str or None, optional

pllim · 2022-10-27T14:45:14Z

            If the unit is ``None`` or not otherwise specified it will raise a
            ``ValueError``

+    psf : `numpy.ndarray` or None, optional


tl;dr -- Is Quantity support planned for the future?

I believe a psf image should always be unitless, but I'm not positive of that.

I am just thinking what if someone stored it as data with pixel unit attached to it.

hmmm... I'm not sure what to do on that point: I think the psf image as being purely an array (because the thing you do with it is (de)convolve it with the image), and I can't think of a reason someone would want it to have pixel units or what would be gained by that. Might be worth waiting to see how use-cases shake out and if anyone requests it?

That is fine. I was just curious if this was discussed.

pllim · 2022-10-27T14:47:08Z


+        # If both are None, there is nothing to do.
+        if self.psf is not None or operand.psf is not None:
+            warnings.warn(f"Not setting psf attribute during {operation.__name__}.", RuntimeWarning)


Why not AstropyUserWarning?

I didn't even know that was a thing. I don't have a strong opinion either way; your suggestion might make the warning more obvious to astropy users?

Yes, I do think AstropyUserWarning is more explicit (short of creating your own warning class).

pllim · 2022-10-27T14:54:14Z

+def test_ccddata_with_psf():
+    psf = _random_psf.copy()
+    ccd = CCDData(_random_array.copy(), unit=u.adu, psf=psf)
+    assert (ccd.psf == psf).all()


Why not use np.testing.assert_array_equal? Same question for all similar occurrences.

I was just following the other tests above.

I think the reasoning was that the created ccd should have an exact copy of the input psf in this case (and the other similar cases) so we really do want to check for exact equality.

Not that it really matters, but np.testing.assert_array_equal is exact equality. np.testing.assert_array_almost_equal is probably the one you're thinking of.

Maybe changing assert (a == b).all() to np.testing.assert_array_equal(a, b) can be a follow-up PR if you are interested.

pllim · 2022-10-27T14:58:50Z

+        ccd.psf = "something"
+
+
+def test_write_read_psf(tmpdir):


Please use tmp_path. We just went through a mini-campaign to get rid of tmpdir.

mwcraig · 2022-10-27T15:16:53Z

Thanks for the review @pllim -- I'll update around noon locally

Co-authored-by: P. L. Lim <2090236+pllim@users.noreply.github.com>

pllim · 2022-10-27T17:54:32Z


+        # If both are None, there is nothing to do.
+        if self.psf is not None or operand.psf is not None:
+            warnings.warn(f"Not setting psf attribute during {operation.__name__}.", RuntimeWarning)


You'll have to add the import yourself. I cannot suggest it at the line where it is supposed to go. Now precommit complains if it is not at the right place.

Suggested change

warnings.warn(f"Not setting psf attribute during {operation.__name__}.", RuntimeWarning)

warnings.warn(f"Not setting psf attribute during {operation.__name__}.", AstropyUserWarning)

pllim · 2022-10-27T17:55:11Z

+    # no warning if both are None
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        ndd2.add(ndd2)


I think this still applies.

pllim · 2022-10-27T17:55:25Z

+        warnings.simplefilter("error")
+        ndd2.add(ndd2)
+
+    with pytest.warns(RuntimeWarning, match="Not setting psf attribute during add"):


Suggested change

with pytest.warns(RuntimeWarning, match="Not setting psf attribute during add"):

with pytest.warns(AstropyUserWarning, match="Not setting psf attribute during add"):

pllim · 2022-10-27T17:55:39Z

+
+    with pytest.warns(RuntimeWarning, match="Not setting psf attribute during add"):
+        ndd1.add(ndd2)
+    with pytest.warns(RuntimeWarning, match="Not setting psf attribute during add"):


Suggested change

with pytest.warns(RuntimeWarning, match="Not setting psf attribute during add"):

with pytest.warns(AstropyUserWarning, match="Not setting psf attribute during add"):

pllim · 2022-10-27T17:55:53Z

+        ndd1.add(ndd2)
+    with pytest.warns(RuntimeWarning, match="Not setting psf attribute during add"):
+        ndd2.add(ndd1)
+    with pytest.warns(RuntimeWarning, match="Not setting psf attribute during add"):


Suggested change

with pytest.warns(RuntimeWarning, match="Not setting psf attribute during add"):

with pytest.warns(AstropyUserWarning, match="Not setting psf attribute during add"):

mwcraig · 2022-10-27T18:56:10Z

@pllim -- thanks for the review. I think all of your comments have been addressed.

Co-authored-by: P. L. Lim <2090236+pllim@users.noreply.github.com>

mwcraig · 2022-10-27T19:39:50Z

Hopefully this time I really have them all!

pllim

LGTM now. Thanks!

pllim · 2022-10-27T20:34:39Z

Interesting... Could it be that you actually support Quantity by accident?

_______________________________ test_psf_setter ________________________________

    def test_psf_setter():
        psf = _random_psf.copy()
        ccd = CCDData(_random_array.copy(), unit=u.adu)
        ccd.psf = psf
        assert (ccd.psf == psf).all()
    
        # cannot set with non-ndarray
>       with pytest.raises(TypeError, match="The psf must be a numpy array."):
E       Failed: DID NOT RAISE <class 'TypeError'>

.../astropy/nddata/tests/test_ccddata.py:1104: Failed

mwcraig · 2022-10-27T20:38:48Z

Interesting... Could it be that you actually support Quantity by accident?
🤔 maybe? Will check this evening but will be away from the keyboard for a few hours now

mwcraig · 2022-10-28T01:27:01Z

Turns out quantity is supported (though we don't get credit for that):

In [1]: from astropy import units as u

In [3]: import numpy as np

In [4]: foo = 5 * u.pixel

In [5]: foo
Out[5]: <Quantity 5. pix>

In [6]: isinstance(foo, np.ndarray)
Out[6]: True

pllim · 2022-10-28T14:49:43Z

Thanks, all!

parejkoj · 2022-10-28T16:07:17Z

Thank you for all the help in getting this merged!

github-actions Bot added the nddata label Sep 23, 2022

pllim reviewed Sep 27, 2022

View reviewed changes

pllim added this to the v5.2 milestone Sep 27, 2022

pllim requested a review from mwcraig September 27, 2022 22:40

mwcraig requested changes Oct 10, 2022

View reviewed changes

parejkoj force-pushed the ccddata-psf-representation branch 2 times, most recently from 1b8062f to 76b639f Compare October 20, 2022 23:40

dhomeier reviewed Oct 21, 2022

View reviewed changes

Comment thread astropy/nddata/tests/test_ccddata.py Outdated

Comment thread astropy/nddata/ccddata.py Outdated

mwcraig reviewed Oct 24, 2022

View reviewed changes

Comment thread docs/nddata/ccddata.rst Outdated

mwcraig reviewed Oct 24, 2022

View reviewed changes

Comment thread astropy/nddata/nddata.py Outdated

mwcraig mentioned this pull request Oct 26, 2022

Update nddata tests to use newer pytest syntax #13905

Merged

10 tasks

parejkoj added 13 commits October 26, 2022 16:17

Add psf support to NDData/CCDData with tests

33ff1dd

Add psf to nddata/ccddata docs

39b6103

Add psf to FITS read/write with tests

abe00a8

Add missing parameter to docstring

4c00151

Add changelog message for new PSF arg

34cdbb3

Add what's new entry

4ee18e3

tweak docstrings

6870f69

tweak rst docs

a137c5e

tweak docstrings

a2faef4

Move psf setter typecheck from nddata to ccddata

c318445

fixup raises tests

2e06856

Add psf to base class

e8cef99

Warn on operations with non-None psf

3219eb9

mwcraig and others added 2 commits October 27, 2022 07:39

Apply suggestions from code review

97da185

Co-authored-by: Derek Homeier <dhomeie@gwdg.de>

Make psf concrete in the nddata base class and add test

67eca51

[pre-commit.ci] auto fixes from pre-commit.com hooks

eb9a717

for more information, see https://pre-commit.ci

mwcraig mentioned this pull request Oct 27, 2022

Improve nddata documentation landing page #13917

Open

mwcraig approved these changes Oct 27, 2022

View reviewed changes

pllim added the whatsnew-needed label Oct 27, 2022

dhomeier approved these changes Oct 27, 2022

View reviewed changes

pllim requested changes Oct 27, 2022

View reviewed changes

Apply suggestions from code review

0ebdd10

Co-authored-by: P. L. Lim <2090236+pllim@users.noreply.github.com>

pllim reviewed Oct 27, 2022

View reviewed changes

Use astropy warning instead of generic warning

9a50b68

pllim reviewed Oct 27, 2022

View reviewed changes

Comment thread astropy/nddata/tests/test_ccddata.py Outdated

Apply suggestions from code review

ec7a47d

Co-authored-by: P. L. Lim <2090236+pllim@users.noreply.github.com>

pllim approved these changes Oct 27, 2022

View reviewed changes

mwcraig reviewed Oct 28, 2022

View reviewed changes

Comment thread astropy/nddata/tests/test_ccddata.py Outdated

Use invalid value for for psf in test

93593e6

pllim merged commit d0a14f7 into astropy:main Oct 28, 2022

	hdu_mask, hdu_uncertainty, hdu_flags, hdu_psf: str or None, optional
	hdu_mask, hdu_uncertainty, hdu_flags, hdu_psf : str or None, optional

	warnings.warn(f"Not setting psf attribute during {operation.__name__}.", RuntimeWarning)
	warnings.warn(f"Not setting psf attribute during {operation.__name__}.", AstropyUserWarning)

	with pytest.warns(RuntimeWarning, match="Not setting psf attribute during add"):
	with pytest.warns(AstropyUserWarning, match="Not setting psf attribute during add"):

Uh oh!

Conversation

parejkoj commented Sep 23, 2022 • edited by pllim Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist for package maintainer(s)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

parejkoj Sep 28, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pllim commented Sep 27, 2022

Uh oh!

mwcraig left a comment

Choose a reason for hiding this comment

Uh oh!

parejkoj commented Oct 11, 2022

Uh oh!

mwcraig commented Oct 17, 2022

Uh oh!

parejkoj commented Oct 20, 2022

Uh oh!

parejkoj commented Oct 20, 2022

Uh oh!

dhomeier left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mwcraig left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

parejkoj commented Oct 24, 2022

Uh oh!

mwcraig commented Oct 27, 2022

Uh oh!

mwcraig left a comment

Choose a reason for hiding this comment

Uh oh!

pllim commented Oct 27, 2022

Uh oh!

pllim commented Oct 27, 2022

Uh oh!

dhomeier commented Oct 27, 2022

Uh oh!

mwcraig commented Oct 27, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

parejkoj commented Sep 23, 2022 •

edited by pllim

Loading

parejkoj Sep 28, 2022 •

edited

Loading