From 7e7635cf7f709f94520e1bc5270df4dd5cac3bed Mon Sep 17 00:00:00 2001 From: Kan Fu Date: Thu, 22 Jan 2026 14:11:24 -0800 Subject: [PATCH 1/2] Update README for guideline and catalog --- README.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 163 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 0c87544..2a8b9b7 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,167 @@ # Python Community Notebooks -Welcome to the **Python Community Notebooks** repository! This collection of Python Jupyter Notebooks is designed to help the user community -explore how to use [onc](https://github.com/OceanNetworksCanada/api-python-client) client library for real-world data manipulation, analysis, and visualization tasks. +## Overview -This repository is intended to be a resource for users of all levels who want to deepen their understanding of Ocean Networks Canada data and its capabilities. -Contribute, share your feedback, and help grow the community of onc users! +The **Python Community Notebooks** repository contains a curated collection of Jupyter notebooks demonstrating practical applications of the [onc](https://github.com/OceanNetworksCanada/api-python-client) Python client library. These notebooks showcase practices for data manipulation, analysis, and visualization using Ocean Networks Canada (ONC) datasets. -Be advised that community scripts are not regulated, endorsed, developed or maintained by Ocean Networks Canada. All feature & bug-fix requests must be sent to the code's original author. +This repository serves as a learning resource for users at all levels seeking to deepen their understanding of oceanographic data processing and analysis techniques. + +### Disclaimer + +Community notebooks are provided as-is and are not regulated, endorsed, developed, or maintained by Ocean Networks Canada. All feature requests and bug reports must be directed to the original notebook author. + +## Quick Start + +### Prerequisites + +- Python 3.10+ +- An ONC API token (see [Token Configuration](#token-configuration)) +- Virtual environment (recommended) + +### Setup + +1. **Clone the repository** + ```bash + git clone https://github.com/OceanNetworksCanada/python-community-notebooks.git + cd python-community-notebooks + ``` + +2. **Create and activate a virtual environment** + ```bash + python -m venv .venv + source .venv/bin/activate # On Windows: .venv\Scripts\activate + ``` + +3. **Install dependencies** + ```bash + pip install -r XXX/requirements.txt # Adjust the path as needed + ``` + +4. **Configure your ONC token** (see [Token Configuration](#token-configuration)) + +5. **Launch Jupyter in the terminal or using your favorite IDE** + ```bash + jupyter notebook + ``` + +## Notebook Catalog + +### IanTBlack + +#### barkley_canyon_vertical_profiler/ + +- **bacvp_ctd_up_profiles.ipynb** + Demonstrates the creation of vertical profile plots for sea water potential density using CTD data. + *Keywords:* gsw + +- **bacvp_videocam_opencv.ipynb** + Illustrates video processing and frame extraction from videocam sources. + *Keywords:* opencv-python, video + + +#### british_columbia_ferries/ + +- **distance_from_terminals.ipynb** + Computes and visualizes time series data for ferry-to-terminal distances using geospatial calculations. + *Keywords:* geopy, xarray + +- **grid_transit.ipynb** + Analyzes transit grid patterns and routing through ferry data. + *Keywords:* xarray + +- **system_sampling_state.ipynb** + Examines sampling state and temporal coverage of ferry system measurements. + *Keywords:* + +- **transit_identifier.ipynb** + Identifies and classifies distinct transit events within ferry operational data. + *Keywords:* + +- **twsb_tsg_clean_no_gaps.ipynb** + Performs data quality assurance and gap-filling for TSG (Thermosalinograph) measurements. + *Keywords:* xarray + + +#### multiple_datasets/ + +- **fraser_river_plume.ipynb** + Analyzes and visualizes the transport and evolution of the Fraser River plume using multi-source oceanographic data. + *Keywords:* hypercoast, xarray, cartopy, gsw, plume + +## Guidelines and Best Practices + +The following guidelines are recommended for consistency across contributed notebooks. Individual contributors may maintain their own conventions; consult their notebook documentation for specific implementation details. + +### Token Configuration + +Authentication to the ONC API requires a personal token. For instructions on obtaining a token, refer to the [api-python-client documentation](https://github.com/OceanNetworksCanada/api-python-client#obtaining-a-token). + +#### Recommended: Environment Variable Storage + +Store your token as an environment variable rather than hardcoding it in notebooks. The `onc` library (version 2.6.0+) automatically reads the `ONC_TOKEN` environment variable when instantiating the `ONC` class. + +**Configuration Steps:** + +1. Create a `.env` file in the repository root: + ``` + ONC_TOKEN=your_token_here + ``` + +2. Add the initialization code to your notebook: + ```python + from dotenv import load_dotenv + from onc import ONC + + load_dotenv() + onc = ONC() # Automatically uses ONC_TOKEN from environment + ``` + +The `load_dotenv()` function searches for the `.env` file in the current directory and parent directories, allowing all notebooks to share a single configuration file. + +### Dependency Management + +#### Virtual Environments + +Since different notebooks may require conflicting library versions, **always use virtual environments** to isolate dependencies. You can also use [uv](https://docs.astral.sh/uv/pip/environments/) or IDEs like [VS Code](https://code.visualstudio.com/docs/python/environments) and [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) to manage virtual environments. + +You may create multiple virtual environments for different notebook sets if needed. + +#### Requirements Files + +Each contributor should maintain a `requirements.txt` file documenting all external library dependencies. You may maintain: +- A single `requirements.txt` covering all your notebooks +- Multiple `requirements.txt` files for notebook-specific dependencies + +#### Installation in Notebooks + +Optionally include an initialization cell to install dependencies within a notebook: +```python +!pip install -r ./requirements.txt # Adjust path as needed +``` + +## Contributing + +Contributions are welcome! When adding new notebooks, please follow these standards: + +### Notebook Structure + +- Include a descriptive title and markdown cells explaining the analysis objective +- Optionally add a brief overview of the data sources and processing steps +- Document all external dependencies in a `requirements.txt` file +- Use clear variable names and include inline comments for complex calculations +- Add your notebook description to this README under the appropriate category. Common dependency libraries like `numpy`, `pandas`, `matplotlib` and `onc` can be omitted in the keywords. + +### Code Organization + +Helper functions and shared utilities could be organized in separate Python modules. To import modules from parent directories within notebooks, use the standard `sys` library, or the notebooks magic command `%cd`: + +```python +import sys +sys.path.append('..') +import module_name +``` + +```python +%cd .. +import module_name +``` \ No newline at end of file From 746421d84d19fb189a7eba7c7a6d62975eafa400 Mon Sep 17 00:00:00 2001 From: Kan Fu Date: Thu, 22 Jan 2026 14:14:05 -0800 Subject: [PATCH 2/2] Move notebooks --- .../barkley_canyon_vertical_profiler}/bacvp_ctd_up_profiles.ipynb | 0 .../barkley_canyon_vertical_profiler}/bacvp_videocam_opencv.ipynb | 0 .../british_columbia_ferries}/distance_from_terminals.ipynb | 0 .../british_columbia_ferries}/grid_transit.ipynb | 0 .../british_columbia_ferries}/system_sampling_state.ipynb | 0 .../british_columbia_ferries}/transit_identifier.ipynb | 0 .../british_columbia_ferries}/twsb_tsg_clean_no_gaps.ipynb | 0 .../multiple_datasets}/fraser_river_plume.ipynb | 0 pcn_common.py => IanTBlack/pcn_common.py | 0 requirements.txt => IanTBlack/requirements.txt | 0 10 files changed, 0 insertions(+), 0 deletions(-) rename {barkley_canyon_vertical_profiler => IanTBlack/barkley_canyon_vertical_profiler}/bacvp_ctd_up_profiles.ipynb (100%) rename {barkley_canyon_vertical_profiler => IanTBlack/barkley_canyon_vertical_profiler}/bacvp_videocam_opencv.ipynb (100%) rename {british_columbia_ferries => IanTBlack/british_columbia_ferries}/distance_from_terminals.ipynb (100%) rename {british_columbia_ferries => IanTBlack/british_columbia_ferries}/grid_transit.ipynb (100%) rename {british_columbia_ferries => IanTBlack/british_columbia_ferries}/system_sampling_state.ipynb (100%) rename {british_columbia_ferries => IanTBlack/british_columbia_ferries}/transit_identifier.ipynb (100%) rename {british_columbia_ferries => IanTBlack/british_columbia_ferries}/twsb_tsg_clean_no_gaps.ipynb (100%) rename {multiple_datasets => IanTBlack/multiple_datasets}/fraser_river_plume.ipynb (100%) rename pcn_common.py => IanTBlack/pcn_common.py (100%) rename requirements.txt => IanTBlack/requirements.txt (100%) diff --git a/barkley_canyon_vertical_profiler/bacvp_ctd_up_profiles.ipynb b/IanTBlack/barkley_canyon_vertical_profiler/bacvp_ctd_up_profiles.ipynb similarity index 100% rename from barkley_canyon_vertical_profiler/bacvp_ctd_up_profiles.ipynb rename to IanTBlack/barkley_canyon_vertical_profiler/bacvp_ctd_up_profiles.ipynb diff --git a/barkley_canyon_vertical_profiler/bacvp_videocam_opencv.ipynb b/IanTBlack/barkley_canyon_vertical_profiler/bacvp_videocam_opencv.ipynb similarity index 100% rename from barkley_canyon_vertical_profiler/bacvp_videocam_opencv.ipynb rename to IanTBlack/barkley_canyon_vertical_profiler/bacvp_videocam_opencv.ipynb diff --git a/british_columbia_ferries/distance_from_terminals.ipynb b/IanTBlack/british_columbia_ferries/distance_from_terminals.ipynb similarity index 100% rename from british_columbia_ferries/distance_from_terminals.ipynb rename to IanTBlack/british_columbia_ferries/distance_from_terminals.ipynb diff --git a/british_columbia_ferries/grid_transit.ipynb b/IanTBlack/british_columbia_ferries/grid_transit.ipynb similarity index 100% rename from british_columbia_ferries/grid_transit.ipynb rename to IanTBlack/british_columbia_ferries/grid_transit.ipynb diff --git a/british_columbia_ferries/system_sampling_state.ipynb b/IanTBlack/british_columbia_ferries/system_sampling_state.ipynb similarity index 100% rename from british_columbia_ferries/system_sampling_state.ipynb rename to IanTBlack/british_columbia_ferries/system_sampling_state.ipynb diff --git a/british_columbia_ferries/transit_identifier.ipynb b/IanTBlack/british_columbia_ferries/transit_identifier.ipynb similarity index 100% rename from british_columbia_ferries/transit_identifier.ipynb rename to IanTBlack/british_columbia_ferries/transit_identifier.ipynb diff --git a/british_columbia_ferries/twsb_tsg_clean_no_gaps.ipynb b/IanTBlack/british_columbia_ferries/twsb_tsg_clean_no_gaps.ipynb similarity index 100% rename from british_columbia_ferries/twsb_tsg_clean_no_gaps.ipynb rename to IanTBlack/british_columbia_ferries/twsb_tsg_clean_no_gaps.ipynb diff --git a/multiple_datasets/fraser_river_plume.ipynb b/IanTBlack/multiple_datasets/fraser_river_plume.ipynb similarity index 100% rename from multiple_datasets/fraser_river_plume.ipynb rename to IanTBlack/multiple_datasets/fraser_river_plume.ipynb diff --git a/pcn_common.py b/IanTBlack/pcn_common.py similarity index 100% rename from pcn_common.py rename to IanTBlack/pcn_common.py diff --git a/requirements.txt b/IanTBlack/requirements.txt similarity index 100% rename from requirements.txt rename to IanTBlack/requirements.txt