From d76e20828afc05416b3605baa01e3d8769a690b5 Mon Sep 17 00:00:00 2001 From: Eshanta Mishra Date: Wed, 12 Aug 2026 19:22:23 +0000 Subject: [PATCH] Add GeoLab notebook template --- templates/GeoLab_Notebook_Template.ipynb | 435 +++++++++++++++++++++++ 1 file changed, 435 insertions(+) create mode 100644 templates/GeoLab_Notebook_Template.ipynb diff --git a/templates/GeoLab_Notebook_Template.ipynb b/templates/GeoLab_Notebook_Template.ipynb new file mode 100644 index 0000000..e21b3cd --- /dev/null +++ b/templates/GeoLab_Notebook_Template.ipynb @@ -0,0 +1,435 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "a399d3b5-94f5-4ff2-8632-b56060e80bac", + "metadata": {}, + "source": [ + "> **TEMPLATE INSTRUCTIONS — delete this entire cell before publishing**\n", + ">\n", + "> This template is designed to help you create consistent, easy-to-follow GeoLab instructional notebooks.\n", + "> The sections below are a suggested structure, so feel free to rename, split, or reorder them to fit your workflow.\n", + "> \n", + "> Before publishing:\n", + ">\n", + "> * Replace all `[Bracketed Placeholders]` throughout the notebook with your content.\n", + "> * Delete any block quote `AUTHOR NOTE (Remove this text)` section.\n", + ">\n", + "> ---\n", + ">\n", + "> **Markdown Style Guide**\n", + ">\n", + "> | Element | Convention |\n", + "> |---|---|\n", + "> | Section headers | `##` for main sections, `###` for sub-sections. Don't skip levels (e.g. no `####` under `##`). |\n", + "> | Bullets | Use `*` for unordered lists, `1.` for ordered/sequential steps.|\n", + "> | Code references | Use backticks for inline code, variable names, and file paths, e.g. `DATA_DIR`. |\n", + "> | Callouts | Use `>` blockquotes for notes, checks, and warnings. |\n", + ">\n", + "> ---\n", + ">\n", + "> **Creating links (Markdown syntax)**\n", + ">\n", + "> ```\n", + "> [Link text](URL)\n", + "> ```\n", + "> Example: `[GeoLab Documentation](https://docs.earthscope.org/geolab)`\n", + ">\n", + "> Links should be left as the default rendered style (underlined, blue). Do not manually style or remove the underline.\n", + ">\n", + "> ---\n", + ">\n", + "> **Equations (LaTeX)**\n", + ">\n", + "> Jupyter markdown cells support LaTeX for mathematical equations. Use inline math for short expressions within a sentence, and display math for standalone equations.\n", + ">\n", + "> | Type | Syntax | Example |\n", + "> |---|---|---|\n", + "> | Inline | `$ ... $` | `$E = mc^2$` |\n", + "> | Display (own line, centered) | `$$ ... $$` | `$$\\int_0^\\infty e^{-x^2}\\,dx = \\frac{\\sqrt{\\pi}}{2}$$` |\n", + ">\n", + "> Use inline math when the equation is short and part of a sentence, e.g. \"the residual is $r_i = y_i - \\hat{y}_i$.\" Use display math for anything with fractions, sums, integrals, or multi-line derivations, since these are hard to read inline." + ] + }, + { + "cell_type": "markdown", + "id": "2abe5d1d-4a2f-4c96-a78c-6c3e5f9ac750", + "metadata": {}, + "source": [ + "# [Notebook Title]" + ] + }, + { + "cell_type": "markdown", + "id": "35320cb4-aed2-4420-8f9c-b3deb365e792", + "metadata": {}, + "source": [ + "**Version:** 1.0 | **Last updated:** [YYYY-MM-DD] | \n", + "\n", + "**Author(s):** [Author(s) Name] | **Author(s) institution:** [Author(s) institution]\n", + "\n", + "**Maintainer (optional):** [Maintainer's name] | **Maintainer's contact (optional):** [Maintainer's contact info]\n", + "\n", + "**Estimated Time:** [Estimated time to complete the notebook] | **Pathway (optional):** [Pathway name if available, eg: MVP1]\n", + "\n", + "**License:** [License type, eg: CC-BY-4.0]\n", + "\n", + "**Citation (optional):** [Optional citation info for citing the notebook]" + ] + }, + { + "cell_type": "markdown", + "id": "b9b1d1c3-569f-459a-8595-e1ba758e4bc7", + "metadata": {}, + "source": [ + "## Introduction\n", + "\n", + "> AUTHOR NOTE (Remove this text): Write 3–5 brief sentences covering all three points below.\n", + "\n", + "\n", + "**What this notebook does:** [Describe the workflow in one sentence.]\n", + "\n", + "**Why it is useful:** [Explain the geophysical application or problem it solves.]\n", + "\n", + "**What you will accomplish:** [Describe the concrete output or result the user will produce.]\n", + "\n", + "---\n", + "\n", + "### Prerequisites\n", + "\n", + "> AUTHOR NOTE (Remove this text): List everything a user needs before starting.\n", + "If this notebook follows another in a sequence, name it explicitly.\n", + "\n", + "Before starting this notebook, you should:\n", + "\n", + "* [ ] Have completed: [*Previous Notebook Name*] *(if applicable)*\n", + "* [ ] Be familiar with: [e.g. basic Python, pandas DataFrames]\n", + "\n", + "---\n", + "\n", + "### GeoLab Compute Resources\n", + "\n", + "> AUTHOR NOTE (Remove this text): Specify the recommended image and server size.\n", + "Check the GeoLab documentation for current options.\n", + "\n", + "| Setting | Recommended |\n", + "|---|---|\n", + "| **Image** | [e.g. `GeoLab`] |\n", + "| **Server size** | [e.g. 4 GB RAM, ~0.5 CPUs] |" + ] + }, + { + "cell_type": "markdown", + "id": "811fc68e-1e81-482c-82dd-5efa2a89d715", + "metadata": {}, + "source": [ + "## Learning Objectives\n", + "\n", + "> AUTHOR NOTE (Remove this text): Write 2–4 objectives. Start each with an action verb (e.g. Load, Stream, Calculate, Visualize, Apply).\n", + "These should match the skills demonstrated in the notebook.\n", + "\n", + "By the end of this notebook, you will be able to:\n", + "\n", + "1. [Action verb + skill, e.g. \"Stream GNSS data in pyArrow format.\"]\n", + "2. [Action verb + skill]" + ] + }, + { + "cell_type": "markdown", + "id": "1ec3d79a-ad70-4c58-b8fc-287501adb7e9", + "metadata": {}, + "source": [ + "## Relevant Documentation & Resources\n", + "\n", + "> AUTHOR NOTE (Remove this text): Link to docs for any external tools, APIs, or datasets used.\n", + "\n", + "* [Documentation 1](URL)\n", + "* [Resource 1](URL)" + ] + }, + { + "cell_type": "markdown", + "id": "076d400d-8c88-4113-a28d-91dac8648679", + "metadata": {}, + "source": [ + "## Contents\n", + "\n", + "> AUTHOR NOTE (Remove this text): Update this list to match your actual section titles once the notebook is complete. \n", + "To get the correct link for each heading, hover over the rendered heading and click the link(¶) icon that appears beside it. \n", + "This updates the browser address bar with the full URL. Copy the anchor from the end of it (e.g. #id-2-data-loading).\n", + "\n", + "1. [Setup & Imports](#id-1-setup-imports)\n", + "2. [Data Loading](#id-2-data-loading)\n", + "3. [Data Exploration](#id-3-data-exploration)\n", + "4. [\\[Core Workflow Step\\]](#id-4-core-workflow-step)\n", + "5. [Visualization](#id-5-visualization)\n", + "6. [Practice & Exploration](#id-6-practice-exploration)\n", + "7. [Troubleshooting & Support](#id-7-troubleshooting-support)" + ] + }, + { + "cell_type": "markdown", + "id": "cca79b91-0348-4ee2-842e-740595288820", + "metadata": {}, + "source": [ + "## 1. Setup & Imports" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "8cd2903c-1b18-4877-a421-f19374f8fcf3", + "metadata": {}, + "outputs": [], + "source": [ + "# Standard library imports\n", + "import os\n", + "\n", + "# Third-party imports\n", + "# TODO: Replace with the libraries your notebook actually uses\n", + "import numpy as np\n", + "import pandas as pd" + ] + }, + { + "cell_type": "markdown", + "id": "aa3e8c77-ceaf-4f6e-be2e-b99b0b7f0125", + "metadata": {}, + "source": [ + "> AUTHOR NOTE (Remove this text): If users need to set any configuration variables (e.g. file paths, date ranges, area of interest), \n", + "define them in one clearly labelled cell so users know exactly what to change.\n", + "\n", + "### Configuration\n", + "\n", + "Set your parameters here before running the rest of the notebook." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "15ecb388-d718-4949-a072-5db6cd398d65", + "metadata": {}, + "outputs": [], + "source": [ + "# Modify these values before running the notebook.\n", + "\n", + "DATA_DIR = \"./data\" # Path to input data\n", + "OUTPUT_DIR = os.path.join(os.environ[\"SCRATCH_BUCKET\"], \"output\") # Path for saving results in SCRATCH folder\n", + "# PARAM_NAME = value # TODO: Add your parameters here\n", + "\n", + "#create directories if needed\n", + "os.makedirs(OUTPUT_DIR, exist_ok=True)\n", + "\n", + "print(f\"Configuration set. Outputs will be saved to: {OUTPUT_DIR}\")" + ] + }, + { + "cell_type": "markdown", + "id": "c1c52777-0410-4a6f-b3e6-198cfeebb318", + "metadata": {}, + "source": [ + "## 2. Data Loading\n", + "\n", + "> AUTHOR NOTE (Remove this text): Before the code, briefly explain:\n", + "> * What data is being loaded (format, source, size)\n", + "> * Why this data is used for this workflow\n", + "> * What the expected result of loading looks like\n", + "\n", + "\n", + "**What:** [Describe the dataset — format, source.]\n", + "\n", + "**Why:** [Explain why this dataset is appropriate for the workflow.]\n", + "\n", + "**Expected result:** After running the cell below, you should see [describe expected output, e.g. \"a summary of the dataset with X rows and Y columns\"]." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "475dd2e2-9db8-453d-b495-d6afa1417d8b", + "metadata": {}, + "outputs": [], + "source": [ + "# TODO: Replace this with your actual data loading code\n", + "# Example:\n", + "# df = pd.read_csv(os.path.join(DATA_DIR, \"your_file.csv\"))\n", + "# print(f\"Loaded {len(df)} rows and {df.shape[1]} columns.\")" + ] + }, + { + "cell_type": "markdown", + "id": "6069a914-e056-472a-a968-516aff9acf58", + "metadata": {}, + "source": [ + "## 3. Data Exploration\n", + "\n", + "> AUTHOR NOTE (Remove this text): Guide the user to inspect and understand the data before processing. Explain what they should look for in the output.\n", + "\n", + "Before processing, take a moment to understand the structure of the data.\n", + "The cells below examine [describe what aspects you're exploring, e.g. \"the column names, data types, and a sample of values\"].\n", + "\n", + "**What to look for:** [Tell users what an expected dataset looks like here, e.g. \"You should see X columns with values in the range of Y - Z\"]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "161efa31-b733-4d24-a5de-595b688bf9ae", + "metadata": {}, + "outputs": [], + "source": [ + "# TODO: Add exploration code, e.g.:\n", + "# df.head() # View the first few rows\n", + "# df.info() # Check data types and missing values\n", + "# df.describe() # Summary statistics" + ] + }, + { + "cell_type": "markdown", + "id": "b3f044a4-6ee3-4aba-a4c9-74793839fd72", + "metadata": {}, + "source": [ + "## 4. [Core Workflow Step]\n", + "\n", + "> AUTHOR NOTE (Remove this text): Rename this section to match your workflow step, e.g. \"4. Cleaning GNSS data\". Add more sections (5, 6...) if your workflow has multiple steps. Each major step should be its own section.\n", + "\n", + "### What is [concept name]?\n", + "\n", + "> AUTHOR NOTE (Remove this text): If this section introduces a new concept, explain it briefly before any code appears. Cover: what it does, why it matters, what to expect.\n", + "\n", + "**What it does:** [Explain the concept or operation in plain language.]\n", + "\n", + "**Why it matters:** [Explain the relevance to the workflow or real-world application.]\n", + "\n", + "**Expected output:** [Describe what a successful result looks like.]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "42de7c31-9908-4286-92fb-4afa03f5f297", + "metadata": {}, + "outputs": [], + "source": [ + "# Step description: [One-line comment describing what this cell does]\n", + "# TODO: Add your workflow code here" + ] + }, + { + "cell_type": "markdown", + "id": "0cad076e-a951-416e-ad88-96dd7fe1f253", + "metadata": {}, + "source": [ + "> AUTHOR NOTE (Remove this text): After important steps, always confirm what success looks like. This helps users catch errors early.\n", + "\n", + "> **Check:** If the cell above ran successfully, you should see [describe expected output].\n", + "> If you see an error, refer to the [Troubleshooting](#id-7-troubleshooting-support) section." + ] + }, + { + "cell_type": "markdown", + "id": "7a66e9a7-c8c7-4b1d-91da-0e4471397815", + "metadata": {}, + "source": [ + "## 5. Visualization\n", + "\n", + "> AUTHOR NOTE (Remove this text): Explain what the visualization shows and how to interpret it. Users should understand what they're looking at before they see it.\n", + "\n", + "The plot below shows [describe what the visualisation represents and what patterns or features the user should look for].\n", + "\n", + "**What to look for:** [Help users with the interpretation, e.g. \"Offsets in the GNSS data could be a sign of earthquake or hardware issues,\"]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "538f9587-fa9f-4e50-a746-b8d2b9c28f25", + "metadata": {}, + "outputs": [], + "source": [ + "# TODO: Add your visualisation code here\n", + "# Example:\n", + "# import matplotlib.pyplot as plt\n", + "# fig, ax = plt.subplots(figsize=(10, 6))\n", + "# ax.set_title(\"[Your Plot Title]\")\n", + "# plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "c5008800-7811-4fbc-9721-9869da927fc2", + "metadata": {}, + "source": [ + "## 6. Practice & Exploration\n", + "\n", + "> AUTHOR NOTE (Remove this text): Provide 2–4 suggested modifications for users to try. These should be concrete and achievable, building on what they've just done. Tie each suggestion back to a learning objective where possible.\n", + "\n", + "Now that you've completed the core workflow, try modifying the parameters below to explore how the results change.\n", + "\n", + "**Try these modifications:**\n", + "\n", + "1. **[Modification 1]:** Change `[PARAMETER_NAME]` in the Configuration section to `[suggested value]` and re-run the notebook. What changes?\n", + "\n", + "2. **[Modification 2]:** [Describe a meaningful variation to try.]\n", + "\n", + "3. **[Modification 3]:** [Describe a more advanced extension for curious users.]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "edf9b94a-b045-4fcf-be34-f2e2f958f124", + "metadata": {}, + "outputs": [], + "source": [ + "# Exploration cell — use this space to experiment" + ] + }, + { + "cell_type": "markdown", + "id": "1e147f5a-2352-4a16-b28b-3f5c1dbea902", + "metadata": {}, + "source": [ + "## 7. Troubleshooting & Support\n", + "\n", + "> AUTHOR NOTE (Remove this text): List the most common errors users are likely to hit in this specific notebook. Be concrete i.e. describe the actual error message, then the fix. Add links to relevant docs or FAQs.\n", + "\n", + "### Common Issues\n", + "\n", + "| Error | Likely cause | Fix |\n", + "|---|---|---|\n", + "| `FileNotFoundError` on data load | Incorrect `DATA_DIR` path | Check the path in the Configuration section |\n", + "| `ModuleNotFoundError: No module named '[x]'` | Missing library | Run `!pip install [x]` in a new cell |\n", + "| [Other common error] | [Cause] | [Fix] |\n", + "\n", + "### Further Resources\n", + "\n", + "> AUTHOR NOTE (Remove this text): Link to GeoLab documentation and community forum. Add links to notebook (or the tools used in the notebook) specific documentation or community forum too, so that the user can continue to troubleshoot independently.\n", + "\n", + "* [GeoLab Documentation](https://docs.earthscope.org/geolab)\n", + "* [GeoLab Community Forum](https://earthscope.discourse.group/latest)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "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.12.13" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}