tavareshugo / 2018-04-16-cambridge

Data Carpentry Course Cambridge 16-17 Apr 2018

workshop-template

This repository is Software Carpentry and Data Carpentry's template for creating websites for workshops.

1. Please do not fork this repository directly on GitHub. Instead, please use GitHub's importer following the instructions below to copy this workshop-template repository and customize it for your workshop.

2. Please do your work in your repository's gh-pages branch, since that is what is automatically published as a website by GitHub.

3. Once you are done, please also let us know the workshop URL. If this is a self-organised workshop, you should also fill in the self-organized workshop form (if you have not already done so), so we can keep track of all workshops. We build the list of workshops on our websites from the data included in your index.md page. We can only do that if you customize that page correctly and let us know the workshop URL.

If you run into problems, or have ideas about how to make this process simpler, please get in touch. The pages on customizing your website, the FAQ, and the design notes have more detail on what we do and why. And please note: if you are teaching Git, please create a separate repository for your learners to practice in.

Creating a Repository

1. Log in to GitHub. (If you do not have an account, you can quickly create one for free.) You must be logged in for the remaining steps to work.

2. Go to GitHub's importer.

3. Paste the url of this repo as the old repository to clone: https://github.com/swcarpentry/workshop-template.

4. Select the owner for your new repository. (This will probably be you, but may instead be an organization you belong to.)

5. Choose a name for your workshop website repository. This name should have the form YYYY-MM-DD-site, e.g., 2016-12-01-miskatonic, where YYYY-MM-DD is the start date of the workshop.

6. Make sure the repository is public.

7. At this point, you should have a page like this:

   

   You can now click "Begin Import". When the process is done, you will receive a message like "Importing complete! Your new repository gvwilson/2016-12-01-miskatonic is ready." and you can go to the new repository by clicking on the name.

Note: some people have had intermittent errors during the import process, possibly because of the network timing out. If you experience a problem, please re-try; if the problem persists, please get in touch.

Customizing Your Website

1. Go into your newly-created repository, which will be at https://github.com/your_username/YYYY-MM-DD-site. For example, if your username is gvwilson, the repository's URL will be https://github.com/gvwilson/2016-12-01-miskatonic.

2. Ensure you are on the gh-pages branch by clicking on the branch under the drop down in the menu bar (see the note below):

   

3. Edit the header of index.md to customize the list of instructors, workshop venue, etc. You can do this in the browser by clicking on it in the file view on GitHub and then selecting the pencil icon in the menu bar:

   

   Editing hints are embedded in index.md, and full instructions are in the customization instructions.

