diff --git a/docs/conf.py b/docs/conf.py index ea12ec890..e50644098 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,6 +15,7 @@ "sphinx.ext.napoleon", # "sphinx_autodoc_typehints",# https://github.com/Parcels-code/virtualship/pull/125#issuecomment-2668766302 "sphinx_copybutton", + "sphinx_design", ] source_suffix = [".rst", ".md"] @@ -44,6 +45,7 @@ "type": "fontawesome", } ], + "announcement": "Warning: this is a pre-release version of the VirtualShip documentation (V1 to be released in September/October 2026). The contents are subject to change and may not be complete.", } html_context = { "github_user": "Parcels-code", @@ -70,11 +72,13 @@ always_document_param_types = True nbsphinx_thumbnails = { + "user-guide/quickstart": "user-guide/_images/AnnaWeber.jpeg", + "user-guide/tutorials/index": "user-guide/_images/AnnaWeber.jpeg", "user-guide/assignments/Research_proposal_intro": "user-guide/_images/MFPtimeline.jpg", "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", "user-guide/teacher-content/UU-ocean-of-future/Tutorial1": "user-guide/_images/freepik_assignment.png", @@ -82,8 +86,9 @@ "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", - "user-guide/teacher-content/UU-dyoc/example_expedition": "user-guide/_images/AnnaWeber.jpeg", - "user-guide/teacher-content/UU-dyoc/file_permissions": "user-guide/_images/AnnaWeber.jpeg", + "user-guide/tutorials/codespaces_guide": "user-guide/_images/AnnaWeber.jpeg", + "user-guide/tutorials/binder_guide": "user-guide/_images/AnnaWeber.jpeg", + "user-guide/user-profiles/educators/letter": "user-guide/_images/freepik_research_vessel.jpg", } sphinx_gallery_conf = {"default_thumb_file": "_static/virtual_ship_logo.png"} diff --git a/docs/user-guide/example_log_instruments.gif b/docs/user-guide/_images/example_log_instruments.gif similarity index 100% rename from docs/user-guide/example_log_instruments.gif rename to docs/user-guide/_images/example_log_instruments.gif diff --git a/docs/user-guide/example_plan_app.gif b/docs/user-guide/_images/example_plan_app.gif similarity index 100% rename from docs/user-guide/example_plan_app.gif rename to docs/user-guide/_images/example_plan_app.gif diff --git a/docs/user-guide/image-1.png b/docs/user-guide/_images/mfp_route.png similarity index 100% rename from docs/user-guide/image-1.png rename to docs/user-guide/_images/mfp_route.png diff --git a/docs/user-guide/developer-content/advisory_group/DBR2_figure.png b/docs/user-guide/archives/advisory_group/DBR2_figure.png similarity index 100% rename from docs/user-guide/developer-content/advisory_group/DBR2_figure.png rename to docs/user-guide/archives/advisory_group/DBR2_figure.png diff --git a/docs/user-guide/developer-content/advisory_group/DBRcycles.png b/docs/user-guide/archives/advisory_group/DBRcycles.png similarity index 100% rename from docs/user-guide/developer-content/advisory_group/DBRcycles.png rename to docs/user-guide/archives/advisory_group/DBRcycles.png diff --git a/docs/user-guide/developer-content/advisory_group/Presentation.html b/docs/user-guide/archives/advisory_group/Presentation.html similarity index 100% rename from docs/user-guide/developer-content/advisory_group/Presentation.html rename to docs/user-guide/archives/advisory_group/Presentation.html diff --git a/docs/user-guide/developer-content/advisory_group/Presentation.qmd b/docs/user-guide/archives/advisory_group/Presentation.qmd similarity index 100% rename from docs/user-guide/developer-content/advisory_group/Presentation.qmd rename to docs/user-guide/archives/advisory_group/Presentation.qmd diff --git a/docs/user-guide/developer-content/advisory_group/evaluation.png b/docs/user-guide/archives/advisory_group/evaluation.png similarity index 100% rename from docs/user-guide/developer-content/advisory_group/evaluation.png rename to docs/user-guide/archives/advisory_group/evaluation.png diff --git a/docs/user-guide/developer-content/advisory_group/evaluation_vr.png b/docs/user-guide/archives/advisory_group/evaluation_vr.png similarity index 100% rename from docs/user-guide/developer-content/advisory_group/evaluation_vr.png rename to docs/user-guide/archives/advisory_group/evaluation_vr.png diff --git a/docs/user-guide/developer-content/advisory_group/software_evaluation.png b/docs/user-guide/archives/advisory_group/software_evaluation.png similarity index 100% rename from docs/user-guide/developer-content/advisory_group/software_evaluation.png rename to docs/user-guide/archives/advisory_group/software_evaluation.png diff --git a/docs/user-guide/developer-content/advisory_group/software_evaluation_bsc.png b/docs/user-guide/archives/advisory_group/software_evaluation_bsc.png similarity index 100% rename from docs/user-guide/developer-content/advisory_group/software_evaluation_bsc.png rename to docs/user-guide/archives/advisory_group/software_evaluation_bsc.png diff --git a/docs/user-guide/developer-content/inspiration-showcase/media/argo_plot.html b/docs/user-guide/archives/inspiration-showcase/media/argo_plot.html similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/media/argo_plot.html rename to docs/user-guide/archives/inspiration-showcase/media/argo_plot.html diff --git a/docs/user-guide/developer-content/inspiration-showcase/media/assignments.png b/docs/user-guide/archives/inspiration-showcase/media/assignments.png similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/media/assignments.png rename to docs/user-guide/archives/inspiration-showcase/media/assignments.png diff --git a/docs/user-guide/developer-content/inspiration-showcase/media/banner.png b/docs/user-guide/archives/inspiration-showcase/media/banner.png similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/media/banner.png rename to docs/user-guide/archives/inspiration-showcase/media/banner.png diff --git a/docs/user-guide/developer-content/inspiration-showcase/media/case_studies.png b/docs/user-guide/archives/inspiration-showcase/media/case_studies.png similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/media/case_studies.png rename to docs/user-guide/archives/inspiration-showcase/media/case_studies.png diff --git a/docs/user-guide/developer-content/inspiration-showcase/media/figure1.png b/docs/user-guide/archives/inspiration-showcase/media/figure1.png similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/media/figure1.png rename to docs/user-guide/archives/inspiration-showcase/media/figure1.png diff --git a/docs/user-guide/developer-content/inspiration-showcase/media/headset.png b/docs/user-guide/archives/inspiration-showcase/media/headset.png similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/media/headset.png rename to docs/user-guide/archives/inspiration-showcase/media/headset.png diff --git a/docs/user-guide/developer-content/inspiration-showcase/media/qrcode_github.png b/docs/user-guide/archives/inspiration-showcase/media/qrcode_github.png similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/media/qrcode_github.png rename to docs/user-guide/archives/inspiration-showcase/media/qrcode_github.png diff --git a/docs/user-guide/developer-content/inspiration-showcase/media/qrcode_website.png b/docs/user-guide/archives/inspiration-showcase/media/qrcode_website.png similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/media/qrcode_website.png rename to docs/user-guide/archives/inspiration-showcase/media/qrcode_website.png diff --git a/docs/user-guide/developer-content/inspiration-showcase/media/ship_still.mp4 b/docs/user-guide/archives/inspiration-showcase/media/ship_still.mp4 similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/media/ship_still.mp4 rename to docs/user-guide/archives/inspiration-showcase/media/ship_still.mp4 diff --git a/docs/user-guide/developer-content/inspiration-showcase/media/tutorials.png b/docs/user-guide/archives/inspiration-showcase/media/tutorials.png similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/media/tutorials.png rename to docs/user-guide/archives/inspiration-showcase/media/tutorials.png diff --git a/docs/user-guide/developer-content/inspiration-showcase/media/userguide_docs.png b/docs/user-guide/archives/inspiration-showcase/media/userguide_docs.png similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/media/userguide_docs.png rename to docs/user-guide/archives/inspiration-showcase/media/userguide_docs.png diff --git a/docs/user-guide/developer-content/inspiration-showcase/media/vr_class.png b/docs/user-guide/archives/inspiration-showcase/media/vr_class.png similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/media/vr_class.png rename to docs/user-guide/archives/inspiration-showcase/media/vr_class.png diff --git a/docs/user-guide/developer-content/inspiration-showcase/media/vr_screenshot.png b/docs/user-guide/archives/inspiration-showcase/media/vr_screenshot.png similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/media/vr_screenshot.png rename to docs/user-guide/archives/inspiration-showcase/media/vr_screenshot.png diff --git a/docs/user-guide/developer-content/inspiration-showcase/media/youtube_channel.png b/docs/user-guide/archives/inspiration-showcase/media/youtube_channel.png similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/media/youtube_channel.png rename to docs/user-guide/archives/inspiration-showcase/media/youtube_channel.png diff --git a/docs/user-guide/developer-content/inspiration-showcase/showcase.html b/docs/user-guide/archives/inspiration-showcase/showcase.html similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/showcase.html rename to docs/user-guide/archives/inspiration-showcase/showcase.html diff --git a/docs/user-guide/developer-content/inspiration-showcase/showcase.qmd b/docs/user-guide/archives/inspiration-showcase/showcase.qmd similarity index 100% rename from docs/user-guide/developer-content/inspiration-showcase/showcase.qmd rename to docs/user-guide/archives/inspiration-showcase/showcase.qmd diff --git a/docs/user-guide/developer-content/nmf-roadshow/media/argo_plot.html b/docs/user-guide/archives/nmf-roadshow/media/argo_plot.html similarity index 100% rename from docs/user-guide/developer-content/nmf-roadshow/media/argo_plot.html rename to docs/user-guide/archives/nmf-roadshow/media/argo_plot.html diff --git a/docs/user-guide/developer-content/nmf-roadshow/media/figure1.png b/docs/user-guide/archives/nmf-roadshow/media/figure1.png similarity index 100% rename from docs/user-guide/developer-content/nmf-roadshow/media/figure1.png rename to docs/user-guide/archives/nmf-roadshow/media/figure1.png diff --git a/docs/user-guide/developer-content/nmf-roadshow/media/nioz_ctd_image.JPEG b/docs/user-guide/archives/nmf-roadshow/media/nioz_ctd_image.JPEG similarity index 100% rename from docs/user-guide/developer-content/nmf-roadshow/media/nioz_ctd_image.JPEG rename to docs/user-guide/archives/nmf-roadshow/media/nioz_ctd_image.JPEG diff --git a/docs/user-guide/developer-content/nmf-roadshow/media/qrcode_form.png b/docs/user-guide/archives/nmf-roadshow/media/qrcode_form.png similarity index 100% rename from docs/user-guide/developer-content/nmf-roadshow/media/qrcode_form.png rename to docs/user-guide/archives/nmf-roadshow/media/qrcode_form.png diff --git a/docs/user-guide/developer-content/nmf-roadshow/media/qrcode_github.png b/docs/user-guide/archives/nmf-roadshow/media/qrcode_github.png similarity index 100% rename from docs/user-guide/developer-content/nmf-roadshow/media/qrcode_github.png rename to docs/user-guide/archives/nmf-roadshow/media/qrcode_github.png diff --git a/docs/user-guide/developer-content/nmf-roadshow/media/ship_still.mp4 b/docs/user-guide/archives/nmf-roadshow/media/ship_still.mp4 similarity index 100% rename from docs/user-guide/developer-content/nmf-roadshow/media/ship_still.mp4 rename to docs/user-guide/archives/nmf-roadshow/media/ship_still.mp4 diff --git a/docs/user-guide/developer-content/nmf-roadshow/media/signup_QRCode.png b/docs/user-guide/archives/nmf-roadshow/media/signup_QRCode.png similarity index 100% rename from docs/user-guide/developer-content/nmf-roadshow/media/signup_QRCode.png rename to docs/user-guide/archives/nmf-roadshow/media/signup_QRCode.png diff --git a/docs/user-guide/developer-content/nmf-roadshow/showcase.html b/docs/user-guide/archives/nmf-roadshow/showcase.html similarity index 100% rename from docs/user-guide/developer-content/nmf-roadshow/showcase.html rename to docs/user-guide/archives/nmf-roadshow/showcase.html diff --git a/docs/user-guide/developer-content/nmf-roadshow/showcase.qmd b/docs/user-guide/archives/nmf-roadshow/showcase.qmd similarity index 100% rename from docs/user-guide/developer-content/nmf-roadshow/showcase.qmd rename to docs/user-guide/archives/nmf-roadshow/showcase.qmd diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/performance/performance_v03.py b/docs/user-guide/archives/parcels-meeting-Nov2025/performance/performance_v03.py similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/performance/performance_v03.py rename to docs/user-guide/archives/parcels-meeting-Nov2025/performance/performance_v03.py diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/performance/performance_v03_fromdata.py b/docs/user-guide/archives/parcels-meeting-Nov2025/performance/performance_v03_fromdata.py similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/performance/performance_v03_fromdata.py rename to docs/user-guide/archives/parcels-meeting-Nov2025/performance/performance_v03_fromdata.py diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/performance/plot_performance.py b/docs/user-guide/archives/parcels-meeting-Nov2025/performance/plot_performance.py similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/performance/plot_performance.py rename to docs/user-guide/archives/parcels-meeting-Nov2025/performance/plot_performance.py diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/performance/results/performance_results.csv b/docs/user-guide/archives/parcels-meeting-Nov2025/performance/results/performance_results.csv similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/performance/results/performance_results.csv rename to docs/user-guide/archives/parcels-meeting-Nov2025/performance/results/performance_results.csv diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/performance/results/performance_results_fromdata.csv b/docs/user-guide/archives/parcels-meeting-Nov2025/performance/results/performance_results_fromdata.csv similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/performance/results/performance_results_fromdata.csv rename to docs/user-guide/archives/parcels-meeting-Nov2025/performance/results/performance_results_fromdata.csv diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/Presentation.html b/docs/user-guide/archives/parcels-meeting-Nov2025/presentation/Presentation.html similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/Presentation.html rename to docs/user-guide/archives/parcels-meeting-Nov2025/presentation/Presentation.html diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/Presentation.qmd b/docs/user-guide/archives/parcels-meeting-Nov2025/presentation/Presentation.qmd similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/Presentation.qmd rename to docs/user-guide/archives/parcels-meeting-Nov2025/presentation/Presentation.qmd diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/Figure_copernicusonly.png b/docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/Figure_copernicusonly.png similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/Figure_copernicusonly.png rename to docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/Figure_copernicusonly.png diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/Figure_fromdata_hiddenlast.png b/docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/Figure_fromdata_hiddenlast.png similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/Figure_fromdata_hiddenlast.png rename to docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/Figure_fromdata_hiddenlast.png diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/Figure_fromdata_nolast.png b/docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/Figure_fromdata_nolast.png similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/Figure_fromdata_nolast.png rename to docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/Figure_fromdata_nolast.png diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/Figure_fromdata_showlast.png b/docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/Figure_fromdata_showlast.png similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/Figure_fromdata_showlast.png rename to docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/Figure_fromdata_showlast.png diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/download (1).png b/docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/download (1).png similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/download (1).png rename to docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/download (1).png diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/figure1.png b/docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/figure1.png similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/figure1.png rename to docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/figure1.png diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/sample_3D_temperature.html b/docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/sample_3D_temperature.html similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/sample_3D_temperature.html rename to docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/sample_3D_temperature.html diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/sample_slider_temperature.html b/docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/sample_slider_temperature.html similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/sample_slider_temperature.html rename to docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/sample_slider_temperature.html diff --git a/docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/snapshot2.png b/docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/snapshot2.png similarity index 100% rename from docs/user-guide/developer-content/parcels-meeting-Nov2025/presentation/images/snapshot2.png rename to docs/user-guide/archives/parcels-meeting-Nov2025/presentation/images/snapshot2.png diff --git a/docs/user-guide/teacher-content/UU-dyoc/example_expedition.md b/docs/user-guide/archives/teaching-25-26/UU-dyoc/example_expedition.md similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/example_expedition.md rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/example_expedition.md diff --git a/docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_A.yaml b/docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_A.yaml similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_A.yaml rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_A.yaml diff --git a/docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_B.yaml b/docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_B.yaml similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_B.yaml rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_B.yaml diff --git a/docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_C.yaml b/docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_C.yaml similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_C.yaml rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_C.yaml diff --git a/docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_D.yaml b/docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_D.yaml similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_D.yaml rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_D.yaml diff --git a/docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_E.yaml b/docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_E.yaml similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_E.yaml rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_E.yaml diff --git a/docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_F.yaml b/docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_F.yaml similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_F.yaml rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_F.yaml diff --git a/docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_H.yaml b/docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_H.yaml similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_H.yaml rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_H.yaml diff --git a/docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_I.yaml b/docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_I.yaml similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_I.yaml rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_I.yaml diff --git a/docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_J.yaml b/docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_J.yaml similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_J.yaml rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_J.yaml diff --git a/docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_K.yaml b/docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_K.yaml similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/expeditions/expedition_K.yaml rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/expeditions/expedition_K.yaml diff --git a/docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/yaml_summary.ipynb b/docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/yaml_summary.ipynb similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/expedition_summaries/yaml_summary.ipynb rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/expedition_summaries/yaml_summary.ipynb diff --git a/docs/user-guide/teacher-content/UU-dyoc/file_permissions.md b/docs/user-guide/archives/teaching-25-26/UU-dyoc/file_permissions.md similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/file_permissions.md rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/file_permissions.md diff --git a/docs/user-guide/teacher-content/UU-dyoc/vsc_overview/Presentation.html b/docs/user-guide/archives/teaching-25-26/UU-dyoc/vsc_overview/Presentation.html similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/vsc_overview/Presentation.html rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/vsc_overview/Presentation.html diff --git a/docs/user-guide/teacher-content/UU-dyoc/vsc_overview/Presentation.qmd b/docs/user-guide/archives/teaching-25-26/UU-dyoc/vsc_overview/Presentation.qmd similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/vsc_overview/Presentation.qmd rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/vsc_overview/Presentation.qmd diff --git a/docs/user-guide/teacher-content/UU-dyoc/vsc_overview/images/ship_still.mp4 b/docs/user-guide/archives/teaching-25-26/UU-dyoc/vsc_overview/images/ship_still.mp4 similarity index 100% rename from docs/user-guide/teacher-content/UU-dyoc/vsc_overview/images/ship_still.mp4 rename to docs/user-guide/archives/teaching-25-26/UU-dyoc/vsc_overview/images/ship_still.mp4 diff --git a/docs/user-guide/teacher-content/UU-ocean-of-future/CTD_transects.ipynb b/docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/CTD_transects.ipynb similarity index 100% rename from docs/user-guide/teacher-content/UU-ocean-of-future/CTD_transects.ipynb rename to docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/CTD_transects.ipynb diff --git a/docs/user-guide/teacher-content/UU-ocean-of-future/CoordinatesExport-Transect.xlsx b/docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/CoordinatesExport-Transect.xlsx similarity index 100% rename from docs/user-guide/teacher-content/UU-ocean-of-future/CoordinatesExport-Transect.xlsx rename to docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/CoordinatesExport-Transect.xlsx diff --git a/docs/user-guide/teacher-content/UU-ocean-of-future/Presentation.html b/docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/Presentation.html similarity index 100% rename from docs/user-guide/teacher-content/UU-ocean-of-future/Presentation.html rename to docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/Presentation.html diff --git a/docs/user-guide/teacher-content/UU-ocean-of-future/Presentation.qmd b/docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/Presentation.qmd similarity index 100% rename from docs/user-guide/teacher-content/UU-ocean-of-future/Presentation.qmd rename to docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/Presentation.qmd diff --git a/docs/user-guide/teacher-content/UU-ocean-of-future/Tutorial1.ipynb b/docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/Tutorial1.ipynb similarity index 100% rename from docs/user-guide/teacher-content/UU-ocean-of-future/Tutorial1.ipynb rename to docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/Tutorial1.ipynb diff --git a/docs/user-guide/teacher-content/UU-ocean-of-future/Tutorial2.ipynb b/docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/Tutorial2.ipynb similarity index 100% rename from docs/user-guide/teacher-content/UU-ocean-of-future/Tutorial2.ipynb rename to docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/Tutorial2.ipynb diff --git a/docs/user-guide/teacher-content/UU-ocean-of-future/_publish.yml b/docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/_publish.yml similarity index 100% rename from docs/user-guide/teacher-content/UU-ocean-of-future/_publish.yml rename to docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/_publish.yml diff --git a/docs/user-guide/teacher-content/UU-ocean-of-future/plot_3D.py b/docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/plot_3D.py similarity index 100% rename from docs/user-guide/teacher-content/UU-ocean-of-future/plot_3D.py rename to docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/plot_3D.py diff --git a/docs/user-guide/teacher-content/UU-ocean-of-future/plot_slider.py b/docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/plot_slider.py similarity index 100% rename from docs/user-guide/teacher-content/UU-ocean-of-future/plot_slider.py rename to docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/plot_slider.py diff --git a/docs/user-guide/teacher-content/UU-ocean-of-future/schedule_monitor.ipynb b/docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/schedule_monitor.ipynb similarity index 100% rename from docs/user-guide/teacher-content/UU-ocean-of-future/schedule_monitor.ipynb rename to docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/schedule_monitor.ipynb diff --git a/docs/user-guide/teacher-content/UU-ocean-of-future/timeseries.py b/docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/timeseries.py similarity index 100% rename from docs/user-guide/teacher-content/UU-ocean-of-future/timeseries.py rename to docs/user-guide/archives/teaching-25-26/UU-ocean-of-future/timeseries.py diff --git a/docs/user-guide/developer-content/yearplan-26-27/gantt_2026-27-1.svg b/docs/user-guide/archives/yearplan-26-27/gantt_2026-27-1.svg similarity index 100% rename from docs/user-guide/developer-content/yearplan-26-27/gantt_2026-27-1.svg rename to docs/user-guide/archives/yearplan-26-27/gantt_2026-27-1.svg diff --git a/docs/user-guide/developer-content/yearplan-26-27/gantt_2026-27.md b/docs/user-guide/archives/yearplan-26-27/gantt_2026-27.md similarity index 100% rename from docs/user-guide/developer-content/yearplan-26-27/gantt_2026-27.md rename to docs/user-guide/archives/yearplan-26-27/gantt_2026-27.md diff --git a/docs/user-guide/assignments/Research_proposal_intro.ipynb b/docs/user-guide/assignments/Research_proposal_intro.ipynb index 2f19e2b1d..aac530361 100644 --- a/docs/user-guide/assignments/Research_proposal_intro.ipynb +++ b/docs/user-guide/assignments/Research_proposal_intro.ipynb @@ -17,7 +17,7 @@ "\n", "You will have access to the ship for a maximum of three weeks, period—a duration identified as a favorable trade-off between research time and ensuring an enjoyable vessel experience. Your vessel will be equipped with two vessel-mounted ADCPs, a CTD, and can collect underway data of temperature and salinity from 2 meters below the hull of the ship. In addition, you can deploy XBTs and up to 30 Argo floats and/or 30 surface drifters. A detailed plan of your route, timing and required instruments needs to be sent in for approval/grading. \n", "\n", - "To get a taste of what it’s like to board a real vessel, you'll find some [general information that is shared with all cruise participants here](../teacher-content/letter.md)\n", + "To get a taste of what it’s like to board a real vessel, you'll find some [general information that is shared with all cruise participants here](../user-profiles/educators/letter.md)\n", "\n", "You might also like to watch the video clip about [Life on board a research ship (RRS Discovery)](https://youtu.be/IHM7JFWg9qw?feature=shared) or the one below. \n", "\n", diff --git a/docs/user-guide/assignments/Sail_the_ship.ipynb b/docs/user-guide/assignments/Sail_the_ship.ipynb deleted file mode 100644 index db2562b7c..000000000 --- a/docs/user-guide/assignments/Sail_the_ship.ipynb +++ /dev/null @@ -1,322 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Sail the ship\n", - "\n", - "```\n", - "Note: This guide is specific to students who are enrolled at Utrecht University.\n", - "```\n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Welcome aboard VirtualShip!\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 we'd like to share with you to ensure a smooth and enriching experience:\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", - "\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", - "**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", - "Before going on any research expedition you need follow a one day Safety at Sea course and get a medical check-up.\n", - "\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", - "**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", - "**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", - "**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", - "**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", - "**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", - "**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", - "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", - "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", - "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": [ - "## 2) Set up your virtual machine\n", - "\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", - "- You aren't limited to the power of your laptop.\n", - "- The environment is pre-configured with all necessary software and dependencies.\n", - "\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": [ - "## 3) Expedition route planning\n", - "\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/` 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.\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/{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": [ - "## 4) Expedition initialisation\n", - "\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", - "
\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/{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", - "Now enter the following command in the Terminal (changing `EXPEDITION_NAME` to something more meaningful for your group's expedition):\n", - "\n", - "`virtualship init EXPEDITION_NAME --from-mfp {CoordinatesExport}.xlsx`\n", - "\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", - "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", - "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", - "**TIP**: Using the `virtualship plan` tool is optional. Advanced users can also edit the `expedition.yaml` file directly if preferred.\n", - "
\n", - "\n", - "### Ship speed\n", - "\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", - "### Underway measurements\n", - "\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", - "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", - "### Instrument/sensor configuration\n", - "\n", - "The most important instrument configuration setting to consider is the list of **sensors** for each instrument, which controls what type of measurements/variables the instrument records in the simulation and therefore what output data you will receive for each instrument.\n", - "\n", - "Sensor lists can be configured for each instrument under _Ship Config Editor_ > _Instrument Configurations_. For example, for the CTD instrument, you can specify which sensors to include in the simulation (e.g., `TEMPERATURE`, `SALINITY`, `OXYGEN`, etc.) by toggling the respective switches on or off.\n", - "\n", - "
\n", - "**Note**: Sensor choices are only relevant for the instruments you plan to deploy as [underway measurements](#underway-measurements) or at waypoints across your expedition schedule [(see below)](#instrument-selection). For example, if you do not select to deploy a CTD at any of your waypoints, the CTD sensor choices will not affect any output data.\n", - "
\n", - "\n", - "
\n", - "**TIP**: See [here](../documentation/full_sensor_list.md) for more information on the sensors available for each instrument.\n", - "
\n", - "\n", - "There are other instrument configurations settings that can be adjusted in the editor as well (e.g. `max_depth` for the CTD), but these are more advanced and in most cases do not need to be changed from the default values.\n", - "\n", - "### 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 which instruments are available in VirtualShip, and a brief introduction to each.\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", - "
" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 6) Run the expedition\n", - "\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", - "
\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", - "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 ;-)\n", - "\n", - "
\n", - "**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!\n", - "
" - ] - }, - { - "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 in `.parquet` [format](https://parquet.apache.org/).\n", - "\n", - "From here you can carry on your analysis. In general, we encourage you to use [Parcels](https://Parcels-code.org/) (i.e. `parcels.read_particlefile()`) to read in VirtualShip output files, and tools such as [Polars](https://www.pola.rs/) and/or [Pandas](https://pandas.pydata.org/) for further data analysis. 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. Use these to help you get started!\n", - "\n", - "If you are using VirtualShip in class, the same tutorial notebooks may 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. \n", - "\n", - "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." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 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/news-and-blogs) 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", - "---" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "ship", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.12.12" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/docs/user-guide/assignments/index.md b/docs/user-guide/assignments/index.md index aacd2dbf5..e7a419684 100644 --- a/docs/user-guide/assignments/index.md +++ b/docs/user-guide/assignments/index.md @@ -11,5 +11,5 @@ Virtualship_research_proposal.ipynb sciencecommunication_assignment.ipynb Code_of_conduct.ipynb case_studies_virtualship.ipynb -Sail_the_ship.ipynb +sail_the_ship.ipynb ``` diff --git a/docs/user-guide/assignments/sail_the_ship.md b/docs/user-guide/assignments/sail_the_ship.md new file mode 100644 index 000000000..670bf929c --- /dev/null +++ b/docs/user-guide/assignments/sail_the_ship.md @@ -0,0 +1,216 @@ +# Sail the ship + +## Welcome aboard VirtualShip! + +Welcome aboard, oceanography students, to our scientific research vessel! We're thrilled to have you join us for this exciting 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 familiarise yourselves with the layout of the ship. Get to know key areas such as the laboratories, living quarters, dining area, and deck spaces. + +**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. + +```{note} +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](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. + +## 2) Set up your virtual machine + +You will be informed by your teacher if you will be using a cloud-based, pre-configured environment for VirtualShip (e.g., GitHub Codespaces) or if you should set up a local installation of the software. Please follow the instructions provided by your teacher to access your virtual machine accordingly. + +## 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, your approved proposal from your instructor may limit the amount of ship time you have received, so make sure to plan your route accordingly! + +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. + +```{note} +The MFP tool is used by professional oceanographers to plan research expeditions, so this is a great opportunity to get a feel for how real-world oceanographic research is planned! +``` + +### 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. + +### _If using a cloud-based workspace_... upload the coordinates to your virtual machine + +```{tip} +We suggest practicing good file management and creating a dedicated folder for your group's expedition data in the workspace. You can do so running `mkdir {your-group-name}` in the Terminal (replacing `{your-group-name}` with your actual group name) or via the File Explore panel in the Codespaces interface. +``` + +Navigate to the directory where your group will be running your expedition (e.g. `{your-group-name}`). Then upload the exported `.xlsx` file (it will be called something like `CruiseDataExport-20260812T1506.xlsx`) by right clicking in the File Explorer panel (ideally in the directory you created for your group's expedition data) and selecting the "Upload" option. From here you will be able to select your MFP export file. + +## 4) Expedition initialisation + +```{important} +When working in the Terminal, navigate to where you would like your expedition to be run on your (virtual) machine. You can do so by `cd {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 {CruiseDataExport}.xlsx` + +```{tip} +The `{CruiseDataExport}.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 own 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](../tutorials/working_with_expedition_yaml.md) 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`. + +### 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](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. + +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). + +### Instrument/sensor configuration + +The most important instrument configuration setting to consider is the list of **sensors** for each instrument, which controls what type of measurements/variables the instrument records in the simulation and therefore what output data you will receive for each instrument. + +Sensor lists can be configured for each instrument under _Ship Config Editor_ > _Instrument Configurations_. For example, for the CTD instrument, you can specify which sensors to include in the simulation (e.g., `TEMPERATURE`, `SALINITY`, `OXYGEN`, etc.) by toggling the respective switches on or off. + +```{note} +Sensor choices are only relevant for the instruments you plan to deploy as [underway measurements](#underway-measurements) or at waypoints across your expedition schedule [(see below)](#instrument-selection). For example, if you do not select to deploy a CTD at any of your waypoints, the CTD sensor choices will not affect any output data. +``` + +```{tip} +See [here](../documentation/full_sensor_list.md) for more information on the sensors available for each instrument. +``` + +There are other instrument configurations settings that can be adjusted in the editor as well (e.g. `max_depth` for the CTD), but these are more advanced and in most cases do not need to be changed from the default values. + +### 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](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Research_proposal_intro.html#Measurement-Options) for more information on which instruments are available in VirtualShip, and a brief introduction to each. +``` + +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. + +### 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](https://data.marine.copernicus.eu/products). + +```{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. +``` + +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 ;-) + +```{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 in `.parquet` [format](https://parquet.apache.org/). + +From here you can carry on your analysis. In general, we encourage you to use [Parcels](https://Parcels-code.org/) (i.e. `parcels.read_particlefile()`) to read in VirtualShip output files, and tools such as [Polars](https://www.pola.rs/) and/or [Pandas](https://pandas.pydata.org/) for further data analysis. 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. Use these to help you get started! + +```{tip} +We also host a [Binder](https://mybinder.org/) environment (note this is separate to the GitHub Codespaces workspace you may be using) with all the necessary post-processing tools pre-installed and all the tutorials ready to use. This might be useful as a means to explore your data at first. See [here](../tutorials/binder_workspace.md) for more detail or await further instruction from your instructor. +``` + +## 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 potentially in the case of this course, a presentation). + +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/news-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. + +If your course assignment involves a presentation, 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: + +- [Normalizing failure: when things go wrong in participatory marine social science fieldwork](https://publications.csiro.au/publications/publication/PIcsiro:EP2022-3465). +- [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). diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md index 24eee0c89..0a512abe9 100644 --- a/docs/user-guide/index.md +++ b/docs/user-guide/index.md @@ -1,21 +1,107 @@ # User Guide -```{toctree} -:maxdepth: 1 +The following sections provide guidance for using VirtualShip, organised by how you intend to interact with the platform. -quickstart -teacher-content/index -tutorials/index -assignments/index +::::{grid} 1 +:gutter: 4 +:padding: 2 2 0 0 +:class-container: sd-text-center + +````{grid-item-card} Quickstart 🚢 +:shadow: md + +Get a general overview of VirtualShip's capabilities and main features to jump right in. + ++++ + +```{button-ref} quickstart +:ref-type: doc +:color: secondary +:expand: + +Quickstart Guide ``` +```` -# Documentation +:::: + +::::{grid} 1 2 2 2 +:gutter: 4 +:padding: 2 2 0 0 +:class-container: sd-text-center + +````{grid-item-card} Learners 🎓 +:shadow: md + +Design an expedition and sail the VirtualShip to collect data and complete assignments. -```{toctree} -:maxdepth: 1 ++++ -documentation/full_sensor_list.md -documentation/copernicus_products.md -documentation/pre_download_data.md -documentation/example_copernicus_download.ipynb +```{button-ref} user-profiles/learners/index +:ref-type: doc +:color: secondary +:expand: + +Learner guide +``` +```` + +````{grid-item-card} Educators 📖 +:shadow: md + +Find teaching content and materials for setting up VirtualShip in your classroom. + ++++ + +```{button-ref} user-profiles/educators/index +:ref-type: doc +:color: secondary +:expand: + +Educator guide ``` +```` + +````{grid-item-card} Researchers 📈 +:shadow: md + +Leverage VirtualShip to design, test, and optimise oceanographic sampling strategies. + ++++ + +```{button-ref} user-profiles/researchers/index +:ref-type: doc +:color: secondary +:expand: + +Researcher guide +``` +```` + +````{grid-item-card} Developers 🖥️ +:shadow: md + +Contribute to the development of VirtualShip... as a programmer, oceanographer, education expert and more! ++++ + +```{button-ref} user-profiles/developers/index +:ref-type: doc +:color: secondary +:expand: + +Developer guide +``` +```` + +:::: + +--- + +# Documentation + +The following guides provide additional, detailed information on VirtualShip's functionality. This is technical information for users who want to understand the inner workings of the software, including its data sources and advanced configuration options. + +- [Available instrument sensors](documentation/full_sensor_list.md) +- [Copernicus Marine Service products](documentation/copernicus_products.md) +- [Pre-downloading data](documentation/pre_download_data.md) +- [Example Copernicus download](documentation/example_copernicus_download.ipynb) diff --git a/docs/user-guide/quickstart.md b/docs/user-guide/quickstart.md index 5f913a797..b9c9c8b42 100644 --- a/docs/user-guide/quickstart.md +++ b/docs/user-guide/quickstart.md @@ -28,7 +28,7 @@ Below is a screenshot of a North Sea expedition. This example expedition departs Feel free to design your expedition as you wish! There is no need to copy these sampling sites in your own expeditions. -![MFP North Sea cruise plan screenshot](image-1.png) +![MFP North Sea cruise plan screenshot](_images/mfp_route.png) ### Export the coordinates @@ -70,7 +70,7 @@ virtualship plan EXPEDITION_NAME The planning tool should look something like this and offers an intuitive way to make your selections: -![example_plan_app](example_plan_app.gif) +![example_plan_app](_images/example_plan_app.gif) ### Ship speed @@ -152,7 +152,7 @@ If this is your first time running VirtualShip, you will be prompted to enter yo Your command line output should look something like this... -![GIF of example VirtualShip log output](example_log_instruments.gif) +![GIF of example VirtualShip log output](_images/example_log_instruments.gif) 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 ;-) diff --git a/docs/user-guide/teacher-content/index.md b/docs/user-guide/teacher-content/index.md deleted file mode 100644 index 89389d8e6..000000000 --- a/docs/user-guide/teacher-content/index.md +++ /dev/null @@ -1,55 +0,0 @@ -# Teacher content - -### Overview - -VirtualShip is used as part of the VirtualShip Classroom, that combines authentic tools with VR to create a virtual fieldwork experience and allows you to teach about sea-based research from your regular classroom. - -All VirtualShip Classroom (VSC) material is open under an MIT licence and freely available! You can use the VSC to teach anything from a 4 hour masterclass up to an open assignment of more than 40 hours. Example assignments are available below and please feel free to customize anything offline or [contribute](../../contributing/index.md) to the assignments provided here. - -Our core learning outcome is for students to appreciate the difficulty of measuring the ocean, making the VSC a valuable tool for students that will go into fieldwork, modelling or anything else. Additional Intended Learning Outcomes [(ILOs)](ILOs.ipynb) were formulated in collaboration with ocean scientists from the Royal Netherlands Institute for Sea Research [(NIOZ)](https://www.nioz.nl/en) and Utrecht University [(UU)](https://www.uu.nl/en). - -The 360 videos are available on our YouTube channel [**_@VirtualShip Classroom_**](https://www.youtube.com/@VirtualShipClassroom) and in high resolution upon request. The videos can be viewed in the classroom or at home using: - -- VR Headsets – Wear a headset and look around naturally by moving your head. -- Smartphones/Tablets – Move your device or swipe the screen to explore. -- PC/Mac Browsers – Click and drag with your mouse to look around. - -The VSC design focuses on creating didactically sound, authentic learning experiences grounded in established learning theories in science education, such as constructivism [(Piaget 1954)](https://www.taylorfrancis.com/books/mono/10.4324/9781315009650/construction-reality-child-jean-piaget) and constructionism [(Papert 1980)](https://worrydream.com/refs/Papert_1980_-_Mindstorms,_1st_ed.pdf). By integrating realistic tasks and a gamified narrative approach within Jupyter notebooks, students learn within a digital replica of the real world, constructing knowledge through ‘learning by doing’ and ‘trial and error’ as they explore oceanography concepts, research methods, and analysis tools. - -We evaluated in several (under)graduate courses and find that the VirtualShip Classroom is highly engaging, and students report on enhanced confidence and knowledge [(Daniels et al. 2025)](https://current-journal.com/articles/10.5334/cjme.121). - -### Teaching materials - -```{toctree} -:maxdepth: 1 - -ILOs.ipynb -letter.md -``` - -### Previous implementations - -```{warning} -The following implementations are examples of how the VSC has been used in the past. They are provided here for reference only and may not be up to date with the latest version of the VSC and/or VirtualShip software. -``` - -#### Utrecht University - -```{nbgallery} ---- -caption: Ocean of the Future (BSc), 2025-26 ---- -UU-ocean-of-future/Tutorial1.ipynb -UU-ocean-of-future/CoordinatesExport-Transect.xlsx -UU-ocean-of-future/Tutorial2.ipynb -UU-ocean-of-future/CTD_transects.ipynb -UU-ocean-of-future/plot_slider.py -``` - -```{nbgallery} ---- -caption: Dynamical Oceanography (MSc), 2025-26 ---- -UU-dyoc/example_expedition.md -UU-dyoc/file_permissions.md -``` diff --git a/docs/user-guide/tutorials/binder_guide.md b/docs/user-guide/tutorials/binder_guide.md new file mode 100644 index 000000000..c15dfa234 --- /dev/null +++ b/docs/user-guide/tutorials/binder_guide.md @@ -0,0 +1,15 @@ +# Post-processing Workspace Guide + +_[This section is under development]_ + +This guide is supposed to be used once you have run VirtualShip simulations, which you may have done either on your own computer or in the VirtualShip workspace [via GitHub Codespaces](../user-profiles/educators/train-the-teacher/codespaces_guide.md). + +The instructions below will guide you through the steps to access the VirtualShip post-processing workspace, upload your VirtualShip simulation output files, and run the example tutorials for analysis. + +## Accessing the VirtualShip post-processing workspace + +## Upload your VirtualShip output files + +## Running the example tutorials + +Note, you will have to adjust the file paths in the example tutorials to point to your uploaded VirtualShip output files. diff --git a/docs/user-guide/tutorials/codespaces_guide.md b/docs/user-guide/tutorials/codespaces_guide.md new file mode 100644 index 000000000..ca6e14113 --- /dev/null +++ b/docs/user-guide/tutorials/codespaces_guide.md @@ -0,0 +1,82 @@ +# Simulation Workspace Guide + +For your classroom activities, we have provided a pre-configured cloud-based environment for the `VirtualShip` software. We host this facility on [GitHub](https://github.com/), for which you will need to create a free account. Please follow the steps below to access the VirtualShip Workspace and get started with your VirtualShip simulations. + +**Read through the instructions below and then return to the rest of the course material to continue with your VirtualShip simulations** + +## 1) Create a GitHub account + +If you do not already have a GitHub account, please sign up for a free account here: [https://github.com/signup](https://github.com/signup) + +## 2) Launch the VirtualShip Workspace via GitHub Codespaces + + + +Navigate to the VirtualShip Workspace repository on GitHub: [https://github.com/j-atkins/virtualship-workspace](https://github.com/j-atkins/virtualship-workspace) + +From here you should see a green button labelled `Code`. Click on this button and select the `Codespaces` tab. Then click on the `Create codespace on main` button to launch your cloud-based environment. + +It will take a few minutes for the Codespace to be created and launched. Once it is ready, you will see a web-based interface that looks similar to the [Visual Studio Code](https://code.visualstudio.com/) editor (if you are familiar with that). + +```{important} +The spin-up time for the Codespace can take a few minutes. There are various stages, the last of which is a "Post Create Command" that will install the `VirtualShip` software and its dependencies. Please be patient and wait for this to complete before proceeding. +``` + +## 3) Using the VirtualShip Workspace + +Once the Codespace is ready, you can start using the VirtualShip Workspace. This browser-based virtual machine replicates the kind of set up you would have on your own computer, but it is hosted in the cloud. This means that you use the resources associated with the cloud instance, rather than your own computer, to run the software. + +Your Codespace will look something like Figure 1 below: + +![](../train-the-teacher/_images/codespaces.png) +_Figure 1. The VirtualShip Workspace interface._ + +Where `A` is the file explorer, `B` is the main editor window and `C` is the Terminal window. For VirtualShip, which is a Command Line Interface (CLI) software, you will mainly be using the Terminal window to run commands (which you will use in the rest of the tutorials in your course). + +Otherwise, you may find the editor window helpful for example to [edit the VirtualShip configuration files](../user-guide/user-profiles/tutorials/working-with-expedition-yaml.md). + +The file explorer will allow you to navigate the file structure of your Codespace, and you can also use it to upload/download files to/from your Codespace by right-clicking on a file or folder and selecting the appropriate option. + +### Persistent storage + +Your instance of the VirtualShip Workspace is associtated with your GitHub account. This means that any files which you create and/or modify (e.g. the output of your VirtualShip simulations) will be tied to your account and will persist between sessions. You can also download files to your own computer if you wish, or upload files from your computer to the workspace. + +Each free user account is limited to approximately 15 GB of storage space per month, which should be sufficient for VirtualShip simulation outputs, which are not too large. + +Please note though that if you delete your Codespace, all files will be deleted and will not be recoverable. If you ever need to delete your workspace and you have important files stored within it, make sure to save them to a location outside the Codespace before deleting it. + +```{tip} +Deleting is not the same as stopping the Codespace. You can stop the Codespace when you are not using it to save your usage time, and then restart it later. See the instructions below for how to stop and restart your Codespace. +``` + +### Compute usage restrictions + +```{important} +The amount of time you can use the Codespace is limited to approximately **60 hours per month** (per free GitHub account). This should be sufficient for your course, but it's good to be aware so that you can limit unnecessary usage. See the GitHub docs for more information on [Codespaces usage limits](https://docs.github.com/en/billing/concepts/product-billing/github-codespaces). + +``` + +```{tip} + +You can stop the Codespace when you are not using it to save your usage time. To do this, click on the "Codespaces" button in the bottom left (`A` in the screenshot below) and then select the "Stop Current Workspace" option (`B`). + +![](../train-the-teacher/_images/stop_codespaces.png) +*Figure 2. Stopping the Codespace to save usage time.* + +You will be able to restart the workspace at a later time, using the same instructions as [above](#launch-the-virtualship-workspace-via-github-codespaces). + +By default the Codespace will automatically stop after 30 minutes of inactivity, these instructions are for if you want to stop it manually before that time. + +``` + +### Collaboration within groups + +_[This section is under development]_ + + + +```{nbgallery} + + +collaboration.md +``` diff --git a/docs/user-guide/tutorials/working_with_expedition_yaml.md b/docs/user-guide/tutorials/working_with_expedition_yaml.md index 6bbf181e6..49f9938db 100644 --- a/docs/user-guide/tutorials/working_with_expedition_yaml.md +++ b/docs/user-guide/tutorials/working_with_expedition_yaml.md @@ -11,7 +11,7 @@ This tutorial describes an alternative means to using the `virtualship plan` com 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. +The `expedition.yaml` file can also be opened and edited in GitHub Codespaces instances in the Editor panel. Simply navigate to the file in the File Explorer panel and (double) click to open it, or open it by using the `code` command in the Terminal, e.g. `code path/to/expedition.yaml`. ``` ```{important} diff --git a/docs/user-guide/user-profiles/developers/index.md b/docs/user-guide/user-profiles/developers/index.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/user-guide/teacher-content/ILOs.ipynb b/docs/user-guide/user-profiles/educators/ILOs.ipynb similarity index 100% rename from docs/user-guide/teacher-content/ILOs.ipynb rename to docs/user-guide/user-profiles/educators/ILOs.ipynb diff --git a/docs/user-guide/user-profiles/educators/index.md b/docs/user-guide/user-profiles/educators/index.md new file mode 100644 index 000000000..bdc38fd5a --- /dev/null +++ b/docs/user-guide/user-profiles/educators/index.md @@ -0,0 +1,77 @@ +# Educators + +The `VirtualShip` software is used as part of the VirtualShip Classroom, which combines authentic tools with VR to create a virtual fieldwork experience and allows you to teach about sea-based research from your regular classroom. All VirtualShip Classroom (VSC) material is open under an MIT licence and freely available! You can use the VSC to teach anything from a four-hour masterclass up to an open assignment of more than 40 hours. + +Our core learning outcome is for students to appreciate the difficulty of measuring the ocean, making the VSC a valuable tool for students that will go into fieldwork, modelling or anything else. Additional [**Intended Learning Outcomes (ILOs)**](ILOs.ipynb) were formulated in collaboration with ocean scientists from the Royal Netherlands Institute for Sea Research [(NIOZ)](https://www.nioz.nl/en) and Utrecht University [(UU)](https://www.uu.nl/en). + +```{note} +The VirtualShip Classroom is focused on creating didactically sound, authentic learning experiences grounded in established learning theories in science education, such as constructivism ([Piaget 1954](https://www.taylorfrancis.com/books/mono/10.4324/9781315009650/construction-reality-child-jean-piaget)) and constructionism ([Papert 1980](https://worrydream.com/refs/Papert_1980_-_Mindstorms,_1st_ed.pdf)). By integrating realistic tasks and a gamified narrative approach, students learn within a digital replica of the real world, constructing knowledge through ‘learning by doing’ and ‘trial and error’ as they explore oceanography concepts, research methods, and analysis tools. +``` + +```{tip} +For more information on the pedagogical approach employed in the VirtualShip Classroom, including evaluation in several (under)graduate courses, see our [Publications](https://virtualship.parcels-code.org/publications) page. + +**In summary, we find that the VirtualShip Classroom is highly engaging, and students report on enhanced confidence and knowledge [(Daniels et al. 2025)](https://current-journal.com/articles/10.5334/cjme.121).** +``` + +## Implementing the VirtualShip Classroom + +We're pleased that you've chosen to use VirtualShip in your teaching! We provide a "Train the Teacher" guide below, which is designed to help you, as the teacher, to get started with the platform and make the most of its features in your classroom. + +:::: + +::::{grid} 1 +:gutter: 4 +:padding: 2 2 0 0 +:class-container: sd-text-center + +````{grid-item-card} Train the Teacher 🎓 +:shadow: md + +Implement the VirtualShip Classroom in your teaching with our step-by-step guide for educators. + ++++ + +```{button-ref} train-the-teacher/train_the_teacher +:ref-type: doc +:color: secondary +:expand: + +Train the Teacher +``` +```` + +:::: + +## Assignments & Teaching Materials + +We also provide a set of assignments and teaching materials, which you might find useful. Some of these are referred to in the "Train the Teacher" guide, but you can also explore them separately here. + +```{nbgallery} +--- +maxdepth: 1 +--- +letter.ipynb +../../assignments/case_studies_virtualship.ipynb +../../assignments/Research_proposal_intro.ipynb +../../assignments/Research_proposal_only.ipynb +../../assignments/Virtualship_research_proposal.ipynb +../../assignments/sciencecommunication_assignment.ipynb +../../assignments/Code_of_conduct.ipynb +``` + +## Post-processing Tutorials + +As mentioned in the "Train the Teacher" guide, we provide a set of tutorials for analysing **output** from `VirtualShip` expeditions, which students can use as a starting point for their post-expedition analysis. + +```{nbgallery} +--- +maxdepth: 1 +--- +../../tutorials/Drifter_data_tutorial.ipynb +../../tutorials/Argo_data_tutorial.ipynb +../../tutorials/CTD_transects.ipynb +../../tutorials/ADCP_transects.ipynb +../../tutorials/xbt_plotting.ipynb +../../tutorials/Ship_underwater_ST_plotting.ipynb +``` diff --git a/docs/user-guide/teacher-content/letter.md b/docs/user-guide/user-profiles/educators/letter.md similarity index 100% rename from docs/user-guide/teacher-content/letter.md rename to docs/user-guide/user-profiles/educators/letter.md diff --git a/docs/user-guide/user-profiles/educators/train-the-teacher/_images/catalog.png b/docs/user-guide/user-profiles/educators/train-the-teacher/_images/catalog.png new file mode 100644 index 000000000..258d1ca5f Binary files /dev/null and b/docs/user-guide/user-profiles/educators/train-the-teacher/_images/catalog.png differ diff --git a/docs/user-guide/user-profiles/educators/train-the-teacher/_images/codespaces.png b/docs/user-guide/user-profiles/educators/train-the-teacher/_images/codespaces.png new file mode 100644 index 000000000..a71d4ed48 Binary files /dev/null and b/docs/user-guide/user-profiles/educators/train-the-teacher/_images/codespaces.png differ diff --git a/docs/user-guide/user-profiles/educators/train-the-teacher/_images/new_workspace.png b/docs/user-guide/user-profiles/educators/train-the-teacher/_images/new_workspace.png new file mode 100644 index 000000000..f1bbf256b Binary files /dev/null and b/docs/user-guide/user-profiles/educators/train-the-teacher/_images/new_workspace.png differ diff --git a/docs/user-guide/user-profiles/educators/train-the-teacher/_images/stop_codespaces.png b/docs/user-guide/user-profiles/educators/train-the-teacher/_images/stop_codespaces.png new file mode 100644 index 000000000..883106198 Binary files /dev/null and b/docs/user-guide/user-profiles/educators/train-the-teacher/_images/stop_codespaces.png differ diff --git a/docs/user-guide/user-profiles/educators/train-the-teacher/_images/surf_invite.png b/docs/user-guide/user-profiles/educators/train-the-teacher/_images/surf_invite.png new file mode 100644 index 000000000..4e8bb23de Binary files /dev/null and b/docs/user-guide/user-profiles/educators/train-the-teacher/_images/surf_invite.png differ diff --git a/docs/user-guide/user-profiles/educators/train-the-teacher/_images/surf_storage.png b/docs/user-guide/user-profiles/educators/train-the-teacher/_images/surf_storage.png new file mode 100644 index 000000000..e8b294dc5 Binary files /dev/null and b/docs/user-guide/user-profiles/educators/train-the-teacher/_images/surf_storage.png differ diff --git a/docs/user-guide/user-profiles/educators/train-the-teacher/_images/virtualship_catalog.png b/docs/user-guide/user-profiles/educators/train-the-teacher/_images/virtualship_catalog.png new file mode 100644 index 000000000..83a788662 Binary files /dev/null and b/docs/user-guide/user-profiles/educators/train-the-teacher/_images/virtualship_catalog.png differ diff --git a/docs/user-guide/user-profiles/educators/train-the-teacher/collaboration.md b/docs/user-guide/user-profiles/educators/train-the-teacher/collaboration.md new file mode 100644 index 000000000..47d60880f --- /dev/null +++ b/docs/user-guide/user-profiles/educators/train-the-teacher/collaboration.md @@ -0,0 +1,3 @@ +# Leaner Guide: Collaboration within groups + +_[This section is under development]_ diff --git a/docs/user-guide/user-profiles/educators/train-the-teacher/lesson_plans.md b/docs/user-guide/user-profiles/educators/train-the-teacher/lesson_plans.md new file mode 100644 index 000000000..33c78733d --- /dev/null +++ b/docs/user-guide/user-profiles/educators/train-the-teacher/lesson_plans.md @@ -0,0 +1,79 @@ +# Example lesson plans + +## 1) Using the `VirtualShip` software + +This example lesson plan is suitable for students with programming knowledge. Students hand in a short research proposal and expedition plan for feedback. They use the `VirtualShip` software to conduct their virtual expedition and analyse the results. They show their results in a presentation that can be assessed. This assignment is recommended to be undertaken in groups, because collaborative learning is beneficial. Suggested learning goals are that students can: + +- identify and address (practical) challenges involved in sea-based research; +- give examples of uncertainty and the synoptic nature of sea-based observations; +- analyze and interpret sea-based observations; +- plan a comprehensive research expedition. + +**An example lesson plan is as follows:** + +| Background lecture on observing the ocean | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _1-2 hours depending on the amount of detail, can also be viewed by student before class as preparation_ | +| Presentation about observing and measuring the ocean, covering different types of observations and instruments followed by steps to conduct ocean research. Sample presentation sides are available on [Edusources](https://edusources.nl/materials/90a4df16-427b-4f95-b2c2-b7bc9b2c6b81/presentation-about-observing-and-measuring-the-ocean). | + +| Prep work / homework | +| --------------------------------------------------------------------------------------------------------------------- | +| _1 hour of homework_ | +| Introduction to VirtualShip research proposals, available [here](../../../assignments/Research_proposal_intro.ipynb). | + +| Tutorial 1 | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _2 hours in class, 4 hours of homework_ | +| Students hand in a short VirtualShip [research proposal](../../../assignments/Virtualship_research_proposal.ipynb) for the lecturer (or an expert colleague) to provide feedback. We recommend ensuring that the research questions are focused enough to be researchable in the granted ship time (typically up to three weeks). | + +```{note} +Because data are taken from the Copernicus Marine Data Store (see [here](../../../documentation/copernicus_products.md) for more technical details), expeditions can take place from 1993 to present (up to 2 weeks into the future). +``` + +```{tip} +An interesting addition can be to let students use the [MyOcean Pro viewer](https://data.marine.copernicus.eu/viewer/) to, for example, track an eddy using sea surface height and deploy their instruments therein. +``` + +| Tutorial 2 | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _4 hours in class_ | +| Students begin their expedition simulations. Please refer back to the main train-the-teacher [documentation](train_the_teacher.md/#sailing-the-ship) for further instructions on running the software in the classroom. | + +| VR component | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| A range of 360° videos are available on [YouTube](https://www.youtube.com/@VirtualShipClassroom). If time allows, let students watch one or more of the ship tours and a-day-at-sea videos. | + +| Tutorial 3 | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _2-4 hours in class, 10 hours of homework_ | +| Encourage the students to analyze their own data using the [example tutorials](../../../tutorials/index.md). For more advanced courses, students can be asked to produce further, derived quantities as part of their analysis. | + +| Presentations | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _Number of hours in class will depend on the number of groups that present, we suggest at least 10-15 minutes for each group including questions_ | +| Students present their results. An example presentation rubric is available on [Edusources](https://edusources.nl/materials/44ff66eb-537d-4ab9-a844-0fba9bd8d240/rubric-to-grade-advanced-student-presentations). | + +## 2) _Not_ using the software + +It is also possible to skip using the `VirtuaShip` software entirely and instead use the Open Education Resources (and potentially the VR component) to teach about oceanography and research methods. This is a good option if you want to focus on the learning outcomes without the technical overhead of using the software. + +This example lesson plan is suitable for all students, regardless of programming knowledge. Students hand in a research proposal and an accompanying expedition plan that can be assessed. The assignment can be conducted in groups or individually. Suggested learning goals are that students can: + +- identify practical challenges of planning sea-based research; +- plan a comprehensive research expedition. + +**An example lesson plan is as follows:** + +| Background lecture on observing the ocean | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _1-2 hours depending on the amount of detail, can also be viewed by student before class as preparation_ | +| Presentation about observing and measuring the ocean, covering different types of observations and instruments followed by steps to conduct ocean research. Sample presentation sides are available on [Edusources](https://edusources.nl/materials/90a4df16-427b-4f95-b2c2-b7bc9b2c6b81/presentation-about-observing-and-measuring-the-ocean). | + +| Tutorial | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _2 hours in class, 4-8 hours of homework_ | +| In class, students discuss their research questions and approach with an expert before submitting a VirtualShip [research proposal](../../assignments/Research_Proposal_only.ipynb). This is a good opportunity to invite oceanography experts to share their perspectives and insights, if you are not one yourself. | + +| VR component | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| A range of 360° videos are available on [YouTube](https://www.youtube.com/@VirtualShipClassroom). If time allows, let students watch one or more of the ship tours and a-day-at-sea videos. | diff --git a/docs/user-guide/user-profiles/educators/train-the-teacher/train_the_teacher.md b/docs/user-guide/user-profiles/educators/train-the-teacher/train_the_teacher.md new file mode 100644 index 000000000..bc6dcf1a8 --- /dev/null +++ b/docs/user-guide/user-profiles/educators/train-the-teacher/train_the_teacher.md @@ -0,0 +1,257 @@ +# Train the teacher + +We're pleased that you've chosen to use VirtualShip in your teaching! This guide is designed to help you get started with the platform and make the most of its features in your classroom. It binds different parts of the documentation together as a central blueprint for implementing the VirtualShip Classroom in your teaching. + +The instructions are currently tailored primarily for educators at partner instutions, as part of the [VirtualShip NKO Scale Up project](https://virtualship.parcels-code.org/blog/scaleup-grant). However, we welcome all educators to explore the guide and adapt it to their own teaching contexts. For more tailored support, please see the [Feedback & support](#feedback-support) section at the end of this guide! + +For this guide, we will assume that you're familiar with the purpose and motivations for using VirtualShip. We will be going through all the practical steps to get you up and running. + +```{important} +No matter how you choose to implement the VirtualShip Classroom, we ask that you please ask your students to complete the end-of-course survey (see [below](#end-of-course-survey)) so that we can collect feedback on their experience with the VirtualShip Classroom. + +This is really important for us to continue to research, evaluate and improve the VirtualShip Classroom! 🙂 +``` + +## Foreword + +### Introduction + +As a reminder, where we refer to the VirtualShip Classroom, we refer to the combination of three core pillars: the `VirtualShip` software, VR / 360° videos and the Open Education Resources. The VirtualShip Classroom is designed to be flexible, the different components interchangable and can be used in a variety of ways, from highly structured to more open-ended activities. + +We discuss some example lesson plans [below](#lesson-plans), but we encourage you to adapt these to your own teaching context and learning objectives. We don't intend for the guidance to be rigid and we encourage you to think about the intended learning outcomes (ILOs) for your students and adapt the activities accoridingly. + +### Our advice + +In our experience, the most successful implementations of VirtualShip are those where the activities have a strong **narrative** ("You have been granted _ weeks of ship time!") and where students are given ample **freedom**, for example to choose their own research question, location and timing (perhaps from a selection of [case studies](../../../assignments/case_studies_virtualship.ipynb)). + +```{note} +Check out evaluations of the VirtualShip Classroom in published paper(s) [here](https://virtualship.parcels-code.org/publications), for more information on the pedagogical approach! +``` + +That being said, the VirtualShip Classroom is a flexible platform and can be used in a variety of ways, from highly structured to more open-ended activities. + +## Lesson plans + +The 'core' implementation of the VirtualShip Classroom has traditionally followed a structure of: + +1. Background lecture on observing the ocean and research methods +2. Introduction to the VirtualShip software (if applicable) +3. In-class tutorials and exercises +4. Assignment hand-in (presentation or article) and feedback. + +::::{grid} 1 +:gutter: 4 +:padding: 2 2 0 0 +:class-container: sd-text-center + +````{grid-item-card} Lesson plans 📖 +:shadow: md + +Click here for more detail on all of these components and some example lesson plans (including links to lecture slides and more). + ++++ + +```{button-ref} lesson_plans +:ref-type: doc +:color: secondary +:expand: + +Lesson plans +``` +```` + +:::: + +```{tip} +No matter how you choose to implement the VirtualShip Classroom, it may be useful to check out some case study [examples](../../../assignments/case_studies_virtualship.ipynb) of research questions and expeditions that students could undertake. +``` + +### Code of conduct + +If students are to work in groups, we recommend that you ask students to read, complete and sign the [Code of Conduct](../../../assignments/Code_of_conduct.ipynb) before starting their VirtualShip expeditions. This is to ensure that students are aware of the expectations for their behaviour and conduct during the course, and to promote a positive and respectful learning environment. + +### Adding the VR / 360° videos component + +The example lesson plans referred to above suggest including the VR component in your teaching. This is not a requirement, but we do recommend it as it can enhance the learning experience and provide students with a more immersive understanding of the challenges of sea-based research. + +All the videos, available on [YouTube](https://www.youtube.com/@VirtualShipClassroom), can be viewed on students' own devices using their mouse to view in 360° if on a laptop/desktop or by moving their devices if watching on a mobile device. However, if the facilities exist at your instition, or you have access to VR headsets, you could use videos in a full VR environment. For more advice on how to arrange this, please get in touch with the VirtualShip Team at [virtualship@uu.nl](mailto:virtualship.uu.nl). + + + +## Setting up a programming environment + +```{tip} +As mentioned in the [Lesson plans section](#lesson-plans), it is not necessary to use the `VirtualShip` software component as part of the VirtualShip Classroom. If this is the case, you can skip the next sections, and refer to the Open Education Resources mentioned in the relevant [example lesson plan](lesson_plans.md/#not-using-the-software). + +❗️ Please do still ask students to complete the end-of-course survey (see [below](#end-of-course-survey)) though so that we can collect feedback on their experience with the VirtualShip Classroom. +``` + +There are broadly two ways to set up the `VirtualShip` software for teaching: + +1. Each student uses a local installation of the software (on their own device), installed via a package manager such as `pip`, `conda` or `pixi`. +2. A software environment is pre-configured on a cloud-based platform/virtual machine. + +Option 1) requires less preparation but can be more challenging for students to set up (especially if inexperienced) with frequent machine-dependent issues (and a lot of time spent on troubleshooting during lesson time!). Option 2) requires more preparation as the course convenor but is generally easier to support in-class, especially for larger groups. It also has the advantage that all students are working with the same resources, versions and infrastructure, which is beneficial for reproducibility and fairness. + +```{important} +At present, for Option 2), we offer an _experimental_ pre-configured cloud-based environment solution via [GitHub Codespaces](https://github.com/features/codespaces) for VirtualShip simualtions (and [Binder](https://mybinder.org/) for a distributable post-processing space). This is a central, free solution that we can support and maintain, but it also has some limitations. Namely, each student must sign up for a GitHub account and the monthly free tier is limited to, in effect, 60 hours of usage (per student/GitHub account). + +This will be sufficient for _most_ courses, but could be insufficient if your planned teaching activities are longer or more intensive. We continually monitor the optimum solution for distributing the VirtualShip software to whole classrooms in the most accessible way possible, and we are open to [feedback/advice](#feedback-support) on this. + +**See the [Pre-configured environment (cloud based)](#pre-configured-environment-cloud-based) section below for more information on this option.** +``` + +### Local installation + +Students can install the `VirtualShip` software on their own devices using `conda` from the command line: + +```bash +# create a new conda environment called 'virtualship' and install the software from the conda-forge channel +conda create -n virtualship -c conda-forge virtualship + +# activate the environment +conda activate virtualship +``` + +This creates an environment named `virtualship` with the latest version of the `VirtualShip` software installed. Students can then run the software from the command line in this environment. + +```{tip} +If you have access to a computer lab, you may also consider installing the software on the those machines. This is similar to a local installation but can bring similar benefits to a cloud-based environment (i.e. the environment is prepared ahead of the lesson, each student has the same resources), but with less flexibility for students to work from home or on their own devices. +``` + +### Pre-configured environment (cloud based) + +We provide a a pre-configured VirtualShip environment via GitHub Codespaces. Here, students will have access to the `VirtualShip` software and all its dependencies, without having to install anything on their own devices. This is a cloud-based solution, so students will need an internet connection and a GitHub account. + +Below we provide a set of instructions which can be distributed to students, for them to get set up on the VirtualShip Workspace. + +```{nbgallery} + +../../../tutorials/codespaces_guide.md + +``` + +```{tip} +Please don't hesitate to [get in touch](#feedback-support) if you have any problems with this approach or require additional support. +``` + +##### Collaboration within groups + +_[This section is under development]_ + + + + +```{nbgallery} + +collaboration.md +``` + +## Sailing the ship + +Now that the technical set up is complete, we are ready to start getting students going with using the `VirtualShip` software! 🚢 🥳 + +The general-purpose **Quickstart guide** below provides a minimal overview of the basic commands and workflow to get started with the software... perhaps useful for you as the course convenor to get a quick overview of the software. + +However, for teaching applications we recommend distributing the student-focused **"Sail the ship" guide** below, which is designed to be more accessible and includes additional context and narrative elements for students. + +```{nbgallery} + +../../../quickstart.md +../../../assignments/sail_the_ship.md + +``` + +### Reviewing Expedition proposals + +The "Sail the ship" guide above is designed to be used in conjunction with a lesson plan similar to that presented in the [example lesson plans](lesson_plans.md) documentation. It relies on students having already chosen a research question, submitting a proposal and having it approved by their instructor/you. + +Reviewing and approving the proposals is a good time to check that students have a realistic plan for their expedition, and we find it is beneficial to prescribe a maximum ship time limit (e.g. 3 weeks) to ensure that students are thinking about the practicalities of their research question and sampling strategy. + +```{tip} +The ship time limit can not currently be set in the `VirtualShip` software, but you could enforce it as part of your assignment instructions. +``` + +### Additional resources used in the VirtualShip workflow + +You will notice in the "Quickstart" and "Sail the Ship" guides that there are a number of additional resources that get used in the VirtualShip workflow. These include the: + +- [Copernicus Marine Data Store](https://data.marine.copernicus.eu/). + - This source of the oceanographic data used in VirtualShip (streamed under-the-hood in the `VirtualShip` software). + - As mentioned in the guides, students will need to set up a _free_ account to access the data. We recommend asking students to do this ahead of time, to avoid delays during the lesson. + - Users are prompted to enter their credentials when they first run the `VirtualShip` software, and the credentials are then stored for future use. +- [Marine Facilities Planning (MFP) tool](https://nioz.marinefacilitiesplanning.com/cruiselocationplanning#) + - This tool is used to plan the expedition route and generate the coordinates for the VirtualShip protocol. + - It is an authentic tool used by real-life oceanographers to plan their research expedtions, and is a good example of the type of software that students may encounter in their future careers. + - There is no sign-up required to use the tool, but students may need some time to get familiar with it. + - As mentioned in the guides, the `VirtualShip` software can ingest exported coordinate files straight from MFP. + +### Simulating Real Life Challenges + +You will notice mentions to "Real Life Challenges" (RLCs) in the "Quickstart" and "Sail the Ship" guides. These are a module in the `VirtualShip` software that can be used to simulate real-life challenges that oceanographers may encounter during their research expeditions. These include things like equipment failures, bad weather, and other unexpected events. They usually require active intervention from the students to resolve. + +They are not 'bugs' and are instead a feature that can be used to teach students about the challenges of oceanographic research: that things rarely go to plan, the scheudle will probably have to adapted and that some contingency planning is required. + +The RLCs can be configured by setting the difficulty level (`--difficulty-level`) parameter in the virtualship run command. It can be set to `“easy”` (no problems, default in the main software distribution), `“medium”` or `“hard”` (e.g. `virtualship run EXPEDITION_NAME --difficulty-level medium`). + +For maximum authenticity, you can set `--difficulty-level hard`, which will scale the number of problems encountered by the complexity of the expedition (longer duration, more waypoints, more instruments will lead to more problems). `--difficulty-level medium` will limit the number of problems to a maximum of 2, regardless of the expedition complexity. + +```{tip} +We can arrange that the default difficulty level is set to `medium` for your course, if you would like to use the RLCs in your teaching without having to ask students to add the `--difficulty-level` parameter themselves on each run. This can enhance immersivity as the RLCs appear more unexpected from the students' perspective. Please [get in touch](#feedback-support) if this is something you would like to do. +``` + +```{note} +It's possible that students will explore this VirtualShip documentation site and understand that they can disable the RLCs by setting `--difficulty-level easy`. If you would like to ensure that students must encounter the RLCs, we suggest making a discussion of how they dealt with these issues part of their assignment. Similar to the ship time limit mentioned [previously](#reviewing-expedition-proposals). +``` + +### VirtualShip output + +Once the simulations have run, the VirtualShip output files will be available in the workspace. These are in `.parquet` format. + +```{tip} +`VirtualShip` depends heavily on `Parcels` under-the-hood for simulating the instrument behaviours. As such, the VirtualShip output is built on `Parcels` output formats. See the `Parcels` [documentation](https://docs.oceanparcels.org/en/main/user_guide/getting_started/tutorial_output.html) for more information on how to work with the `.parquet` files. +``` + +VirtualShip does not provide explicit tooling for analysis, as this will be dependent on the specific learning objectives and research questions of the students. However, we provide a number of **example tutorials**, which provide sample code for simple first analysis of the VirtualShip output, for each instrument type: + +```{nbgallery} + +../../../tutorials/index.md + +``` + +#### Pre-configured post-processing workspace + +We also host a VirtualShip post-processing environment via [Binder](https://mybinder.org/), which is a cloud-based Jupyter Notebook environment. This can be used to run the example tutorials and any other analysis code that students may wish to write, without having to install anything on their own devices. All relevant dependencies are pre-installed in this environment, the post-processing tutorials are directly available in the workspace, and the VirtualShip output files can be uploaded to the environment for analysis. + +This is of course optional, but is offered as a means to make the post-processing analysis more accessible to students with less time spent setting up their local environment. + +```{note} +This Binder environment is a separate workspace protocol to the GitHub Codespaces environment used for running the VirtualShip Simulations, and described [above](#pre-configured-environment-cloud-based). We made the decision to separate these two environments to minimise the amount of compute time on the Codespaces environment, which has a monthly limit per user. + +The Binder environment does not have monthly quotas, but is not suitable for running the VirtualShip simulations themselves (low RAM and non-persistent storage). Hence the need (for now 🤞) to have these as two separate environments. +``` + +See the "Post-processing Workspace" guide below for more information on how to use this environment, and can also be distributed to students as part of your course. + + + +```{nbgallery} + +../../../tutorials/binder_guide.md + +``` + +## ❗️ End-of-course survey + +```{important} +We would be really grateful for your help in collecting feedback from your students on their experience with VirtualShip. This will help us to improve the platform, research its impact and to better understand how it is being used in different contexts. + +Please distribute the following survey link to your students at the end of the course: https://survey.uu.nl/jfe/form/SV_0OLu4lKYPyLhAxM +``` + +## Feedback & support + +If you have any feedback on this guide, would like additional support or if you have suggestions for improvements, please reach out to us via our [GitHub issue tracker](https://github.com/Parcels-code/virtualship/issues) or by email: [virtualship@uu.nl](mailto:virtualship@uu.nl). + +We are always happy to hear from educators and will do our best to support you in your teaching with VirtualShip! diff --git a/docs/user-guide/user-profiles/learners/index.md b/docs/user-guide/user-profiles/learners/index.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/user-guide/user-profiles/researchers/index.md b/docs/user-guide/user-profiles/researchers/index.md new file mode 100644 index 000000000..e69de29bb diff --git a/pixi.toml b/pixi.toml index a429025d1..e3265c143 100644 --- a/pixi.toml +++ b/pixi.toml @@ -41,6 +41,7 @@ pyarrow = "*" ipdb = ">=0.13.13,<0.14" cmocean = ">=4.0.3,<5" numba = ">=0.59.0" +sphinx-design = ">=0.7.0,<0.8" [pypi-dependencies] parcels = { git = "https://github.com/Parcels-code/Parcels", branch = "main" }