JOSS manuscript #265
JOSS manuscript #265
Conversation
for more information, see https://pre-commit.ci
|
Great. Thanks for initiating this! |
|
Hello, thanks for involving me, I appreciate it. I aim to haveread through it by tomorrow evening. |
|
I am happy to participate in the paper and will separate a time to revise the manuscript until the end of this week. |
iuryt
left a comment
iuryt
left a comment
There was a problem hiding this comment.
I have added a couple of comments and suggestions. Feel free to accept, reject or adapt as needed.
There was a problem hiding this comment.
I have a couple of suggestions for this figure. This is a version with some of my suggestions, but I could work on the .py directly, but I couldn't make virtualship run MY_EXPEDITION work. Do we have a tutorial on how to setup the environment using pixi? The current pyproject.toml does not have [tool.pixi.workspace].
If you send the output files by email, I would be happy to directly add my suggestions to figure1.py.
What I changed in this figure:
- Enlarged all text in panel a) as well as the waypoints and their arrows.
- left-aligned the titles
- If I understand correctly, panel b) is the speed, not the velocity
| 2. `virtualship plan`: Launches a user-friendly Terminal-based expedition planning User Interface (UI), built using [`Textual`](https://textual.textualize.io/). This allows users to intuitively modify their expedition waypoint locations, timings and instrument selections. | ||
| 3. `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`](https://zarr.dev/) format. | ||
|
|
||
| A full example workflow is outlined in the [Quickstart Guide](https://virtualship.readthedocs.io/en/latest/user-guide/quickstart.html) documentation. |
There was a problem hiding this comment.
This example from Quickstart Guide mentions both schedule.yaml and expedition.yaml. Is this outdated?
There was a problem hiding this comment.
I updated the quickstart previously to mention only expedition.yaml. I cannot spot any mention of schedule.yaml in the latest version... have I missed something?
There was a problem hiding this comment.
It's on the video, but now I noticed that we are already disclaiming that the video might be outdated. Sorry.
docs/paper/paper.md
Outdated
|
|
||
| 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 for the user to specify local `NetCDF` files for data ingestion, if preferred, with the necessary file stuctures and naming conventions outlined in the relevant [documentation](https://virtualship.readthedocs.io/en/latest/user-guide/documentation/example_copernicus_download.html). |
There was a problem hiding this comment.
This citation for ARCO is with double parenthesis. Is there a way to avoid that?
| # Applications and future outlook | ||
|
|
||
| `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]. We encourage researchers to continue to use `VirtualShip` as a cost-effective means to plan future expeditions, as a tool for accessing ocean model data in a realistic manner, and to compare models to observations in a like-for-like manner. | ||
|
|
There was a problem hiding this comment.
| The package opens space for many other research applications. It can support cruise planning by letting users test sampling routes before going to sea. It also provides a natural way to explore real-time adaptive strategies in which sampling plans shift as forecasts or observations update. The same workflow can be used to investigate sampling efficiency, for example, examining how platform number or spacing shapes the ability to capture features of interest. | |
| The tool also supports instrument design experiments, which offers value for work on autonomous systems. Users can design and test control strategies for gliders, REMUS vehicles, Saildrones, and semi-autonomous platforms such as Argo floats, or even new instruments during the early stages of their development. A future tutorial could show users how to define custom instruments. | |
There was a problem hiding this comment.
This suggestion adds two new paragraphs for this section.
erikvansebille
left a comment
erikvansebille
left a comment
There was a problem hiding this comment.
Great paper! A few comments below
|
Thanks everyone for engaging and already providing feedback so quickly! I will digest properly and incorporate it all soon. |
surgura
left a comment
surgura
left a comment
There was a problem hiding this comment.
Thanks for the effort; I added some comments. I think this doc gives a good overview of the package.
docs/paper/paper.md
Outdated
|
|
||
| # Summary | ||
|
|
||
| `VirtualShip` is a Python-based package which exploits the customisability of the open-source `Parcels` Lagrangian simulation framework [@Lange2017; @Delandmeter2019] to simulate measurements as if they were coming from real-life oceanographic instruments. The software builds a virtual ocean world by streaming data from the [Copernicus Marine Data Store](https://marine.copernicus.eu/) on-the-fly, facilitating virtual expeditions anywhere on the globe. |
There was a problem hiding this comment.
I would first write what the package does, and only afterwards that it uses parcels. That way the reader immediately knows what they're looking. So something like:
VShip is a Python package for simulating measurements as if they were coming from real-life oceanographic instruments, based on parcels...
For the reader/user it is not particularly important that vship uses parcels.
docs/paper/paper.md
Outdated
|
|
||
| # Summary | ||
|
|
||
| `VirtualShip` is a Python-based package which exploits the customisability of the open-source `Parcels` Lagrangian simulation framework [@Lange2017; @Delandmeter2019] to simulate measurements as if they were coming from real-life oceanographic instruments. The software builds a virtual ocean world by streaming data from the [Copernicus Marine Data Store](https://marine.copernicus.eu/) on-the-fly, facilitating virtual expeditions anywhere on the globe. |
There was a problem hiding this comment.
I would prevent using the word 'virtual' twice
docs/paper/paper.md
Outdated
|
|
||
| # 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, planning future expeditions and deployments, and directly comparing observational strategies with model data. |
There was a problem hiding this comment.
I would slightly reorder to emphasize the goal
Fieldwork is a vital component of marine science education, yet access to sea-going experiences is increasingly limited by financial costs, logistical constraints, and environmental impacts. We present VirtualShip, an educational tool that provides an authentic fieldwork experience for students. It enables learners to plan oceanographic expeditions and deployments, conduct fieldwork in a realistic setting, and directly compare observational strategies with model data.
There was a problem hiding this comment.
In the end I have not incorporated this specific comment, simply because I prefer to keep the target audience more general for education and research communities
|
|
||
| # 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. |
There was a problem hiding this comment.
Maybe explicitly specify somewhere that knowledge of the vship code / parcels itself is not required by students to use the tool. In fact, no programming knowledge is required at all (at least that use to be the goal when I started, not sure if still true)
There was a problem hiding this comment.
I have also not incorporated this specific comment in the end, similarly to the comment above. Again just to avoid referencing just student users and not the wider research community. I'm also hesitant to advertise it as requiring absolutely no programming knowledge because it does need a bit of set up and e.g. Terminal knowledge for users to feel confident with it
docs/paper/paper.md
Outdated
|
|
||
| # Acknowledgements | ||
|
|
||
| <!-- TODO: Do co-authors have anyone else they want to acknowledge? --> |
|
Hi all, I have now made a second draft of the manuscript, incorporating your suggested changes. I will re-request your review for this version. Please mark the PR with your official approval when you're happy with the manuscript and giving your green light for me to submit. With this in mind, early Jan is looking like when I'll submit! @iuryt I have incorporated your suggested changes to Fig. 1 apart from the helpful enlarged text in panel a. Could you please add your version of a) to the figure? This should just require adding your .png version and changing the path in line 63 of figure1.py. |
j-atkins
requested review from
VeckoTheGecko,
ammedd,
erikvansebille,
iuryt and
surgura
and removed request for
VeckoTheGecko and
surgura
erikvansebille
left a comment
erikvansebille
left a comment
There was a problem hiding this comment.
A few minor suggestions below; mostly on the affiliation order
| index: 2 | ||
| - name: Woods Hole Oceanographic Institution, Falmouth, MA, USA | ||
| index: 3 | ||
| date: 4 December 2025 |
There was a problem hiding this comment.
Update the data to early January?
There was a problem hiding this comment.
Yes, I will update this at the very last when I know which date it's being submitted
docs/paper/paper.md
Outdated
|
|
||
| The software is designed to be highly accessible to the user. It is wrapped into three high-level command line interface commands (using [Click](https://click.palletsprojects.com/en/stable/)): | ||
|
|
||
| 1. `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 NIOZ MFP tool). |
There was a problem hiding this comment.
| 1. `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 NIOZ MFP tool). | |
| 1. `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 [Marine Facilities Planning](https://nioz.marinefacilitiesplanning.com/cruiselocationplanning#) tool). |
Co-authored-by: Erik van Sebille <[email protected]>
for more information, see https://pre-commit.ci
…ity, and adjust figure layout
for more information, see https://pre-commit.ci
|
I've made other changes to make the figure more clear and easier to read. I've edited panel a) using Inkscape to make it more focused on the region of study and also with larger font size. I hope I have not undone something you have implemented. 
|
|
Thanks @iuryt, this is great! Your changes definitely help a lot with readability. My only subsequent change is that I prefer the colorbars to match the horizontal extent of the subplots, so I have removed 
|
This PR is for visibility of a draft of the VirtualShip JOSS manuscript, and for the review as co-authors to be organised here.
Feel free to add comments and commits to this PR, or branch off as new PRs for suggested changes.
@VeckoTheGecko @iuryt @surgura you have all made substantial contributions to the code. I have listed you as co-authors, alongside @ammedd and @erikvansebille. In the first place, are you happy to be involved with the manuscript? If so, please also let me know what kind of timeline I can expect to get your feedback!