Feedback from Nav on Introduction & Set-up

[amyheather]

This is feedback from Nav Mustafee on the Introduction and Set-up sections (6th July) - thank you Nav!

• The inclusion of figures (really well done!), highlighted boxes, icons, etc. has made the book visually very attractive!
• Easy to use navigation – left and right.
• The introductory paragraphs on DES in FOSS are succinct!
• Excellent treatment of Git and GitHub, including how organisations can use it for collaboration!
• I liked the term “time capsule” (dependency management)
• Adding packages to the environment --> Nice flow --> first identify the current package and then edit the .yaml file with the current package number! Nice touch!! The Python version is now 3.13.5.
• The book is very well explained.. and more to come!!

---

Welcome Page

• 1. A short definition of RAP and why it is important can be added (or perhaps a link?).
• 2a. Choose your language (Python/R) – the interface is not changing, i.e., it appears like a button, but when pressed, it does not change to a different shade, etc. This appears to be happening only on the welcome page; in other pages, the button changes to “teal”.

• 2b. I was also wondering if the Python/R selection option needs to appear on every page? Some readers may expect to see a change in the content based on the option selected. This might happen in the sections of the book on the coding element, so you can toggle between the two and get a good understanding of both Python and R code (as is happening in section dependency management). But for sections like the introduction, there may not be any change to the content of the book.

---

Reproducibility and RAPs

• 3. Replicability definition. Not sure what it meant by “implement your methods”. Does it mean algorithms, or perhaps the logic of the DES model? NISO's definition of “results replicable” approaches this from the research question and the finding perspective. For applied studies (like our work), not sure if we can take the research angle? I think what we are saying that the case study being the same (or not?) and the objectives of the modelling exercise also being the same (think of two student projects), if the results of the first study, say developed in SimPy, are similar to the second project (which uses a different software or libraries or is different code), then we say the results are replicable. I am speaking loud here. Not sure how to express the definition applicable to DES in a sentence?
• 4. Section 2.2: Typo “If work is reproducibility ..”
• 5. Section 2.2: “.. results are reproducible..” (rather than results are reliable)?

---

Guidelines

• 6. Introduction > Guidelines: 2. NHS ‘Levels of RA’.. “The following framework has been sourced from …” (or some other word?, in place of “directly copied from”)

---

Open-source language

• 7. NHS Level of RAP – Not sure about SQL (Structured Query Language) as a database will be required. The database could be free (like SQLite) or proprietary (e.g., ORACLE). For procedural logic, I think you need more than just SQL; for example, Oracle has a language called PL/SQL, where SQL code is embedded between program constructs. I would only keep Python and R.
• 8. FOSS: “Freedom to do what you want”, does it necessarily mean that the software will also be free (in monetary terms)? Are there FOSS software that are not “free” and you have to pay, but “free” to modify and distribute? Just thinking loud, as “free” can be applied to both.

---

Version Control

• 9. The screenshot “Create a new repository” could perhaps be populated with the suggested text and options presented earlier, i.e., with repository name, visibility, .gitignore, license and other options.
• 10. One question which occurred to me – some readers may develop both R and Python versions of the FOSS models. Thus, I guess, two repos will be needed – one using .gitignore Python and R, respectively? --> I've add a note about creating separate repositorities for each project (e.g. python v.s. r tutorials) under 2. Create a new repository
• 11. Cloning of repository: Excellent! No stones unturned 😊 ◦ There may be opportunities to provide a bit more information (or links?). For example, to download GitBash (Windows 11), I used the following video: https://www.youtube.com/watch?v=cweFdzKMeS0&ab_channel=AdrianDolinay ◦ P.S: In relation to Git, the four videos available at https://git-scm.com/doc could be linked. (but this may also not be necessary as the focus is not on collaboration using Git). --> I've add the Git bash video within 2. Clone the repository, and a further information section at the end with the other git videos
• 12. Cloning of repository: “This will have created a local copy of the repository, which you can open with your preferred development environment (e.g. VSCode, RStudio)”. Great!! ◦ For those new to using Git integration with VSCode or RStudio, perhaps a link to a video may help.
• 13. Merge the changes: Here we moved from the command line to the GitHub interface for the “merge”, and after the merge, again returned to the local machine (“5. Close your branch”). This is OK, but a question may be asked as to which commands are needed to achieve the same functionality using Git Bash? --> add command line alternative, but explained benefit of using website

