{"id":23317461,"url":"https://github.com/ccamara/course-starter-r","last_synced_at":"2025-04-07T04:29:43.612Z","repository":{"id":149791973,"uuid":"436199469","full_name":"ccamara/course-starter-r","owner":"ccamara","description":null,"archived":false,"fork":false,"pushed_at":"2021-12-09T11:47:05.000Z","size":262,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-13T08:52:45.187Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ccamara.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-08T10:04:42.000Z","updated_at":"2021-12-09T11:47:07.000Z","dependencies_parsed_at":"2023-06-02T15:45:35.944Z","dependency_job_id":null,"html_url":"https://github.com/ccamara/course-starter-r","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccamara%2Fcourse-starter-r","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccamara%2Fcourse-starter-r/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccamara%2Fcourse-starter-r/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccamara%2Fcourse-starter-r/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ccamara","download_url":"https://codeload.github.com/ccamara/course-starter-r/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247593252,"owners_count":20963674,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-20T16:30:23.352Z","updated_at":"2025-04-07T04:29:43.595Z","avatar_url":"https://github.com/ccamara.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Online course starter: R\n\nThis is a starter repo based on the\n[course framework](https://github.com/ines/spacy-course) I developed for my\n[spaCy course](https://course.spacy.io). The front-end is powered by\n[Gatsby](http://gatsbyjs.org/) and [Reveal.js](https://revealjs.com) and the\nback-end code execution uses [Binder](https://mybinder.org) 💖\n\n_This repo could use some better code examples. Also, if you have experience\nwith R, feel free to suggest improvements to the\n[test logic and template](#adding-tests). It all works as expected, but there\nmight be ways to make it more elegant._\n\n[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/ccamara/courser-starter-r)\n\n[![](https://user-images.githubusercontent.com/13643239/56341448-68fe9380-61b5-11e9-816f-5c71ae71b94f.png)](https://course-starter-r.netlify.com)\n\n## ✅ Quickstart\n\n1. [Import](https://github.com/new/import) this repo, install it and make sure\n   the app is running locally.\n2. Customize the [`meta.json`](meta.json) and\n   [`binder/install.R`](binder/install.R).\n3. Build a [Binder](https://mybinder.org) from the `binder` branch of this repo.\n4. Add content (chapters, exercises and slides) and optionally add separate\n   content license.\n5. Customize the UI theme in [`theme.sass`](theme.sass) and update images in\n   [`static`](static) as needed.\n6. Deploy the app, e.g. to [Netlify](https://netlify.com).\n\n### Running the app\n\nTo start the local development server, install [Gatsby](https://gatsbyjs.org)\nand then all other dependencies. This should serve up the app on\n`localhost:8000`.\n\n```bash\nnpm install -g gatsby-cli  # Install Gatsby globally\nnpm install                # Install dependencies\nnpm run dev                # Run the development server\n```\n\n## 💡Introduction\n\n\u003e This section was contributed by [@laderast](https://github.com/laderast).\n\u003e Thanks! ✨\n\n### How does this repo work?\n\nThe course repository works with two components: Gatsby (front-end), and Binder\n(back-end). We'll go over both of these to understand how it works as a whole.\n\n### What is Gatsby?\n\n[Gatsby](https://www.gatsbyjs.org/) is a JavaScript/react.js based web page\nbuilding framework, like Hugo, or Jekyll. The nice thing about it being\nJavaScript is that JavaScript widgets that you build are tightly integrated.\n\nYou can think of Gatsby as being the client side of the lesson framework. All\ncode, solutions, tests, and chapter.md files are handled by Gatsby.\n\n### What is Binder?\n\n[Binder](https://gke.mybinder.org/) is a way of building Docker containers from\nrepositories that can be launched on a remote server/cluster (such as\nmybinder.org). This Docker container can be based on a Dockerfile, or R image.\nThe thing about Binder is that the containers are ephemeral - if they're not\nused, they're deleted off the Binder servers. The main applications of Binder\nare:\n\n1. Reproducible Research (shareable notebooks) and\n2. Education (shareable notebooks)\n\nYou can think of Binder as being the server side of the lesson framework. It\nneeds the instructions on how to build the docker container (which is in the\n`binder/` folder), and the data you want to use for the lessons (in the `data/`\nfolder).\n\nThe only thing you need to get started with R and Binder is a repo that has a\n`runtime.txt` file, or a Dockerfile. The rest, such as datafiles, are optional,\nbut are usually contained in a Binder repository.\n\n### How does Gatsby work with Binder?\n\n![code-execution](https://user-images.githubusercontent.com/3315629/60834090-b49d5980-a174-11e9-9d69-966084ba97b9.png)\n\nInes was super clever and designed a JavaScript plugin for Gatsby called\n[Juniper](https://github.com/ines/juniper) to handle communication to and from\nthe Binder container using Jupyter kernels. That's how code gets executed on the\nBinder container, and how code output (such as terminal messages, images, etc)\nare received from the Binder container.\n\n## Branches of this repo\n\n![Course-repo](https://user-images.githubusercontent.com/3315629/60834054-a18a8980-a174-11e9-930d-c61df5faba7b.png)\n\nThere are two branches of this repo, which are used for different tasks:\n\n- **master** - this is what the course is served out of via netlify:\n  http://r-bootcamp.netlify.com - any changes to exercises in this branch will\n  show up on the netlify page. The netlify page uses a JavaScript framework\n  called Gatsby to build the pages. Gatsby submits code to binder and receives\n  the output. It also handles the code checking. The parts of the repo that are\n  handled by Gatsby include:\n\n1. exercises/solutions/tests\n2. chapter.md files\n3. slides (using reveal.js)\n\n- **binder** - this is what the Binder image is built from. The reason they're\n  different is that binder forces a Docker container rebuild when a branch is\n  updated. So, if we served our container out of master, it would rebuild\n  everytime we modified a `chapter.md` or an exercise. If you need to add\n  packages, you will add them to the `binder/install.R` for this branch, and if\n  you need to add datasets, you can add them to the `data/` folder. The parts of\n  the repo handled by Binder include:\n\n1. datasets in data/ folder (the container needs access to these to load data\n   from submitted code)\n2. installation instructions in the binder/ folder for installing dependencies\n\nI would say that the easiest thing to do is to occasionally merge `master` into\n`binder` when you need to update the data:\n\nNote that rebuilding the binder container can take a little bit of time (usually\non the order of 5 or 10 minutes or so), since it is installing/compiling\n`tidyverse` for the container. You can always check the build status of the\ncontainer by clicking the badge below and looking at the log.\n\nYou can view the binder container here:\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/ines/course-starter-r/binder)\nor at: https://mybinder.org/v2/gh/ines/course-starter-r/binder\n\n- you can launch an Rstudio instance to test the container by using the \"new\"\n  tab in the top right corner, and selecting 'Rstudio'. This is super helpful if\n  you want to test if code will work in the binder container.\n\n### Adding Packages\n\nIf you need to add packages, add the appropriate `install.packages()` statement\ninto `binder/install.R`. When you do, check that the container was built\nproperly by clicking the binder link above.\n\nCurrently, `tidyverse` is installed in the binder container.\n\n### `data/` folder\n\nIf you want to access datasets in the data folder, you can always refer to this\nfolder as `data/`. For example, to use `data/pets.csv`:\n\n```\npets \u003c- read.csv(\"data/pets.csv\")\n```\n\nRemember, if you need to add a dataset to the repo, it needs to be done in the\n`binder` branch into the `data/` folder.\n\n### Using `decampr` to transfer your DataCamp repository\n\nIf you would like to transfer your courses from DataCamp, there is a package\nmade for that: [`decampr`](http://github.com/laderast/decampr). It will scan\nyour repository and attempt to extract exercise instructions, quizzes, exercise\ncode, and solutions and write them to the appropriate directory for your\nproject. For more info, please check out the `decampr` repo:\nhttp://github.com/laderast/decampr\n\n## 🎨 Customization\n\nThe app separates its source and content – so you usually shouldn't have to dig\ninto the JavaScript source to change things. The following points of\ncustomization are available:\n\n| Location             | Description                                                                                                                           |\n| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| `meta.json`          | General config settings, title, description etc.                                                                                      |\n| `theme.sass`         | Color theme.                                                                                                                          |\n| `binder/install.R`   | Packages to install.                                                                                                                  |\n| `binder/runtime.txt` | YYYY-MM-DD snapshot at MRAN that will be used for installing libraries. [See here](https://github.com/binder-examples/r) for details. |\n| `chapters`           | The chapters, one Markdown file per chapter.                                                                                          |\n| `slides`             | The slides, one Markdown file per slide deck.                                                                                         |\n| `static`             | Static assets like images, will be copied to the root.                                                                                |\n\n### `meta.json`\n\nThe following meta settings are available. **Note that you have to re-start\nGatsby to see the changes if you're editing it while the server is running.**\n\n| Setting              | Description                                                                                                                                |\n| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| `courseId`           | Unique ID of the course. Will be used when saving completed exercises to the browser's local storage.                                      |\n| `title`              | The title of the course.                                                                                                                   |\n| `slogan`             | Course slogan, displayed in the page title on the front page.                                                                              |\n| `description`        | Course description. Used for site meta and in footer.                                                                                      |\n| `bio`                | Author bio. Used in the footer.                                                                                                            |\n| `siteUrl`            | URL of the deployed site (without trailing slash).                                                                                         |\n| `twitter`            | Author twitter handle, used in Twitter cards meta.                                                                                         |\n| `fonts`              | [Google Fonts](https://fonts.google.com) to load. Should be the font part of the URL in the embed string, e.g. `Lato:400,400i,700,700i`.   |\n| `testTemplate`       | Template used to validate the answers. `${solution}` will be replaced with the user code and `${test}` with the contents of the test file. |\n| `juniper.repo`       | Repo to build on Binder in `user/repo` format. Usually the same as this repo.                                                              |\n| `juniper.branch`     | Branch to build. Ideally not `master`, so the image is not rebuilt every time you push.                                                    |\n| `juniper.lang`       | Code language for syntax highlighting.                                                                                                     |\n| `juniper.kernelType` | The name of the kernel to use.                                                                                                             |\n| `juniper.debug`      | Logs additional debugging info to the console.                                                                                             |\n| `showProfileImage`   | Whether to show the profile image in the footer. If `true`, a file `static/profile.jpg` needs to be available.                             |\n| `footerLinks`        | List of objects with `\"text\"` and `\"url\"` to display as links in the footer.                                                               |\n| `theme`              | Currently only used for the progressive web app, e.g. as the theme color on mobile. For the UI theme, edit `theme.sass`.                   |\n\n### Static assets\n\nAll files added to `/static` will become available at the root of the deployed\nsite. So `/static/image.jpg` can be referenced in your course as `/image.jpg`.\nThe following assets need to be available and can be customized:\n\n| File              | Description                                              |\n| ----------------- | -------------------------------------------------------- |\n| `icon.png`        | Custom [favicon](https://en.wikipedia.org/wiki/Favicon). |\n| `logo.svg`        | The course logo.                                         |\n| `profile.jpg`     | Photo or profile image.                                  |\n| `social.jpg`      | Social image, displayed in Twitter and Facebook cards.   |\n| `icon_check.svg`  | \"Check\" icon displayed on \"Mark as completed\" button.    |\n| `icon_slides.svg` | Icon displayed in the corner of a slides exercise.       |\n\n## ✏️ Content\n\n### File formats\n\n#### Chapters\n\nChapters are placed in [`/chapters`](/chapters) and are Markdown files\nconsisting of `\u003cexercise\u003e` components. They'll be turned into pages, e.g.\n`/chapter1`. In their frontmatter block at the top of the file, they need to\nspecify `type: chapter`, as well as the following meta:\n\n```yaml\n---\ntitle: The chapter title\ndescription: The chapter description\nprev: /chapter1 # exact path to previous chapter or null to not show a link\nnext: /chapter3 # exact path to next chapter or null to not show a link\nid: 2 # unique identifier for chapter\ntype: chapter # important: this creates a standalone page from the chapter\n---\n\n```\n\n#### Slides\n\nSlides are placed in [`/slides`](/slides) and are markdown files consisting of\nslide content, separated by `---`. They need to specify the following\nfrontmatter block at the top of the file:\n\n```yaml\n---\ntype: slides\n---\n\n```\n\nThe **first and last slide** use a special layout and will display the headline\nin the center of the slide. **Speaker notes** (in this case, the script) can be\nadded at the end of a slide, prefixed by `Notes:`. They'll then be shown on the\nright next to the slides. Here's an example slides file:\n\n```markdown\n---\ntype: slides\n---\n\n# Processing pipelines\n\nNotes: This is a slide deck about processing pipelines.\n\n---\n\n# Next slide\n\n- Some bullet points here\n- And another bullet point\n\n\u003cimg src=\"/image.jpg\" alt=\"An image located in /static\" /\u003e\n```\n\n### Custom Elements\n\nWhen using custom elements, make sure to place a newline between the\nopening/closing tags and the children. Otherwise, Markdown content may not\nrender correctly.\n\n#### `\u003cexercise\u003e`\n\nContainer of a single exercise.\n\n| Argument     | Type            | Description                                                    |\n| ------------ | --------------- | -------------------------------------------------------------- |\n| `id`         | number / string | Unique exercise ID within chapter.                             |\n| `title`      | string          | Exercise title.                                                |\n| `type`       | string          | Optional type. `\"slides\"` makes container wider and adds icon. |\n| **children** | -               | The contents of the exercise.                                  |\n\n```markdown\n\u003cexercise id=\"1\" title=\"Introduction to spaCy\"\u003e\n\nContent goes here...\n\n\u003c/exercise\u003e\n```\n\n#### `\u003ccodeblock\u003e`\n\n| Argument     | Type            | Description                                                                                  |\n| ------------ | --------------- | -------------------------------------------------------------------------------------------- |\n| `id`         | number / string | Unique identifier of the code exercise.                                                      |\n| `source`     | string          | Name of the source file (without file extension). Defaults to `exc_${id}` if not set.        |\n| `solution`   | string          | Name of the solution file (without file extension). Defaults to `solution_${id}` if not set. |\n| `test`       | string          | Name of the test file (without file extension). Defaults to `test_${id}` if not set.         |\n| **children** | string          | Optional hints displayed when the user clicks \"Show hints\".                                  |\n\n```markdown\n\u003ccodeblock id=\"02_03\"\u003e\n\nThis is a hint!\n\n\u003c/codeblock\u003e\n```\n\n#### `\u003cslides\u003e`\n\nContainer to display slides interactively using Reveal.js and a Markdown file.\n\n| Argument | Type   | Description                                   |\n| -------- | ------ | --------------------------------------------- |\n| `source` | string | Name of slides file (without file extension). |\n\n```markdown\n\u003cslides source=\"chapter1_01_introduction-to-spacy\"\u003e\n\u003c/slides\u003e\n```\n\n#### `\u003cchoice\u003e`\n\nContainer for multiple-choice question.\n\n| Argument     | Type            | Description                                                                                  |\n| ------------ | --------------- | -------------------------------------------------------------------------------------------- |\n| `id`         | string / number | Optional unique ID. Can be used if more than one choice question is present in one exercise. |\n| **children** | nodes           | Only `\u003copt\u003e` components for the options.                                                     |\n\n```markdown\n\u003cchoice\u003e\n\n\u003copt text=\"Option one\"\u003eYou have selected option one! This is not good.\u003c/opt\u003e\n\u003copt text=\"Option two\" correct=\"true\"\u003eYay! \u003c/opt\u003e\n\n\u003c/choice\u003e\n```\n\n#### `\u003copt\u003e`\n\nA multiple-choice option.\n\n| Argument     | Type   | Description                                                                                    |\n| ------------ | ------ | ---------------------------------------------------------------------------------------------- |\n| `text`       | string | The option text to be displayed. Supports inline HTML.                                         |\n| `correct`    | string | `\"true\"` if the option is the correct answer.                                                  |\n| **children** | string | The text to be displayed if the option is selected (explaining why it's correct or incorrect). |\n\n### Setting up Binder\n\nThe [`install.R`](binder/install.R) in the repository defines the packages that\nare installed when building it with Binder. You can specify the binder settings\nlike repo, branch and kernel type in the `\"juniper\"` section of the `meta.json`.\nI'd recommend running the very first build via the interface on the\n[Binder website](https://mybinder.org), as this gives you a detailed build log\nand feedback on whether everything worked as expected. Enter your repository\nURL, click \"launch\" and wait for it to install the dependencies and build the\nimage.\n\n![Binder](https://user-images.githubusercontent.com/13643239/39412757-a518d416-4c21-11e8-9dad-8b4cc14737bc.png)\n\n### Adding tests\n\nTo validate the code when the user hits \"Submit\", we're currently using a\nslightly hacky trick. Since the R code is sent back to the kernel as a string,\nwe can manipulate it and add tests – for example, exercise `exc_01_02_01.R` will\nbe validated using `test_01_02_01.R` (if available). The user code and test are\ncombined using a string template. At the moment, the `testTemplate` in the\n`meta.json` looks like this:\n\n```r\nsuccess \u003c- function(text) {\n    cat(paste(\"\\033[32m\", text, \"\\033[0m\", sep = \"\"))\n}\n\n.solution \u003c- \"${solutionEscaped}\"\n\n${solution}\n\n${test}\ntryCatch({\n    test()\n}, error = function(e) {\n    cat(paste(\"\\033[31m\", e[1], \"\\033[0m\", sep = \"\"))\n})\n```\n\nIf present, `${solution}` will be replaced with the string value of the\nsubmitted user code, and `${solutionEscaped}` with the code but with all `\"`\nreplaced by `\\\"`, so we can assign it to a variable as a string and check\nwhether the submission includes something. We also insert the regular solution,\nso we can actually run it and check the objects it creates. `${test}` is\nreplaced by the contents of the test file. The template also defines a `success`\nfunction, which prints a formatted green message and can be used in the tests.\nFinally, the `tryCatch` expression checks if the test function raises a `stop`\nand if so, it outputs the formatted error message. This also hides the full\nerror traceback (which can easily leak the correct answers).\n\nA test file could then look like this:\n\n```r\ntest \u003c- function() {\n    if (some_var != length(mtcars)) {\n        stop(\"Are you getting the correct length?\")\n    }\n    if (!grepl(\"print(mtcars$gear)\", .solution, fixed = TRUE)) {\n        stop(\"Are you printing the correct variable?\")\n    }\n    success(\"Well done!\")\n}\n```\n\nThe string answer is available as `.solution`, and the test also has access to\nthe solution code.\n\n---\n\nFor more details on how it all works behind the scenes, see\n[the original course repo](https://github.com/ines/spacy-course).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fccamara%2Fcourse-starter-r","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fccamara%2Fcourse-starter-r","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fccamara%2Fcourse-starter-r/lists"}