Skip to content

Commit

Permalink
notebook template updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@ttdu
ttdu authored May 7, 2024
2 parents df54a80 + 01e174d commit 7ed1c03
Showing 1 changed file with 116 additions and 103 deletions.
219 changes: 116 additions & 103 deletions contributing/notebook_template/notebook_template.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,16 @@
"# Tutorial Title\n",
"***\n",
"## Learning Goals\n",
"Write three to five learning goals using [Bloom's taxonomy](https://tips.uark.edu/using-blooms-taxonomy/) as a guide:\n",
"\n",
"Write three to five learning goals. We highly recommend using [Bloom's taxonomy](https://tips.uark.edu/using-blooms-taxonomy/) as a guide. Bloom’s Taxonomy is a classification of the different objectives and skills that educators set for their audience. The taxonomy is divided into six hierarchical categories, making it easy to communicate the goals of your Notebook and classify the expected difficulty level.\n",
"\n",
"(Delete the above text after you've added your goals)\n",
"\n",
"```\n",
"By the end of this tutorial, you will:\n",
"\n",
"- Understand how to use aperture photometry to turn a series of two-dimensional\n",
" images into a one-dimensional time series.\n",
"- Be able to determine the most useful aperture for photometry on a *Kepler/K2*\n",
" target.\n",
"- Create your own light curve for a single quarter/campaign of *Kepler/K2* data.\n",
"- Understand how to query the MAST Archive for TESS Observations.\n",
"- Create your own light curve using TESS data.\n",
"```"
]
},
Expand All @@ -29,21 +29,19 @@
}
},
"source": [
"## Table of Contents\n",
"* [Introduction](#Introduction)\n",
"* [Main Content (Rename)](#Main-Content-(Rename))\n",
" * [Loading Data (Rename)](#Loading-Data-(Rename,-e.g.-Querying-for-TESS-Data))\n",
" * [File and Data Information](#File-and-Data-Information)\n",
" * [Visualization, where relevant](#Visualization,-where-relevant)\n",
"* [Exercises](#Exercises)\n",
"* [Additional Resources](#Additional-Resources)\n",
"\n",
"## Introduction\n",
"Write a short introduction explaining the purpose of the tutorial. Define any terms or common acronyms that your audience may not know. If you're using some kind of domain-specific astronomical symbol or unusual mathematical concept, make sure you define it (for example, in its mathematical form) and link to any definitions (from literature, Wikipedia, etc.).\n",
"\n",
"If there are background materials or resources that may be useful to the reader to provide additional context, you may link to it here. If your tutorial is a continuation from another tutorial, or there are other tutorials that would be useful for the reader to read before or after your tutorial, mention that here as well.\n",
"\n",
"Finally, under this section you should add a description of the workflow in your notebook. This will essentially be a table of contents outlining the functional cells of the notebook, i.e. the main sections. Each section should link users to the actual section for easier navigation through the notebook. Refer to the example below for how to hyperlink sections on a Jupyter Notebook: \n",
"\n",
"\n",
"The workflow for this notebook consists of:\n",
"* [Main Content](#Main-Content)\n",
" * [Loading Data](#Loading-Data)\n",
" * [File and Data Information](#File-and-Data-Information)\n",
"* [Visualization](#Visualization)\n",
"* [Exercises](#Exercises)\n",
"* [Additional Resources](#Additional-Resources)"
"If there are background materials or resources that may be useful to the reader, link to it here. If your tutorial is a continuation from another tutorial, or there are other tutorials that would be useful for the reader to read before or after your tutorial, mention that here as well."
]
},
{
Expand All @@ -56,6 +54,7 @@
"source": [
"## Imports\n",
"Describe the main packages we're using here and their use-case for this notebook. If there's something unusual, explain what the library is, and why we need it.\n",
"\n",
"- *numpy* to handle array functions\n",
"- *astropy.io fits* for accessing FITS files\n",
"- *astropy.table Table* for creating tidy tables of the data\n",
Expand Down Expand Up @@ -94,9 +93,11 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Main Content\n",
"## Main Content (Rename)\n",
"\n",
"Where reasonable, \"Main Content\" should be renamed with the overall objective of the Notebook.\n",
"\n",
"The main content of your tutorial should be subdivided into sections with useful, descriptive headings that make sense based on the content. Break sections up with standard Markdown syntax headings:\n",
"The main content of your tutorial should be subdivided into sections with useful, **descriptive headings** that make sense based on the content. Break sections up with standard Markdown syntax headings:\n",
"\n",
"```\n",
"## Section 1\n",
Expand All @@ -111,7 +112,9 @@
"\n",
"A complete thought that's as important as Section 1 but doesn't need subsections.\n",
"\n",
"```"
"```\n",
"\n",
"Code should have comments. Text in cells is necessary, but not sufficient, to explain code."
]
},
{
Expand All @@ -122,11 +125,13 @@
}
},
"source": [
"### Loading Data\n",
"## Loading Data (Rename, e.g. Querying for TESS Data)\n",
"\n",
"Loading data and file information should appear within your main content, at the same time the data is going to be used, if possible. These elements of your tutorial can be their own sections within the main content, but avoid generic or vague headings like “Loading Data” and instead use descriptive headings pertinent to the content of the tutorial and the actual data being downloaded or files being used.\n",
"Many tutorials include a section on loading or downloading data. Try avoid generic or vague headings like “Loading Data” and instead use descriptive headings pertinent to the content of the tutorial, data downloaded, or particular files (e.g. \"Accessing light curves\" or \"Querying MAST for Kepler Observations\"). \n",
"\n",
"If the user needs to download data to run the tutorial properly, where possible, use [astroquery](https://astroquery.readthedocs.io/en/latest/) (or similar) to retrieve files. If this is not possible, see the [data guide](https://github.com/spacetelescope/style-guides/blob/master/guides/where-to-put-your-data.md) for other options."
"If the user needs to download data to run the tutorial properly, where possible, use [astroquery](https://astroquery.readthedocs.io/en/latest/) (or similar) to retrieve files. If this is not possible, see the [data guide](https://github.com/spacetelescope/style-guides/blob/master/guides/where-to-put-your-data.md) for other options.\n",
"\n",
"Let's do an example query for MAST data:"
]
},
{
Expand All @@ -137,7 +142,7 @@
}
},
"source": [
"For example, if we wanted to query for data from MAST for Kepler we might do something like:"
"For example, if we wanted to query for data from MAST for TESS we might do something like:"
]
},
{
Expand All @@ -150,10 +155,14 @@
},
"outputs": [],
"source": [
"keplerObs = Observations.query_criteria(target_name='kplr008957091', obs_collection='Kepler')\n",
"keplerProds = Observations.get_product_list(keplerObs[0])\n",
"yourProd = Observations.filter_products(keplerProds,extension='kplr008957091-2012277125453_lpd-targ.fits.gz',\n",
" mrp_only=False)"
"# Query for a reproducible TESS Observation\n",
"TESSObs = Observations.query_criteria(target_name='8262242', t_exptime=[120,120])\n",
"\n",
"# Get the list of corresponding products\n",
"TESSProds = Observations.get_product_list(TESSObs[0])\n",
"\n",
"# Filter for the products we want\n",
"yourProd = Observations.filter_products(TESSProds,description='Light curves')"
]
},
{
Expand All @@ -167,7 +176,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Where possible (if the code supports it), use code examples that visually display the data in the tutorial. For example, if you are showing an object such as a Table, display a preview of the table:"
"Where possible (if the code supports it), use code examples that visually display the data in the tutorial. For example, if you are showing an object such as an Astropy Table, display a preview:"
]
},
{
Expand All @@ -176,25 +185,36 @@
"metadata": {},
"outputs": [],
"source": [
"# Display the first five products in the results table\n",
"# (in this case, there is only one product to display)\n",
"yourProd[0:5]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Downloads to a Local Machine\n",
"\n",
"Be cognizant of file size when writing a tutorial; users should not need to wait for more than ~60 seconds for something to download. A 10MB file is likely appropriate. A 10 GB file is definitely not."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# Download the products\n",
"output = Observations.download_products(yourProd, mrp_only=False, cache=False)\n",
"# Download the products to our local directory\n",
"output = Observations.download_products(yourProd)\n",
"output"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Explain pertinent details about the file you've just downloaded. For example, if working with Kepler light curves, explain what's in the different file extensions:\n",
"Explain pertinent details about the file you've just downloaded. For example, if working with TESS light curves, explain what's in the different file extensions:\n",
"\n",
"```\n",
"- No. 0 (Primary): This HDU contains metadata related to the entire file.\n",
Expand All @@ -215,96 +235,74 @@
"metadata": {},
"outputs": [],
"source": [
"# Get the path to the file\n",
"file = output['Local Path'][0]\n",
"\n",
"# Print out some information about our file\n",
"print('The HDU list of our output file:\\n')\n",
"print(fits.info(file))\n",
"\n",
"data = fits.getdata(file, 1)['FLUX']\n",
"time = fits.getdata(file, 1)['TIME']"
"# Load in the flux and time data\n",
"time = fits.getdata(file, 1)['time']\n",
"flux = fits.getdata(file, 1)['pdcsap_flux']"
]
},
{
"cell_type": "markdown",
"metadata": {},
"metadata": {
"tags": []
},
"source": [
"## Visualization\n",
"## Visualization, where relevant\n",
"\n",
"When presenting any visuals and/or plots from the data, make sure you are using color palettes that are color-blind friendly and using language that keeps accessibility in mind. The most common form of color vision deficiency involves differentiating between red and green, so avoiding colormaps with both red and green (e.g. `viridis`) will avoid many problems in general. \n",
"\n",
"When presenting any visuals and/or plots from the data, make sure you are using color palettes that are color-blind friendly and using language that keeps accessibility in mind. The most common form of color vision deficiency involves differentiating between red and green, so avoiding colormaps with both red and green will avoid many problems in general. Use descriptive keywords not pertaining to the color of the object you are referring to. It is good practice to make your plots and images large enough to ensure that important details are not hard to see. On the same note, make sure that tick labels, legends, and other plot notations are not too small, and make sure they are descriptive enough that the user can understand what is being represented by the data. "
"Use descriptive keywords not pertaining to the color of the object you are referring to. It is also good practice to make your plots and images large enough to ensure that important details are not hard to see. On the same note, make sure that tick labels, legends, and other plot notations are not too small, and make sure they are descriptive enough that the user can understand what is being represented by the data. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"metadata": {
"jp-MarkdownHeadingCollapsed": true,
"tags": []
},
"source": [
"Let's plot the first four images of the Kepler TPF we just downloaded to see where the center of the PSF is located..."
"Let's plot the light curve from the file we just downloaded."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"scrolled": true
"scrolled": true,
"tags": []
},
"outputs": [],
"source": [
"imgs = 4\n",
"# Create the figure\n",
"fig, ax = plt.subplots(1, figsize=(5,5))\n",
"# Show the image data\n",
"ax.plot(time, flux)\n",
"\n",
"fig, axs = plt.subplots(1, imgs, figsize=(20, 20))\n",
"# Set x/y labels\n",
"ax.set_xlabel(\"Date (BTJD)\")\n",
"ax.set_ylabel(\"Flux (e-/s)\")\n",
"\n",
"for idx in range(0, imgs):\n",
" # Plotting\n",
" axs[idx].imshow(data[idx], cmap='bone', origin='lower')\n",
" \n",
" # Formatting\n",
" axs[idx].set_title(f'Image #{idx}', fontsize=25)\n",
" axs[idx].tick_params(axis='both', which='major', labelsize=20)"
"# Set the title for the image, make the font large\n",
"ax.set_title(\"TIC 8262242 light curve\", fontsize=25)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Looks like it's typically located around (x,y)=(4,4). Let's gather all the images and extract the flux at (4,4) from each of them to patch our lightcurve together..."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"lightcurve = []\n",
"## Exercises (optional)\n",
"\n",
"for idx in range(0, len(data)):\n",
" \n",
" flux = data[idx][4, 4]\n",
" lightcurve.append(flux)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# Plotting\n",
"plt.figure(1, figsize=(10, 6))\n",
"plt.plot(time, lightcurve)\n",
"\n",
"# Formatting\n",
"obj = fits.getheader(file)['OBJECT']\n",
"plt.title(f'Object: {obj}', fontsize=25)\n",
"plt.xlabel('Time - 2454833 (BKJD days)', fontsize=20)\n",
"plt.ylabel('Flux (e-/s)', fontsize=20)\n",
"plt.tick_params(axis='both', which='major', labelsize=15)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Exercises\n",
"Exercises are optional, but encouraged. Exercises can be woven into the main content of your tutorial, or appear in their own section toward the end of the tutorial. Final exercises can be more challenging, similar to homework problems. They can be minimal or take as long as 30 minutes to an hour to complete. If you do have one or more exercises in your tutorial, be sure to leave a blank code cell underneath each to show the reader that they're meant to try out their new skill right there. You may also want to include a \"solutions\" notebook next to your main notebook for the reader to check their work after they have finished their attempt."
"Exercises are optional, but encouraged. Exercises are often **most effective when woven into the main content** of your tutorial, but they can appear in their own section towards the end. Final exercises might be more challenging, similar to homework problems. They can be minimal or take as long as 30 minutes to an hour to complete. \n",
"\n",
"It may be helpful to again reference [Bloom's taxonomy](https://tips.uark.edu/using-blooms-taxonomy/) as you're writing the exercises. This may help you to classify the level of difficulty and design exercises appropriate to the learning goals.\n",
"\n",
"If you do have one or more exercises in your tutorial, be sure to leave a blank code cell underneath each to show the reader that they're meant to try out their new skill right there. You may also want to include a \"solutions\" notebook next to your main notebook for the reader to check their work after they have finished their attempt."
]
},
{
Expand All @@ -316,8 +314,8 @@
"This section is optional. Try to weave resource links into the main content of your tutorial so that they are falling in line with the context of your writing. For resources that do not fit cleanly into your narrative, you may include an additional resources section at the end of your tutorial. Usually a list of links using Markdown bullet list plus link format is appropriate:\n",
"\n",
"- [MAST API](https://mast.stsci.edu/api/v0/index.html)\n",
"- [Kepler Archive Page (MAST)](https://archive.stsci.edu/kepler/)\n",
"- [Kepler Archive Manual](https://archive.stsci.edu/kepler/manuals/archive_manual.pdf)\n",
"- [TESS Archive Page (MAST)](https://archive.stsci.edu/tess/)\n",
"- [TESS Archive Manual](https://outerspace.stsci.edu/display/TESS/TESS+Archive+Manual)\n",
"- [Exo.MAST website](https://exo.mast.stsci.edu/)"
]
},
Expand Down Expand Up @@ -348,23 +346,38 @@
},
"source": [
"## About this Notebook\n",
"Let the world know who the author of this great tutorial is! If possible and appropriate, include a contact email address for users who might need support (for example, `[email protected]`). You can also optionally include keywords, your funding source, or a last update date in this section.\n",
"Let the world know who the author of this great tutorial is! If possible and appropriate, include a contact email address for users who might need support (for example, `[email protected]`). You should also include keywords and a last updated date in this section.\n",
"\n",
"**Author(s):** Jessie Blogs, Jenny V. Medina, Thomas Dutkiewicz <br>\n",
"**Keyword(s):** Tutorial, lightkurve, kepler, introduction, template <br>\n",
"**Last Updated:** Aug 2022 <br>\n",
"**Next Review:** Mar 2023\n",
"**Keyword(s):** Tutorial, lightkurve, TESS, introduction, template <br>\n",
"**First published:** Sep 2020 <br>\n",
"**Last updated:** Aug 2022 <br>\n",
"\n",
"***\n",
"[Top of Page](#top)\n",
"<img style=\"float: right;\" src=\"https://raw.githubusercontent.com/spacetelescope/notebooks/master/assets/stsci_pri_combo_mark_horizonal_white_bkgd.png\" alt=\"Space Telescope Logo\" width=\"200px\"/> "
"<img style=\"float: right;\" src=\"https://raw.githubusercontent.com/spacetelescope/style-guides/main/guides/images/stsci-logo.png\" alt=\"Space Telescope Logo\" width=\"200px\"/> "
]
}
],
"metadata": {
"language_info": {
"name": "python"
}
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"nbformat": 4,
"nbformat_minor": 4
}
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.11.5"
}
},
"nbformat": 4,
"nbformat_minor": 4
}

0 comments on commit 7ed1c03

Please sign in to comment.