From 5b57cd646d5ea8630095a3704449faaf5de84a70 Mon Sep 17 00:00:00 2001 From: Marion <56403724+MarionBWeinzierl@users.noreply.github.com> Date: Tue, 10 Mar 2026 09:54:31 +0000 Subject: [PATCH 1/2] Create README.md from template --- README.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..79683f3 --- /dev/null +++ b/README.md @@ -0,0 +1,158 @@ + + +# Reproducibility in Computing + +This repository contains documentation, resources, and code for the `` session +designed and delivered by Jack Franklin and Marion Weinzierl of [ICCS](https://github.com/Cambridge-ICCS). +All materials, including slides and videos, are available such that individuals can cover the +course in their own time. + +A website for this workshop can be found at [\](https://iccs.cam.ac.uk/). + + +## Contents + +- [Learning Objectives](#learning-objectives) +- [Teaching material](#teaching-material) +- [Preparation and prerequisites](#preparation-and-prerequisites) +- [Installation and setup](#installation-and-setup) +- [License information](#license) +- [Contribution Guidelines and Support](#contribution-guidelines-and-support) + + +## Learning Objectives + +The key learning objective from this workshop is to +_Provide participants with \_. + +However, more specifically we will achieve this through to: + +* add more detailed objectives here, +* list any specific tools and techniques to be used, +* add any other sub-skills that will be covered, +* state what the outcome of the exercises/lecture will be. + +With regards to specific content we cover: + +* optionally, consider adding specific takeaway skills here +* for example, classification and regression with neural networks +* for example, how to add and commit files to git + +## Teaching Material + +### Slides +The slides for this workshop can be viewed here: [\](https://iccs.cam.ac.uk/) + +### Exercises +The exercises for the course can be found in the [exercises](exercises/) directory. +These take the form of \. + +### Worked Solutions +Worked solutions for all of the exercises can be found in the [worked solutions](worked-solutions/) directory. +These are for recapping after the course in case you missed anything, and contain example solutions. + + +## Preparation and prerequisites + +### Prerequisites + +To get the most out of the session we assume a basic understanding in a few areas and +for you to do some preparation in advance. +This expected knowledge is outlined below, along with resources for reading if you +are unfamiliar with any areas. + +- List here any key skills or knowledge that will be assumed of a user for the course, + - for example, basic calculus (integration and differentiation of a function) and matrix algebra +- Provide resources where appropriate, + - for example, Basic Neural Networks - we recommend the + [video series by 3Blue1Brown](https://www.3blue1brown.com/topics/neural-networks), at least chapters 1-3. +- Also include any programming expectations + - for example, the course will be taught in Python using [`numpy`](https://numpy.org/) + and [`pandas`](https://pandas.pydata.org/docs/getting_started/index.html). + - We assume users are familiar with the basics of Python. This includes: + - Basic mathematical operations + - Writing and running scripts/programs + - Writing and using functions +- If users need to clone the repository from GitHub/Lab using git also note this. + The [ICCS Summer School](https://www.youtube.com/watch?v=ZrwzK4CnJ3Q) should provide the necessary knowledge. + + +### Preparation + +List here anything that you expect participants to have on their computer in advance of the course in order to participate. +For example: + +- A text editor - e.g. vim/[neovim](https://neovim.io/), [gedit](https://gedit.en.softonic.com/), [vscode](https://code.visualstudio.com/), [sublimetext](https://www.sublimetext.com/) etc. to open and edit code files +- A terminal emulator - e.g. [GNOME Terminal](https://help.gnome.org/users/gnome-terminal/stable/), [wezterm](https://wezfurlong.org/wezterm/index.html), [Windows Terminal (windows only)](https://learn.microsoft.com/en-us/windows/terminal/), [iTerm (mac only)](https://iterm2.com/) +- A Python 3 installation + +Remember that participants will have a mix of Unix and Windows systems, and these should be covered +to ensure smooth delivery. Whilst Unix may be a presumed first choice, provide links to information +for setup on Windows, for example +[Windows' getting-started with python information](https://learn.microsoft.com/en-us/windows/python/beginners). + +If you require assistance or further information with any of these please reach out to +us before the session. + + +## Installation and setup + +Here you should include any instructions required for setup in preparation for the course. +These may be followed during the sesison as a walkthrough, but you should provide clear +instructions here for participants who take longer, needs additional help, or return to work +in their own time. +It is possible that many participants will not have done this in advance, +which you should be prepared for, but having these clear instructions means +that they can be pointed at this instead of holding up the session. + +Things to include are: + +- obtaining the code, for example instructions on how to clone the code locally: + ``` + git clone https://github.com/Cambridge-ICCS/.git + ``` + or fork the repository if this is required. +- Setup of a computing environment if appropriate. + e.g. in Python: + ``` + python3 -m venv my-workshop-venv + source my-workshop-venv/bin/activate + deactivate + ``` +- Installation of any dependencies + - Provide links and instructions + - If using Python, Julia, R etc. package these or use a `requirements.txt` file +- getting started instructions + - instructions on how to get started with the first exercises of the workshop. + for example, loading the first jupyter notebook, or building andnrunning the first exercise + +Note that you might consider providing a [Google Colab](https://colab.research.google.com/) +or binder implementation that can be run online in case participants have issues using the +code on their local machine. Instructions for this approach should also be provided. + + +## License + +The code materials in this project are licensed under the [MIT License](LICENSE). + + +## Contribution Guidelines and Support + +If you spot an issue with the materials please let us know by +[opening an issue](https://github.com/Cambridge-ICCS//issues) +here on GitHub clearly describing the problem. + +If you are able to fix an issue that you spot, or an +[existing open issue](https://github.com/Cambridge-ICCS//issues) +please get in touch by commenting on the issue thread. + +Contributions from the community are welcome. +To contribute back to the repository please first +[fork it](https://github.com/Cambridge-ICCS//fork), +make the necessary changes to fix the problem, and then open a pull request back to +this repository clearly describing the changes you have made. +We will then preform a review and merge once ready. + +If you would like support using these materials, adapting them to your needs, or +delivering them please get in touch either via GitHub or via +[ICCS](https://github.com/Cambridge-ICCS). From 8444b371f8bed3e21acac1997756fe489bd05451 Mon Sep 17 00:00:00 2001 From: Marion <56403724+MarionBWeinzierl@users.noreply.github.com> Date: Thu, 7 May 2026 10:29:49 +0100 Subject: [PATCH 2/2] Add more info to the readme and remove template text --- README.md | 110 ++++++++++++------------------------------------------ 1 file changed, 24 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index 79683f3..8c98f0a 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,12 @@ # Reproducibility in Computing -This repository contains documentation, resources, and code for the `` session +This repository contains documentation, resources, and code for the Reproducibility in Computing session designed and delivered by Jack Franklin and Marion Weinzierl of [ICCS](https://github.com/Cambridge-ICCS). All materials, including slides and videos, are available such that individuals can cover the course in their own time. -A website for this workshop can be found at [\](https://iccs.cam.ac.uk/). +A website for this workshop can be found at TODO: provide link. ## Contents @@ -22,113 +22,51 @@ A website for this workshop can be found at [\_. - -However, more specifically we will achieve this through to: - -* add more detailed objectives here, -* list any specific tools and techniques to be used, -* add any other sub-skills that will be covered, -* state what the outcome of the exercises/lecture will be. - -With regards to specific content we cover: - -* optionally, consider adding specific takeaway skills here -* for example, classification and regression with neural networks -* for example, how to add and commit files to git +The key learning objective from this workshop is raise the awareness of the importance of software reproducibility, and give the participants and understanding +and basic tools to improve it. ## Teaching Material ### Slides -The slides for this workshop can be viewed here: [\](https://iccs.cam.ac.uk/) +The slides for this workshop can be viewed here: TODO: provide link ### Exercises + +TODO + The exercises for the course can be found in the [exercises](exercises/) directory. These take the form of \. -### Worked Solutions +### Worked Solution +TODO + Worked solutions for all of the exercises can be found in the [worked solutions](worked-solutions/) directory. These are for recapping after the course in case you missed anything, and contain example solutions. +### Mini ReproHack + +The [Mini ReproHack repository](https://github.com/Cambridge-ICCS/MiniReproHack) can be used before, alongside or after this course, to learn hands-on what makes software reproducible. It contains instructions on how do a [reproducibility hackathon](www.reprohack.org) by trying to reproduce the results of real climate science papers. + ## Preparation and prerequisites ### Prerequisites -To get the most out of the session we assume a basic understanding in a few areas and -for you to do some preparation in advance. -This expected knowledge is outlined below, along with resources for reading if you -are unfamiliar with any areas. - -- List here any key skills or knowledge that will be assumed of a user for the course, - - for example, basic calculus (integration and differentiation of a function) and matrix algebra -- Provide resources where appropriate, - - for example, Basic Neural Networks - we recommend the - [video series by 3Blue1Brown](https://www.3blue1brown.com/topics/neural-networks), at least chapters 1-3. -- Also include any programming expectations - - for example, the course will be taught in Python using [`numpy`](https://numpy.org/) - and [`pandas`](https://pandas.pydata.org/docs/getting_started/index.html). - - We assume users are familiar with the basics of Python. This includes: - - Basic mathematical operations - - Writing and running scripts/programs - - Writing and using functions -- If users need to clone the repository from GitHub/Lab using git also note this. - The [ICCS Summer School](https://www.youtube.com/watch?v=ZrwzK4CnJ3Q) should provide the necessary knowledge. +To get the most out of the session we assume a basic understanding of the research process, programming in Python and research software. +The ICCS [RSE Skills workshop](https://github.com/jatkinson1000/rse-skills-workshop) gives you an overview of many of the topics mentioned in this course. -### Preparation - -List here anything that you expect participants to have on their computer in advance of the course in order to participate. -For example: -- A text editor - e.g. vim/[neovim](https://neovim.io/), [gedit](https://gedit.en.softonic.com/), [vscode](https://code.visualstudio.com/), [sublimetext](https://www.sublimetext.com/) etc. to open and edit code files -- A terminal emulator - e.g. [GNOME Terminal](https://help.gnome.org/users/gnome-terminal/stable/), [wezterm](https://wezfurlong.org/wezterm/index.html), [Windows Terminal (windows only)](https://learn.microsoft.com/en-us/windows/terminal/), [iTerm (mac only)](https://iterm2.com/) -- A Python 3 installation +### Preparation -Remember that participants will have a mix of Unix and Windows systems, and these should be covered -to ensure smooth delivery. Whilst Unix may be a presumed first choice, provide links to information -for setup on Windows, for example -[Windows' getting-started with python information](https://learn.microsoft.com/en-us/windows/python/beginners). +It is helpful but not mandatory to do a [mini ReproHack](#mini-reprohack) before the session to get a better understanding of the problem of software and research reproducibility. -If you require assistance or further information with any of these please reach out to -us before the session. +If you want to follow along with the exercises, basic Python coding skills and a Python development environment are required. ## Installation and setup -Here you should include any instructions required for setup in preparation for the course. -These may be followed during the sesison as a walkthrough, but you should provide clear -instructions here for participants who take longer, needs additional help, or return to work -in their own time. -It is possible that many participants will not have done this in advance, -which you should be prepared for, but having these clear instructions means -that they can be pointed at this instead of holding up the session. - -Things to include are: - -- obtaining the code, for example instructions on how to clone the code locally: - ``` - git clone https://github.com/Cambridge-ICCS/.git - ``` - or fork the repository if this is required. -- Setup of a computing environment if appropriate. - e.g. in Python: - ``` - python3 -m venv my-workshop-venv - source my-workshop-venv/bin/activate - deactivate - ``` -- Installation of any dependencies - - Provide links and instructions - - If using Python, Julia, R etc. package these or use a `requirements.txt` file -- getting started instructions - - instructions on how to get started with the first exercises of the workshop. - for example, loading the first jupyter notebook, or building andnrunning the first exercise - -Note that you might consider providing a [Google Colab](https://colab.research.google.com/) -or binder implementation that can be run online in case participants have issues using the -code on their local machine. Instructions for this approach should also be provided. +TODO ## License @@ -139,16 +77,16 @@ The code materials in this project are licensed under the [MIT License](LICENSE) ## Contribution Guidelines and Support If you spot an issue with the materials please let us know by -[opening an issue](https://github.com/Cambridge-ICCS//issues) +[opening an issue](https://github.com/Cambridge-ICCS/ReproducibilityInComputingCourse/issues) here on GitHub clearly describing the problem. If you are able to fix an issue that you spot, or an -[existing open issue](https://github.com/Cambridge-ICCS//issues) +[existing open issue](https://github.com/Cambridge-ICCS/ReproducibilityInComputingCourse/issues) please get in touch by commenting on the issue thread. Contributions from the community are welcome. To contribute back to the repository please first -[fork it](https://github.com/Cambridge-ICCS//fork), +[fork it](https://github.com/Cambridge-ICCS/ReproducibilityInComputingCourse/fork), make the necessary changes to fix the problem, and then open a pull request back to this repository clearly describing the changes you have made. We will then preform a review and merge once ready.