diff --git a/docs/conf.py b/docs/conf.py index ceb8c01a..3995449c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -80,6 +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": "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/assignments/Sail_the_ship.ipynb b/docs/user-guide/assignments/Sail_the_ship.ipynb index 2a2d8577..f5c1ec75 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. 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", "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..bd2e508e 100644 --- a/docs/user-guide/quickstart.md +++ b/docs/user-guide/quickstart.md @@ -58,16 +58,16 @@ 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](./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: ``` 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) diff --git a/docs/user-guide/tutorials/index.md b/docs/user-guide/tutorials/index.md index f2fab7b4..35b04234 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 @@ -25,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..daa1fc15 --- /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 and experienced users. + +### 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_. 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`. +``` + +- **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. + + 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: