diff --git a/docs/paper/jats/figure1.png b/docs/paper/jats/figure1.png deleted file mode 100644 index 7316fcce..00000000 Binary files a/docs/paper/jats/figure1.png and /dev/null differ diff --git a/docs/paper/jats/paper.jats b/docs/paper/jats/paper.jats deleted file mode 100644 index 757f87d5..00000000 --- a/docs/paper/jats/paper.jats +++ /dev/null @@ -1,677 +0,0 @@ - - -
- - - - -Journal of Open Source Software -JOSS - -2475-9066 - -Open Journals - - - -0 -N/A - -VirtualShip for simulating oceanographic fieldwork in the -global ocean - - - -https://orcid.org/0000-0002-5735-3312 - -Atkins -Jamie R. C. - - - -* - - -https://orcid.org/0009-0005-9805-5257 - -Daniels -Emma E. - - - - - -Hodgskin -Nick - - - - - -Stuurman -Aart C. - - - - -https://orcid.org/0000-0002-2484-510X - -Simoes-Sousa -Iury - - - - -https://orcid.org/0000-0003-2041-0704 - -van Sebille -Erik - - - - - - -Freudenthal Institute, Utrecht University, the -Netherlands - - - - -Institute for Marine and Atmospheric Research, Utrecht -University, the Netherlands - - - - -Woods Hole Oceanographic Institution, Falmouth, MA, -USA - - - - -* E-mail: - - -5 -1 -2026 - -¿VOL? -¿ISSUE? -¿PAGE? - -Authors of papers retain copyright and release the -work under a Creative Commons Attribution 4.0 International License (CC -BY 4.0) -1970 -The article authors - -Authors of papers retain copyright and release the work under -a Creative Commons Attribution 4.0 International License (CC BY -4.0) - - - -Python -oceanography -fieldwork simulation -(under)graduate training -Lagrangian modelling -instrument and sampling design - - - - - - Summary -

VirtualShip is a Python-based package for - simulating measurements as if they were coming from real-life - oceanographic instruments, facilitating student training, expedition - planning, and design of sampling/instrument strategies. The software - exploits the customisability of the open-source - Parcels Lagrangian simulation framework - (Delandmeter - & van Sebille, 2019; - Lange - & van Sebille, 2017) and builds a virtual ocean by - streaming data from the - Copernicus - Marine Data Store on-the-fly, enabling expeditions anywhere - on the globe.

- - - Statement of need -

Marine science relies on fieldwork for data collection, yet - sea-going opportunities are limited due to financial costs, logistical - constraints, and environmental burdens. We present an alternative - means, namely VirtualShip, for training - scientists to conduct oceanographic fieldwork in an authentic manner, - to plan future expeditions and deployments, and to directly compare - observational and instrumentational strategies with model data.

-

VirtualShip goes beyond simply extracting - grid-cell values from model output. Instead, it uses programmable - behaviours and sophisticated interpolation techniques (with - Parcels underpinnings) to access data in exact - locations and timings, as if they were being collected by real-world - instruments. VirtualShip shares some - functionality with existing tools, such as - OceanSpy - (Almansi - et al., 2019) and VirtualFleet - (Maze - & Balem, 2023), but extends capabilities to mesh many - different instrument deployments into a unified expedition simulation - framework. Moreover, VirtualShip exploits - readily available, streamable data via the Copernicus Marine Data - Store, removing the need for users to download and manage large - datasets locally and/or arrange for access to remote servers. - VirtualShip can also integrate coordinate files - exported from the - Marine - Facilities Planning (MFP) tool, giving users the option to - define expedition waypoints via an intuitive web-based mapping - interface.

- - - Functionality -

