Sail the ship#

Note: This guide is specific to students who are enrolled at Utrecht University.

Welcome aboard VirtualShip!#

Welcome aboard, oceanography students, to our scientific research vessel! We’re thrilled to have you join us for this exciting 3-week journey into the depths of the ocean. As we embark on this voyage of exploration and discovery, there are a few things we’d like to share with you to ensure a smooth and enriching experience:

Introduction to the Vessel: Take some time to familiarize yourselves with the layout of the ship. Get to know key areas such as the laboratories, living quarters, dining area, and deck spaces. E.g. at https://viewer.foleon.com/preview/vo2PZClgA/rv-wim-wolff

Daily Routine: Life on a research vessel follows a structured daily routine. We’ll have designated times for meals, research activities, data analysis, and downtime. It’s important to maintain this routine to ensure that our work is conducted efficiently and that everyone onboard has the opportunity to rest and recharge.

Safety Orientation: Safety is our top priority. As we set sail, we’ll conduct a comprehensive safety orientation. This will cover important topics such as emergency procedures, the location of safety equipment, and proper use of personal protective gear. Please pay close attention during this orientation to ensure your safety and the safety of others on board.

Respect for the Environment: As we explore the ocean, it’s essential to maintain a deep respect for the marine environment. We’ll adhere to strict environmental protocols to minimize our impact on marine ecosystems and wildlife. Remember to dispose of waste properly and avoid disturbing marine life whenever possible.

Teamwork and Collaboration: Oceanographic research is a collaborative effort that requires teamwork and cooperation. You’ll be working closely with your fellow students. Embrace the opportunity to learn from each other and support one another throughout the journey.

Emergency procedures#

Before going on any research expedition you need follow a one day Safety at Sea course and get a medical check-up.

Of course this is not needed for your virtual fieldwork, but we would like to draw for your attention to the following on-board emergency procedures.

Safety Drills: We conduct regular safety drills to ensure that everyone on board is well-prepared in case of an emergency. Specifically, fire and boat drills are held once a week. These drills are not just routine; they are essential survival training and should be taken seriously. To minimize disruption to the research program, science party members are usually notified in advance of the scheduled drills. In the event that you must continue working during a drill, prior arrangements can be made through the Chief Scientist.

Emergency Signal: In the event of an emergency signal, your immediate action is crucial. Don life jackets, put on long-sleeved garments, and wear a hat or head covering if available. Then, proceed to the designated station indicated on the station card located next to your bunk.

On-Call Readiness: Please keep in mind that while on board the ship, you may be called upon without warning to assist during your off-watch periods. Emergencies can happen at any time, and your readiness to respond promptly and efficiently is essential to the safety of all aboard.

Boat Drill (Abandon Ship): The signal for abandon ship is seven or more short blasts followed by one long blast of the ship’s whistle and general alarm. When this signal is heard, report to your designated life raft station. There the Mate in charge will explain the procedures for launching and embarking into the life rafts. The rafts will not be launched during a drill.

Fire and Emergency Drills: The signal is one long blast on the ship’s whistle and general alarm bell, lasting for ten seconds or more. During this drill, members of the science party muster in the designated area. Attendance will be taken and reported to the bridge.

Man Overboard: If someone falls overboard, throw a life-ring into the water towards the person. Keep your eye on the person at all times and point towards the person. Shout “MAN OVERBOARD, STARBOARD (or PORT),” and call the bridge on the sound powered phone or squawk box to inform them without losing sight of the person if possible. If you hear someone hail “Man Overboard,” pass the word to the bridge.

Your virtual expedition
#

Now let’s get started on running your VirtualShip expedition. Follow the steps below to set up your coding environment, plan your expedition, and launch your simulation.

Before that though, make sure you have had your research question approved by your instructor!

1) Register with the Copernicus Marine Data Store#

You will need to register for Copernicus Marine Service account (see here), if you have not done so already. This is required to access the oceanographic data that VirtualShip uses to run your expedition.

2) Set up your virtual machine#

In the class, we will use VirtualShip in the cloud (in this case, SURF Research Cloud - called SURF RC from here-on). This has several advantages:

  • You aren’t limited to the power of your laptop.

  • The environment is pre-configured with all necessary software and dependencies.

Follow the instructions here to set up your SURF RC environment for VirtualShip.

Note: If you have Anaconda installed on your local machine and would like to run VirtualShip locally instead of on SURF RC, please see VirtualShip - Installation for instructions.

