Tutorial: Creating light curves using custom aperture photometry

[astrobel]

This is the introductory tutorial in a series of notebooks that will guide users through the process of Kepler/K2 photometry, from the basics through to detrending and handling systematics.

In this notebook, users will learn to use Kepler target pixel files (TPFs) to create their own light curves with tools from lightkurve. The tutorial will introduce the basic concepts of aperture photometry, and discuss the process of choosing the best aperture mask for a given target.

Assumed knowledge for this tutorial:

• Familiarity with lightkurve, particularly the handling of LightCurve objects and some basic understanding of TargetPixelFile objects.
• How to download Kepler/K2 data with lightkurve and how to load your own FITS files (still thinking about this one - whether to include FITS header familiarity in here, since it can be useful when working with TPFs? Might just go with lightkurve to start.)
• Understanding terminology relating to the Kepler/K2 missions and the practical applications of that terminology, e.g. quarter/campaign, TPF, pointing.

There are three key learning goals for this tutorial:

1. Understanding what "aperture photometry" means and how to use it to turn a pixel image into a time series
2. Being able to determine the most useful aperture mask for performing aperture photometry
3. Creating a time series for a single quarter/campaign TPF using lightkurve

One idea for at least part of the tutorial is to walk through an example using a TPF with multiple clearly variable signals in the pixel light curves (long-ish period trends), instructing users in manually picking pixels to reduce contamination. This sort of manual work is not feasible for large datasets, but it would nicely illustrate the example, and is definitely suitable for a casual user's purposes.

Any thoughts appreciated!

[ojhall94]

This sounds great! I'll be making a start on the issue for using TPF products with lightkurve in a bit, so we should check over each others work to make sure that it leads nicely into the more advanced use you'll be writing about.

How to download Kepler/K2 data with lightkurve and how to load your own FITS files (still thinking about this one - whether to include FITS header familiarity in here, since it can be useful when working with TPFs? Might just go with lightkurve to start.)

My opinion is lightkurve first-- I reckon as we start padding out the different tutorials it'll be come clear to us how to start inter-linking them effectively.

[barentsen]

This sounds great!

how to load your own FITS files (still thinking about this one - whether to include FITS header familiarity in here, since it can be useful when working with TPFs? Might just go with lightkurve to start.)

My recommendation is to only briefly mention that there are different ways to open and use FITS files, and link to one of the following:

• The Using Target Pixel File Products with Lightkurve notebook Oli is working on.
• The existing notebook Plotting Images from Kepler Target Pixel Files which demonstrates how to open a TPF file with astropy.io.fits (though it could be extended slightly to discuss the headers in more detail).
• A separate notebook titled "How to do aperture photometry using astropy.io.fits and photutils?" which we could envisage adding if we have too much time!

[astrobel]

Hi everyone, just to let you know there's now a draft version of this notebook in the Drive folder. A few sections of it are still a work in progress, and some of it is a little experimental (!), but I would love any feedback on the structure so far.

[barentsen]

@astrobel Oops, I only see an empty file called "Untitled0.ipynb" in Drive from you. Could something have gone wrong with the upload?

[astrobel]

Hi all, the completed first draft of this notebook is now live in the Drive folder, and ready for review! Looking forward to everyone's thoughts and comments :)

[ojhall94]

Hey @astrobel, just had read through the tutorial and it looks great! Your writing is really clear (unsurprisingly) and I learned a couple of things I didn't yet know.

Others will probably have more comments, but the main things that stick out to me are:

• The interact() functionality won't work on Colab so probably aren't ideal for these tutorials, so I've been removing them from mine. Some of the material in your tutorial here could maybe be repurposed for an interact()-specific tutorial that could be downloaded.

• If you get told that this is too long (not sure what the limits are), you could definitely cut this into two or maybe even 3 tutorials that follow on from one another but still have a great narrative.

[barentsen]

Just to confirm: Bokeh widgets (such as interact) can not be used in Google Colab yet (see here). They also won't work in statically-compiled versions of the tutorial.

Stay tuned for more feedback. My first impression is super positive!

[astrobel]

Thanks @ojhall94 and @barentsen! I've removed the interactivity from the tutorial. Looking forward to your comments!

