Peer review from Alison: setup

[amyheather]

Feedback from @AliHarp

Setup>Version control

• >creating a branch.. Third line "But with multiple collaborators.."

• 2. Open a terminal or GitBash – could just be called ‘Open a terminal window’ as you talk about other options.

• Could you add comments to the code chunk in 3. – eg #stage your changes #save a snapshot with a message #upload to github.

• You could also add a commit message formating convention explanation

• With your merge explanation, would a table or flowchart help, and or a beginner recommendation? There are multiple steps/substeps

• Setup>Version control>Merging using the command line... Alternatively, if you prefer to...

• 5. Close your branch – just for consistency, call it ‘Delete’? Could you briefly explain what prune means and why it is necessary?

• In Further Info, is it worth linking to Github docs

Setup>Environments

• I’m mainly looking at the R version, but in the Python version in Tools you say “We’d recommend using a tool that can do both:”

• Also in the Python Tools table you talk about top-level and snaphots without previous explanation – this could do with brief definitions.

• Also in the python table – uv can customise environment location unless I’m reading this wrong. And: Is Mamba not ‘very fast’?

• Remove the hyphen from ‘and-‘ from the first bullet in Tools (Python)

• Could the title ‘Version’ by made more clear – eg Python/R Version Management --> Unfortunately I can't - Quarto renders the table of contents once for the page - which basically means I can't dynamically change the table of contents with the Python and R buttons. This means the Python and R versions of the page have to share the same H2 headers

• ‘Set the active R version’ – this isn’t clear: Note: If you later change versions manually or with other tools, you may need to reset this.) – could you briefly explain what reset means and how to do it?

• You have a ‘find out more about each tool’ expandable callout in Python – might be good to have the same in R.

• Recreate and Troubleshoot: You might want to start with a brief explanation of why recreation might be needed. (both R and Python)

• Sorry to jump around – in the Python section you have Conda Channels callout box – might be worth linking to Anadconda licencing to keep it current if it changes (the bit about 200 or more employees)?

Setup>structuring as a package:

• (R) Create the package structure - Version: 0.0.0.9000 – should you start a 0.1.0? --> This gets explained later on page - have moved explanation up to be with first time 0.0.0.9000 is mentioned!

• At the end you talk about the NOTE in the output and say ‘don’t worry about it’ – is it worth being a bit more reassuring – this is expected because we haven’t built the full model yet but will resolve as we add code… or something.

• devtools::load_all() isn’t explain – you could add a callout like you do with %autoreload?

• (Python) Python has several different tools for building and managing packages. “We have chosen flit for this tutorial and our example models due to its simplicity and ease of setup”. – maybe how it is simpler or what trade-offs exists.

• A brief trouble-shooting section might be useful

Setup>Code Organisation:

• “Generally, we’ve used more classes in Python and more functions in R - as is typical, since R code often relies less on classes - but neither approach is exclusive, and often either could have been used. The choice is mostly a matter of language style, clarity, and what fits best for the problem at hand.” Is a bit confusing – it isn’t clear on why this matters or when people should choose differently. I wonder whether this is a detour which is adding unnecessary complexity that can confuse rather than clarify. Maybe just ‘you’ll see both approaches in this work, choose based on what makes your code clearer’? --> Removed R6.

• Example – you talk about inheritance but don’t explain when it should be used – you show its possible, but not when its preferable.

• Again R6 is dropped in with but only briefly discussed, whereas most R uses would have encountered R3 first (through base R and tidyverse) – this may need more explanation. Maybe through an expandable callout – e.g. ‘it is closest to Python syntax, but in your own work you may use R3 as it is simpler and more common, or stick with functions which is more common in R.’ A lot of healthcare users will be using R and some of it feels a bit Python centric, or forcing R into Python shape :D --> Removed R6.

• This also comes across in the ‘Test yourself’ – you say ‘Turn the code into a function or class’ but it isn’t clear which is better for this particular code block or what should guide choice. I think some guidance is needed for when (for this) you should consider a class, and when a function is simpler and makes sense. In the solution you could explain trade-offs. Eg after the function: The function approach works well because…. The class approach would be better if…. To get a sense of why someone should change the approach they are already using. --> Removed R6. Add explanation of use cases in Python programming paradgims.

• Package structure and code organisation kind of work together but the link isn’t clear. --> add intro section at start of code org that explains the link.

• Overall the functions section is great, the classes section is good but could explain better when to use them, but the paradigms section and exercise are a bit confusing.