Usage Example Notebook Submission

Conventions for Jupyter notebooks

Contribution to VEDA’s documentation is always welcome - just open a Pull Request on the veda-docs repository.

You can submit a PR by forking the repository and submitting a PR with your fork. However, PR previews will not work for PRs from forks. You can push directly to this repository by becoming a collaborator. If you are not already a collaborator of the veda-docs repository, please email your github handle and veda@uah.edu along with a message like “please add me as a collaborator to the veda-docs repository so I can push a branch”. If you are not someone already familiar with the VEDA team, please add some additional information about your interest in contributing to the documentation.

Once you are a collaborator, you will be able to submit a PR from a branch of this repository (that is, not a branch from a fork) and PR previews will help in the review process.

Please note that this documentation site is rendered using Quarto, which adds a small set of configuration options on top of vanilla Markdown and Jupyter Notebooks.

Notebook Author Guidelines

There are two template notebooks in this section that you can use as a starting place. Alternatively you can pull specific cells from that notebook into your own.

Style

  • Each code cell should come after a markdown cell with some explanatory text. This is preferred over comments in the code cells.
  • The max header should be ##.
  • Only include imports that are needed for the notebook to run.
  • We don’t enforce any formatting, but periodically run black on all the notebooks. We also encourage you to run black on your notebooks via pre-commit, following the instructions below on automatic linting with pre-commit.

Automatic linting with pre-commit

This repository is configured with pre-commit, which can automatically lint your notebooks anytime you git commit changes. Follow these steps to enable pre-commit (you only need to do this once):

  1. Install the pre-commit library.
  2. Open a terminal.
  3. Navigate to the root of the veda-docs repository.
  4. Run pre-commit install.

Rendering information

The first cell in every notebook is a raw cell that contains the following metadata for rendering with our site builder Quarto.

---
title: Short title
description: One sentence description
author: Author Name
date: May 2, 2023
execute:
  freeze: true
---

Running notebooks

We store evaluated notebooks in this repository. So before you commit your notebook, you should restart your kernel and run all cells in order.

Normally we run the notebooks on VEDA JupyterHub.

To run the notebooks with a new image, use the JupyterHub image selection interface and under “Custom Image” type in the address to the public ecr image with the full tag sha.

Something like: public.ecr.aws/nasa-veda/pangeo-notebook:60b023fba2ca5f9e19d285c245987e368e27c0ea626b65777b204cec14b697c7

Standard sections

To give the notebooks a standard look and feel we typically include the following sections:

  • Run this Notebook: The section explains how to run the notebook locally, on VEDA JupyterHub or on mybinder. There are several examples of what this section can look like in the template notebooks.
  • Approach: List a few steps that outline the approach you be taking in this notebook.
  • About the data: Optional description of the dataset
  • Declare your collection of interest: This section reiterates how you can discover which collections are available. You can copy the example of this section from one of the template notebooks.

From then on the standard sections diverge depending on whether the notebook access the data directly or uses the raster API. Check the template notebooks for some ideas of common patterns.

Using complex geometries

If you are defining the AOI using a bounding box, you can include it in the text of the notebook, but for more complex geometries we prefer that the notebook access the geometry directly from a canonical source. You can check the template notebooks for examples of this. If the complex geometry is not available online the VEDA team can help get it up in a public s3 bucket.