3) Expedition route planning#

NIOZ MFP tool#

The first step is to plan the expedition route for your chosen research question, bearing in mind the time needed for your sampling strategy, and traveling to and from a port suitable for research vessels (remember though, you have a three week ship time limit).

Your route can be created with the online NIOZ MFP tool. Documentation on how to use the website can be found here. Alternatively, you can watch this video, which runs through how to use the MFP tool.

Export the coordinates from MFP#

Once you have finalised your MFP expedition route, select “Export” on the right hand side of the window –> “Export Coordinates” –> “DD”. This will download your coordinates as an .xlsx (Excel) file, which we will later feed into the VirtualShip protocol to initialise the expedition.

Upload the coordinates to your virtual machine#

Important: If you have not done so already, make sure you create a folder for your group’s expedition data in the persistent storage on SURF RC (i.e. the data/storage/ folder). You can do so by running mkdir /data/storage/{your-group-name} in Terminal, replacing {your-group-name} with your actual group name, or by using the “New Folder” button in the JupyterLab file explorer panel.

Back in the SURF RC JupyterLab interface, use the file explorer on the left hand side to navigate to the directory where your group will be running your expedition (i.e. data/storage/{your-group-name}).

Then upload the exported .xlsx file (it will be called something like “Coordinates-20251125T1403.xlsx”) by either dragging and dropping it from your laptop’s Downloads into the file explorer, or by using the “Upload Files” button (the icon with an upward arrow) at the top of the file explorer panel.

4) Expedition initialisation#

Open a Terminal window if you do not already have one open. Remember, this can be done from the Launcher tab by clicking on “Terminal” button under the “Other” section, or by going to the “File” menu –> “New” –> “Terminal”.

Important: Once in Terminal, navigate to where you would like your expedition to be run on your (virtual) machine. You can do so by cd /data/storage/{your-group-name}, replacing {your-group-name} with your actual group name. This is where you will be working from for the rest of the session.

Now enter the following command in the Terminal (changing EXPEDITION_NAME to something more meaningful for your group’s expedition):

virtualship init EXPEDITION_NAME --from-mfp {CoordinatesExport}.xlsx

Tip: The {CoordinatesExport}.xlsx in the command above refers to the .xlsx file exported from MFP and uploaded to your virtual machine earlier. Replace the filename with the name of your .xlsx file.

This will create a folder/directory called EXPEDITION_NAME (or what you have changed this to) with a single file: expedition.yaml. This file contains details on the ship and instrument configurations, as well as the expedition schedule based on the sampling site coordinates that you specified in your MFP export. The --from-mfp flag indicates that the exported coordinates should be used.

5) Expedition scheduling & ship configuration#

Tip: From here, you should replace any references to EXPEDITION_NAME with the actual name you used for your expedition when running any virtualship commands.

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).

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 for more details on how to do so).

The easiest way to do so is to use the bespoke VirtualShip planning tool. Enter the following command in Terminal: virtualship plan EXPEDITION_NAME.

TIP: Using the virtualship plan tool is optional. Advanced users can also edit the expedition.yaml file directly if preferred.

Ship speed#

In the planning tool which appears, under Ship Config Editor > Ship Speed & Onboard Measurements, there is an option to change the ship speed. However, for this course, you should leave this as the default 10 knots value.

Underway measurements#

VirtualShip is capable of taking underway temperature and salinity measurements, as well as onboard ADCP measurements, as the ship sails across the length of the expedition (see here for more detail). These underway measurements can be switched on/off under Ship Config Editor > Ship Speed & Onboard Measurements as well.

For the underway ADCP, there is a choice of using the 38 kHz OceanObserver or the 300 kHz SeaSeven version (see here for more detail on the two ADCP types).

Waypoint datetimes#

Note: VirtualShip supports running experiments in the years 1993 through to the present day by leveraging the suite of products available on the Copernicus Marine Data Store.

You will need to enter dates and times for each of the sampling stations/waypoints selected in the MFP route planning stage. This can be done under Schedule Editor > Waypoints & Instrument Selection in the planning tool.

Each waypoint has its own sub-panel for parameter inputs (click on it to expand the selection options). Here, the time for each waypoint can be inputted. There is also an option to adjust the latitude/longitude coordinates and you can add or remove waypoints.

