bgc-argo-tutorials: A practical guide to biogeochemical Argo data analysis

bgc-argo-tutorials provides a series of lessons on the analysis of biogeochemical Argo (BGC-Argo) data written in Python and Jupyter Notebook. Specifically, bgc-argo-tuorials teaches you how to search, identify, download, visualize, and post-process the vertical profiles of physical and biogeochemical oceanographic variables measured by autonomous floats in the global ocean. An overview of bgc-argo-tutorials is provided as a peer-reviewed article in the Journal of Open Source Education. If you find bgc-argo-tutorials useful, please consider citing our paper:

Fujishima, H. and Hayashida, H. (submitted): bgc-argo-tutorials: A practical guide to biogeochemical Argo data analysis, Journal of Open Source Education.

🚨 Ready to dive into BGC-Argo data but not sure where to begin? Give bgc-argo-tutorials a try!

---

🚀 Getting Started

To try bgc-argo-tutorials, click on , which allows you to test our Jupyter Notebooks (i.e., lessons) on cloud. This is useful if you do not have a Jupyter environment or if you just want to check out bgc-argo-tutorials before installing them.

To install bgc-argo-tutorials on your local system, the best way is to use git for keeping your copy up to date with the source.

🛠️ Installation and Setup

We highly recommend using conda to manage your Python environment, as it automatically handles the complex system-level dependencies required for oceanographic mapping tools (like cartopy). However, if your institution restricts conda, we also provide a standard pip installation method.

1. Clone the repository and navigate into it:

   git clone https://github.com/hakaseh/bgc-argo-tutorials.git
   cd bgc-argo-tutorials
   

Option 1: Using Conda (Recommended)

1. Create the environment from the provided YAML file:

   conda env create -f environment.yml
   

2. Activate the environment:

   conda activate bgc-argo-tutorials
   

Option 2: Using Pip (For Non-Conda Users)

1. Create a Python virtual environment:

   python -m venv env
   

2. Activate the virtual environment:

   On macOS and Linux:

   source env/bin/activate
   

   On Windows:

   env\Scripts\activate
   

3. Install the required packages:

   pip install -r requirements.txt
   

   🚨 A note on cartopy for pip users: The cartopy mapping library requires underlying system binaries (specifically GEOS and PROJ). While pip usually installs pre-compiled versions successfully, older or highly restricted operating systems might throw compiler errors. If this happens, you may need to install the geos and proj system binaries locally before pip install will work.

Final step (common to both conda and pip)

Register this specific environment as a permanent Jupyter kernel:

python -m ipykernel install --user --name=bgc-argo-tutorials --display-name="bgc-argo-tutorials"

Finally, launch Jupyter (e.g., jupyter notebook or jupyterlab), open lesson_01.ipynb. It should automatically set bgc-argo-tutorials as your kernel. If not, select that kernel from the notebook's drop-down menu on the upper-right corner. Now you are all set!

Re-opening

When you re-open bgc-argo-tutorials, take the following steps:

1. Open your Terminal.
2. Go to the bgc-argo-tutorials directory (i.e., cd bgc-argo-tutorials).
3. Activate your virtual environment (i.e., source env/bin/activate for Mac/Linux and env\Scripts\activate for Windows).
4. Start the Jupyter session (i.e., jupyter notebook or jupyterlab).

Directory Structure

bgc-argo-tutorials consists of the following folders:

• lessons contains the main Jupyter Notebook tutorials.
• index_files contains customized index files generated in lessons.
• figures contains figures generated in lessons.
• floats contains the float time series and individual profiles downloaded in Lesson 3 and the interpolated time series generated in lessons.
• _drafts contains lessons in progress (incomplete and untested).

Workshop

We introduced bgc-argo-tutorials to the OneArgo community by holding a side event at the OneArgo International Workshop in Sendai, Japan, on June 2, 2026. The recording is available on YouTube. The presentation slides can be downloaded from this link.

🗳️ Feedback

We want to hear your thoughts! Please feel free to provide your user experience by visiting this link. Your feedback will help us improve the contents of bgc-argo-tutorials.

☎️ Contact

For questions and comments, feel free to create a new issue or replying to an existing one by visiting Issues. Alternatively, you may send a message to @hakaseh.

📚 Resources

• Argo Online School: An e-learning tool to get started with Argo
• Bittig et al. (2019): An overview of the BGC-Argo program
• Claustre et al. 2020: A review of the BGC-Argo program
• Wong et al. 2020: A 20-year history of the Argo prgoram
• OceanOPS Argo map: A mapping tool for Argo float distributions
• Argo fleet monitoring: A tracking tool for Argo floats
• Peer-reviewed articles using the BGC-Argo data
• Argopy: A Python library for Argo data analysis
• BGC-Argo data products: Post-processed data products
• BGC-Argo+: A dataset containing all available biogeochemical Argo data with a secondary quality control applied. Data available as individual float files or in monthly 1x1 gridded options.
• EasyOneArgo

🗃️ Old Repo

bgc-argo-tutorials was initially hosted on Gitlab, but was later moved to Github for the JOSE submission. We kept the old repository for reference to issues.

🇯🇵　日本語 (Japanese Language Support)

bgc-argo-tutorialsでは、日本語によるサポートやワークショップも実施しております。お気軽にお問い合わせください（海洋研究開発機構　林田博士）。