From 32f8fd9c6ff42aa88dbfb6db561e947173fc940c Mon Sep 17 00:00:00 2001 From: Neha Moopen Date: Mon, 28 Nov 2022 22:27:02 +0100 Subject: [PATCH] added code for r users to download good-enough-project-template --- 04-project-management.Rmd | 11 + docs/2-acknowledgements.html | 176 ++++--- docs/3-preparation.html | 180 +++---- docs/3.1-data-andor-code.html | 337 ++++++++++++ docs/3.2-terminal.html | 339 ++++++++++++ docs/3.3-git.html | 497 ++++++++++++++++++ docs/3.4-final-test.html | 401 ++++++++++++++ docs/4-introduction.html | 184 +++---- docs/4.1-schedule.html | 431 +++++++++++++++ docs/4.2-course-materials.html | 354 +++++++++++++ docs/404.html | 336 ++++++++++++ docs/5-project-management.html | 184 +++---- docs/5.1-project-setup.html | 365 +++++++++++++ docs/5.2-version-control.html | 362 +++++++++++++ docs/5.3-publication-licensing.html | 357 +++++++++++++ docs/6-code-quality.html | 184 +++---- docs/6.1-readability.html | 358 +++++++++++++ docs/6.2-reusability.html | 357 +++++++++++++ docs/6.3-robustness.html | 373 +++++++++++++ docs/7-documentation.html | 184 +++---- docs/7.1-comments-and-docstrings.html | 360 +++++++++++++ docs/7.2-the-readme-page.html | 365 +++++++++++++ docs/8-accessibility-reproducibility.html | 184 +++---- docs/8.1-dependencies.html | 357 +++++++++++++ docs/8.2-binder.html | 361 +++++++++++++ docs/8.3-archiving.html | 356 +++++++++++++ docs/9-references.html | 180 +++---- docs/index.html | 178 +++---- .../anchor-sections-hash.css | 2 + .../anchor-sections-1.1.0/anchor-sections.css | 4 + .../anchor-sections-1.1.0/anchor-sections.js | 11 + .../gitbook-2.6.7/css/plugin-bookdown.css | 6 + docs/libs/gitbook-2.6.7/js/plugin-search.js | 93 +++- docs/libs/jquery-3.6.0/jquery-3.6.0.min.js | 2 + docs/libs/vembedr-0.1.5/css/vembedr.css | 14 + docs/search_index.json | 2 +- 36 files changed, 7613 insertions(+), 832 deletions(-) create mode 100644 docs/3.1-data-andor-code.html create mode 100644 docs/3.2-terminal.html create mode 100644 docs/3.3-git.html create mode 100644 docs/3.4-final-test.html create mode 100644 docs/4.1-schedule.html create mode 100644 docs/4.2-course-materials.html create mode 100644 docs/404.html create mode 100644 docs/5.1-project-setup.html create mode 100644 docs/5.2-version-control.html create mode 100644 docs/5.3-publication-licensing.html create mode 100644 docs/6.1-readability.html create mode 100644 docs/6.2-reusability.html create mode 100644 docs/6.3-robustness.html create mode 100644 docs/7.1-comments-and-docstrings.html create mode 100644 docs/7.2-the-readme-page.html create mode 100644 docs/8.1-dependencies.html create mode 100644 docs/8.2-binder.html create mode 100644 docs/8.3-archiving.html create mode 100644 docs/libs/anchor-sections-1.1.0/anchor-sections-hash.css create mode 100644 docs/libs/anchor-sections-1.1.0/anchor-sections.css create mode 100644 docs/libs/anchor-sections-1.1.0/anchor-sections.js create mode 100644 docs/libs/jquery-3.6.0/jquery-3.6.0.min.js create mode 100644 docs/libs/vembedr-0.1.5/css/vembedr.css diff --git a/04-project-management.Rmd b/04-project-management.Rmd index decc91b..96633f7 100644 --- a/04-project-management.Rmd +++ b/04-project-management.Rmd @@ -40,6 +40,17 @@ _NB: You can check the slides for more detail._ * Use the instructions [on this slide](../slides/slides_project-setup.html#6) to clone a template repository of a project folder structure to your computer. Remember to also follow the instructions on removing the .git folder that is downloaded. +* R users can also use the following code: + +```{r eval=FALSE, echo=TRUE} + +# install.packages("usethis") + +usethis::use_zip("https://github.com/bvreede/good-enough-project-template/archive/refs/heads/master.zip", + destdir = getwd()) +``` + + * Place your project files in the right folder. * Adjust paths in your code, and be sure to use relative paths! diff --git a/docs/2-acknowledgements.html b/docs/2-acknowledgements.html index 9fce185..7f00299 100644 --- a/docs/2-acknowledgements.html +++ b/docs/2-acknowledgements.html @@ -6,12 +6,11 @@ 2 Acknowledgements | Best Practices in Writing Reproducible Code - + - @@ -24,7 +23,7 @@ - + @@ -33,16 +32,15 @@ - - - - - - - - - - + + + + + + + + + @@ -51,16 +49,17 @@ - - - - + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

3.1 Data and/or Code

+
    +

  • Bring some code! We will be working on improving your workflow, so it is nice to have material to work with. Consider that we will need something that is small enough that you can edit/play with it during the workshop, but also comprehensive so that someone else may be able to reproduce your project on their computer (i.e.: it is nice if there is an output for someone to see at the end!). NB: If you will not have code to work on, you can still take advantage of the workshop, but please contact your instructor before the course.

    • +

  • Optional: if your data cannot be public, fake it! We will be exchanging repositories at the end of the day, and try to reproduce each other’s work. This can be problematic if your data cannot be shared. If the structure of the data can be put online, you could simulate the dataset (including covariates, so simple models have similar outcomes) using a package like fakeR, which simulates fake data within the same structure. Or check out or this post on conjurer.

    • +
+
+
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/3.2-terminal.html b/docs/3.2-terminal.html new file mode 100644 index 0000000..908275c --- /dev/null +++ b/docs/3.2-terminal.html @@ -0,0 +1,339 @@ + + + + + + + 3.2 Terminal | Best Practices in Writing Reproducible Code + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

3.2 Terminal

+

Some of the work we will do will take place over the command line, for which you will need a terminal.

+
    +

  • Mac OS and Linux have easily accessible terminals (the program is usually called Terminal, so that’s easy).

    • +

  • Windows’ default terminal (Command Prompt) uses different commands, so we do not recommend it for this workshop. Instead, as you install Git (next sub-section), you can get the Git Bash terminal with your installation.

    • +
+

If you have no experience with the terminal at all, we recommend practicing with it for some basic folder navigation to start. This 8.5 minute video is a good introduction.

+
+
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/3.3-git.html b/docs/3.3-git.html new file mode 100644 index 0000000..f8e8295 --- /dev/null +++ b/docs/3.3-git.html @@ -0,0 +1,497 @@ + + + + + + + 3.3 Git | Best Practices in Writing Reproducible Code + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

3.3 Git

+
+

3.3.1 Coding Platforms

+

Sign up for a GitHub, GitLab, or BitBucket account.

+

Please note our workshop materials and demonstrations will be in GitHub, but most things we will show you have easy parallels on the other networks, so you can likely just follow along.

+
+
+

3.3.2 Install Git

+

You first want to double-check if Git is already installed on your computer.

+

Go to your terminal and enter which git to request the path to your Git executable:

+
which git
+## /usr/local/bin/git
+

and then git --version to see its version:

+
git --version
+## git version 2.31.1
+

If the terminal returns a path and version, that means you have Git and you can skip this installation step! That being said, you might want to ensure your Git is the latest version.

+

If you don’t see a path and version, but something like git: command not found - then you definitely need to continue with installation. Follow the the instructions relevant to your operating system.

+
    +

  • Windows: Go to gitforwindows.org. Make sure you include Git Bash in your installation!

    • +

  • Mac: Go to git-scm.com and install the the latest version available.

    • +

  • Linux: Go the Linux-specific page of git-scm.com. There are commands specific to various package managers.

    • +
+
+
+

3.3.3 git config

+

Now that installation is done, it’s time to introduce yourself to Git!

+

Go to your terminal and type the following, one after the other:

+
git config --global user.name 'Your Name'
+git config --global user.email 'yourname@example.com'
+git config --global --list
+

Important: make sure you use the email associated with your GitHub account!

+

The first two commands won’t return any information, the last one will confirm if Git received your introduction alright. That is, your name and email will be returned.

+
+
+

3.3.4 Set up SSH keys

+

SSH keys provide a more secure way of logging onto servers than relying on passwords alone. It’s similar to how two-factor authentication provides an extra layer of security over regular passwords/passcodes.

+

There are number of steps involved in this setup, but we’re going to summarize it here - so you don’t get lost:

+
    +
  1. Check for existing SSH keys.
    2. +
  2. Generate new SSH keys.
    3. +
  3. Add private key to the ssh-agent.
    4. +
  4. Add public key to your GitHub/GitLab/BitBucket account.
    5. +
  5. Test your SSH connection.
    6. +
+

These instructions are borrowed heavily from Happy Git with R, GitHub’s user guides, and NLeSC Small Scale Initiative - Introduction to GitVersion Control with Git.

+
+

3.3.4.1 Check for existing SSH keys.

+

Go to your terminal and type the following command to list existing SSH keys:

+
ls -al ~/.ssh
+

If you have key pairs already, they may look like the following:

+
    +

  • id_rsa.pub (public key) & id_rsa (private key)

    • +

  • id_ecdsa.pub (public key) & id_ecdsa (private key)

    • +

  • id_ed25519.pub (public key) & id_ed25519 (private key)

    • +
+

If you’re happy to stick with your existing keys, then you can jump to step 3 which is about adding the private key to the ssh-agent.

+
+
+

3.3.4.2 Generate new SSH keys

+

Go to your terminal and type the following command, substituting “USEFUL-LABEL” with something like your GitHub username and/or your device.

+
ssh-keygen -t ed25519 -C "USEFUL-LABEL"
+

Accept the proposal to save the key in the default file location. Just press Enter here:

+
> Enter a file in which to save the key (/Users/you/.ssh/id_ed25519): [Press enter]
+

If you’re new to setting up SSH keys, then skip the option to enter a passphrase. It’s a best practice, but you can come back to it after the workshop. Just leave the passphrase option empty and press Enter:

+
> Enter passphrase (empty for no passphrase):
+

Here’s an example of how it should have played out, if everything went smoothly:

+
jenny@2015-mbp ~ $ ssh-keygen -t rsa -b 4096 -C "USEFUL-COMMENT"
+Generating public/private rsa key pair.
+Enter file in which to save the key (/Users/jenny/.ssh/id_rsa):     
+Enter passphrase (empty for no passphrase): 
+Enter same passphrase again: 
+Your identification has been saved in /Users/jenny/.ssh/id_rsa.
+Your public key has been saved in /Users/jenny/.ssh/id_rsa.pub.
+The key fingerprint is:
+SHA256:ki0TNHm8qIvpH7/c0qQmdv2xxhYHCwlpn3+rVhKVeDo USEFUL-COMMENT
+The key's randomart image is:
++---[RSA 4096]----+
+|      o+   . .   |
+|     .=.o . +    |
+|     ..= + +     |
+|      .+* E      |
+|     .= So =     |
+|    .  +. = +    |
+|   o.. = ..* .   |
+|  o ++=.o =o.    |
+| ..o.++o.=+.     |
++----[SHA256]-----+
+
+
+

3.3.4.3 Add private key to the ssh-agent

+

While the actions are similar, the specific commands for this step vary between operating systems. Therefore, we’ll link you to the relevant GitHub guide for this step: Generating a new SSH key and adding it to the ssh-agent

+

Make sure you’re following the instructions for the right operating system and then jump to the sub-section on Adding your SSH key to the ssh-agent.

+

Effectively, what this step does is to ‘activate’ your private key.

+
+
+

3.3.4.4 Add public key to your GitHub/GitLab/BitBucket account

+
    +

  • Open your public SSH key (the file ending with .pub) in a text editor and copy the whole key. Make sure to avoid copying any newlines or whitespace.

    • +

  • On GitHub, click on your profile picture and go to Settings -> SSH & GPG keys.

    • +

  • Click on New SSH key.

    • +

  • Paste your public key in the box and give it an informative label, maybe the same as the “USEFUL-LABEL” you used when generating the keys.

    • +
+
+
+

3.3.4.5 Test your SSH connection

+

Open your terminal and type in the following command:

+
ssh -T git@github.com
+

You may see a warning which includes an RSA key fingerprint. Make sure this fingerprint matches that of GitHub’s, you can double-check that here: GitHub’s SSH key fingerprints

+

If the fingerprint matches, type yes if you were asked if wanted to continue connecting.

+

If all goes well, you’ll see something like the following:

+
> Hi username! You've successfully authenticated, but GitHub does not provide shell access.
+

Make sure it’s your username that terminal returns!

+
+
+

3.3.4.6 Troubleshooting

+

GitHub has a whole page on Troubleshooting SSH. If you run into issues, you should double-check if your errors are covered here.

+

We have collected some commonly seen errors:

+
    +

  • You have made the key pair and copied the public key to GitHub, but SSH will not connect. +Are you sure that you turned on the agent?

    • +

  • You recieve an error message like “Error: Permission denied (publickey)”. Follow the link to GitHub guide on this issue.

    • +

  • Did you remember to add the public key to GitHub?

    • +

  • Did you set up SSH keys, but connect to your GitHub using HTTPS?

    +

    You can check your remote URL by going to terminal and typing:

    • +
+
git remote -v
+

An SSH remote should like this:

+
git@github.com:USERNAME/REPOSITORY.git
+

Whereas a HTTPS remote will look this:

+
https://github.com/USERNAME/REPOSITORY.git
+

You can switch between the SSH & HTTPS remotes for your repo using the following command: git remote set-url +See GitHub’s user guide on Changing a remote repository’s URL

+
    +

  • Did you remember to configure Mac OS Sierra or High Sierra to persistently store your passphrase in the keychain?

    • +

  • You can run commands like ssh-keygen or eval, but they do not return any information, not even an error message. +If you are on Windows and have have Citrix workspace installed, there is a known bug where Citrix interferes with the SSH key generation process.

    +
      +
    • Uninstall Citrix workspace
      • +
    • Restart your computer
      • +
    • Restart the SSH key generation tutorial.
      • +
    • If, after setting up SSH key pairs, you want to reinstall Citrix, be sure to do so via the Microsoft store.
      • +
    • +
+
+
+
+

3.3.5 If SSH fails, HTTPS!

+

If you find yourself despairing over the SSH key setup, don’t worry! HTTPS is a sufficient back-up!

+

You will need to create a Personal Access Token from Github to identify yourself over the HTTPS protocol:

+
    +

  • Click on your profile icon (top right side of your screen)

    • +

  • Go to Settings -> Developer Settings -> Personal Access Tokens

    • +

  • Create a new token, and select the ‘repo’ scope for its access.

    • +

  • Copy the token and use it when Git asks for a password when connecting to Github.

    • +
+

See the Github website for more info.

+
+

3.3.5.1 Troubleshooting Personal Access Tokens

+

You can only view a Personal Access Token once, and they are impossible to type. However, you can store it in your system so it can be used to authenticate you without your having to re-enter it.

+
    +

  • If you are on Windows, go to the terminal and type git config --global credential.helper wincred

    • +

  • If you are on a different system, and git does not cache your credentials automatically, here is a Github tutorial to fix that.

    • +
+
+
+
+
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/3.4-final-test.html b/docs/3.4-final-test.html new file mode 100644 index 0000000..6352c37 --- /dev/null +++ b/docs/3.4-final-test.html @@ -0,0 +1,401 @@ + + + + + + + 3.4 Final Test! | Best Practices in Writing Reproducible Code + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

3.4 Final Test!

+

If you’ve set up your SSH keys alright, we can try going ahead and seeing whether you can push and pull from GitHub successfully. If you’re going the HTTPS route due to issues, no worries! Just make sure your switch out the SSH clone URL for the HTTPS clone URL.

+

This is something we’ll do during the workshop as well, but trying it out beforehand reduces chances of errors while the course is ongoing.

+

The sequence of steps is as follows:

+
    +

  1. Create a test repository on GitHub.

    2. +

  2. Clone the test repository.

    3. +

  3. Make local changes.

    4. +

  4. Push the local changes to GitHub. This is where the magic happens (or not)!

    5. +

  5. If all went well, you can refresh the webpage with your GitHub repository and you’ll see your local changes.

    6. +

  6. Make changes online.

    7. +

  7. Pull the online changes to your computer, so your local repository is up to date.

    8. +

  8. If all went well, then your online changes are available locally as well. It also means you’re fully set up with Git & GitHub!

    9. +
+
+

3.4.0.1 Create a test repository on GitHub

+
    +

  • Log into GitHub.

    • +

  • Click the green New (repository) button.

    • +

  • You can name your repository as testrepo.

    • +

  • Make sure it’s a Public repository.

    • +

  • Click YES, when asked if you want to initialize the repository with a README.

    • +

  • Click the green Create repository button.

    • +

  • Copy the SSH URL for cloning via the green Clone or Download button.

    • +
+
+
+

3.4.0.2 Clone the test repository

+

Go to your terminal and type the following command, substituting the SSH clone URL you copied in the previous step after git clone:

+
git clone git@github.com:username/testrepo.git
+

This should create a local copy of your repository as a folder with files contained within.

+
+
+

3.4.0.3 Make local changes

+

Navigate to the folder of your repository and open the README file. Make an edit, such as This is a line I’m adding offline to my local copy. Save the file and close it.

+
+
+

3.4.0.4 Push the local changes to GitHub

+

Go to your terminal and type the following command(s):

+
git add .
+

This adds all changed files to a ‘staging area’.

+
git commit -m "insert-understandable-message-here"
+

Now you’re officially ‘committing’ the changes you made. You want to add a understandable commit message so you have a clear record of your changes.

+
git push
+

With this command, you push the local changes and commit message to your repository online.

+

This is where errors can pop up if the SSH set-up didn’t go as smoothly as expected. Troubleshoot the error messages the best you can!

+

If everything went smoothly, you can refresh the webpage with GitHub repository and you should see that your changes have been synced.

+
+
+

3.4.0.5 Make changes online

+

Now we want to go the other way around, open your README file on GitHub and make an edit online. You can do this by:

+
    +

  • Clicking on the README file and the pencil icon to open edit mode.

    • +

  • Add a sentence to your README like This is a line I’m adding from GitHub.com.

    • +

  • When saving, you’ll have to provide a meaningful commit message again.

    • +
+
+
+

3.4.0.6 Pull from GitHub

+

Now go to your terminal and type the following command:

+
git pull
+

If all goes well, you’ll see some activity in the terminal which suggests the changes are being downloaded. You can then check out your README file and see whether your online change has been synced.

+
+
+

3.4.0.7 Wrap-Up

+

Did it work? You did it! You pushed and pulled from GitHub successfully, woohoo!

+ +
+
+ +
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/4-introduction.html b/docs/4-introduction.html index 7dbb4a2..2e1582e 100644 --- a/docs/4-introduction.html +++ b/docs/4-introduction.html @@ -6,12 +6,11 @@ 4 Introduction | Best Practices in Writing Reproducible Code - + - @@ -24,25 +23,24 @@ - + - - - - - - - - - - - - + + + + + + + + + + + @@ -51,16 +49,17 @@ - - - - + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

4.1 Schedule

+
+

4.1.1 Pre-Workshop Installation Support

+

Neha will be available the entire afternoon prior to Day 1 of the workshop to help with any installation issues, especially Git.

+
+
+

4.1.2 Day 1

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TimeActivity
8:00Installation Support
9:00Welcome & introduction (slides)
9:30Project setup & version control with git
10:45Questions & discussion
11:00Break
11:15Code quality
12:45Questions & discussion
13:00End
+
+
+

4.1.3 Day 2

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TimeActivity
9:00Code quality discussion
9:15Documentation
10:45Questions & discussion
11:00Break
11:15Accessibility & reproducibility
12:15Reproduction of projects
13:00End
+
+
+
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/4.2-course-materials.html b/docs/4.2-course-materials.html new file mode 100644 index 0000000..c0e9db8 --- /dev/null +++ b/docs/4.2-course-materials.html @@ -0,0 +1,354 @@ + + + + + + + 4.2 Course Materials | Best Practices in Writing Reproducible Code + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+ + +
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/404.html b/docs/404.html new file mode 100644 index 0000000..8c943b7 --- /dev/null +++ b/docs/404.html @@ -0,0 +1,336 @@ + + + + + + + Page not found | Best Practices in Writing Reproducible Code + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

Page not found

+

The page you requested cannot be found (perhaps it was moved or renamed).

+

You may want to try searching to find the page's new location, or use +the table of contents to find the page you are looking for.

+
+
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/5-project-management.html b/docs/5-project-management.html index 2f0e8ac..c555757 100644 --- a/docs/5-project-management.html +++ b/docs/5-project-management.html @@ -6,12 +6,11 @@ 5 Project Management | Best Practices in Writing Reproducible Code - + - @@ -24,25 +23,24 @@ - + - - - - - - - - - - - - + + + + + + + + + + + @@ -51,16 +49,17 @@ - - - - + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

5.1 Project setup

+
+

5.1.1 Video

+
+
+ +
+
+
+
+

5.1.2 Slides

+ +

Slides

+
+
+

5.1.3 Exercises

+

NB: You can check the slides for more detail.

+
    +

  • The video and slides ask you to use a tool called cookiecutter to install a project structure in your system. However, we’re going to skip that and go straight to the ‘backup’ instructions! It will be more efficient for us during the online version of the course.

    • +

  • Use the instructions on this slide to clone a template repository of a project folder structure to your computer. Remember to also follow the instructions on removing the .git folder that is downloaded.

    • +

  • R users can also use the following code:

    • +
+
# install.packages("usethis")
+
+usethis::use_zip("https://github.com/bvreede/good-enough-project-template/archive/refs/heads/master.zip",
+                 destdir = getwd())
+
    +

  • Place your project files in the right folder.

    • +

  • Adjust paths in your code, and be sure to use relative paths!

    • +

  • Does your code run in the new folder structure?

    • +
+
+
+
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/5.2-version-control.html b/docs/5.2-version-control.html new file mode 100644 index 0000000..ef5387d --- /dev/null +++ b/docs/5.2-version-control.html @@ -0,0 +1,362 @@ + + + + + + + 5.2 Version control | Best Practices in Writing Reproducible Code + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

5.2 Version control

+
+

5.2.1 Video

+
+
+ +
+
+
+
+

5.2.2 Slides

+ +

Slides

+
+
+

5.2.3 Exercise

+
    +

  • Follow the steps in the video (or on these slides) to turn your folder into a git repository.

    • +

  • Make a remote version of your project on GitHub!

    • +

  • Please note: are there (temporary) files you do not wish to track? +Add them to the .gitignore file. +Consider a .gitignore template for your language: examples on this github repo.

    • +

  • Can you use Git and push to Github from your IDE?

    • +

  • Experiment with editing and committing on GitHub itself. You can then ‘download’ your code to your local repository using git pull.

    • +

  • Optional: What happens if you edit the same file online and locally, and try to push/pull? +(Hint: this often causes a ‘merge conflict’, which is no fun to experience. +Going through it today means we can assist you if necessary!)

    • +
+
+
+
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/5.3-publication-licensing.html b/docs/5.3-publication-licensing.html new file mode 100644 index 0000000..43d3f2f --- /dev/null +++ b/docs/5.3-publication-licensing.html @@ -0,0 +1,357 @@ + + + + + + + 5.3 Publication & licensing | Best Practices in Writing Reproducible Code + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

5.3 Publication & licensing

+
+

5.3.1 Video

+
+
+ +
+
+
+
+

5.3.2 Slides

+ +

Slides

+
+
+

5.3.3 Exercise

+
    +

  • Check the license in your project

    • +

  • Take a look at other license options via choosealicense.com.

    • +

  • Do you want to change your license? Go into your Github and change the LICENSE.md file. Don’t forget to pull your remote changes!

    • +
+ +
+
+ +
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/6-code-quality.html b/docs/6-code-quality.html index b57d76b..147b85f 100644 --- a/docs/6-code-quality.html +++ b/docs/6-code-quality.html @@ -6,12 +6,11 @@ 6 Code Quality | Best Practices in Writing Reproducible Code - + - @@ -24,25 +23,24 @@ - + - - - - - - - - - - - - + + + + + + + + + + + @@ -51,16 +49,17 @@ - - - - + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

6.1 Readability

+
+

6.1.1 Video

+
+
+ +
+
+
+
+

6.1.2 Slides

+ +

Slides

+
+
+

6.1.3 Exercise

+
    +

  • Use a linter to run through your code and identify style issues.

    • +

  • Edit your code to improve the style compatibility, based on the feedback from your linter. +If you work with Python, consider applying autopep8 to automatically fix linting issues.

    • +

  • For the R users: a course participant found styler, which may do the same for R!

    • +

  • If you find code that is hard to read, or variable names that need adjusting, make a note to work on it. +(Again, use #TODO or another consistent label!)

    • +
+
+
+
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/6.2-reusability.html b/docs/6.2-reusability.html new file mode 100644 index 0000000..2685d6d --- /dev/null +++ b/docs/6.2-reusability.html @@ -0,0 +1,357 @@ + + + + + + + 6.2 Reusability | Best Practices in Writing Reproducible Code + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

6.2 Reusability

+
+

6.2.1 Video

+
+
+ +
+
+
+
+

6.2.2 Slides

+ +

Slides

+
+
+

6.2.3 Exercise

+

Visualize your code.

+
    +

  • Use yellow for scripted code, purple for structured code (for-loops, functions, etc.), and green for comments

    • +

  • Use any tool that works for you (powerpoint, word, paint, or good old pencils and paper)

    • +

  • During this exercise, try to identify yellow parts that can be structured and turned into (a) function(s). Label them, or rewrite them if you have time.

    • +

  • Make a screenshot or picture of your visualization, and share it on Teams!

    • +
+
+
+
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/6.3-robustness.html b/docs/6.3-robustness.html new file mode 100644 index 0000000..09d78e7 --- /dev/null +++ b/docs/6.3-robustness.html @@ -0,0 +1,373 @@ + + + + + + + 6.3 Robustness | Best Practices in Writing Reproducible Code + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

6.3 Robustness

+
+

6.3.1 Video

+
+
+ +
+
+
+
+

6.3.2 Slides

+ +

Slides

+
+
+

6.3.3 Exercise

+
    +

  • Identify assumptions in your code

    +
      +

    • What assumptions/expectations exist on your data or (user) input?

      • +

    • What assumptions/expectations exist on the input of (a) function(s)?

      • +
    • +
+

Based on the assumptions/expectations you were able to identify, work on increasing the robustness of your code. +Choose one:

+
    +

  • Make the input/data assumptions explicit

    +
      +

    • Option 1: Explicitly state assumptions on data or input in your README.md.

      • +

    • Option 2: Write a piece of code that tests the validity of data/input, and reports an error if the expectations are not met.

      • +
    • +

  • Test the input for a function. Modify the code inside your function to:

    +
      +

    • check the value of the arguments passed to your function using if/else statements;

      • +

    • raise an error in case an argument is out of the range of acceptable values.

      • +
    • +
+ +
+
+ +
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/7-documentation.html b/docs/7-documentation.html index 7805a45..814c9b6 100644 --- a/docs/7-documentation.html +++ b/docs/7-documentation.html @@ -6,12 +6,11 @@ 7 Documentation | Best Practices in Writing Reproducible Code - + - @@ -24,25 +23,24 @@ - + - - - - - - - - - - - - + + + + + + + + + + + @@ -51,16 +49,17 @@ - - - - + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

7.1 Comments and docstrings

+
+

7.1.1 Video

+
+
+ +
+
+
+
+

7.1.2 Slides

+ +

Slides

+
+
+

7.1.3 Exercise

+
    +

  • Add a docstring to a function, preferably the last function you worked on (so it’s fresh in your memory). +Keep in mind: what does my user need to know when they are working with this function?

    • +

  • Grab a limited chunk of code to work on, and look at the existing comments. +Can you replace a ‘how’ comment with a ‘why’ comment? +Think: what is the purpose of this code? Rather than: this is how this code works.

    • +

  • Are there elements in your chunk that are currently without comments that would benefit from clarification? +Try to comment on the thought behind the code rather than simply translating its process in English.

    • +

  • Can you delete superfluous comments or zombie code?

    • +
+
+
+
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/7.2-the-readme-page.html b/docs/7.2-the-readme-page.html new file mode 100644 index 0000000..642f95d --- /dev/null +++ b/docs/7.2-the-readme-page.html @@ -0,0 +1,365 @@ + + + + + + + 7.2 The README page | Best Practices in Writing Reproducible Code + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

7.2 The README page

+
+

7.2.1 Video

+
+
+ +
+
+
+
+

7.2.2 Slides

+ +

Slides

+
+
+

7.2.3 Exercise

+

Edit your README file. +Take your time. This is important!

+

Make sure to include the following information:

+
    +

  • What does your project do?

    • +

  • How does the user access your project? (E.g. download, or clone with git clone…)

    • +

  • How does the user call the main script(s) that should be executed?

    • +

  • And perhaps any other elements you are inspired to add (check out the examples!)

    • +
+

Do you want to truly understand the importance of decent installation information? +Read this experience by Elisabeth Bik, trying to install image forensics software. +Look at the README of the software, and see what you can learn.

+

NB: We will have another chance to take a look at dependencies and prerequisites, but if you have opportunity to add these here: please do!

+ +
+
+ +
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/8-accessibility-reproducibility.html b/docs/8-accessibility-reproducibility.html index c3f514e..f81496e 100644 --- a/docs/8-accessibility-reproducibility.html +++ b/docs/8-accessibility-reproducibility.html @@ -6,12 +6,11 @@ 8 Accessibility & Reproducibility | Best Practices in Writing Reproducible Code - + - @@ -24,25 +23,24 @@ - + - - - - - - - - - - - - + + + + + + + + + + + @@ -51,16 +49,17 @@ - - - - + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

8.1 Dependencies

+
+

8.1.1 Video

+
+
+ +
+
+
+
+

8.1.2 Slides

+ +

Slides

+
+
+

8.1.3 Exercise

+

Address dependencies and language versions in your README.

+
    +

  • What version of your coding language is required?

    • +

  • Which packages does a user need to install before running your project? +What versions?

    • +

  • Can you provide their installation instructions?

    • +
+
+
+
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/8.2-binder.html b/docs/8.2-binder.html new file mode 100644 index 0000000..39f1605 --- /dev/null +++ b/docs/8.2-binder.html @@ -0,0 +1,361 @@ + + + + + + + 8.2 Binder | Best Practices in Writing Reproducible Code + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

8.2 Binder

+
+

8.2.1 Video

+
+
+ +
+
+
+
+

8.2.2 Exercise (optional)

+

For R

+
    +

  • Generate a file called runtime.txt, either in the root of your project, or in a (hidden) folder called .binder/.

    • +

  • Write in the file: r-2020-10-02 – or specify the R version with r-3.6-2020-10-02.

    • +

  • Write a file called install.R, in .binder/ or in root, and use it to write install code for your packages, e.g.:

    +
    install.packages("ggplot2")
+install.packages("dplyr")
    • +

  • Binderise your project by following the instructions via mybinder.org

    • +
+

For Python

+

Binder automatically loads Python 3.6.

+
    +

  • Add dependencies to your binder in the requirements.txt file like this:

    +
    numpy==1.14.5
+pandas==1.1.2
    • +

  • Binderise your project by following the instructions via mybinder.org

    • +
+
+
+
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/8.3-archiving.html b/docs/8.3-archiving.html new file mode 100644 index 0000000..0d397df --- /dev/null +++ b/docs/8.3-archiving.html @@ -0,0 +1,356 @@ + + + + + + + 8.3 Archiving | Best Practices in Writing Reproducible Code + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+
+ + +
+
+ +
+
+

8.3 Archiving

+
+

8.3.1 Video

+
+
+ +
+
+
+
+

8.3.2 Slides

+ +

Slides

+
+
+

8.3.3 Exercise (optional)

+ + +
+
+ +
+ +
+
+
+ + +
+
+ + + + + + + + + + + + + diff --git a/docs/9-references.html b/docs/9-references.html index 93d6054..9db2bc5 100644 --- a/docs/9-references.html +++ b/docs/9-references.html @@ -6,12 +6,11 @@ 9 References | Best Practices in Writing Reproducible Code - + - @@ -24,25 +23,24 @@ - + - - - - - - - - - - - + + + + + + + + + + @@ -51,16 +49,17 @@ - - - - + + + +