Merge pull request #71 from archaeolauren/callout-01

Style edits to episode 01 callout "Why should I care"

Author: archaeolauren

episodes/01-introduction.md

@@ -1,5 +1,5 @@
 ---
-title: "Course introduction"
+title: "Course Introduction"
 teaching: 10
 exercises: 10
 ---
@@ -34,21 +34,20 @@ That is, enabling others to run our code and obtain the same results we did.
 ## Why should I care about reproducibility?
 
 Scientific transparency and rigor are key factors in research.
-Scientific methodology and results need to be published openly and replicated and confirmed by several independent parties.
-However, research papers often lack the full details required for independent reproduction or replication. 
-Many attempts at reproducing or replicating the results of scientific studies have failed in a variety of disciplines ranging from psychology ([The Open Science Collaboration (2015)][replication-crisis-osc]) to cancer sciences ([Errington et al (2021)][replication-crisis-errington]).
-These are called [**the reproducibility and replicability crises**][reproducibility-crisis] - ongoing methodological crises in which the results of many scientific studies are difficult or impossible to repeat.
+Scientific methodology and results need to be published openly, replicated and confirmed by several independent parties.
+However, research papers often lack the full details required for independent reproduction (reaching the same results with the same data) or replication (reaching the same results with new data). 
+Across many disciplines, the failure of attempts to reproduce or replicate scientific conclusions have resulted in [**reproducibility and replicability crises**][reproducibility-crisis], leading to reduced confidence in the scientific conclusions of fields as diverse as psychology ([The Open Science Collaboration (2015)][replication-crisis-osc]) and cancer sciences ([Errington et al (2021)][replication-crisis-errington]).
 
 Reproducible research is a practice that ensures that researchers can repeat the same analysis multiple times with the same results.
 It offers many benefits to those who practice it:
 
-* Reproducible research helps researchers remember how and why they performed specific tasks and analyses; this enables easier explanation of work to collaborators and reviewers.
-* Reproducible research enables researchers to quickly modify analyses and figures - this is often required at all stages of research and automating this process saves loads of time.
-* Reproducible research enables reusability of previously conducted tasks so that new projects that require the same or similar tasks become much easier and efficient by reusing or reconfiguring previous work.
-* Reproducible research supports researchers' career development by facilitating the reuse and citation of all research outputs - including both code and data.
+* Reproducible research helps researchers remember how and why they performed specific tasks and analyses; this makes work easier to explain to collaborators and reviewers.
+* Reproducible research enables researchers to quickly modify analyses and figures, saving time and effort when datasets or methods change.
+* Reproducible research is reusable; tasks can be recycled or reconfigured in future work.
+* Reproducible research supports researchers' career development by facilitating the citation of all research outputs, including both code and data.
 * Reproducible research is a strong indicator of rigor, trustworthiness, and transparency in scientific research.
   This can increase the quality and speed of peer review, because reviewers can directly access the analytical process described in a manuscript.
-  It increases the probability that errors are caught early on - by collaborators or during the peer-review process, helping alleviate the reproducibility crisis.  
+  It increases the probability that errors are caught early on, by collaborators or during the peer-review process, helping alleviate the reproducibility crisis.  
 
 However, reproducible research often requires that researchers implement new practices and learn new tools.
 This course aims to teach some of these practices and tools pertaining to the use of software to conduct reproducible research.
