PCOMPBIOL-D-25-01084

wavess: An R package for agent-based simulation of within-host virus sequence evolution

PLOS Computational Biology

Dear Dr. Leitner,

Thank you for submitting your manuscript to PLOS Computational Biology. After careful consideration, we feel that it has merit but does not fully meet PLOS Computational Biology's publication criteria as it currently stands. Therefore, we invite you to submit a revised version of the manuscript that addresses the points raised during the review process.

Please submit your revised manuscript within 30 days Sep 28 2025 11:59PM. If you will need more time than this to complete your revisions, please reply to this message or contact the journal office at ploscompbiol@plos.org. When you're ready to submit your revision, log on to https://www.editorialmanager.com/pcompbiol/ and select the 'Submissions Needing Revision' folder to locate your manuscript file.

Please include the following items when submitting your revised manuscript:

* A rebuttal letter that responds to each point raised by the editor and reviewer(s). You should upload this letter as a separate file labeled 'Response to Reviewers'. This file does not need to include responses to formatting updates and technical items listed in the 'Journal Requirements' section below.

* A marked-up copy of your manuscript that highlights changes made to the original version. You should upload this as a separate file labeled 'Revised Manuscript with Track Changes'.

* An unmarked version of your revised paper without tracked changes. You should upload this as a separate file labeled 'Manuscript'.

If you would like to make changes to your financial disclosure, competing interests statement, or data availability statement, please make these updates within the submission form at the time of resubmission. Guidelines for resubmitting your figure files are available below the reviewer comments at the end of this letter.

We look forward to receiving your revised manuscript.

Kind regards,

Jordan Douglas

Academic Editor

PLOS Computational Biology

Natalia Komarova

Section Editor

PLOS Computational Biology

Additional Editor Comments:

Thank you for your interesting, relevant, and highly-polished mansucript; which has met positive feedback from all three Reviewers. Please work through these very minor revisions proposed by the Reviewers. I look forward to seeing the revised manuscript.

Jordan Douglas

Journal Requirements:

If the reviewer comments include a recommendation to cite specific previously published works, please review and evaluate these publications to determine whether they are relevant and should be cited. There is no requirement to cite these works unless the editor has indicated otherwise.

1) We ask that a manuscript source file is provided at Revision. Please upload your manuscript file as a .doc, .docx, .rtf or .tex. If you are providing a .tex file, please upload it under the item type u2018LaTeX Source Fileu2019 and leave your .pdf version as the item type u2018Manuscriptu2019.

2) Please upload all main figures as separate Figure files in .tif or .eps format. For more information about how to convert and format your figure files please see our guidelines: 

https://journals.plos.org/ploscompbiol/s/figures

3) We notice that your supplementary Figures are included in the manuscript file. Please remove them and upload them with the file type 'Supporting Information'. Please ensure that each Supporting Information file has a legend listed in the manuscript after the references list.

4) Please amend your detailed Financial Disclosure statement. This is published with the article. It must therefore be completed in full sentences and contain the exact wording you wish to be published.

1) State what role the funders took in the study. If the funders had no role in your study, please state: "The funders had no role in study design, data collection and analysis, decision to publish, or preparation of the manuscript."

2) If any authors received a salary from any of your funders, please state which authors and which funders..

If you did not receive any funding for this study, please simply state: u201cThe authors received no specific funding for this work.u201d

Reviewers' comments:

Reviewer's Responses to Questions

Comments to the Authors:

Please note here if the review is uploaded as an attachment.

Reviewer #1: This work offers robust computational tools for simulating virus evolution within a host.

Its framework supports recombination, latent infected cell reservoirs, and three types of selection. The system is applied to investigate selection pressures on HIV-1 env sequences, using longitudinal samples from 11 individuals. Validation against real within-host virus data is thorough and rigorous.

Overall, this is a well-constructed and relevant contribution.

comments:

