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. If you would like to run black yourself do
pip install black[jupyter]
and then black
.
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.
Recommended libraries
Mapping + Visualization
- folium: folium adds Leaflet.js support to python projects for visualizing data in a map.
- holoviz: High-level tools that make it easier to apply Python plotting libraries to your data.
- ipyleaflet: Interactive maps in the Jupyter notebook. ipyleaflet is built on ipywidgets allowing for bidirectional communication between front- and backends (learn more: Interactive GIS in Jupyter with ipyleaflet).
Using STAC for cataloging data
To present consistent best practices, we always access data via the STAC API.
- pystac: PySTAC is a library for creating SpatioTemporal Asset Catalogs (STAC) in Python 3.
- pystac-client: A Python client for working with STAC Catalogs and APIs.
Analyzing data
- rioxarray: rasterio xarray extension
- stackstac: stackstac.stack turns a STAC collection into a lazy xarray.DataArray, backed by dask.
Generate “Launch in VEDA JupyterHub” link
We use nbgitpuller
links to open the VEDA JupyterHub with a particular notebook pulled in. These links have the form: https://hub.openveda.cloud/hub/user-redirect/git-pull?repo=https://github.com/NASA-IMPACT/veda-docs&urlpath=lab/tree/veda-docs/notebooks/quickstarts/open-and-plot.ipynb&branch=main
If you are writing a notebook and want to share it with others you can generate your own nbgitpuller
link using this link generator.