From b20b9819e9e11a179f15819eccf6ba23a316e412 Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Tue, 3 Feb 2026 15:06:19 +0100 Subject: [PATCH 1/9] remove duplicates and add thumbnail for surf tutorials --- docs/conf.py | 2 ++ docs/user-guide/_images/surf_logo.png | Bin 0 -> 6194 bytes docs/user-guide/tutorials/index.md | 2 -- 3 files changed, 2 insertions(+), 2 deletions(-) create mode 100644 docs/user-guide/_images/surf_logo.png diff --git a/docs/conf.py b/docs/conf.py index ceb8c01a..fa39fbb3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -80,6 +80,8 @@ "user-guide/teacher-content/ILOs": "user-guide/_images/ILOs.jpg", "user-guide/teacher-content/UU-ocean-of-future/Tutorial1": "user-guide/_images/freepik_assignment.png", "user-guide/teacher-content/UU-ocean-of-future/Tutorial2": "user-guide/_images/freepik_assignment.png", + "user-guide/tutorials/surf_collaborative_setup.ipynb": "user-guide/_images/surf_logo.png", + "user-guide/tutorials/surf_research_cloud_setup.ipynb": "user-guide/_images/surf_logo.png", } sphinx_gallery_conf = {"default_thumb_file": "_static/virtual_ship_logo.png"} diff --git a/docs/user-guide/_images/surf_logo.png b/docs/user-guide/_images/surf_logo.png new file mode 100644 index 0000000000000000000000000000000000000000..df11f91dcb6f1c49d30ce9eee85a992a89e567cc GIT binary patch literal 6194 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 literal 0 HcmV?d00001 diff --git a/docs/user-guide/tutorials/index.md b/docs/user-guide/tutorials/index.md index f2fab7b4..49190b66 100644 --- a/docs/user-guide/tutorials/index.md +++ b/docs/user-guide/tutorials/index.md @@ -5,8 +5,6 @@ maxdepth: 1 caption: Post-processing results --- -surf_research_cloud_setup.ipynb -surf_collaborative_setup.ipynb ADCP_data_tutorial.ipynb CTD_data_tutorial.ipynb Drifter_data_tutorial.ipynb From 784fa578f8f718106264dd8ec4e6a8a520b3a40e Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Tue, 3 Feb 2026 16:15:04 +0100 Subject: [PATCH 2/9] add tutorial doc on how to ineract with expedition.yaml --- docs/user-guide/tutorials/index.md | 8 ++ .../tutorials/working_with_expedition_yaml.md | 105 ++++++++++++++++++ 2 files changed, 113 insertions(+) create mode 100644 docs/user-guide/tutorials/working_with_expedition_yaml.md diff --git a/docs/user-guide/tutorials/index.md b/docs/user-guide/tutorials/index.md index 49190b66..35b04234 100644 --- a/docs/user-guide/tutorials/index.md +++ b/docs/user-guide/tutorials/index.md @@ -23,3 +23,11 @@ caption: SURF Research Cloud set up surf_research_cloud_setup.ipynb surf_collaborative_setup.ipynb ``` + +```{nbgallery} +--- +maxdepth: 1 +caption: Miscellaneous +--- +working_with_expedition_yaml.md +``` diff --git a/docs/user-guide/tutorials/working_with_expedition_yaml.md b/docs/user-guide/tutorials/working_with_expedition_yaml.md new file mode 100644 index 00000000..9f9b0311 --- /dev/null +++ b/docs/user-guide/tutorials/working_with_expedition_yaml.md @@ -0,0 +1,105 @@ +## Working with the `expedition.yaml` file + +This tutorial will guide you through the structure of the `expedition.yaml` file and how to modify it. + +The `expedition.yaml` file is ingested by `virtualship run` and is used to configure expeditions. It contains metadata and settings that define the parameters of an expedition, including information about ship speed, instrument configurations, waypoint timings and instrument selections. + +This tutorial describes an alternative means to using the `virtualship plan` command, which provides a user-friendly interface for interacting with `expedition.yaml` but can become cumbersome for long, complex expeditions with many waypoints and instruments. Interacting with the `expedition.yaml` file directly tends to be faster for larger expeditions. + +### Editing the file + +The `expedition.yaml` file can be opened and edited using any text editor that supports YAML format. Make your changes and save the file to write the changes to your expedition directory. + +```{tip} +The `expedition.yaml` file can also be opened and edited in Jupyter Lab environments using the built-in text editor. Simply navigate to the file in the file browser and (double) click to open it in a new tab. +``` + +```{important} +The `expedition.yaml` file is highly sensitive to indentation and formatting, so please ensure that you maintain the correct formatting (as described [below](#specifics-for-each-section)) when making modifications. +``` + +### Structure + +The `expedition.yaml` file is written in [YAML](https://en.wikipedia.org/wiki/YAML) format, which is a human-readable data serialization standard. Below is an annotated example of a simple `expedition.yaml` file with two waypoints: + +```yaml +# EXAMPLE EXPEDITION.YAML +# +schedule: # <-- 1. expedition schedule section + waypoints: + - instrument: # <-- Waypoint 1 + - CTD + - CTD_BGC + - ARGO_FLOAT + - DRIFTER + location: + latitude: 45.604174 + longitude: -43.886739 + time: 1998-03-08 03:37:00 + - instrument: # <-- Waypoint 2 + - ARGO_FLOAT + - DRIFTER + - XBT + location: + latitude: 48.185988 + longitude: -32.988302 + time: 1998-03-10 03:05:00 +# +instruments_config: # <-- 2. instrument configuration section + adcp_config: + num_bins: 40 + max_depth_meter: -1000.0 + period_minutes: 5.0 + ship_underwater_st_config: + period_minutes: 5.0 + argo_float_config: ... + ctd_bgc_config: ... + ctd_config: ... + drifter_config: ... + xbt_config: ... +# +ship_config: # <-- 3. ship configuration section + ship_speed_knots: 10.0 +``` + +```{note} +In the example above, some instrument configuration parameters are replaced by ellipses (`...`) for brevity. In a real `expedition.yaml` file, these sections would contain detailed configuration settings for each instrument. +``` + +### Specifics for each section + +#### 1. `schedule` + +This section contains a list of `waypoints` that define the expedition's route. Each waypoint includes: + +- **Instruments (`instrument`)**: A list of instruments to be deployed at that waypoint. Add or remove instruments by adding or deleting entries on _new lines_. + +```{tip} +Full list of instruments supported for deployment at waypoints (case-sensitive): `CTD`, `CTD_BGC`, `DRIFTER`, `ARGO_FLOAT`, `XBT`. +``` + +- **Location (`location`)**: The geographical coordinates (latitude and longitude) of the waypoint. These must be in decimal degrees (DD) format. + +- **Time (`time`)**: The scheduled time for reaching the waypoint, specifically in YYYY-MM-DD HH:MM:SS format. + +#### 2. `instruments_config` + +This section defines the configuration settings for each instrument used in the expedition. Each instrument has its own subsection where specific parameters can be set. + +Because **underway instruments** (e.g., ADCP, Ship Underwater ST) collect data continuously while the ship is moving, their deployment is not tied to specific waypoints. Instead, the presence of their configuration sections in `instruments_config` indicates that they will be active throughout the expedition. This means that if you wish to turn off an underway instrument, you can remove its configuration section or simply set it to `null`, for example: + +```yaml +instruments_config: + adcp_config: null + ship_underwater_st_config: null +``` + +For **all other instruments**, e.g. CTD, ARGO_FLOAT etc., the paramters can often be left as the default values unless advanced customisations are required. + +#### 3. `ship_config` + +This section contains setting related to the ship itself, specifically: + +- **Ship speed (`ship_speed_knots`)**: The speed of the ship in knots. Note in most cases this should be left as the default value unless there is a specific reason to change it. + + From ea17e9b74873f6d40179cc3c7ba04f59383d878f Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Tue, 3 Feb 2026 16:35:03 +0100 Subject: [PATCH 3/9] point to information on expedition.yaml in rest of docs --- docs/user-guide/assignments/Sail_the_ship.ipynb | 7 ++++++- docs/user-guide/quickstart.md | 4 ++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/assignments/Sail_the_ship.ipynb b/docs/user-guide/assignments/Sail_the_ship.ipynb index 2a2d8577..4314779a 100644 --- a/docs/user-guide/assignments/Sail_the_ship.ipynb +++ b/docs/user-guide/assignments/Sail_the_ship.ipynb @@ -156,6 +156,11 @@ "\n", "The next step is to finalise the expedition schedule plan, including setting times and instrument selection choices for each waypoint, as well as configuring the ship (including any underway measurement instruments). \n", "\n", + "
\n", + "**NOTE**: This section describes the process of finalising the expedition schedule and instrument selection using the `virtualship plan` application. This is the recommended way for most users but when expeditions become larger with many waypoints, it can become cumbersome to use the planning tool (note, using VirtualShip in a remote terminal / cloud-based environment can also introduce lag in the user-interface). **In this case, you may prefer to edit the** `expedition.yaml` **file directly (see [here](https://virtualship.readthedocs.io/en/latest/user-guide/tutorials/working_with_expedition_yaml.html) for more details on how to do so)**.\n", + "
\n", + "\n", + "\n", "The easiest way to do so is to use the bespoke VirtualShip planning tool. Enter the following command in Terminal: `virtualship plan EXPEDITION_NAME`.\n", "\n", "\n", @@ -294,7 +299,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.9" + "version": "3.12.12" } }, "nbformat": 4, diff --git a/docs/user-guide/quickstart.md b/docs/user-guide/quickstart.md index 2d927df0..7a4706ad 100644 --- a/docs/user-guide/quickstart.md +++ b/docs/user-guide/quickstart.md @@ -58,6 +58,10 @@ For advanced users: it is also possible to run the expedition initialisation ste ## 3) Expedition scheduling & ship configuration +```{important} +This section describes the process of finalising the expedition schedule and instrument selection using the `virtualship plan` application. This is the recommended way for most users but when expeditions become larger with many waypoints, it can become cumbersome to use the planning tool (note, using VirtualShip in a remote terminal / cloud-based environment can also introduce lag in the user-interface). **In this case, you may prefer to edit the `expedition.yaml` file directly (see [here](https://virtualship.readthedocs.io/en/latest/user-guide/tutorials/working_with_expedition_yaml.html) for more details on how to do so)**. +``` + The next step is to finalise the expedition schedule plan, including setting times and instrument selection choices for each waypoint, as well as configuring the ship (such as its speed and underway measurement instruments). The easiest way to do so is to use the bespoke VirtualShip planning tool via the following command: ``` From 56d296606d760705b09b7dd29519056700427dcf Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Tue, 3 Feb 2026 16:40:20 +0100 Subject: [PATCH 4/9] point to docs in yaml file --- src/virtualship/static/expedition.yaml | 2 ++ tests/expedition/expedition_dir/expedition.yaml | 2 ++ 2 files changed, 4 insertions(+) diff --git a/src/virtualship/static/expedition.yaml b/src/virtualship/static/expedition.yaml index 388961c0..51534859 100644 --- a/src/virtualship/static/expedition.yaml +++ b/src/virtualship/static/expedition.yaml @@ -1,3 +1,5 @@ +# see https://virtualship.readthedocs.io/en/latest/user-guide/tutorials/working_with_expedition_yaml.html for more details on how to edit this file +# schedule: waypoints: - instrument: diff --git a/tests/expedition/expedition_dir/expedition.yaml b/tests/expedition/expedition_dir/expedition.yaml index 65e0b540..0d2bb155 100644 --- a/tests/expedition/expedition_dir/expedition.yaml +++ b/tests/expedition/expedition_dir/expedition.yaml @@ -1,3 +1,5 @@ +# see https://virtualship.readthedocs.io/en/latest/user-guide/tutorials/working_with_expedition_yaml.html for more details on how to edit this file +# schedule: waypoints: - instrument: From 40de54ba3704024a6b315c93d73142ef25a65da5 Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Tue, 3 Feb 2026 16:57:15 +0100 Subject: [PATCH 5/9] update yaml guidance thumbnail --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index fa39fbb3..4555e7f3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -82,6 +82,7 @@ "user-guide/teacher-content/UU-ocean-of-future/Tutorial2": "user-guide/_images/freepik_assignment.png", "user-guide/tutorials/surf_collaborative_setup.ipynb": "user-guide/_images/surf_logo.png", "user-guide/tutorials/surf_research_cloud_setup.ipynb": "user-guide/_images/surf_logo.png", + "user-guide/tutorials/working_with_expedition_yaml.ipynb": "user-guide/_images/AnnaWeber.jpeg", } sphinx_gallery_conf = {"default_thumb_file": "_static/virtual_ship_logo.png"} From 6b0d886ed861537950e1349ae755805f33472e24 Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Tue, 3 Feb 2026 17:17:46 +0100 Subject: [PATCH 6/9] use relative paths --- docs/user-guide/assignments/Sail_the_ship.ipynb | 2 +- docs/user-guide/quickstart.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/assignments/Sail_the_ship.ipynb b/docs/user-guide/assignments/Sail_the_ship.ipynb index 4314779a..cbfc7d75 100644 --- a/docs/user-guide/assignments/Sail_the_ship.ipynb +++ b/docs/user-guide/assignments/Sail_the_ship.ipynb @@ -157,7 +157,7 @@ "The next step is to finalise the expedition schedule plan, including setting times and instrument selection choices for each waypoint, as well as configuring the ship (including any underway measurement instruments). \n", "\n", "
\n", - "**NOTE**: This section describes the process of finalising the expedition schedule and instrument selection using the `virtualship plan` application. This is the recommended way for most users but when expeditions become larger with many waypoints, it can become cumbersome to use the planning tool (note, using VirtualShip in a remote terminal / cloud-based environment can also introduce lag in the user-interface). **In this case, you may prefer to edit the** `expedition.yaml` **file directly (see [here](https://virtualship.readthedocs.io/en/latest/user-guide/tutorials/working_with_expedition_yaml.html) for more details on how to do so)**.\n", + "**NOTE**: This section describes the process of finalising the expedition schedule and instrument selection using the `virtualship plan` application. This is the recommended way for most users but when expeditions become larger with many waypoints, it can become cumbersome to use the planning tool (note, using VirtualShip in a remote terminal / cloud-based environment can also introduce lag in the user-interface). **In this case, you may prefer to edit the** `expedition.yaml` **file directly (see [here](../tutorials/working_with_expedition_yaml.md) for more details on how to do so)**.\n", "
\n", "\n", "\n", diff --git a/docs/user-guide/quickstart.md b/docs/user-guide/quickstart.md index 7a4706ad..b90f2f34 100644 --- a/docs/user-guide/quickstart.md +++ b/docs/user-guide/quickstart.md @@ -59,7 +59,7 @@ For advanced users: it is also possible to run the expedition initialisation ste ## 3) Expedition scheduling & ship configuration ```{important} -This section describes the process of finalising the expedition schedule and instrument selection using the `virtualship plan` application. This is the recommended way for most users but when expeditions become larger with many waypoints, it can become cumbersome to use the planning tool (note, using VirtualShip in a remote terminal / cloud-based environment can also introduce lag in the user-interface). **In this case, you may prefer to edit the `expedition.yaml` file directly (see [here](https://virtualship.readthedocs.io/en/latest/user-guide/tutorials/working_with_expedition_yaml.html) for more details on how to do so)**. +This section describes the process of finalising the expedition schedule and instrument selection using the `virtualship plan` application. This is the recommended way for most users but when expeditions become larger with many waypoints, it can become cumbersome to use the planning tool (note, using VirtualShip in a remote terminal / cloud-based environment can also introduce lag in the user-interface). **In this case, you may prefer to edit the `expedition.yaml` file directly (see [here](./tutorials/working_with_expedition_yaml.md) for more details on how to do so)**. ``` The next step is to finalise the expedition schedule plan, including setting times and instrument selection choices for each waypoint, as well as configuring the ship (such as its speed and underway measurement instruments). The easiest way to do so is to use the bespoke VirtualShip planning tool via the following command: From e631a99d2c02c64bcdf76e4a5cf081c177ab3ec7 Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Tue, 3 Feb 2026 17:36:50 +0100 Subject: [PATCH 7/9] fix thumbnails --- docs/conf.py | 6 +++--- docs/user-guide/_images/surf_logo.png | Bin 6194 -> 0 bytes 2 files changed, 3 insertions(+), 3 deletions(-) delete mode 100644 docs/user-guide/_images/surf_logo.png diff --git a/docs/conf.py b/docs/conf.py index 4555e7f3..3995449c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -80,9 +80,9 @@ "user-guide/teacher-content/ILOs": "user-guide/_images/ILOs.jpg", "user-guide/teacher-content/UU-ocean-of-future/Tutorial1": "user-guide/_images/freepik_assignment.png", "user-guide/teacher-content/UU-ocean-of-future/Tutorial2": "user-guide/_images/freepik_assignment.png", - "user-guide/tutorials/surf_collaborative_setup.ipynb": "user-guide/_images/surf_logo.png", - "user-guide/tutorials/surf_research_cloud_setup.ipynb": "user-guide/_images/surf_logo.png", - "user-guide/tutorials/working_with_expedition_yaml.ipynb": "user-guide/_images/AnnaWeber.jpeg", + "user-guide/tutorials/surf_collaborative_setup": "user-guide/_images/freepik_research_vessel.jpg", + "user-guide/tutorials/surf_research_cloud_setup": "user-guide/_images/freepik_research_vessel.jpg", + "user-guide/tutorials/working_with_expedition_yaml": "user-guide/_images/AnnaWeber.jpeg", } sphinx_gallery_conf = {"default_thumb_file": "_static/virtual_ship_logo.png"} diff --git a/docs/user-guide/_images/surf_logo.png b/docs/user-guide/_images/surf_logo.png deleted file mode 100644 index df11f91dcb6f1c49d30ce9eee85a992a89e567cc..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6194 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 From 60fa98353715fa3dd3555163756e33d91319d9a7 Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Fri, 6 Feb 2026 11:46:40 +0100 Subject: [PATCH 8/9] remove duplicate note/tip --- docs/user-guide/quickstart.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/user-guide/quickstart.md b/docs/user-guide/quickstart.md index b90f2f34..bd2e508e 100644 --- a/docs/user-guide/quickstart.md +++ b/docs/user-guide/quickstart.md @@ -68,10 +68,6 @@ The next step is to finalise the expedition schedule plan, including setting tim virtualship plan EXPEDITION_NAME ``` -```{tip} -Using the `virtualship plan` tool is optional. Advanced users can also edit the `expedition.yaml` file directly if preferred. -``` - The planning tool should look something like this and offers an intuitive way to make your selections: ![example_plan_app](example_plan_app.gif) From a074eb0abe56e223dcdf21b1dd932aadb5ff3c01 Mon Sep 17 00:00:00 2001 From: j-atkins <106238905+j-atkins@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:31:40 +0100 Subject: [PATCH 9/9] post review edits --- docs/user-guide/assignments/Sail_the_ship.ipynb | 2 +- docs/user-guide/tutorials/working_with_expedition_yaml.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/assignments/Sail_the_ship.ipynb b/docs/user-guide/assignments/Sail_the_ship.ipynb index cbfc7d75..f5c1ec75 100644 --- a/docs/user-guide/assignments/Sail_the_ship.ipynb +++ b/docs/user-guide/assignments/Sail_the_ship.ipynb @@ -157,7 +157,7 @@ "The next step is to finalise the expedition schedule plan, including setting times and instrument selection choices for each waypoint, as well as configuring the ship (including any underway measurement instruments). \n", "\n", "
\n", - "**NOTE**: This section describes the process of finalising the expedition schedule and instrument selection using the `virtualship plan` application. This is the recommended way for most users but when expeditions become larger with many waypoints, it can become cumbersome to use the planning tool (note, using VirtualShip in a remote terminal / cloud-based environment can also introduce lag in the user-interface). **In this case, you may prefer to edit the** `expedition.yaml` **file directly (see [here](../tutorials/working_with_expedition_yaml.md) for more details on how to do so)**.\n", + "**NOTE**: This section describes the process of finalising the expedition schedule and instrument selection using the `virtualship plan` application. For expeditions with many waypoints, it can become cumbersome to use the planning tool (note, using VirtualShip in a remote terminal / cloud-based environment can also introduce lag in the user-interface). **In this case, you may prefer to edit the** `expedition.yaml` **file directly (see [here](../tutorials/working_with_expedition_yaml.md) for more details on how to do so)**.\n", "
\n", "\n", "\n", diff --git a/docs/user-guide/tutorials/working_with_expedition_yaml.md b/docs/user-guide/tutorials/working_with_expedition_yaml.md index 9f9b0311..daa1fc15 100644 --- a/docs/user-guide/tutorials/working_with_expedition_yaml.md +++ b/docs/user-guide/tutorials/working_with_expedition_yaml.md @@ -4,7 +4,7 @@ This tutorial will guide you through the structure of the `expedition.yaml` file The `expedition.yaml` file is ingested by `virtualship run` and is used to configure expeditions. It contains metadata and settings that define the parameters of an expedition, including information about ship speed, instrument configurations, waypoint timings and instrument selections. -This tutorial describes an alternative means to using the `virtualship plan` command, which provides a user-friendly interface for interacting with `expedition.yaml` but can become cumbersome for long, complex expeditions with many waypoints and instruments. Interacting with the `expedition.yaml` file directly tends to be faster for larger expeditions. +This tutorial describes an alternative means to using the `virtualship plan` command, which provides a user-friendly interface for interacting with `expedition.yaml` but can become cumbersome for long, complex expeditions with many waypoints and instruments. Interacting with the `expedition.yaml` file directly tends to be faster for larger expeditions and experienced users. ### Editing the file @@ -72,7 +72,7 @@ In the example above, some instrument configuration parameters are replaced by e This section contains a list of `waypoints` that define the expedition's route. Each waypoint includes: -- **Instruments (`instrument`)**: A list of instruments to be deployed at that waypoint. Add or remove instruments by adding or deleting entries on _new lines_. +- **Instruments (`instrument`)**: A list of instruments to be deployed at that waypoint. Add or remove instruments by adding or deleting entries on _new lines_. The instrument selection can also be left empty (i.e., no instruments deployed at that waypoint) by setting the parameter to: `instrument: null`. ```{tip} Full list of instruments supported for deployment at waypoints (case-sensitive): `CTD`, `CTD_BGC`, `DRIFTER`, `ARGO_FLOAT`, `XBT`.