@@ -57,7 +56,7 @@ Review [the Reproducible Research Discussion](./reproducible-research-discussion
 
 ::::::::::::::::::::::::::::::
 
-## Practices for building better research software
+## Practices for Building Better Research Software
 
 The practices we will cover for building better research software fall into three areas.
 
@@ -92,7 +91,7 @@ Write your reflections in the shared collaborative document.
 
 ::::::::::::::::::
 
-## Our research software project
+## Our Research Software Project
 
 You are going to follow a fairly typical experience of a new researcher (e.g. a PhD student or a postdoc) joining a research group.
 You were emailed some spacewalks data and analysis code bundled in the `spacewalks.zip` archive, written by another group 
@@ -245,7 +244,7 @@ So, we cannot even run the code on our machines.
 There is also a number of issues we identified with the software project that could do with improving.
 For the rest of this course, we will work on fixing these issues and applying some good software engineering practices.
 
-## Further reading
+## Further Reading
 
 We recommend the following resources for some additional reading on reproducible research:
 
@@ -259,6 +258,6 @@ We recommend the following resources for some additional reading on reproducible
 * [Training materials on different aspects of research software engineering][intersect-rse-training] (including open source, reproducibility, research software testing, engineering, design, continuous integration, collaboration, version control, packaging,  etc.), compiled by the [INTERSECT project](https://intersect-training.org/)
 * [Curated resources][forrt-resources] by the [Framework for Open and Reproducible Research Training](https://forrt.org/) (FORRT)
 
-## Acknowledgements and references
+## Acknowledgements and References
 
 The content of this course borrows from or references [various work](learners/reference.md#litref), especially the [original version of this course with python examples][bbrs-py].

episodes/02-better-start-version-control.md

@@ -1,5 +1,5 @@
 ---
-title: Better start with a software project
+title: Better Start With a Software Project
 teaching: 30
 exercises: 30
 ---
@@ -32,7 +32,7 @@ produces can be trusted and others can build upon it with confidence.
 Let's begin by creating a new software project from our existing code,
 and start tracking changes to it with version control.
 
-## From script to software project
+## From Script to Software Project
 
 In the previous episode you have unzipped `spacewalks.zip` into a directory `spacewalks` in your home directory.
 
@@ -70,7 +70,7 @@ Over the rest of the course, we will transform a collection of these files into
 The first thing you may notice that our software project contains folder `astronaut-data-analysis-old` which presumably tries to keep track of older versions of the code. There is a better way to do that using version control tool, such as Git, and we can delete this folder but will wait until after we set up our version control with git.
 This way we can keep that version in our history and can delete it so it isn't currently in our folder.
 
-## Version control
+## Version Control
 
 Before we do any further changes to our software, we want to make sure we can keep a history of what changes we have done since we inherited the code from our colleague.
 
@@ -729,7 +729,7 @@ On branch main
 nothing to commit, working tree clean
 ```
 
-## Interacting with a remote Git server
+## Interacting With a Remote Git Server
 
 Git is distributed version control system and lets us synchronise work between multiple copies of the same repository - 
 which may not be on your machine (called **remote repositories**).
@@ -830,7 +830,7 @@ This command tells Git to update the "main" branch on the "origin" remote.
 The `-u` flag (short for `--set-upstream`) sets the 'tracking reference' for the current branch,
 so that in future `git push` will default to sending to `origin main`.
 
-## Software project in GitHub
+## Software Project in GitHub
 
 We now have our software project in GitHub and have linked it to our local working copy.
 We are ready to start more work on software development and publishing and backing up that work on GitHub.
@@ -903,7 +903,7 @@ At this point, the code in your local software project's directory should be as
 
 :::
 
-## Further reading
+## Further Reading
 
 We recommend the following resources for some additional reading on the topic of this episode:
 

episodes/03-reproducible-dev-environment.md

@@ -1,5 +1,5 @@
 ---
-title: Reproducible software environments
+title: Reproducible Software Environments
 teaching: 30
 exercises: 0
 ---
@@ -59,7 +59,7 @@ If you run into problems not mentioned here, please open an [issue in the lesson
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
-## Software dependencies
+## Software Dependencies
 
 If we have a look at our script, we may notice a few library calls such as `library("tidyverse")` throughout the code.
 
@@ -74,7 +74,7 @@ As a result, each R project you work on may require a different setup and set of
 To prevent conflicts and maintain reproducibility across projects, it’s helpful to keep these configurations isolated.
 The typical solution is to create a project-specific environment using tools like {renv}, which maintains its own library of packages and records exact versions in a lockfile—ensuring that the project always runs with the same package set it was developed with.
 
-## What are virtual software environments?
+## What Are Virtual Software Environments?
 
 So what exactly are virtual software environments, and why use them?
 
@@ -119,7 +119,7 @@ We should not let the difficulty of attaining "perfect" reproducibility prevent
 
 ::::::::::::::::::::::::::::::
 
-## Managing virtual environments R-style
+## Managing Virtual Environments R-Style
 
 Instantiating virtual environments in R is multi-step, multi-tool process.
 
@@ -375,7 +375,7 @@ Furthermore, your expertise will develop as you get more practice with managing
 
 ::::::::::::::::::::::::::::::
 
-## Running the code and reproducing results
+## Running the Code and Reproducing Results
 
 We are now setup to run our code from the newly created R project 
 
@@ -452,7 +452,7 @@ At this point, the code in your local software project's directory should be as
 
 ::::::
 
-## Further reading
+## Further Reading
 
 We recommend the following resources for some additional reading on the topic of this episode:
 

episodes/04-code-readability.md

@@ -1,5 +1,5 @@
 ---
-title: Code readability
+title: Code Readability
 teaching: 60
 exercises: 30
 ---
@@ -62,7 +62,7 @@ renv::restore()
 
 :::
 
-## Place `library` functions at the top
+## Place `library` Functions at the Top
 
 Let’s look at our code again. One thing that stands out is that we’re calling library() in multiple places throughout the script. By convention, all libraries should be loaded at the top so dependencies are easy to see and not buried in the code. This improves readability and makes the code easier to reuse and maintain.
 
@@ -152,7 +152,7 @@ Let's make sure we commit our changes.
  $ git add eva_data_analysis.R
  $ git commit -m "Move library calls to the top of the script"
 ```
-## Rules for variable names in R
+## Rules for Variable Names in R
 
  $ git add eva_data_analysis.R
  $ git commit -m "Move library calls to the top of the script"
@@ -318,7 +318,7 @@ As we have now updated all the variable names to be more descriptive, we can now
 To do so, we open our repository in GitHub, switch to the Issues tab, find the issue to "improve variable names" we created earlier.
 There are more automated ways to close issues based on a commit/pull request that we will learn later, for now we will click the "Close issue" button at the bottom of the discussion.
 
-## Remove unused variables and imports
+## Remove Unused Variables and Imports
 
 Unused variables or import statements can cause confusion about what the code is doing, making it harder to read and easier to introduce mistakes. Such things may seem harmless as they do not cause immediate syntax errors - but they can potentially lead to subtle program logic errors, unexpected behavior, wrong results and issues later on making them especially tricky to detect and fix. Over time, this makes the codebase more fragile and harder to maintain and extend.
 
@@ -437,7 +437,7 @@ The IDE understands the underlying structure of the code, which makes these comp
 
 
 
-## Use existing packages from known developers
+## Use Existing Packages From Known Developers
 
 Our script currently reads the data line-by-line from the JSON data file and uses custom code to manipulate the data. Variables of interest are stored in lists but there are more suitable data structures (e.g. dataframes or tibbles) to store data in our case.
 
@@ -520,7 +520,7 @@ print(p)
 
 We have committed the code and the environment changes together since they are related and form one logical unit of change.
 
-## Use comments to explain functionality
+## Use Comments to Explain Functionality
 
 Commenting is a very useful practice to help convey the context of the code. It can be helpful as a reminder for your future self or your collaborators as to why code is written in a certain way, how it is achieving a specific task, or the real-world implications of your code.
 
@@ -655,7 +655,7 @@ Commit changes:
  $ git push origin main
 ```
 
-## Separate units of functionality
+## Separate Units of Functionality
 
 Functions are a fundamental concept in writing software and are one of the core ways you can organize your code to improve its readability. A function is an isolated section of code that performs a single, *specific* task that can be simple or complex.
 
@@ -848,7 +848,7 @@ plot_cumulative_time_in_space(eva_tbl, graph_file)
 
 :::
 
-## Use `roxygen2` comments to document functions
+## Use `roxygen2` Comments to Document Functions
 
 Now that we’ve written a few functions, it’s time to document them so we can quickly remember what they do. That way, someone reading this code later can understand the intent without having to reverse-engineer the implementation.
 
@@ -1171,7 +1171,7 @@ At this point, the code in your local software project's directory should be as
 
 :::
 
-## Further reading
+## Further Reading
 
 We recommend the following resources for some additional reading on the topic of this episode:
 

episodes/05-code-structure.md

@@ -1,5 +1,5 @@
 ---
-title: Code structure
+title: Code Structure
 teaching: 60
 exercises: 30
 ---
@@ -52,7 +52,7 @@ $ source venv_spacewalks/Scripts/activate # Windows
 
 :::
 
-## Functions for modular and reusable code 
+## Functions for Modular and Reusable Code 
 
 As we have already seen in the previous episode - functions play a key role in creating modular and reusable code.
 After extracting units of functionality into separate functions, the main part of our code became much simpler and more readable, only containing the invocation of the following three functions:
@@ -211,7 +211,7 @@ print("--END--")
 
 Even though our code became a bit longer than previously, it is more readable and new functions we added can potentially be reused elsewhere too.
 
-## Creating a main function
+## Creating a Main Function
 
 Now we also want to move the main functionality into a main function.
 There is a common code structure (pattern) for writing a main function in Python:
@@ -405,7 +405,7 @@ if __name__ == "__main__":
     main(input_file, output_file, graph_file)
 ```
 
-## Command-line interface to code
+## Command-Line Interface to Code
 
 A common way to structure code is to have a command-line interface to allow the passing of various parameters. 
 For example, we can pass the input data file to be read and the output file 
@@ -576,7 +576,7 @@ Remember to commit our changes.
 (venv_spacewalks) $ git commit -m "Add command line functionality to script"
 ```
 
-## Directory structure for software projects
+## Directory Structure for Software Projects
 
 Expanding on the code structure theme, following conventions on consistent and informative directory structure 
 for your projects will ensure people will immediately know where to find things within your project, especially helpful 
@@ -823,7 +823,7 @@ At this point, the code in your local software project's directory should be as
 
 ::::::
 
-## Further reading
+## Further Reading
 
 We recommend the following resources for some additional reading on the topic of this episode:
 

episodes/06-code-correctness.md

@@ -1,5 +1,5 @@
 ---
-title: "Code correctness & testing"
+title: "Code Correctness & Testing"
 teaching: 60
 exercises: 30
 ---
@@ -55,7 +55,7 @@ $ source venv_spacewalks/Scripts/activate # Windows
 
 :::
 
-## Why use software testing?
+## Why Use Software Testing?
 
 Including testing in our research workflow helps us to produce **better software** and conduct **better research**:
 
@@ -74,7 +74,7 @@ Including testing in our research workflow helps us to produce **better software
   step-by-step approach that we can apply to verify that our code is
   correct.
 
-## Types of software tests
+## Types of Software Tests
 
 There are many different types of software tests, including:
 
@@ -125,7 +125,7 @@ Fill in the blanks in the sentences below:
 :::
 :::
 
-## Informal testing
+## Informal Testing
 
 How should we test our code? One approach is to copy/paste the code or a function into a Python terminal - *different from a command line terminal* - which allows you to interact with the Python interpreter more directly.
 From the Python terminal we can then run one function or a piece of code at a time and check that they behave as expected.
@@ -224,7 +224,7 @@ However, there are limitations to this approach:
 :::
 ::::::
 
-## Formal testing
+## Formal Testing
 
 We can overcome some of these limitations by formalising our testing process. 
 A formal approach to testing our code is to write dedicated test functions to check it. 
@@ -397,7 +397,7 @@ To run our remaining tests we would have to manually comment out our failing tes
 As our code base grows, testing in this way becomes cumbersome and error-prone. 
 These limitations can be overcome by automating our tests using a **testing framework**.
 
-## Testing frameworks
+## Testing Frameworks
 
 Testing frameworks can automatically find all the tests in our code base, run all of them (so we do not have to invoke 
 them explicitly or, even worse, forget to invoke them), and present the test results as a readable summary.
@@ -644,7 +644,7 @@ As a result, running the function raises a `NameError` rather than returning a c
 :::
 :::
 
-## Test suite design
+## Test Suite Design
 
 We now have the tools in place to automatically run tests. 
 However, that alone is not enough to properly test code.
@@ -1187,7 +1187,7 @@ if __name__ == "__main__":
 
 There is an [optional exercise](../learners/test-suite-exercise.md) to implement additional tests and practice writing tests some more.
 
-## Continuous Integration for automated testing
+## Continuous Integration for Automated Testing
 
 Continuous Integration (CI) services provide the infrastructure to automatically run every test function in 
 the test code suite every time changes are pushed to a remote repository.
@@ -1220,7 +1220,7 @@ https://github.com/carpentries-incubator/bbrs-software-project/tree/07-software-
 
 ::::::
 
-## Further reading
+## Further Reading
 
 We recommend the following resources for some additional reading on the
 topic of this episode: