This issue is part of the JOSS review at https://github.com/openjournals/joss-reviews/issues/2436

Please note that this represents my initial review and does not take into account recent efforts by the submitting author to address issues.

Software paper review

The work of Opasic et al. introduces the CancerSim software, which is a Python package used to simulate the somatic evolution of cancers. CancerSim employs a 2D lattice model, which allows the generational mutational profile and spatial heterogeneity of tumors to be modeled in an abstract manner as governed by key parameters related to cell division and mutation probabilities.

Major Comments

[ ] A detailed description of the simulation outputs is missing in both the paper and the software documentation (Documentation: Functional documentation). This may make it more difficult for users to fully evaluate if the software fits their needs (before using it), but perhaps more importantly, it is not initially clear how users can proceed with further analysis of the simulation outputs.
[ ] Although short descriptions of the key tumor models are provided in the paper¸ a detailed description of the key tumor model parameters and how they relate to each other is missing from both the paper and documentation (Documentation: Functional documentation).
[ ] Although the summary of CancerSim itself is fairly detailed, there is no discussion of CancerSim in a broader context of cancer modeling methods or how CancerSim compares to other simulators. As such, I didn't get any sense of how CancerSim fits into the broader landscape of tumor modeling and cancer simulation methodologies. (Software paper: State of the field)

Minor Comments

[ ] This comment is related to the second major comment. There is no discussion or guidance on how users should determine key model parameters in a practical setting; e.g., should parameters be extracted directly from experimental measurements of cell division, or extracted from experimentally determined sequencing data (summary mentions reproducing sequencing data), or directly calibrated to some experimental data. I think some discussion and guidance in this area is needed to help users to evaluate the practical applicability of CancerSim to modeling their specific tumor systems, but will also be helpful for students and other non-specialists in further connecting the model to the tumor biology and available experimental methods.
[ ] I think you may need to clarify that CancerSim installs as the casim package, both in the paper and the documentation.
[ ] Summary, second paragraph, third sentence: This sentence is a little unclear to me. Does it mean that CancerSim can reproduce multi-region sequencing/profiling data? If so, I'd recommend re-wording a bit to make this more clear.
[ ] Summary, second paragraph, fourth sentence: I'd recommend listing a few examples to help make the point more clearly.
[ ] Summary, first paragraph, third sentence: please change "existence tumour" to "existence a tumour".
[ ] Summary, third paragraph, first sentence: I think a comma after "neoplasm type" is a little easier to read.
[ ] Summary, third paragraph, second sentence: I'd suggest rewriting "It resembles the most to superficially" as "It most closely resembles superficially"
[ ] Summary, fourth paragraph, sentence three: Please replace "mutation cell" with "mutation the cell".
[ ] Summary, paragraph five, sentence three: Can the division probabilities change during the course of a simulation in response to a cell acquiring a specific mutation? Or are the division probabilities just fixed at the beginning in a way that models beneficial or deleterious effects?

Reply to software paper review issue #16

This issue is part of the JOSS review at openjournals/joss-reviews#2436

Please note that this represents my initial review and does not take into account recent efforts by the submitting author to address issues.

Software paper review

The work of Opasic et al. introduces the CancerSim software, which is a Python package used to simulate the somatic evolution of cancers. CancerSim employs a 2D lattice model, which allows the generational mutational profile and spatial heterogeneity of tumors to be modeled in an abstract manner as governed by key parameters related to cell division and mutation probabilities.

