Tutorial: Using Light Curve Products with Lightkurve

[ojhall94]

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

In this first notebook, we will focus on downloading and plotting a light curve for objects a user is interested in. I think this should be a completely ''blind'' notebook, in the sense that it can be an entry point for somebody who hasn't used Lightkurve or Python before.

I've had a look through the STScI notebooks on downloading & plotting Kepler light curves. These are very Astropy & MAST centric, and so I'm not concerned about replicating anything here--- ideally this notebook should showcase Lightkurve's ease of access to plotting the data.

We can draw inspiration from existing Lightkurve tutorials:

• What are LightCurveFile objects?
• What are LightCurve objects?
• What are TargetPixelFile objects

---

Learning Goals:

• How to access light curve data
• What does the metadata mean?
• What units does a light curve have?
• How can I plot light cuve(s)
• How can I combine multiple light curves?

To think about:

• Do we cover any light curve manipulation at this stage? Custom light curve correction is dealt with later on, but do we want to handle some default corrections here with the flatten()' orbin()' functionality?
• How much do we dive into explaining API features of Lightkurve? E.g. the existing Lightkurve documentation focuses on 'What are x object?'. Should we include these kinds of explanations in this tutorial, or stay focused on explaining how the API is used instead.

[ojhall94]

Should we include the interactive functionality here (http://docs.lightkurve.org/tutorials/04-interact-with-lightcurves-and-tpf.html)?

[ojhall94]

I've started getting to work on this notebook over on Google Colab. It's a bit wordy at the moment because I tend to write first and edit later. Having a bit of a writers block, so criticism very welcome :)

[ojhall94]

This one is ready for review I think. It's on the shared Google Drive under Using-Light-Curve-File-Products-with-Lightkurve.ipynb. Planning to add some deep links once I've written the two other tutorials in this series.

[barentsen]

This is looking really good @ojhall94. I really like your writing style! :+1:

Here are some suggestions for your consideration:

• In addition to the data access via MAST, it's worth highlighting that one can also open a light curve file from disk using lk.open(filename).
• Most metadata is contained in the FITS headers, which can be accessed via the lcf.header() method. I'd explain that only a small subset of the metadata is passed on to the LightCurve object properties.
• I'd use lcfile instead of lc as the variable name for LightCurveFile objects.
• The Kinemuchi paper is a great link. I would also add a brief link to the official handbooks (instrument manual, archive manual, and data processing handbook) which are available via http://archive.stsci.edu/kepler . In particular, if you end up including the header() method, we should e.g. link to the page in the handbook that lists the meaning of all the header keywords.
• It would be worth including a deep link to the page over on docs.lightkurve.org that lists all the methods and properties of the KeplerLightCurve and KeplerLightCurveFile classes.
• You could mention in passing that everything you say also applies to TESS, e.g. a TessLightCurveFile class exists.
• You mention How can I combine multiple light curves? in your learning goals above. I'd probably leave this for a separate notebook!

Again, awesome job!! This is exciting!

[ojhall94]

Hi Geert,

Thanks for the comments! I've tried to implement them all into the current version of the Colab notebook.

The version you reviewed was incomplete--- that's on me, since I built it locally first and then failed to upload properly. I've fixed that now.

• The Kinemuchi paper is a great link. I would also add a brief link to the official handbooks (instrument manual, archive manual, and data processing handbook) which are available via http://archive.stsci.edu/kepler . In particular, if you end up including the header() method, we should e.g. link to the page in the handbook that lists the meaning of all the header keywords.

I can't seem to find any part of the documentation that provides more detail on these metadata than the description column in the Header does already, but I might be missing something.

• You mention How can I combine multiple light curves? in your learning goals above. I'd probably leave this for a separate notebook!

I've removed this section for now for a separate notebook, in that case :)

[barentsen]

The version you reviewed was incomplete--- that's on me, since I built it locally first and then failed to upload properly. I've fixed that now.

Ahh, that's why the end was so abrupt =)

Your notebook looks great!

I took the liberty to go ahead and edit the notebook a little. It's easy to reverse changes in Colab, so I figured out this would be an efficient way to proceed. Can you go through the notebook and see if you're OK with the changes I made?

The most noteworthy changes are:

• I changed the title from "How to use Light Curve File Products" into "How to use Kepler Light Curve File Products with Lightkurve" to differentiate it from this existing notebook. Are you OK with that?
• I went ahead and tried to re-organize the start using the astropy-style preamble (cf. Slack discussion).
• I added "Light curve", "Light curve file", "Photometry", "Channel", "Quarter", etc to the Defining Terms section.
• I slightly re-organized the section about accessing metadata. For example, I tried to put more focus on the fact that the full list of metadata is accessible via the header() method.

