Tutorial: Understanding Target Pixel File Products with Lightkurve

[ojhall94]

This notebook will form part of the series: Getting started with Kepler and K2 data products.

In this second notebook, we will focus on downloading and studying a target pixel file. This will include i.e. looking at the flux in individual pixels, setting a rudimentary aperture, and plotting the background. The user may already be familiar with how to use Light Curve products (#3) we can point back to that. When talking about aperture photometry, it should point forward to #2.

We can draw inspiration from existing Lightkurve tutorials:

• What are TargetPixelFile objects
• How to perform aperture photometry with custom apertures?
• How to interactively inspect Target Pixel Files and Light Curves

---

Learning Goals:

• How to access TPF data
• What does the metadata mean?
• What does a TPF look like, and how can I understand the content of differen pixels?
• How do I plot the flux content of pixels?
• How do I set an aperture mask?
• How do I interact with a TPF?

To think about:

• Do we include the interactive functionality?
• Do we include things like the Gaia catalogue interact_sky() functions?

[astrobel]

I think it would be a great idea to include interactive functionality in this tutorial! For the regular interact() function, it might work well to put that near the beginning so users can poke around and then go on to learn what the various functions mean: e.g. under learning goal "what does a TPF look like?" As for interact_sky(), I would certainly find that useful, but as it's auxiliary to the main goal of the notebook, it might be good to put it at the end as a "bonus" example.

[ojhall94]

Great ideas, thanks Isabel! Hoping to get started on this notebook today or tomorrow.

[ojhall94]

Finished a first draft of the notebook, it's on Google Drive under the same name as this issue. I'll add some deep links tomorrow or Monday.

[barentsen]

Thanks for posting the draft notebook @ojhall94!

Here are my first impressions:

• I would not shy away from briefly recapping the structure and contents a Target Pixel File at the start, and explain that Lightkurve exists so that users can avoid having to remember the details of the FITS file structure. We can link to https://github.com/spacetelescope/notebooks/blob/master/notebooks/MAST/Kepler/Kepler_TPF/kepler_tpf.ipynb and https://github.com/spacetelescope/notebooks/blob/master/notebooks/MAST/K2/K2_TPF/k2_tpf.ipynb for more detailed tutorials about the FITS structure.
• It may be useful to remind readers that Target Pixel Files can also be opened from a local file using lk.open() -- I get that question a lot.
• I notice interact() is used prominently at the start. Unfortunately interact() will definitely not work in Colab or the rendered versions of the notebooks, because it requires a running Bokeh server. It may be best not to depend on interact() too much in our tutorials. Where we use it, we'd have to accompany it with an explanation as to why it may not render for the reader, which is distracting. (I wish it was different, but there is no solution on the horizon to make it work in static notebooks!)
• I would emphasize the use of tpf.header() as the way to access metadata. It is of course great to demo show_properties() and explain what all the properties/arrays mean, but the object properties only expose a subset of the metadata.
• Quite a bit of matplotlib magic was needed to plot the image of the background flux. If we think it is worth plotting the background, should we just add it as a feature of tpf.plot()?

Feel free to push back of course!!

[ojhall94]

Thanks for the comments @barentsen!

I've been working through the notebook start to finish implementing your comments, and trying to mimic the style that we settled on for Tutorial #3. For some paragraphs that means I've replicated them verbatim but changed the object names and links. Not sure if this is a good idea or not... I'll let the crowd deci

• I would not shy away from briefly recapping the structure and contents a Target Pixel File at the start, and explain that Lightkurve exists so that users can avoid having to remember the details of the FITS file structure. We can link to https://github.com/spacetelescope/notebooks/blob/master/notebooks/MAST/Kepler/Kepler_TPF/kepler_tpf.ipynb and https://github.com/spacetelescope/notebooks/blob/master/notebooks/MAST/K2/K2_TPF/k2_tpf.ipynb for more detailed tutorials about the FITS structure.

I'll get on this one tomorrow :)

• I would emphasize the use of tpf.header() as the way to access metadata. It is of course great to demo show_properties() and explain what all the properties/arrays mean, but the object properties only expose a subset of the metadata.

Unless I'm missing something, there isn't actually a header() method in KeplerTargetPixelFile, but there is the header attribute, which does the same thing. Not sure if this is intended or not.

• Quite a bit of matplotlib magic was needed to plot the image of the background flux. If we think it is worth plotting the background, should we just add it as a feature of tpf.plot()?

I think it is worth explaining to the user that the background is a thing that exists and is removed (especially if they wind up working with TESS data). It would be trivial to add to tpf.plot(), I could open a PR tomorrow.

[barentsen]

there isn't actually a header() method in KeplerTargetPixelFile, but there is the header attribute, which does the same thing. Not sure if this is intended or not.

Oops, LightCurveFile has a header() method whereas TargetPixelFile has a header attribute. That is inconsistent and bad! I fixed it over in https://github.com/KeplerGO/lightkurve/pull/736. Both classes now have a consistent get_header() method. Please use that!

To use this new feature, you'll have to use the master branch of Lightkurve in Colab. I'll push a new release to pypi in a few days, but the easiest solution for now is to have the notebook install Lightkurve straight from the master branch as follows:

!pip install --quiet git+https://github.com/KeplerGO/lightkurve.git

I think it is worth explaining to the user that the background is a thing ... It would be trivial to add to tpf.plot(), I could open a PR tomorrow.

I think this is a good idea!

[ojhall94]

Done & done!

[ojhall94]

At Rebekah's request, I split this tutorial and split in two. Tutorial #4 (this one) is now "Understanding Target Pixel File Products with Lightkurve", which focuses on the basics of downloading a TPF, plotting it, and understanding the metadata.

The new tutorial #9 instead focuses on plotting and understanding background file products and performing simple aperture photometry with Lightkurve's built in tools, to build a foundation for more advanced aperture photometry later on (see #2).

[barentsen]

I'm fine with splitting this tutorial in two, but I recommend adding at least one or two cells to the shortened "Understanding TPFs" tutorial which explain what tpf.time and tpf.flux contain. Those properties are the raison d'être of TPFs after all.

[ojhall94]

Done!

[ojhall94]

Updated this notebook to be Lightkurve 2.0 compatible.

[barentsen]

I carried out a final review and made a few changes:

• Changed title to "Using Kepler Target Pixel File Products with Lightkurve" for consistency with the light curve tutorial.
• Explained that a TPF filename can be accessed using tpf.path
• Added an example of the use of tpf.time which was missing
• Added an example of using to wcs, i.e. tpf.wcs.pixel_to_world(0, 0)
• Added an example on using a different quality_bitmask

[lglattly]

@ojhall94 and @barentsen I finished copy editing this tutorial "Using Kepler Target Pixel File Products with Lightkurve."

As with the other tutorials, I made small copy editing changes throughout, and I also combined the information from summary and companion content into the Introduction section as per the tutorial template. I also made sure that all of the terms used were defined in text, and then I removed the Defining Terms section, as per the template. Here again, I didn't touch the Additional Resources section in case there are resources listed that need to be worked into the text somehow (there might be a few at the bottom of the list, the rest I saw linked to in the text).

Other than the Additional Resources section incorporation, the tutorial is all set on my end and ready to go!

[barentsen]

Thank you! I reviewed the Additional Resources section and believe all the necessary materials are linked in the text.

[barentsen]

This notebook has successfully been merged into spacetelescope/notebooks. Thanks everyone! Closing the issue...