[REVIEW]: A course on the setup, running, and analysis of biomolecular simulations

[editorialbot]

Submitting author: @degiacom (Matteo Degiacomi)
Repository: https://github.com/CCPBioSim/BioSim-analysis-workshop
Branch with paper.md (empty if default branch):
Version: v1.0
Editor: @arm61
Reviewers: @raquellrios, @djcole56
Archive: Pending
Paper kind: learning module

Status

Status badge code:

HTML: <a href="https://jose.theoj.org/papers/085047c344a15394568f262b57eb920f"><img src="https://jose.theoj.org/papers/085047c344a15394568f262b57eb920f/status.svg"></a>
Markdown: [![status](https://jose.theoj.org/papers/085047c344a15394568f262b57eb920f/status.svg)](https://jose.theoj.org/papers/085047c344a15394568f262b57eb920f)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) by leaving comments in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@raquellrios & @djcole56, your review will be checklist based. Each of you will have a separate checklist that you should update when carrying out your review.
First of all you need to run this command in a separate comment to create the checklist:

@editorialbot generate my checklist

The reviewer guidelines are available here: https://openjournals.readthedocs.io/en/jose/reviewer_guidelines.html. Any questions/concerns please let @arm61 know.

✨ Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest ✨

Checklists

📝 Checklist for @djcole56

[editorialbot]

Hello humans, I'm @editorialbot, a robot that can help you with some common editorial tasks.

For a list of things I can do to help you, just type:

@editorialbot commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@editorialbot generate pdf

[editorialbot]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

✅ OK DOIs

- 10.5281/zenodo.13155316 is OK
- 10.1038/s41586-021-03819-2 is OK
- 10.25080/Majora-629e541a-00e is OK
- 10.1038/253694a0 is OK
- 10.1126/science.1208351 is OK
- 10.1021/acs.jchemed.1c00022 is OK
- 10.1140/epjb/s10051-021-00249-x is OK
- 10.1016/j.neuron.2018.08.011 is OK
- 10.1016/j.bpj.2022.11.2277 is OK
- 10.1002/jcc.21787 is OK

🟡 SKIP DOIs

- No DOI given, and none found for title: Scikit-Learn: Machine Learning in Python

❌ MISSING DOIs

- None

❌ INVALID DOIs

- None

[editorialbot]

Software report:

github.com/AlDanial/cloc v 1.90  T=0.36 s (61.3 files/s, 26524.5 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Jupyter Notebook                 9              0           7142           1112
Python                           1            103            263            223
Markdown                         5             88              0            195
TeX                              1             10              0            161
YAML                             3              1             10             56
Bourne Shell                     1             14             63             35
CSV                              1              0              0             26
XML                              1              0              0             18
-------------------------------------------------------------------------------
SUM:                            22            216           7478           1826
-------------------------------------------------------------------------------

Commit count by author:

    24	Matteo Degiacomi
    17	DEGIACOMI
    10	ppxasjsm
     3	Toni Mey
     1	Micaela Matta

[editorialbot]

Paper file info:

📄 Wordcount for paper.md is 1437

✅ The paper includes a Statement of need section

[editorialbot]

License info:

🟡 License found: Other (Check here for OSI approval)

[editorialbot]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[ppxasjsm]

Hi @raquellrios, @djcole56 anything I could help with to get you started with the review?

[djcole56]

Review checklist for @djcole56

Conflict of interest

• As the reviewer I confirm that I have read the JOSE conflict of interest policy and that there are no conflicts of interest for me to review this work.

Code of Conduct

• I confirm that I read and will adhere to the JOSE code of conduct.

General checks

• Repository: Is the source for this learning module available at the https://github.com/CCPBioSim/BioSim-analysis-workshop?
• License: Does the repository contain a plain-text LICENSE file with the contents of a standard license? (OSI-approved for code, Creative Commons for content)
• Version: Does the release version given match the repository release?
• Authorship: Has the submitting author (@degiacom) made visible contributions to the module? Does the full list of authors seem appropriate and complete?

Documentation

• A statement of need: Do the authors clearly state the need for this module and who the target audience is?
• Installation instructions: Is there a clearly stated list of dependencies?
• Usage: Does the documentation explain how someone would adopt the module, and include examples of how to use it?
• Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the module 2) Report issues or problems with the module 3) Seek support

Pedagogy / Instructional design (Work-in-progress: reviewers, please comment!)

• Learning objectives: Does the module make the learning objectives plainly clear? (We don't require explicitly written learning objectives; only that they be evident from content and design.)
• Content scope and length: Is the content substantial for learning a given topic? Is the length of the module appropriate?
• Pedagogy: Does the module seem easy to follow? Does it observe guidance on cognitive load? (working memory limits of 7 +/- 2 chunks of information)
• Content quality: Is the writing of good quality, concise, engaging? Are the code components well crafted? Does the module seem complete?
• Instructional design: Is the instructional design deliberate and apparent? For example, exploit worked-example effects; effective multi-media use; low extraneous cognitive load.

JOSE paper

• Authors: Does the paper.md file include a list of authors with their affiliations?
• A statement of need: Does the paper clearly state the need for this module and who the target audience is?
• Description: Does the paper describe the learning materials and sequence?
• Does it describe how it has been used in the classroom or other settings, and how someone might adopt it?
• Could someone else teach with this module, given the right expertise?
• Does the paper tell the "story" of how the authors came to develop it, or what their expertise is?
• References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

[djcole56]

Hi, I'll drop any issues with the notebooks in here as I'm going along.

In 4_Simulation_Setup, only this method works:

lig27_smiles = "[H:7][C@:6]1([C:13](=[C:11]([C:9](=[O:10])[O:8]1)[O:12][H:19])[O:14][H:20])[C@:3]([H:4])([C:2]([H:16])([H:17])[O:1][H:15])[O:5][H:18]"
ligand = Molecule.from_mapped_smiles(lig27_smiles)

ie reading from file does not (I guess because it's not a mapped smiles).

More generally, it would be good to include instruction for how to make a mapped smiles if this is necessary input.

[djcole56]

@ppxasjsm @degiacom Finished going through the material. The course comprises a series of around 8 lectures and 8 workshops, with the first half devoted to setting up and running biomolecular simulations, and the second half to data analysis, including introductions to machine learning. The lectures are very clear and could be adopted by other teachers for their own courses. The workshops are presented through Jupyter notebooks, and I followed them on Google colab (as I imagine most students would). These are again very clearly presented and at a suitable level for a graduate or advanced undergrad class. Worked examples and problems are used throughout to hold attention, and the material usually progresses nicely from toy models to realistic simulation data. This course is commended for focusing on the fundamentals of simulation and analysis that is mostly agnostic to the underlying MD codes, and doesn't require any expensive licenses.

The material has clearly been used for teaching on several occasions, so I only found the one issue (above). Also nglview is not always able to run the trajectories on colab, but I this is a recurring problem, and not the authors' issue (it might still be worth warning students that they can use their favourite pdb viewer if this happens).

If I understand the journal requirements correctly, the GitHub page needs a 'statement of need' and 'community guidelines', then I'm happy to sign it off.

[arm61]

The statement of need is typically for the paper not the GitHub repo.