Major Comments
* [ ]  A detailed description of the simulation outputs is missing in both the paper and the software documentation (Documentation: Functional documentation). This may make it more difficult for users to fully evaluate if the software fits their needs (before using it), but perhaps more importantly, it is not initially clear how users can proceed with further analysis of the simulation outputs.
We have added documentation of the simulation outputs to the paper, the README and the API documentation (CancerSimulator.run() method). Related commits: 3760a0, 4fb51c, 1e1ee0, 61220b .
* [ ]   Although short descriptions of the key tumor models are provided in the paper¸ a detailed description of the key tumor model parameters and how they relate to each other is missing from both the paper and documentation (Documentation: Functional documentation).
All parameters are now documented in the paper, in the README, the online documentation, and in the template params.py file (as comments). In addition, the API reference manual for the CancerSimulationParameters class was amended. Relevant commits: d6de50, f95e93, d6a38d, 4a39b4d, f046b6, c96f26,
* [ ]  Although the summary of CancerSim itself is fairly detailed, there is no discussion of CancerSim in a broader context of cancer modeling methods or how CancerSim compares to other simulators. As such, I didn't get any sense of how CancerSim fits into the broader landscape of tumor modeling and cancer simulation methodologies. (Software paper: State of the field)
We added a short discussion of a recently published cancer simulation code [waclaw2015] to the introduction. In the interest of overall paper length, we kept this discussion to a minimum. The main point is that our model abstracts away many of the fine grained model parameters of advanced tumour growth models. It thereby offers an entry point for newcomers to the field to perform their first steps in cancer modeling and to study the effect of choice of sampling positions and sample size on the observed tumour profile in comparison to the whole tumour profile. Relevant commits: 4a39b4

Minor Comments
* [ ]  This comment is related to the second major comment. There is no discussion or guidance on how users should determine key model parameters in a practical setting; e.g., should parameters be extracted directly from experimental measurements of cell division, or extracted from experimentally determined sequencing data (summary mentions reproducing sequencing data), or directly calibrated to some experimental data. I think some discussion and guidance in this area is needed to help users to evaluate the practical applicability of CancerSim to modeling their specific tumor systems, but will also be helpful for students and other non-specialists in further connecting the model to the tumor biology and available experimental methods.
A short recommendation for users how to apply their own parameters has been added to the paper and the README. Further clarification about the role of each parameter and how to choose its value and permissive values is given by the extended documentation of the template parameter file params.py and the table explaining all parameters in the paper. Relevant commits: df2fade
* [ ]  I think you may need to clarify that CancerSim installs as the `casim` package, both in the paper and the documentation.
A short note in this regard was added to the README, the online documentation, and the paper. Relevant commits: e4161ff
* [ ]  Summary, second paragraph, third sentence: This sentence is a little unclear to me. Does it mean that CancerSim can reproduce multi-region sequencing/profiling data? If so, I'd recommend re-wording a bit to make this more clear.
We clarified that sentence (4581588). Indeed, our code allows to generate mutation profiles from multiple samples taken at different positions of the tumour. This feature was previously hidden from the user, i.e. the user would have to hardcode the coordinates into the code casim.py. We have now exposed the sampling coordinates in the public API through the parameter sampling_positions in CancerSimulationParameters. Relevant commits: 839c23a3, 7e32183
* [ ]  Summary, second paragraph, fourth sentence: I'd recommend listing a few examples to help make the point more clearly.
We added needle biopsy and liquid biopsy as examples.
* [ ]   Summary, first paragraph, third sentence: please change "existence tumour" to "existence a tumour".
done
* [ ]  Summary, third paragraph, first sentence: I think a comma after "neoplasm type" is a little easier to read.
done.
* [ ]  Summary, third paragraph, second sentence: I'd suggest rewriting "It resembles the most to superficially" as "It most closely resembles superficially"
done
* [ ]  Summary, fourth paragraph, sentence three: Please replace "mutation cell" with "mutation the cell".
done
* [ ]  Summary, paragraph five, sentence three: Can the division probabilities change during the course of a simulation in response to a cell acquiring a specific mutation? Or are the division probabilities just fixed at the beginning in a way that models beneficial or deleterious effects?
Both is possible: In a single run, the parameters division_probability, death_probability, mutation_probability and their counterparts for carriers of beneficial/deleterious mutations, adv_mutant_division_probability, adv_mutant_mutation_probability, and adv_mutant_death_probability determine the growth rate of tumour cells without and with beneficial/deleterious mutations. These parameters are constant over the course of a run. It is however possible to save a run with all its internal state variables to disk, reload the run and continue the reloaded run after modifying selected parameters. This opens up the possibility to modify growth and mutation parameters to model some of the mentioned effects like dormancy or cancer therapy. This feature is now documented in more detail in the paper, README, online documentation and in a new example notebook. Relevant commit: 93e47a04

mpievolbio-scicomp / cancer_sim