VirtualShip simulates the deployment of - virtual instruments commonly used in oceanographic fieldwork, with - emphasis on realism in how users plan and execute expeditions. For - example, users must consider ship speed and instrument - deployment/recovery times to ensure their expedition is feasible - within given time constraints. Possible instrument selections include - surface Drifter - (Lumpkin - et al., 2017), CTD - (Conductivity-Temperature-Depth; Johnson et al. - (2007)), - Argo float - (Jayne - et al., 2017), XBT (Expendable - Bathythermograph; Goni et al. - (2019)), - underway ADCP (Acoustic Doppler Current - Profiler; Kostaschuk et al. - (2005)), - and underway temperature/salinity - (Gordon - et al., 2014) probes. More detail on each instrument is - available in the - documentation.

-

The software can simulate complex multidisciplinary expeditions. - One example is a virtual expedition across the Agulhas Current and the - South Eastern Atlantic that deploys a suite of instruments to sample - physical and biogeochemical properties - ([fig:fig1]). Key - circulation features appear early in the expedition track, with - enhanced ADCP speeds marking the strong Agulhas Current - ([fig:fig1]b) and - drifters that turn back toward the Indian Ocean indicating the Agulhas - Retroflection - ([fig:fig1]c). The - CTD profiles capture the vertical structure of temperature and oxygen - along the route, including the warmer surface waters of the Agulhas - region ([fig:fig1]d, - early waypoints) and the Oxygen Minimum Zone in the South Eastern - Atlantic - ([fig:fig1]e, final - waypoints).

-

The software is designed to be highly intuitive to the user. It is - wrapped into three high-level command line interface commands using - Click:

- - -

virtualship init: Initialises the - expedition directory structure and an - expedition.yaml configuration file, which - controls the expedition route, instrument choices and deployment - timings. A common workflow is for users to import pre-determined - waypoint coordinates using the --from-mfp - flag in combination with a coordinates .csv - or .xlsx file (e.g. exported from the - MFP - tool).

- - -

virtualship plan: Launches a - user-friendly Terminal-based expedition planning User Interface - (UI), built using - Textual. - This allows users to intuitively set their waypoint timings and - instrument selections, and also modify their waypoint - locations.

- - -

virtualship run: Executes the virtual - expedition according to the planned configuration. This includes - streaming data via the - Copernicus - Marine Data Store, simulating the instrument beahviours - and sampling, and saving the output in - Zarr - format.

- - -

A full example workflow is outlined in the - Quickstart - Guide documentation.

- -

Example VirtualShip expedition simulated in July/August - 2023. Expedition waypoints displayed via the MFP tool (a), Underway - ADCP measurements (b), Surface drifter releases (c; 90-day lifetime - per drifter), and CTD vertical profiles for temperature (d) and - oxygen (e). Black triangles in b), d) and e) mark waypoint locations - across the expedition route, corresponding to the purple markers in - a).

- - - - - Implementation -

Under the hood, VirtualShip is modular and - extensible. The workflows are designed around - Instrument base classes and instrument-specific - subclasses and methods. This means the platform can be easily extended - to add new instrument types. Instrument behaviours are coded as - Parcels kernels, which allows for extensive - customisability. For example, a Drifter advects - passively with ocean currents, a CTD performs - vertical profiling in the water column and an - ArgoFloat cycles between ascent, descent and - drift phases, all whilst sampling physical and/or biogeochemical - fields at their respective locations and times.

-

Moreover, the data ingestion system relies on Analysis-Ready and - Cloud-Optimized data (ARCO; Stern et al. - (2022), - Abernathey et al. - (2021)) - streamed directly from the Copernicus Marine Data Store, via the - copernicusmarine - Python toolbox. This means users can simulate expeditions anywhere in - the global ocean without downloading large datasets by default. - Leveraging the suite of - physics - and biogeochemical products available on the Copernicus - plaform, expeditions are possible from 1993 to present and forecasted - two weeks into the future. There is also an - option - for the user to specify local NetCDF files for - data ingestion, if preferred.

- - - Applications and future outlook -