[barentsen]

@astrobel I like this tutorial a lot! It's fairly long, but your writing style is awesome, and the sections belong together, so I have no problem with the length at all! :+1: :+1:

My single biggest comment is that it would be good to summarize in the tutorial how the Kepler pipeline created aperture masks, which is explained in Smith et al. 2016, "Finding Optimal Apertures in Kepler Data". (This paper is effectively identical to Chapter 7 of the Kepler Data Processing Handbook, which will be good to reference as well.)

Right now, Section 1.3 may give the impression that the Kepler pipeline did not take crowding or shot noise into account. To keep everyone happy, I would reword this slightly to point out that the default pipeline apertures did take those things into account in an automated way, but that a manual refinement can often be worthwhile for a number of reasons (e.g. because the catalog used by the pipeline did not have access to Gaia DR2 yet, or e.g. because you want to verify which pixels a signal appears to come from.)

Two smaller comments:

• I would be explicit about the fact that it can be really hard to decide by eye what the perfect aperture is, which is of course why the pipeline used various metrics. You can perhaps use estimate_cdpp() in one of the examples to show how someone might use that metric to measure whether the quality of a light curve has improved, whilst of course cautioning for the limitations of that metric.
• I would explicitly mention that light curves created using custom aperture photometry will include various sources of systematic noise (e.g. spacecraft motion, PSF changes, etc....). I would say out loud that one still needs to run noise correction after obtaining a custom light curve. (Though it's also interesting to point out that some noise effects, such as PSF changes and spacecraft motion, will be less dominant in light curves created using larger apertures ... albeit at the expense of more random shot noise in those light curves.) Of course details about noise removal are beyond the scope of the tutorial.

(I think you can probably address these comments with a few small additions here and there!)

Awesome job :+1: :+1:

[barentsen]

I carried out a final review of this tutorial (which is awesome & important), and took the liberty to make a final few changes:

• I removed the temporary placeholder links to other tutorials for now, and changed them into generic phrases (e.g. "this is explained in other tutorials"). We can add the inter-tutorial links later when we have a few tutorials merged and know their actual location.
• I changed the TPF data to use quality_bitmask='hard', such that the cadences affected by Argabrightening are removed. This simplifies the notebook by not having to explain the big horrible spikes due to Argabrightening. I modified Section 2.1 to explain the smaller remaining systematic signals near days 935 and 970 instead (which are due to focus changes / earth downlinks, and much smaller than the Argabrightening peaks).
• I expanded Section 3.1 slightly to explain that the background star can be selected by passing a reference_pixel argument to create_threshold_mask(), and slightly re-organized the remainder of the notebook accordingly.

During the final review, I fixed two small Lightkurve bugs which were affecting the tutorial:

• https://github.com/KeplerGO/lightkurve/pull/807
• https://github.com/KeplerGO/lightkurve/pull/813

And, finally, this tutorial also made me want to improve the visual style of plotting the aperture masks, which I am proposing to do here:

• https://github.com/KeplerGO/lightkurve/pull/814

That's it! @astrobel would you be willing to have a quick glance over your awesome notebook to check that I didn't do anything silly? If not, then this notebook is ready to be moved on to copy-editing!

[astrobel]

@barentsen Thanks so much for the thorough review and changes! It's looking good to me. I wonder if, because of the new addition to Section 3.1, we can cut the current Section 3.2? (Since that was a product of my oversight, oops!)

[barentsen]

I like keeping Section 3.2. I frequently end up making custom apertures directly using numpy arrays, so I think it's useful to document how to do it!

[lglattly]

@astrobel I finished proofreading this tutorial and it was in excellent shape! I made some very small stylistic/editorial changes, and I had one question about a sentence I didn't want to edit without consulting you, which I put in as a comment in the notebook. I still may need to shuffle around some sections depending on how we finalize the tutorial template this week, so I'll let you know when copy editing is completely finished.

[lglattly]

@astrobel (cc @barentsen) the copy editing on this tutorial "Creating Light Curves Using Custom Aperture Photometry" is complete! I reviewed the changes you made to the section structure and additions to the text and everything looks great. This tutorial is all set on my end and ready to go!

[barentsen]

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