---

Dependency Management

• 14. The section on “Conda” mentions “Mamba” (the latter appears to be a C++ implementation of the former and is faster). Perhaps there could be a separate section for Mamba with some explanatory text - https://anaconda.org/conda-forge/mamba (Mamba is also referred to in Sections 2 and 2.1).

• 15. Creating the environment (Section 2.2) – “In the project root, we create environment.yaml.” ◦ As we are currently working through the A&E example, perhaps we can be more specific here? Is this the same root folder as the one created for Git? --> Clarified on page, and made separate issue about having a clear narrative on what is being worked on etc. (Clearer workflow re: illustrative examples VS creating the model examples #55)

• 16. Section 2.2 title (Creating the Environment) – I would include in brackets (Conda/Mamba).

• 16b. I would also consider having a screenshot of Anaconda Navigator (say, the default option; like we used Git for version control) and indicate the location of “Anaconda Prompt” (for CLI commands that follow section 2.2) – see example below. --> not done exactly this, as would suggest terminal and git bash as more universal default for anyone not using anaconda navigator - but have added a new section "How will we work" which explains this and mentions anaconda prompt and anaconda navigator

• 16c. Touch command – I think this is for Linux (can we mention that any text editor can be used?)

• 17. Following the above screenshots, perhaps another screenshot of the CLI interface, the directory (Git directory to be navigated using CD command), and the command itself (see below): --> creating a little example project structure instead using ├── and └──

• 18. Last line of Section 2.4: I think it is mentioned that the environment will need to be activated first and then the prune command is to be used. Should it not be the other way, i.e., first update the environment with the new packages, and then run the conda activate des-example environment? --> needs to be active - have add some explanation about this, and why
• 19. Great to see the instructions for the other dependency management tools. ◦ P.S: I have tested with only Conda (I had Anaconda Navigator installed, so used that).

---

Structuring a Package

• 20. Creating a folder in the project directory – is this the same top-level Git folder?
• 21. I think Linux commands are used here. Perhaps we can say that directories in Windows can be created using Explorer, in place of touch, a text processing software, or VS Code can be used, etc. ◦ init.py (two underscores)?
• 22. Make project file: pyproject.toml  “The dynamic field tells flit to extract the version and description from our init.py file”. ◦ Note that the init.py file does not include a description. Also, the variable names are different (“version” rather than “version”). Pls check pyproject.toml. --> version name differences is fine, they need to be in those formats, but I have amended so description is given in pyproject.toml rather than dynamic, as that is a simpler workflow
• 23. Same comment as before  “To update our environment, adding our new package, execute the following (env update) in the command line (after running conda activate des-example)”. Why not update the env first and then run conda activate?

---

Code Organisation

• 24. Line 1: “… when you need to reuse code” (rather than “reuse something”)?
• 25. Class example is Dog and the method is bark. Just wondering if we can have a more operations management-related class 😊 Same for subclasses and inheritance examples.
• 26. Section 3 – programming paradigms; does this come earlier in the page (before functions and classes)? --> kept in place but add some explanation/justification for why
• 27. Functional programming – perhaps terms like “no side effects” and “first-class citizens” can be rephrased a bit.
• 28. I expected a section on synchronisation of the code with GitHub. This could also be a task for the reader! Nicely bringing version control, online repository, dependency management, packages, Jupiter notebook, etc. as one final activity to end the section! --> have add an activity with this task - converting code to function or class, and syncing with github