VirtualShip has already been extensvely - applied in Master’s teaching settings at Utrecht University as part of - the - VirtualShip - Classroom initiative. Educational assignments and tutorials - have been developed alongside to integrate the tool into coursework, - including projects where students design their own research - question(s) and execute their fieldwork and analysis using - VirtualShip. Its application has been shown to - be successful, with students reporting increased self-efficacy and - knowledge in executing oceanographic fieldwork - (Daniels - et al., 2025).

-

The package opens space for many other research applications. It - can support real-life expedition planning by letting users test - sampling routes before going to sea. It also provides tooling to - explore real-time adaptive strategies in which sampling plans shift as - forecasts or observations update. The same workflow can also be used - to investigate sampling efficiency, for example, examining how - waypoint number or spacing shapes the ability to capture features of - interest. Moreover, the software is well-suited for developing - Observation System Simulation Experiments (OSSEs; e.g. Errico et al. - (2013)) - to test and optimise observational strategies in a cost- and - time-efficient manner. This framework further enables instrument - design experiments that are relevant to autonomous observing systems. - There is potential for users to prototype and test control strategies - for gliders, REMUS vehicles, and Saildrones, as well as explore - concepts for new instruments at early stages of development. Future - tutorials could demonstrate how to define custom instruments within - the VirtualShip framework.

-

Both the customisability of the VirtualShip - platform and the exciting potential for new ARCO-based data hosting - services in domains beyond oceanography (e.g., - atmospheric - science) means there is potential to extend VirtualShip (or - “VirtualShip-like” tools) to other domains in the future. Furthermore, - as the Parcels underpinnings themselves - continue to evolve, with a future (at time of writing) - v4.0 - release focusing on alignment with - Pangeo - standards and Xarray data structures - (Hoyer - & Hamman, 2017), VirtualShip will - also benefit from these improvements, further enhancing its - capabilities, extensibility and compatability with modern cloud-based - data pipelines.

- - - Acknowledgements -

The VirtualShip project is funded through the Utrecht - University-NIOZ (Royal Netherlands Institute for Sea Research) - collaboration.

