Programming practices chapter (now on a branch, rather than a fork) #14
Conversation
|
|
|
No spelling errors! 🎉 |
|
Re-rendered previews from the latest commit:
Updated at 2023-11-30 with changes from d2bd74a |
|
|
||
| In both R and Python, a _t_-test is a very well-defined, specific function that takes two lists of numbers and returns the _t_-statistic and _p_-value. | ||
| Since this is a part of a standard, widely used library in each language, it is already tested as part of those libraries. | ||
| In your own software, you might need to do some verification of your input (for instance, what happens if you pass an empty list of numbers?) but probably not too much, since you can be fairly confident that the _t_-test function does what it is documented to do in the programming language you choose to use. |
There was a problem hiding this comment.
I'm a little confused by this sentence. Can you explain what you mean here?
There was a problem hiding this comment.
I think what I'm trying to say is that a t-test (or the function to perform one) has a specific input and output, and is very commonly used in a wide variety of applications. So it's probably okay to assume that it's doing what its documentation says it will do, without verifying it yourself or writing your own tests for it, unless you're doing something really non-standard with it, or making a mistake in your own code (like the empty list example).
This would be in contrast to the sequencing pipeline example, where it's (as far as I know) not practical to have a single well-tested and widely used function that goes from raw reads to a volcano plot - there are a lot of very subjective decisions and data transformations that have to happen to get from point A to point B, and they can't be completely encapsulated or abstracted away, which makes it more important to make sure that each step is doing what you expect it to do.
I guess another way to think about this would be the difference between using a programming language as a calculator or a set of steps (which is more or less where I started, and where I think many people probably start), and using it to build more complex software with more extensive computing/testing requirements. I think as someone gravitates toward the latter, the argument for automation starts to make a bit more sense.
Does that make any sense to you? I guess I'll have to think about how to get all that across more concisely - let me know if you have ideas.
There was a problem hiding this comment.
Yes. I think this is a good point. Let's just figure out how we can get this point across more concisely.
It sounds like to me you are saying that as the complexity of an analysis increases, so does the decisions and parameters surrounding it. This means its even more critical to carefully read and consider the documentation of the software you are using to figure out what best fits the goals for your data.
There was a problem hiding this comment.
Could probably make a toy graph illustrating this idea. x axis is complexity of the analysis y is the number of decisions and parameters associated with the analysis.
(This idea would need some polishing).
There was a problem hiding this comment.
Here's a graph I added to the slides (I'll link to it in the part of the text you referenced):
I also toyed with labeling the parts of the graph off the "y = x" line, but I'm not sure if this is helpful or counter-productive: maybe we shouldn't even mention overengineering since it's such an uncommon case in academic software (in my experience at least!)
Let me know what you think.
There was a problem hiding this comment.
Made some minor edits to these slides but overall I love the concept!!! Great visual.
…ub_Automation_for_Scientists into jjc2718/programming-practices
|
I think this covers what we need! I'm going to merge! |
|
Note that the URL error warning is a bug and something I have to address elsewhere. |
Revised version of #9 - I think the automated steps should run now!
Purpose/implementation Section
What changes are being implemented in this Pull Request?
Adding a chapter that introduces good programming practices and how they relate to scientific software development, and a short intro to how automation fits in.
Tell potential reviewers what kind of feedback you are soliciting.
Any feedback would be great! Structure, text, concepts I'm missing, etc.
New Content Checklist
New content/chapter is in an Rmd file with this kind of format and headers.
New content/chapter contains learning objectives.
Bookdown successfully re-renders and any new content files have been added to the _bookdown.yml.
Spell check runs successfully).
Any newly necessary packages that are needed have been added to the Dockerfile and image.
Images are in the correct format for rendering.
Every new image has alt text and is in a Google Slide.
Each slide is described in the notes of the slide so learners relying on a screen reader can access the content. See https://lastcallmedia.com/blog/accessible-comics for more guidance on this.
The color palette choices of the slide are contrasted in a way that is friendly to those with color vision deficiencies.
You can check this using Color Oracle.