4. Edit _config.yml to customize certain site-wide variables, such as: carpentry (to tell us which carpentry workshop this is), title (overall title for all pages), repository (so that URLs resolve correctly both locally and on GitHub), workshop_repo (the URL of the workshop repository on GitHub) and workshop_site (the repository's GitHub Pages URL).

   Editing hints are embedded in _config.yml, and full instructions are in the customization instructions.

5. Edit the schedule.html file to edit the schedule for your upcoming workshop. This file is located in the _includes directory, make sure to choose the one from the appropriate dc (Data Carpentry workshop), lc (Library Carpentry), or sc (Software Carpentry) subdirectory.

6. Alternatively, if you are already familiar with Git, you can clone the repository to your desktop, edit index.md, _config.yml, and schedule.html there, and push your changes back to the repository.

   git clone -b gh-pages https://github.com/your_username/YYYY-MM-DD-site
   

   You should specify -b gh-pages to checkout the gh-pages branch because the imported repository doesn't have a master branch.

   In order to view your changes once you are done editing, you must push to your GitHub repository:

   git push origin gh-pages
   

7. When you are done editing, go to the GitHub Pages URL for your workshop and preview your changes. In the example above, this is https://gvwilson.github.io/2016-12-01-miskatonic. The finished page should look something like this.

8. Optional: you can now change the README.md file in your website's repository, which contains these instructions, so that it contains a short description of your workshop and a link to the workshop website.

Note: please do all of your work in your repository's gh-pages branch, since GitHub automatically publishes that as a website.

Note: this template includes some files and directories that most workshops do not need, but which provide a standard place to put extra content if desired. See the design notes for more information about these.

Further instructions are available in the customization instructions. This FAQ includes a few extra tips (additions are always welcome) and these notes on the background and design of this template may help as well.

Checking Your Changes

If you want to preview your changes on your own machine before publishing them on GitHub, you can do so as described below.

1. Install the software described below. This may require some work, so feel free to preview by pushing to the website.

2. Run the command

   make serve
   

   and go to http://0.0.0.0:4000 to preview your site. You can also run this command by typing make serve (assuming you have Make installed).

3. Run the command

   make workshop-check
   

   to check for a few common errors in your workshop's home page. (You must have Python 3 installed to do this.)

(Optional) Linking to Your Page

At the top of your repository on GitHub you'll see

No description or website provided. — Edit

Click 'Edit' and add:

1. A very brief description of your workshop in the "Description" box (e.g., "Miskatonic University workshop, Dec. 2016")

2. The URL for your workshop in the "Website" box (e.g., https://gvwilson.github.io/2016-12-01-miskatonic)

This will help people find your website if they come to your repository's home page.

Creating Extra Pages

In rare cases, you may want to add extra pages to your workshop website. You can do this by putting either Markdown or HTML pages in the website's root directory and styling them according to the instructions give in the lesson template. If you do this, you must also edit _config.yml to set these three values:

1. carpentry is either "dc" (for Data Carpentry), "swc" (for Software Carpentry), or "lc" (for Library Carpentry). This determines which logos are loaded.

2. title is the title of your workshop (typically the venue and date).

3. email is the contact email address for your workshop, e.g., [email protected].

Note: carpentry and email duplicate information that's in index.md, but there is no way to avoid this without requiring people to edit both files in the usual case where no extra pages are created.

Installing Software

If you want to set up Jekyll so that you can preview changes on your own machine before pushing them to GitHub, you must install the software described below. (Note: Julian Thilo has written instructions for installing Jekyll on Windows.)

1. Ruby. This is included with Linux and macOS; the simplest option on Windows is to use RubyInstaller. You can test your installation by running ruby --version. For more information, see the Ruby installation guidelines.

2. RubyGems (the package manager for Ruby). You can test your installation by running gem --version.

3. Jekyll. You can install this by running gem install jekyll.

Setting Up a Separate Repository for Learners

If you are teaching Git, you should create a separate repository for learners to use in that lesson. You should not have them use the workshop website repository because:

• your workshop website repository contains many files that most learners don't need to see during the lesson, and

• you probably don't want to accidentally merge a damaging pull request from a novice Git user into your workshop's website while you are using it to teach.

You can call this repository whatever you like, and add whatever content you need to it.

Getting and Giving Help

We are committed to offering a pleasant setup experience for our learners and organizers. If you find bugs in our instructions, or would like to suggest improvements, please file an issue or mail us.

2018-04-16-cambridge's Issues

tips for lesson content delivery

General suggestions for lesson content delivery

Like we discussed, due to time constraints some bits of the materials we tend to
not demonstrate "interactively", but rather show and explain them using the
materials page, or if time really is tight, just mention where they exist in the
materials for those interested.

A lot of it is about improvising, depending on the feedback of learners we might
need to go through something again, or go slower, or faster... Different trainers
also go slower, or faster.

Spreadsheets

I'll do this lesson, so you can see how it goes...

OpenRefine

We usually cover the whole lesson.

The only thing we want to ensure is that most (if not all) of it is finished in the
morning, so we have plenty of time for R. So, as time runs out, we might not do all of
the proposed challenges.

R lessons

Before we start

We usually explain why R is useful for reproducibility, then open R studio and
present the interface.

Then we discuss a bit about the working directory (and use
the chance to emphasise how it's good to have a tidy directory structure) and
set the project to the course materials folder.

And that's pretty much it. The materials have a lot of extra details, e.g. about
help, function arguments, etc.
We cover these things as we're going through the introduction.

---

Intro to R

Here we pretty much follow the materials. At the very beginning we put some code
directly on the console. Then we explain actually the code is "lost", so it's best
to write code in the script. Then describe the "Ctrl + Enter" shortcut to run
code from the script to the console.

TIP: when presenting the round() function, do not use a number with .5,
otherwise we will descend into hell of how R rounds numbers. E.g. round(3.15, 1)
and round(3.151, 1) return different results (at least on my machine)

---

Starting with data

We follow the materials closely at the beginning.

The section on factors people usually struggle... they don't see the point of
why we're talking about it. So we tend to simplify it a bit and mention that
it is really useful for changing the order of characters in graphs for example,
from the alphabetical default.

We don't tend to do challenge 17.

And we usually skip the formatting dates,
unless there is time at the end of the dplyr section (usually there isn't).
This is one of those sections that we show it's in the materials for those interested
in working with dates.

---

Manipulating data frames

We used to cover all of this, until they recently introduced "spread" and "gather".
We'll have to see if there's time to cover this.

Again, depending on how the time is progressing, we might shorten some of the
challenges a bit.

It's essential to do the last section on exporting data, since that is used for
the plotting.

---

Visualising data

We cover all of this up to (and including) the faceting.

After that we usually don't do the customization interactively (it's a lot of
typing!) and instead show the course page with the further examples of how
everything can be customized.

If there is time, people can play around with customising their plots, and we can
go around the room answering peoples queries. If someone asks a question about
how to customise something, we might demonstrate it interactively to everyone.

Often I think it's useful when people ask for "how do you change X in the plot?"
to show that web-search is often the most efficient.

---

R and SQL

We're usually really running out of time when we get here (and people are tired
too).

So, we give a very brief (non-technical) explanation of what a database is, basically
thinking of it like a collection of tables that have some relationship between them.
For example, medical data about children, which would be on a table, and medical data on
their parents, which would be on another table. These two tables could be related to
each other based on the parent's names.

Then explain there is a specific language, SQL, used for interacting with databases.
We will not cover this specific language in the course, but instead use dplyr
functions that can do this for us.

I would then prioritize covering steps up to (including) "laziness" (perhaps
skipping, or just briefly mention, the SQL translation).

The other two sections, "Complex database queries" and "Creating db" might have to
just be shown from the course page itself. The cartoon with the joins is worth
showing, because it is well illustrated.

check course survey link

Need to check with Gabriella if the post-course survey link is correct (they usually use a custom one for their training).

Github page not displaying markdown correctly

Hugo - the Day 1 & Day 2 areas Markdown code does not get rendered.
If edit on web then preview changes show rendered fine.
Cloned repo onto my mac and looked at index.md with MacDown and it displayed fine.
Think it must be jeckyll-realted i.e. when it generates the static page?