diff --git a/docs/conf.py b/docs/conf.py index 2b8edd6a..aeacbfff 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -75,7 +75,7 @@ "user-guide/assignments/Research_Proposal_only": "user-guide/_images/MFP.jpg", "user-guide/assignments/Virtualship_research_proposal": "user-guide/_images/AnnaWeber.jpeg", "user-guide/assignments/sciencecommunication_assignment": "user-guide/_images/marine_ss.jpg", - # "user-guide/assignments/Sail_the_ship": "user-guide/_images/freepik_research_vessel.jpg", + "user-guide/assignments/Sail_the_ship": "user-guide/_images/freepik_research_vessel.jpg", "user-guide/assignments/Code_of_conduct": "user-guide/_images/freepik_code_of_conduct.jpg", "user-guide/teacher-content/ILOs": "user-guide/_images/ILOs.jpg", } diff --git a/docs/user-guide/assignments/Sail_the_ship.ipynb b/docs/user-guide/assignments/Sail_the_ship.ipynb index 3f62d06a..6009a994 100644 --- a/docs/user-guide/assignments/Sail_the_ship.ipynb +++ b/docs/user-guide/assignments/Sail_the_ship.ipynb @@ -4,178 +4,271 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Start your expedition!\n", + "# Sail the ship\n", "\n", - "https://www.youtube.com/watch?v=G82kIgc1imk\n", - "\n", - "" + "```\n", + "Note: This guide is specific to students who are enrolled at Utrecht University.\n", + "```\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "On your (virtual) machine change directory into the folder where your expedition will be run. Initialize the virtualship by copying the commands directly into a terminal.\n", + "## Welcome aboard VirtualShip!\n", "\n", - ">Usage: virtualship init [OPTIONS] PATH\n", - ">\n", - "> Initialize a directory for a new expedition, with an example schedule and\n", - "> ship config files.\n", + "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:\n", "\n", - "```\n", - "virtualship init EXPEDITION_NAME\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "This will create a folder `EXPEDITION_NAME` with two files: `schedule.yaml` and\t`ship_config.yaml`.\n", + "**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\n", "\n", - "You can populate the `schedule.yaml` file manually with each sampling CTD station and XBT/DRIFTER/ARGO_FLOAT deployment position. Or use the exported cruise coordinates from MFP. In that case, add an extra column to the .xlsx file called `Instrument` and on each line write which instruments you want to use or deploy there. Multiple instrument are allowed, e.g. `DRIFTER, CTD` or `DRIFTER, ARGO_FLOAT`. If you want to use your MFP export, make sure your directory is clean and run:\n", + "**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.\n", "\n", - "```\n", - "virtualship init EXPEDITION_NAME --from-mfp CoordinatesExport.xlsx\n", - "```" + "**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.\n", + "\n", + "**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.\n", + "\n", + "**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." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ + "## Emergency procedures\n", "\n", - "Mind that the route between points will be sailed as the shortest great-cirlce distance. \n", + "Before going on any research expedition you need follow a one day Safety at Sea course and get a medical check-up.\n", "\n", - "Instrument configurations can be provided in `ship_config`. \n", + "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.\n", "\n", - "Under `adcp_config` provide the configuration of your ADCP, so either `max_depth_meter: -1000.0` if you want to use the OceanObserver or `max_depth_meter: -150.0` if you want to use the SeaSeven. \n", + "**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.\n", "\n", - "If you don't need the ADCP to measure, remove the `adcp_config` and underlying lines from the configuration file. \n", + "**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.\n", "\n", - "If you do not want to collect underway data, remove `ship_underwater_st_config` from the configuration file.\n", + "**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.\n", "\n", - "Change the xbt, drifter and argo_float configurations if you want.\n", + "**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.\n", "\n", - "For the CTD, provide the maximum depth you will want to measure at. All other CTD casts will be done to approximately 20 meter of the ocean floor. \n", + "**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.\n", "\n", - "When you have finished your schedule and config, run the fetch command to download input data for the virtual ship from the Copernicus marine data store. \n", - "You will need to register via: https://data.marine.copernicus.eu/register \n", - "You can provide your username and password as command line arguments. If you don't you will be prompted for your credentials.\n", + "**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." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Your virtual expedition...\n", "\n", - "> Usage: virtualship fetch [OPTIONS] PATH\n", - ">\n", - "> Download input data for an expedition.\n", + "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. \n", "\n", - "```\n", - "virtualship fetch EXPEDITION_NAME --username --password \n", - "```\n", + "
\n", + "Before that though, make sure you have had your research question approved by your instructor!\n", + "
" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 1) Register with the Copernicus Marine Data Store\n", "\n", - "```\n", - "virtualship fetch EXPEDITION_NAME\n", - "```" + "You will need to register for **Copernicus Marine Service** account (see [here](https://data.marine.copernicus.eu/register)), if you have not done so already. This is required to access the oceanographic data that VirtualShip uses to run your expedition." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Waiting for your data download is a great time to practice your level of patience. A skill much needed in oceanographic fieldwork ;-)\n", + "## 2) Set up your virtual machine\n", "\n", - "After your input data has been downloaded you can do your expedition:\n", + "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:\n", "\n", - "> Usage: virtualship run [OPTIONS] PATH\n", - ">\n", - "> Run the expedition.\n", + "- You aren't limited to the power of your laptop.\n", + "- The environment is pre-configured with all necessary software and dependencies.\n", "\n", - "```\n", - "virtualship run EXPEDITION_NAME\n", - "```" + "**Follow the instructions [here](https://virtualship.readthedocs.io/en/latest/user-guide/tutorials/surf_research_cloud_setup.html) to set up your SURF RC environment for VirtualShip.**\n", + "\n", + "
\n", + "**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](https://virtualship.readthedocs.io/en/latest/#installation) for instructions.\n", + "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "It might take up to an hour to gather the data depending on your choices. Meanwhile read up on some of the onboard safety procedures and browse through blogs and cruise reports if you want. \n", + "## 3) Expedition route planning\n", "\n", - "To download your results, zip the results folder to continue your analysis offline:\n", - "```\n", - "zip -r results.zip results/\n", - "```" + "### NIOZ MFP tool\n", + "\n", + "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).\n", + "\n", + "Your route can be created with the online [NIOZ MFP tool](https://nioz.marinefacilitiesplanning.com/cruiselocationplanning#). Documentation on how to use the website can be found [here](https://surfdrive.surf.nl/files/index.php/s/84TFmsAAzcSD56F). Alternatively, you can watch this [video](https://www.youtube.com/watch?v=yIpYX2xCvsM&list=PLE-LzO7kk1gLM74U4PLDh8RywYXmZcloz&ab_channel=VirtualShipClassroom), which runs through how to use the MFP tool.\n", + "\n", + "\n", + "### Export the coordinates from MFP\n", + "\n", + "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.\\\n", + "\n", + "### Upload the coordinates to your virtual machine\n", + "\n", + "
\n", + "**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-osl/` folder). You can do so by running `mkdir /data/storage-osl/{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.\n", + "
\n", + "\n", + "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-osl/{your-group-name}`). \n", + "\n", + "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." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Welcome aboard\n", - "\n", - "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 I'd like to share with you to ensure a smooth and enriching experience:\n", + "## 4) Expedition initialisation\n", "\n", - "**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\n", + "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\".\n", "\n", - "**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.\n", + "
\n", + "**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-osl/{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.\n", + "
\n", "\n", - "**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.\n", + "Now enter the following command in the Terminal (changing `EXPEDITION_NAME` to something more meaningful for your group's expedition):\n", "\n", - "**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.\n", + "`virtualship init EXPEDITION_NAME --from-mfp {CoordinatesExport}.xlsx`\n", "\n", - "**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.\n", + "
\n", + "**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.\n", + "
\n", "\n", - "![ship layout](https://www.nioz.nl/application/files/1116/0873/1068/CROP_bestand_3_SG_2.1_Bijlage_-_Algemeen_Plan.jpg)" + "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." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ + "## 5) Expedition scheduling & ship configuration\n", "\n", + "
\n", + "**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.\n", + "
\n", "\n", - "### Emergency procedures\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", - "Before going on any research expedition you need follow a one day Safety at Sea course and get a medical check-up.\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", - "Of course this is not needed for your virtual fieldwork, but I like to draw for your attention to the following on-board emergency procedures.\n", "\n", - "**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.\n", + "### Ship speed\n", "\n", - "**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.\n", + "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.\n", "\n", - "**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.\n", + "### Underway measurements\n", "\n", - "**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.\n", + "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](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Research_proposal_intro.html#Underway-Data) for more detail). These underway measurements can be switched on/off under _Ship Config Editor_ > _Ship Speed & Onboard Measurements_ as well.\n", "\n", - "**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.\n", + "For the underway ADCP, there is a choice of using the 38 kHz OceanObserver or the 300 kHz SeaSeven version (see [here](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Research_proposal_intro.html#ADCP) for more detail on the two ADCP types).\n", "\n", - "**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." + "### Waypoint datetimes\n", + "\n", + "
\n", + "**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.\n", + "
\n", + "\n", + "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.\n", + "\n", + "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.\n", + "\n", + "
\n", + "**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.\n", + "
\n", + "\n", + "
\n", + "**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.\n", + "
\n", + "\n", + "### Instrument selection\n", + "\n", + "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.\n", + "\n", + "
\n", + "**TIP**: Click [here](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Research_proposal_intro.html#Measurement-Options) for more information on what measurement options are available, and a brief introduction to each instrument.\n", + "
\n", + "\n", + "You can make instrument selections for each waypoint in the same sub-panels as the [waypoint time](#waypoint-datetimes) selection by simply switching each on or off. Multiple instruments are allowed at each waypoint.\n", + "\n", + "\n", + "### Save changes\n", + "\n", + "When you are happy with your ship configuration and schedule plan, press _Save Changes_ at the bottom of the planning tool.\n", + "\n", + "
\n", + "**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.\n", + "
\n", + "\n", + "
\n", + "**CAUTION**: The `virtualship plan` tool will check that the ship can reach each waypoint according to the prescribed ship speed (10 knots). However, before the ultimate simulation step (i.e. step 6 below) there will be a final, automated check that the schedule also accounts for the time taken to conduct the measurements at each site (e.g. a CTD cast in deeper waters will take longer). Therefore, we recommend to take this extra time into account at this stage of the planning by estimating how long each measurement will take and adding this time on.\n", + "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Reporting\n", - "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 reports needs to be written. \n", - "You can find many cruise reports online, e.g. https://www.bodc.ac.uk/resources/inventories/cruise_inventory/reports/pe358.pdf and blogs from many different cruises, e.g. https://www.nioz.nl/en/blog/topic/1027. \n", + "## 6) Run the expedition\n", "\n", - "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. \n", + "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](https://data.marine.copernicus.eu/products).\n", "\n", - "I look forward to seeing the impact of your collective efforts during the presentations!\n", + "
\n", + "**NOTE**: You will need to register for a Copernicus Marine Service account (you can do so [here](https://data.marine.copernicus.eu/register)), if you have not done so already.\n", + "
\n", "\n", - "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!\n", + "You can run your expedition simulation using the command: \n", + "\n", + "`virtualship run EXPEDITION_NAME`\n", + "\n", + "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).\n", + "\n", + "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 ;-)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 7) Results\n", + "\n", + "Upon successfully completing the simulation, results from the expedition will be stored in the `EXPEDITION_NAME/results` directory, written as [Zarr](https://zarr.dev/) files.\n", "\n", - "E.g. Normalizing failure: when things go wrong in participatory marine social science fieldwork. https://publications.csiro.au/publications/publication/PIcsiro:EP2022-3465\n", + "From here you can carry on your post-processing analysis, **but we will focus more on this in the next VirtualShip classroom session**.\n", "\n", - "E.g. Emotions and failure in academic life: Normalising the experience and building resilience. https://www.cambridge.org/core/journals/journal-of-management-and-organization/article/emotions-and-failure-in-academic-life-normalising-the-experience-and-building-resilience/91FD71A50A32404D8EDFFB7886FF3521" + "In general, we encourage you to explore and analyse these data using [Xarray](https://docs.xarray.dev/en/stable/). We also provide various further [VirtualShip tutorials](https://virtualship.readthedocs.io/en/latest/user-guide/tutorials/index.html) which provide examples of how to visualise data recorded by the VirtualShip instruments." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "![Our ocean provides](https://seewhatgrows.org/wp-content/uploads/2019/06/our-ocean.jpg)\n", - "![10 ways to help our ocean](https://oceanservice.noaa.gov/ocean/help-ocean.jpg)" + "## Reporting\n", + "\n", + "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).\n", + "\n", + "You can find many cruise [reports](https://www.bodc.ac.uk/resources/inventories/cruise_inventory/reports/pe358.pdf) and [blogs](https://www.nioz.nl/en/blog/topic/1027) online from many different cruises.\n", + "\n", + "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. \n", + "\n", + "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. \n", + "\n", + "We look forward to seeing the impact of your collective efforts during the presentations in a few weeks time!\n", + "\n", + "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!\n", + "\n", + "For example:\n", + "\n", + "- [Normalizing failure: when things go wrong in participatory marine social science fieldwork](https://publications.csiro.au/publications/publication/PIcsiro:EP2022-3465).\n", + "- [Emotions and failure in academic life: Normalising the experience and building resilience](https://www.cambridge.org/core/journals/journal-of-management-and-organization/article/emotions-and-failure-in-academic-life-normalising-the-experience-and-building-resilience/91FD71A50A32404D8EDFFB7886FF3521).\n", + "\n", + "---" ] } ], @@ -195,7 +288,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.15" + "version": "3.12.9" } }, "nbformat": 4, diff --git a/docs/user-guide/assignments/index.md b/docs/user-guide/assignments/index.md index d213532b..e488222c 100644 --- a/docs/user-guide/assignments/index.md +++ b/docs/user-guide/assignments/index.md @@ -11,4 +11,5 @@ Research_Proposal_only.ipynb sciencecommunication_assignment.ipynb Code_of_conduct.ipynb case_studies_virtualship.ipynb +Sail_the_ship.ipynb ``` diff --git a/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb b/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb index f6bbbf1a..64c78d8d 100644 --- a/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb +++ b/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb @@ -25,6 +25,10 @@ "\n", "Navigate to the [SURF Research Cloud Dashboard](https://portal.live.surfresearchcloud.nl/), and click \"access\" on the shared workspace.\n", "\n", + "
\n", + "**TIP**: You may sometimes hit a server error when accessing the workspace. If this happens, keep on trying (refresh), as the server spin-up can be a bit overloaded at times, but should get through eventually. Unfortunately this is out of our control.\n", + "
\n", + "\n", "## 3. Jupyter workspace layout and additional config\n", "\n", "```\n", @@ -38,19 +42,23 @@ "├── KERNEL-README.ipynb\n", "├── data\n", "│ └── datasets\n", - "| └── shared-storage <--- The shared persistent storage\n", + "| └── storage-osl <--- The shared persistent storage\n", "└── scratch\n", "```\n", "\n", "__Note__: the persistent storage folder may be called something slightly different in your instance, for example it may have a name specific to the course you are enrolled on, such as `data/storage-1-sept`.\n", "\n", - "In the Jupyter launcher, you can open a Terminal session by clicking on the \"Terminal\" box. From here you can navigate the workspace directory structure and run commands.\n", + "In the Jupyter launcher, you can open a Terminal session by clicking on \"Terminal\" button under the \"Other\" section, or by going to the \"File\" menu --> \"New\" --> \"Terminal\". From here you can navigate the workspace directory structure and run commands.\n", + "\n", + "
\n", + "**INFO**: VirtualShip is a command line interface (CLI) based tool. We will be working predominantly via the command line in Terminal (typing out commands instead of pointing and clicking). If you are unfamiliar with what a CLI is, see [here](https://www.w3schools.com/whatis/whatis_cli.asp) for more information. In our case, the Terminal is just a way to access the CLI on the SURF RC virtual machine.\n", + "
\n", "\n", - "The `data/shared-storage` folder is your persistent storage. Here you can make a folder (e.g., by running `mkdir data/shared-storage/{your-group-name}` as a command in the Terminal, replacing `{your-group-name}` with your group name) to house your work for the unit. This folder will be visible to anyone using the workspace, but only you will be able to make edits to it. This is the primary place you should store your `virtualship` configs and content relevant to this unit.\n", + "The `data/storage-osl` folder is your persistent storage. Here you can make a folder (e.g., by running `mkdir data/storage-osl/{your-group-name}` as a command in the Terminal, replacing `{your-group-name}` with your group name) to house your work for the unit. This folder will be visible to anyone using the workspace, but only you will be able to make edits to it. This is the primary place you should store your `virtualship` configs and content relevant to this unit.\n", "\n", "---\n", "\n", - "To be able to run VirtualShip from the Terminal, we need to take some additional steps which are detailed in the `KERNEL-README.ipynb`. This contains important information for configuring your environment. Specifically, for our uses, the \"Initialize conda\" section (also copied below). Do the following:\n", + "To be able to run VirtualShip from the Terminal, we need to take some additional steps which are detailed in the `KERNEL-README.ipynb` in your home folder. This contains important information for configuring your environment. Specifically, for our uses, the \"Initialize conda\" section (also copied below). Do the following:\n", "\n", "#### Initialize conda\n", "\n", @@ -80,7 +88,13 @@ "\n", "Here you can do `conda activate virtualship` to activate the environment called \"virtualship\". This environment is a shared environment among all workspace users that can be centrally updated. If you want, you can create and manage your own environments by running the relevant conda commands.\n", "\n", - "With the `virtualship` environment, you now have access to the `virtualship` command in your Terminal, which can be confirmed by running `virtualship --help`. From here you can `cd` into `data/shared-storage/{your-name}` and run `virtualship` commands as you would on your local machine (see the VirtualShip [quickstart guide](https://virtualship.readthedocs.io/en/latest/user-guide/quickstart.html)). \n", + "With the `virtualship` environment, you now have access to the `virtualship` command in your Terminal, which can be confirmed by running `virtualship --help`. \n", + "\n", + "From here you can `cd` ('change directory') into `data/storage-osl/{your-name}` and run `virtualship` commands as you would on your local machine (see the VirtualShip [quickstart guide](https://virtualship.readthedocs.io/en/latest/user-guide/quickstart.html)). \n", + "\n", + "
\n", + "**TIP**: Return to your course-specific instructions/assignment notebook now if you were following along with this setup in class!\n", + "
\n", "\n", "---\n", "\n",