Add new exception report notebook for COS

[srosagomez]

This notebook checklist has been made available to us by the Notebooks For All team.
Its purpose is to serve as a guide for both the notebook author and the technical reviewer highlighting critical aspects to consider when striving to develop an accessible and effective notebook.

The First Cell

• The title of the notebook in a first-level heading (eg. <h1> or # in markdown).
• A brief description of the notebook.
• A table of contents in an ordered list (1., 2., etc. in Markdown).
• The author(s) and affiliation(s) (if relevant).
• The date first published.
• The date last edited (if relevant).
• A link to the notebook's source(s) (if relevant).

The Rest of the Cells

• There is only one H1 (# in Markdown) used in the notebook.
• The notebook uses other heading tags in order (meaning it does not skip numbers).

Text

• All link text is descriptive. It tells users where they will be taken if they open the link.
• All acronyms are defined at least the first time they are used.
• Field-specific/specialized terms are used when needed, but not excessively.

Code

• Code sections are introduced and explained before they appear in the notebook. This can be fulfilled with a heading in a prior Markdown cell, a sentence preceding it, or a code comment in the code section.
• Code has explanatory comments (if relevant). This is most important for long sections of code.
• If the author has control over the syntax highlighting theme in the notebook, that theme has enough color contrast to be legible.
• Code and code explanations focus on one task at a time. Unless comparison is the point of the notebook, only one method for completing the task is described at a time.

Images

• All images (jpg, png, svgs) have an image description. This could be

  • Alt text (an alt property)
  • Empty alt text for decorative images/images meant to be skipped (an alt attribute with no value)
  • Captions
  • If no other options will work, the image is decribed in surrounding paragraphs.

• Any text present in images exists in a text form outside of the image (this can be alt text, captions, or surrounding text.)

Visualizations

• All visualizations have an image description. Review the previous section, Images, for more information on how to add it.

• Visualization descriptions include

  • The type of visualization (like bar chart, scatter plot, etc.)
  • Title
  • Axis labels and range
  • Key or legend
  • An explanation of the visualization's significance to the notebook (like the trend, an outlier in the data, what the author learned from it, etc.)

• All visualizations and their parts have enough color contrast (color contrast checker) to be legible. Remember that transparent colors have lower contrast than their opaque versions.

• All visualizations convey information with more visual cues than color coding. Use text labels, patterns, or icons alongside color to achieve this.

• All visualizations have an additional way for notebook readers to access the information. Linking to the original data, including a table of the data in the same notebook, or sonifying the plot are all options.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[haticekaratay]

I was reviewing the script and noticed the if __name__ == "__main__": block used for testing. I just wanted to flag that this might not be immediately clear to many users, especially those working primarily in notebooks. Typically, notebook users won't be running scripts directly from the command line, and this main block might not be the best fit for those workflows.

• If you want users to be able to run this test from their notebooks, it might be helpful to provide some instructions on how to do so. Notebook users may not know how to interact with the main block, and it could create confusion. OR
• You could move the logic in the main block into a dedicated function. This way, users can call the function directly from their notebook or another script without needing to figure out how to trigger the main() block. It will also allow you to run tests with a simple function call rather than hardcoding things.
• also noticed that the file path in the main() block is hardcoded, but it seems like the file doesn’t exist. It might be better to either check for the file’s existence or make the path dynamic (e.g., allow the user to input the file path).
  In short :)
  If testing isn’t needed in the notebook workflow, consider removing the if __name__ == "__main__": block entirely.
  If you want users to be able to test from the notebook, encapsulate the logic into a separate function with clear instructions.
  Let me know what you think, and feel free to reach out if you'd like to discuss this further. Thanks again for all your hard work on this!

[haticekaratay]

There is some code duplication in plotting the same data tice for flux. vs wavelength. You can wrap the plotting logic into a loop to reduce redundancy.

for i, axis in enumerate(ax[0]):
    # Plotting flux vs wavelength on top row
    axis.plot(wl, flux,
              lw=2,
              color="black")
    axis.set_xlabel(r'Wavelength [$\AA$]')
    axis.set_ylabel(r'Flux [$erg\ s^{-1}\ cm^{-2}\ \AA^{-1}$]')
    if i == 0:
        axis.set_title("Flux vs Wavelength")
    else:
        axis.set_title("Flux vs Wavelength, ZOOMED")
        axis.set_ylim(0, 0.6e-13)

Reply via ReviewNB

[haticekaratay]

@srosagomez, this feedback is from an engineering perspective. However, if you prefer to keep your tutorial as is for clarity, that's fine with me. A clear workflow is more important than avoiding code duplication in the tutorial. Please check the readability and let me know :)

[haticekaratay]

I noticed that you have already implemented the code in the above cell. Could you please do the same for this code cell?

[haticekaratay]

Hi @srosagomez,
I liked your notebook—it’s well-written and easy to follow. There’s not much that needs updating. I’ve added a few minor comments above, but that’s it!

Great job, and thanks for your work on this!

[haticekaratay]

This is a new notebook. Could you also please update the toc.yml so that it renders on the HTML pages?

[haticekaratay]

Thanks for your work! All looks good to me!