Let me know what you think!

[ojhall94]

Thanks for making those changes Geert! Really like the way it flows now. I'll make sure to try and carry the style through to the next tutorial. Happy with all the changes you made.

At one point you mention the features of the KeplerLightCurve will be featured in a different tutorial. Shall we add this to our Section 1? I'll set up an issue for it later this week so we can discuss its contents.

[barentsen]

At one point you mention the features of the KeplerLightCurve will be featured in a different tutorial. Shall we add this to our Section 1?

I worry that having separate tutorials for KeplerLightCurve vs KeplerLightCurveFile is going to confuse people, so perhaps it's best to only have one?

A lot of the functionality of a KeplerLightCurve object can be explained as part of separate task-focused tutorials, e.g. how to combine multiple quarters, how to remove long-term trends, how to write a light curve to disk, etc, can all be separate tutorials.

My recommendation is to add a brief list of the most important methods of KeplerLightCurve to this tutorial, and keep details for task-focused tutorials. What do you think?

[nksaunders]

This is looking really great @ojhall94!

To tag onto this discussion about including functionality of KeplerLightCurve objects, one additional component of lightkurve you could include in this is the ability to create a LightCurve object for any timeseries data by setting time, flux, and flux_err attributes. That way if someone is trying to figure out how to use lightkurve with their own observations they'll have a clear example of how to do it.

Should this be its own standalone tutorial? It's also tied into the work @barentsen is doing in #6, since people might want to read their own community-provided K2 light curves that we don't explicitly support.

[barentsen]

Should this be its own standalone tutorial?

I think so! Short and focused tutorials are easier to create, consume, and discover! I went ahead and added How to read and write your own light curve files and objects to the Google Doc!

[ojhall94]

Hi all,

Thanks for the feedback! I agree that a series of shorter and sweeter tutorials might better for these. I've gone ahead and added how to combine multiple quarters to the google doc. Not sure what to do about flatten() and normalize(), or what tutorial category to put those in, though.

[ojhall94]

I've added some Figures at Rebekah's request, but not sure if this bloats it too much. Welcoming feedback!

[ojhall94]

Touched this up to match the new Lightkurve updates, ready for people to take a look at it again!

[ojhall94]

Rebekah commented on the tutorial that Sections 3 and onwards might be better suited to separate tutorial. This tutorial would deal with explaining the metadata only, and the first tutorial would just focus on downloading and plotting data. What are your thoughts @barentsen ?

[astrobel]

Finally got around to reading through this notebook, and I think it's great!! A really clear introduction to using light curve data in Lightkurve, and pitched at a level that I feel is accessible to both beginners and experts. I particularly love the metadata section; I learnt a lot. On the topic of splitting it, I don't feel like the metadata section would work as well on its own. By combining something fairly abstract with a tangible exploration of the data, it's a lot more meaningful.

One thing that's been on my mind is the possibility of putting a table of contents at the beginning of the tutorials. For something like this, which is of considerable length and has two distinct sections, a ToC would make it easier to skip ahead for people with some background knowledge who only want to focus on one part.

[barentsen]

I carried out a final review and love this tutorial!

I made a few minor changes:

• Section 1: At the end, I added an example showing that the location of the light curve file can be accessed using klc.filename, which is a common question.
• Section 2: added a one-line example demonstrating how a figure can be saved using matplotlib, which is a common question.
• Section 3: I removed the demo of klc.show_properties() because that method really doesn't show anything useful right now. We'd have to work on improving that method, but it should not hold up this notebook.

I declare this notebook ready for copy-editing. Thank again @ojhall94! :+1:

[ojhall94]

Awesome, thanks for the changes @barentsen!

[lglattly]

@ojhall94 and @barentsen I finished copy editing this tutorial "How to Use Kepler Light Curve Products with Lightkurve," and it was also in great shape!

Like the others, I made small copy editing changes throughout, and I combined the information from the summary with the Introduction section. I was seeing all of the terms from the defining terms section being defined and described in the text, so I went ahead and removed that section.

I haven't removed the Additional Resources section at the end in case some of the resources need to be incorporated to the text. I also had a question about the number associated with the pixel channels, which I left as a comment in the notebook. Other than those two things, this tutorial is all set on my end and ready to go!

[barentsen]

I reviewed the Additional Resources section and confirmed that all the necessary materials are included in the text.

[barentsen]

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