- - - - - - - - - LangeMichael - van SebilleErik - - Parcels v0.9: prototyping a Lagrangian ocean analysis framework for the petascale age - Geoscientific Model Development - Copernicus GmbH - 2017 - 10 - 11 - 1991-9603 - http://dx.doi.org/10.5194/gmd-10-4175-2017 - 10.5194/gmd-10-4175-2017 - 4175 - 4186 - - - - - - DelandmeterPhilippe - van SebilleErik - - The Parcels v2.0 Lagrangian framework: new field interpolation schemes - Geoscientific Model Development - Copernicus GmbH - 2019 - 12 - 8 - 1991-9603 - http://dx.doi.org/10.5194/gmd-12-3571-2019 - 10.5194/gmd-12-3571-2019 - 3571 - 3584 - - - - - - DanielsEmma - ChytasChristos - SebilleErik van - - The virtual ship classroom: Developing virtual fieldwork as an authentic learning environment for physical oceanography - Current: The Journal of Marine Education - 202509 - 10.5334/cjme.121 - - - - - - AlmansiMattia - GelderloosRenske - HaineThomas W. n. - SaberiAtousa - SiddiquiAli H. - - OceanSpy: A python package to facilitate ocean model data analysis and visualization - Journal of Open Source Software - The Open Journal - 2019 - 4 - 39 - https://doi.org/10.21105/joss.01506 - 10.21105/joss.01506 - 1506 - - - - - - - AbernatheyRyan P. - AugspurgerTom - BanihirweAnderson - Blackmon-LucaCharles C. - CroneTimothy J. - GentemannChelle L. - HammanJoseph J. - HendersonNaomi - LeporeChiara - McCaieTheo A. - RobinsonNiall H. - SignellRichard P. - - Cloud-native repositories for big scientific data - Computing in Science & Engineering - 2021 - 23 - 2 - 10.1109/MCSE.2021.3059437 - 26 - 35 - - - - - - MazeGuillaume - BalemKevin - - Virtual fleet - recovery - Zenodo - 202301 - https://doi.org/10.5281/zenodo.7520147 - 10.5281/zenodo.7520147 - - - - - - SternCharles - AbernatheyRyan - HammanJoseph - WegenerRachel - LeporeChiara - HarkinsSean - MeroseAlexander - - Pangeo forge: Crowdsourcing analysis-ready, cloud optimized data production - Frontiers in Climate - 2022 - Volume 3 - 2021 - 2624-9553 - https://www.frontiersin.org/journals/climate/articles/10.3389/fclim.2021.782909 - 10.3389/fclim.2021.782909 - - - - - - HoyerS. - HammanJ. - - Xarray: N-D labeled arrays and datasets in Python - Journal of Open Research Software - Ubiquity Press - 2017 - 5 - 1 - https://doi.org/10.5334/jors.148 - 10.5334/jors.148 - - - - - - ErricoRonald M. - YangRunhua - PrivéNikki C. - TaiKing-Sheng - TodlingRicardo - SienkiewiczMeta E. - GuoJing - - Development and validation of observing-system simulation experiments at NASA’s global modeling and assimilation office - Quarterly Journal of the Royal Meteorological Society - 2013 - 139 - 674 - https://rmets.onlinelibrary.wiley.com/doi/abs/10.1002/qj.2027 - https://doi.org/10.1002/qj.2027 - 1162 - 1178 - - - - - - LumpkinRick - ÖzgökmenTamay - CenturioniLuca - - Advances in the application of surface drifters - Annual Review of Marine Science - Annual Reviews - 2017 - 9 - Volume 9, 2017 - 1941-0611 - https://www.annualreviews.org/content/journals/10.1146/annurev-marine-010816-060641 - https://doi.org/10.1146/annurev-marine-010816-060641 - 59 - 81 - - - - - - JayneSteven R. - RoemmichDean - ZilbermanNathalie - RiserStephen C. - JohnsonKenneth S. - JohnsonGregory C. - PiotrowiczStephen R. - - The argo program: Present and future - Oceanography - Oceanography Society - 2017 - 20251217 - 30 - 2 - http://www.jstor.org/stable/26201840 - 18 - 28 - - - - - - GoniGustavo J. - SprintallJanet - BringasFrancis - ChengLijing - CiranoMauro - DongShenfu - DominguesRicardo - GoesMarlos - LopezHosmay - MorrowRosemary - RiveroUlises - RossbyThomas - ToddRobert E. - TrinanesJoaquin - ZilbermanNathalie - BaringerMolly - BoyerTim - CowleyRebecca - DominguesCatia M. - HutchinsonKatherine - KrampMartin - MataMauricio M. - ReseghettiFranco - SunCharles - Bhaskar TVSUdaya - VolkovDenis - - More than 50 years of successful continuous temperature section measurements by the global expendable bathythermograph network, its integrability, societal benefits, and future - Frontiers in Marine Science - 2019 - Volume 6 - 2019 - 2296-7745 - https://www.frontiersin.org/journals/marine-science/articles/10.3389/fmars.2019.00452 - 10.3389/fmars.2019.00452 - - - - - - KostaschukRay - BestJim - VillardPaul - PeakallJeff - FranklinMark - - Measuring flow velocity and sediment transport with an acoustic doppler current profiler - Geomorphology - 2005 - 68 - 1 - 0169-555X - https://www.sciencedirect.com/science/article/pii/S0169555X04002879 - https://doi.org/10.1016/j.geomorph.2004.07.012 - 25 - 37 - - - - - - GordonArnold L. - FlamentPierre - VillanoyCesar - CenturioniLuca - - The nascent kuroshio of lamon bay - Journal of Geophysical Research: Oceans - 2014 - 119 - 7 - https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1002/2014JC009882 - https://doi.org/10.1002/2014JC009882 - 4251 - 4263 - - - - - - JohnsonGregory C. - TooleJohn M. - LarsonNordeen G. - - Sensor corrections for sea-bird SBE-41CP and SBE-41 CTDs - Journal of Atmospheric and Oceanic Technology - American Meteorological Society - Boston MA, USA - 2007 - 24 - 6 - https://journals.ametsoc.org/view/journals/atot/24/6/jtech2016_1.xml - 10.1175/JTECH2016.1 - 1117 - 1130 - - - - -
diff --git a/docs/paper/paper.md b/docs/paper/paper.md index 90cba6e9..3b0940f3 100644 --- a/docs/paper/paper.md +++ b/docs/paper/paper.md @@ -47,10 +47,10 @@ Marine science relies on fieldwork for data collection, yet sea-going opportunit `VirtualShip` goes beyond simply extracting grid-cell values from model output. Instead, it uses programmable behaviours and sophisticated interpolation techniques (with `Parcels` underpinnings) to access data in exact locations and timings, as if they were being collected by real-world instruments. `VirtualShip` shares some functionality with existing tools, such as `OceanSpy` [@Almansi2019] and `VirtualFleet` [@Maze2023], but extends capabilities to mesh many different instrument deployments into a unified expedition simulation framework. Moreover, `VirtualShip` exploits readily available, streamable data via the Copernicus Marine Data Store, removing the need for users to download and manage large datasets locally and/or arrange for access to remote servers. `VirtualShip` can also integrate coordinate files exported from the [Marine Facilities Planning](https://www.marinefacilitiesplanning.com/cruiselocationplanning#) (MFP) tool, giving users the option to define expedition waypoints via an intuitive web-based mapping interface. -# Functionality - `VirtualShip` simulates the deployment of virtual instruments commonly used in oceanographic fieldwork, with emphasis on realism in how users plan and execute expeditions. For example, users must consider ship speed and instrument deployment/recovery times to ensure their expedition is feasible within given time constraints. Possible instrument selections include surface `Drifter` [@Lumpkin2017], `CTD` (Conductivity-Temperature-Depth; @Johnson2007), `Argo float` [@Jayne2017], `XBT` (Expendable Bathythermograph; @Goni2019), underway `ADCP` (Acoustic Doppler Current Profiler; @Kostaschuk2005), and underway `temperature/salinity` [@Gordon2014] probes. More detail on each instrument is available in the [documentation](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Research_proposal_intro.html#Measurement-Options). +# Software design + The software can simulate complex multidisciplinary expeditions. One example is a virtual expedition across the Agulhas Current and the South Eastern Atlantic that deploys a suite of instruments to sample physical and biogeochemical properties (\autoref{fig:fig1}). Key circulation features appear early in the expedition track, with enhanced ADCP speeds marking the strong Agulhas Current (\autoref{fig:fig1}b) and drifters that turn back toward the Indian Ocean indicating the Agulhas Retroflection (\autoref{fig:fig1}c). The CTD profiles capture the vertical structure of temperature and oxygen along the route, including the warmer surface waters of the Agulhas region (\autoref{fig:fig1}d, early waypoints) and the Oxygen Minimum Zone in the South Eastern Atlantic (\autoref{fig:fig1}e, final waypoints). The software is designed to be highly intuitive to the user. It is wrapped into three high-level command line interface commands using [Click](https://click.palletsprojects.com/en/stable/): @@ -61,15 +61,13 @@ The software is designed to be highly intuitive to the user. It is wrapped into A full example workflow is outlined in the [Quickstart Guide](https://virtualship.readthedocs.io/en/latest/user-guide/quickstart.html) documentation. -![Example VirtualShip expedition simulated in July/August 2023. Expedition waypoints displayed via the MFP tool (a), Underway ADCP measurements (b), Surface drifter releases (c; 90-day lifetime per drifter), and CTD vertical profiles for temperature (d) and oxygen (e). Black triangles in b), d) and e) mark waypoint locations across the expedition route, corresponding to the purple markers in a).\label{fig:fig1}](figure1.png) - -# Implementation - Under the hood, `VirtualShip` is modular and extensible. The workflows are designed around `Instrument` base classes and instrument-specific subclasses and methods. This means the platform can be easily extended to add new instrument types. Instrument behaviours are coded as `Parcels` kernels, which allows for extensive customisability. For example, a `Drifter` advects passively with ocean currents, a `CTD` performs vertical profiling in the water column and an `ArgoFloat` cycles between ascent, descent and drift phases, all whilst sampling physical and/or biogeochemical fields at their respective locations and times. Moreover, the data ingestion system relies on Analysis-Ready and Cloud-Optimized data (ARCO; @Stern2022, @Abernathey2021) streamed directly from the Copernicus Marine Data Store, via the [`copernicusmarine`](https://github.com/mercator-ocean/copernicus-marine-toolbox) Python toolbox. This means users can simulate expeditions anywhere in the global ocean without downloading large datasets by default. Leveraging the suite of [physics and biogeochemical products](https://virtualship.readthedocs.io/en/latest/user-guide/documentation/copernicus_products.html) available on the Copernicus plaform, expeditions are possible from 1993 to present and forecasted two weeks into the future. There is also an [option](https://virtualship.readthedocs.io/en/latest/user-guide/documentation/pre_download_data.html) for the user to specify local `NetCDF` files for data ingestion, if preferred. -# Applications and future outlook +![Example VirtualShip expedition simulated in July/August 2023. Expedition waypoints displayed via the MFP tool (a), Underway ADCP measurements (b), Surface drifter releases (c; 90-day lifetime per drifter), and CTD vertical profiles for temperature (d) and oxygen (e). Black triangles in b), d) and e) mark waypoint locations across the expedition route, corresponding to the purple markers in a).\label{fig:fig1}](figure1.png) + +# Research impact statement `VirtualShip` has already been extensvely applied in Master's teaching settings at Utrecht University as part of the [VirtualShip Classroom](https://www.uu.nl/en/research/sustainability/sustainable-ocean/education/virtual-ship) initiative. Educational assignments and tutorials have been developed alongside to integrate the tool into coursework, including projects where students design their own research question(s) and execute their fieldwork and analysis using `VirtualShip`. Its application has been shown to be successful, with students reporting increased self-efficacy and knowledge in executing oceanographic fieldwork [@Daniels2025]. @@ -77,6 +75,10 @@ The package opens space for many other research applications. It can support rea Both the customisability of the `VirtualShip` platform and the exciting potential for new ARCO-based data hosting services in domains beyond oceanography (e.g., [atmospheric science](https://climate.copernicus.eu/work-progress-our-data-stores-turn-arco)) means there is potential to extend VirtualShip (or "VirtualShip-like" tools) to other domains in the future. Furthermore, as the `Parcels` underpinnings themselves continue to evolve, with a future (at time of writing) [v4.0 release](https://docs.oceanparcels.org/en/v4-dev/v4/) focusing on alignment with [Pangeo](https://pangeo.io/) standards and `Xarray` data structures [@Hoyer2017], `VirtualShip` will also benefit from these improvements, further enhancing its capabilities, extensibility and compatability with modern cloud-based data pipelines. +# AI usage disclosure + +Generative AI technologies (Gemini v2.0/2.5/3.0, ChatGPT v4o/5.0/5.1/5.2 and GitHub Copilot) were used for code generation, refactoring and test scaffolding. AI-assisted autocompletion tools (via GitHub Copilot) were used in the writing of this manuscript. Authors carefully reviewed and edited all AI-assisted content and made the core desigin decisions without use of AI. + # Acknowledgements The VirtualShip project is funded through the Utrecht University-NIOZ (Royal Netherlands Institute for Sea Research) collaboration. diff --git a/docs/paper/paper.pdf b/docs/paper/paper.pdf index a9e7fbb2..9720edc1 100644 Binary files a/docs/paper/paper.pdf and b/docs/paper/paper.pdf differ