(i) Figure 1, insets (G) and (I), from Grenfell (2004; https://doi.org/10.1126/science.1090727) compare HIV population-level phylogeny with within-host HIV phylogeny. In this study, the authors found that the phylogenies reconstructed from the simulated sequences closely resembled the within-host phylogenies derived from empirical data across all tested summary statistics.

Given these results, would it be feasible to also reconstruct the population-level HIV phylogeny using this simulation framework?

(ii) Latin Hypercube Sampling (LHS) assumes that the input parameter distributions are uncorrelated. Is this assumption realistic in practice?

(iii) second paragraph section 2.3.3: correct "the the".

(iv) section 6.3: The R version v5.3.3 has not yet been released.

Reviewer #2: In the manuscript ”wavess: An R package for agent-based simulation of within-host virus sequence evolution”, the authors describe the titular R package and the model underlying it. In addition, they thoroughly test its sensitivity to varying parameters and compare its results to real data. The biological and mathematical theory behind the model as well as its results are convincing, and the manuscript is very clearly written (and so is the model code behind it). The model itself represents a significant contribution to the growing field of agent-based modelling in pathogen evolution.

I tested the R package using the detailed instructions provided by the authors, and it works as advertised. While I am no expert on R, their code appears on closer reading to do what is stated in the description in the manuscript. The biological assumptions of the model also seem to be well-founded. Finally, the package allows for a large degree of customisation to suit various modelling needs.

My main comments are really more intended as points of discussion or food for thought:

- The authors state that both viruses and their host cells are treated as agents in the model. However, it seems that the infection process itself is not explicitly modelled. Rather, a sample determined through a fitness function is taken from the previous generation of viral sequences and transferred to the following. This is a valid method, but I would not say that it treats the viruses as agents in their own right. As the agency of host cells is also limited, I would almost say that the main agents of the model are the sequences themselves.

- As a consequence of the above, the phylogeny of the model strains cannot be tracked directly, but has to be reconstructed. Again, this is not a problem as such, but one advantage of the agent-based approach can be the ability to directly track relationships between individual agents (e.g., ancestors and descendants). I think a small note on this choice of methodology, possibly in the section on future modelling directions, could benefit the discussion.

Minor comments:

- Drawing a random number from a beta distribution to calculate cross-reactivity seems reasonable, but it would be a good idea with a note on the reasoning behind using this specific distribution.

- The expression given in eq. 3 appears to always give an immune cost of 0 at time t0. However, eq. 4 then describes a starting immune cost. Should this be added to eq. 3?

- It is stated in section 4.2 that 96 % of empirical summary statistics fall within the range of simulated statistics. Since a probability distribution is calculated based on the model results, would it be possible to test whether this observation matches the theoretical probability of outliers?

- In eq. 8, the sum runs over the variable t, but no t appears inside the sum. It would make the equation easier to understand to explicitly show what exactly is summed over.

- On page 10, line 4: “We next subset the simulations to include…”. I found this sentence hard to parse, and suggest replacing it with “We next took a subset of the simulations including…”

- Page 12, line 7: a small grammatical error in “…which parameters was perturbed…”

All in all, I find this model highly interesting and the associated package quite user-friendly. I thank the authors for their contribution to this interesting field.

Reviewer #3: This paper serves as a comprehensive introduction and explanation of a recently implemented R package for simulating within-host evolution of viral sequences. The package simulates models of viral fitness and selection, host immune response, latent reservoirs, and recombination. The model virus that this was built for is HIV but it is applicable well beyond that.

I found the paper easy to follow and well written. The package works as described and has comprehensive vignettes to walk the user through the main functions.

In my view, the paper is publishable as is but could be improved by addressing the following:

0. I think you should make some of the use cases for this software clearer - how would people use it to "allow for the investigation of factors such as the

role of recombination"? (to quote the abstract). An obvious way would be to do parameter inference eg via approximate Bayesian computation or similar - you could mention and reference some works along these lines.

1. in the intro, explain how the paper is structured. Many of the details are relegated to section 6 - it would be good to signal that up front.

2. "Many modeling frameworks" referred to in the intro but only 2 referenced. Add some references here or point to another article where we can find a fuller list.

3. figure 4 needs to be larger to be able to read it, currently lots of detail and a very small font

4. Section 3.2 Page 8: I was confused by "Mean number of transitions per timepoint" as I was unsure what you meant by transition (my mind first turned to transitions vs transversions.) Looking back several pages in the paper I understood but you could remind readers here what you mean.

5. IN the R package, the vignettes are not being found by the system. Eg:

> library(wavess)

> vignette("prepare_input_data")

Warning message:

vignette ‘prepare_input_data’ not found

6. (v minor point) In the vignettes, pipes |> and %>% are both used - choose one (|> works throughout by the looks)

7. With any simulation package, users always ask "but what about...?" In section 5 you discuss a little about future directions but it is not clear how you have structured the implementation to allow others to contribute extensions themselves. THis would be worth a word (or at least thinking about).

**********

Have the authors made all data and (if applicable) computational code underlying the findings in their manuscript fully available?

The PLOS Data policy requires authors to make all data and code underlying the findings described in their manuscript fully available without restriction, with rare exception (please refer to the Data Availability Statement in the manuscript PDF file). The data and code should be provided as part of the manuscript or its supporting information, or deposited to a public repository. For example, in addition to summary statistics, the data points behind means, medians and variance measures should be available. If there are restrictions on publicly sharing data or code —e.g. participant privacy or use of data from a third party—those must be specified.

Reviewer #1: Yes

Reviewer #2: Yes

Reviewer #3: Yes

**********

PLOS authors have the option to publish the peer review history of their article (what does this mean?). If published, this will include your full peer review and any attached files.

If you choose “no”, your identity will remain anonymous but your review may still be made public.

Do you want your identity to be public for this peer review? For information about this choice, including consent withdrawal, please see our Privacy Policy.

Reviewer #1: No

Reviewer #2: Yes: Andreas Eilersen

Reviewer #3: No

Figure resubmission:

While revising your submission, please upload your figure files to the Preflight Analysis and Conversion Engine (PACE) digital diagnostic tool, https://pacev2.apexcovantage.com/. PACE helps ensure that figures meet PLOS requirements. To use PACE, you must first register as a user. Registration is free. Then, login and navigate to the UPLOAD tab, where you will find detailed instructions on how to use the tool. If you encounter any issues or have any questions when using PACE, please email PLOS at figures@plos.org. Please note that Supporting Information files do not need this step. If there are other versions of figure files still present in your submission file inventory at resubmission, please replace them with the PACE-processed versions.

Reproducibility:

To enhance the reproducibility of your results, we recommend that authors of applicable studies deposit laboratory protocols in protocols.io, where a protocol can be assigned its own identifier (DOI) such that it can be cited independently in the future. Additionally, PLOS ONE offers an option to publish peer-reviewed clinical study protocols. Read more information on sharing protocols at https://plos.org/protocols?utm_medium=editorial-email&utm_source=authorletters&utm_campaign=protocols

Dear Leitner,

We are pleased to inform you that your manuscript 'wavess: An R package for simulation of adaptive within-host virus sequence evolution' has been provisionally accepted for publication in PLOS Computational Biology.

Before your manuscript can be formally accepted you will need to complete some formatting changes, which you will receive in a follow up email. A member of our team will be in touch with a set of requests.

Please note that your manuscript will not be scheduled for publication until you have made the required changes, so a swift response is appreciated.

IMPORTANT: The editorial review process is now complete. PLOS will only permit corrections to spelling, formatting or significant scientific errors from this point onwards. Requests for major changes, or any which affect the scientific understanding of your work, will cause delays to the publication date of your manuscript.

Should you, your institution's press office or the journal office choose to press release your paper, you will automatically be opted out of early publication. We ask that you notify us now if you or your institution is planning to press release the article. All press must be co-ordinated with PLOS.

Thank you again for supporting Open Access publishing; we are looking forward to publishing your work in PLOS Computational Biology. 

Best regards,

Jordan Douglas

Academic Editor

PLOS Computational Biology

Natalia Komarova

Section Editor

PLOS Computational Biology

***********************************************************