Note: It is important to ensure that the timings for each station are realistic. There must be enough time for the ship to travel to each site at the prescribed speed (10 knots). The expedition schedule will be automatically verified when you press Save Changes in the planning tool.

Tip: The MFP route planning tool will give estimated durations of sailing between sites at the 10 knots sailing speed. This can be useful to refer back to when planning the expedition timings and entering these into the virtualship plan tool.

Instrument selection#

You should now consider which measurements are to be taken at each sampling site (think about those required for your chosen research question), and therefore which instruments need to be selected in the planning tool at each waypoint.

Tip: Click here for more information on what measurement options are available, and a brief introduction to each instrument.

You can make instrument selections for each waypoint in the same sub-panels as the waypoint time selection by simply switching each on or off. Multiple instruments are allowed at each waypoint.

Save changes#

When you are happy with your ship configuration and schedule plan, press Save Changes at the bottom of the planning tool.

Note: On pressing Save Changes the tool will check the selections are valid (for example that the ship will be able to reach each waypoint in time). If they are, the changes will be saved to the expedition.yaml file, ready for the next steps. If your selections are invalid you should be provided with information on how to fix them.

6) Run the expedition#

You are now ready to run your virtual expedition! This stage will take all the measurements for each of instruments you selected at each waypoint in your expedition schedule, using input data sourced from the Copernicus Marine Data Store.

Note: You will need to register for a Copernicus Marine Service account (you can do so here), if you have not done so already.

You can run your expedition simulation using the command:

virtualship run EXPEDITION_NAME

If this is your first time running VirtualShip, you will be prompted to enter your own Copernicus Marine Data Store credentials (these will be saved automatically for future use).

Small simulations (e.g. small space-time domains and fewer instrument deployments) will be relatively fast. For large, complex expeditions, it could take up to an hour to simulate the measurements depending on your choices. Waiting for simulation is a great time to practice your level of patience. A skill much needed in oceanographic fieldwork ;-)

Tip: Not using underway instruments will speed up the simulation time considerably. So, if you do not plan to use underway temperature/salinity or ADCP measurements, make sure to switch these off in the planning tool before running the expedition.

Important: VirtualShip may encounter ‘real-life challenges’ during the expedition, which simulate the various problems and unexpected events that can occur during real-life oceanographic expeditions (e.g. instrument and/or equipment failure, logistical challenges etc.). These may require your intervention to ensure your expedition schedule can continue!

7) Results#

Upon successfully completing the simulation, results from the expedition will be stored in the EXPEDITION_NAME/results directory, written as Zarr files.

From here you can carry on your analysis. In general, we encourage you to explore and analyse these data using Xarray. We also provide various further VirtualShip tutorials which provide examples of how to visualise data recorded by the VirtualShip instruments. Use these to help you get started!

If you are using VirtualShip in class, the same tutorial notebooks will be uploaded in your SURF RC environment for you to use and interact directly with the code. These should be available in e.g. the data/storage/tutorials/ directory. You will notice that there is a notebook file dedicated to visualising each of the different instruments available in VirtualShip.

To run these notebooks with your own data, you will need to copy the them over to your expedition working directory (i.e. data/storage/{your-group-name}). This can be done by either 1) using the file explorer panel in JupyterLab to copy the relevant files or the via the command line in Terminal. In the terminal, running cp -r /data/storage/tutorials/* /data/storage/{your-group-name}/ would copy all the tutorial notebooks to your group’s directory, so if you only want to copy specific ones, make sure to adjust the command accordingly.

Reporting#

Reporting your journey is an essential aspect of our oceanographic research expedition. It allows us to share our experiences, communicate our findings, and contribute to the broader scientific community. After each scientific expedition a cruise report should be written (or in the case of this course, a presentation).

You can find many cruise reports and blogs online from many different cruises.

Reporting our journey allows us to validate the data collected during our research activities. It provides context for our findings and helps ensure that our results are accurately interpreted and understood. Detailed reports enable us to cross-reference our observations with environmental conditions, sampling locations, and other relevant factors, enhancing the reliability and credibility of our data.

Our reports also serve as valuable educational resources for students, educators, and the general public. They provide insights into the process of scientific inquiry, the challenges of conducting research at sea, and the significance of oceanographic discoveries.

We look forward to seeing the impact of your collective efforts during the presentations in a few weeks time!

Please don’t worry if your results are insufficient to answer your research question. Share your failure and things you would do different a next time instead!

For example: