Include a one-paragraph summary of the course here.
+
+
+
+
+
+
+Learning Objectives
+
+
+
+
+
List course learning objectives here.
+
These describe concepts the learners should grasp and techniques they should be able to use by the end of the course.
+
You can think of these as completing the phrase “after this course, the participant should be able to…”
+
They are not supposed to be as detailed as the learning objectives of each section, but more high-level.
+
+
+
+
+
Target Audience
+
Brief description of target audience here.
+
+
+
Prerequisites
+
Detail any prerequisite skills needed to attend this course, with links to other relevant materials/courses if possible.
+
+
+
+
Exercises
+
Exercises in these materials are labelled according to their level of difficulty:
+
+
+
+
+
+
+
+
Level
+
Description
+
+
+
+
+
+
Exercises in level 1 are simpler and designed to get you familiar with the concepts and syntax covered in the course.
+
+
+
+
Exercises in level 2 combine different concepts together and apply it to a given task.
+
+
+
+
Exercises in level 3 require going beyond the concepts and syntax introduced to solve new problems.
+
+
+
+
+
+
+
Authors
+
+
About the authors:
+
+
Hugo Tavares
+Affiliation: Bioinformatics Training Facility, University of Cambridge
+Roles: writing - original draft; conceptualisation; coding
+
Martin van Rongen
+Affiliation: Bioinformatics Training Facility, University of Cambridge
+Roles: writing - review & editing; conceptualisation; coding
+
+
+
+
Citation
+
+
Please cite these materials if:
+
+
You adapted or used any of them in your own teaching.
+
These materials were useful for your research work. For example, you can cite us in the methods section of your paper: “We carried our analyses based on the recommendations in TODO.”.
+
+
You can cite these materials as:
+
+
TODO
+
+
Or in BibTeX format:
+
@Misc{,
+ author = {},
+ title = {},
+ month = {},
+ year = {},
+ url = {},
+ doi = {}
+}
+
+
+
Acknowledgements
+
+
+
List any other sources of materials that were used.
+
Or other people that may have advised during the material development (but are not authors).
Setup the required software to work on the materials.
+
Render and preview the course website locally.
+
Understand file/directory organisation for course materials and course files.
+
Remember how the navigation bar for materials is configured.
+
+
+
+
+
3.1 Introduction
+
In the sections below, we detail how files/directories are organised and how you can build the course website locally.
+Please only edit the files indicated in the instructions below. If you need help with the site configuration, please get in touch with us so we can revise our template.
+
If you just need a reminder, here is a TLDR-summary:
+
+
Clone the repository git clone <repo> (or run git pull to update your local clone).
+
Write materials in the markdown/notebook files in the materials/ directory. You can organise files in sub-directories (e.g. if they are part of a top-level section).
+
Edit the materials/_chapters.yml file to adjust the chapter layout.
+
Data files and/or scripts for the participants can be saved in course_files/{data,scripts}, respectively.
+
Build the site locally with quarto render. Open the file _site/index.html to view your changes.
+
Add, commit and push changes to the repository.
+If using executable documents (.Rmd/.qmd), make sure to also push the _freeze directory.
If you are developing materials using executable .qmd documents, it is recommended that you also install the extensions for your favourite IDE.
+
+
If you are developing materials using JupyterLab or Jupyter Notebooks, please install Jupytext.
+
+
Use the paired notebook feature to have synchronised .ipynb/.qmd files. Only .qmd files should be pushed to the repository (.ipynb files have been added to .gitignore).
+
+
Clone the course repository with git clone.
+
+
You’re now ready to start editing the course content.
+If you use either VS Code or RStudio, we’ve included *.code-workspace and *.Rproj files that you can use to open your project in those programs, respectively.
+
+
+
3.3 Build the Site
+
After a fresh clone, you may want to render the website locally first, to check that Quarto is setup correctly. You can also follow this workflow thereafter, every time you edit the materials.
+
+
Run quarto render to built the site.
+
The local copy of the site will be saved in the _site folder - open the index.html file to open the local copy of your site.
+
+
Note that the _site folder is local and not pushed to GitHub (it’s been added to .gitignore). The public site is built automatically by GitHub Actions every time a new push is made.
+
+
+
The website you are reading right now gives an example of how the course website will look like.
+
+
+
3.4 File Organisation
+
There are three things that you may edit:
+
+
Files in materials/ - this contains all the markdown/notebook files with the written materials (rendered on the site).
+
Files in course_files/ - this contains the files that participants will have on their training machines.
+
The index.md file - this is the homepage for the course.
+
+
+
3.4.1 Course Materials
+
The materials can be written as plain markdown .md, Rmarkdown .Rmd, Quarto markdown .qmd or Jupyter notebooks .ipynb. As mentioned in Setup, if you are using Jupyter Notebooks, make sure to use Jupytext to have paired .ipynb/.qmd files.
+
The following conventions should be used:
+
+
Please name your files with a two-digit numeric prefix. For example 01-first_lesson.md. Use relatively descriptive names for the files (unlike this example!).
+
Always include the following YAML header, at the top of each file:
+
---
+title: Lesson Title # keep this concise
+---
+
This title will appear both on the navigation bar on the left and as the title of the page. For example, the page you are viewing now has title: Course Rendering.
+
Organise your files into sub-directories, if they are all part of a logical section of materials. For example:
If you want to create slides using Quarto (documentation), please include them in a directory materials/<section_folder>/slides/.
+
+
+
+
3.4.2 Course Files & Data
+
When we run a workshop, participants will have all the necessary files for the course on the training computers.
+Generally, there are two types of files we may want to distribute to the participants:
+
+
scripts - any scripts for exercises or examples we want to run interactively during the course.
+
data - any data files (CSV, FASTQ, etc.) that are used.
+
+
These course files should be in a directory called course_files and specify all the paths in the materials relative to that. So, this will be the directory structure you end up with:
As you develop the materials and identify suitable data for the workshop, you can place it in the directory course_files/data/ (within that you can set any directory structure you want) and scripts for the participants in course_files/scripts (again you can organise this in any way you think is useful).
+
However, as a rule, only scripts should be pushed to the repository.
+Generally, we do not keep data in the repository, unless the files are text-based and/or small. We keep the data files on our Dropbox, so anyone can download them from a stable link (including with wget).
+
+
+
+
+
+
+Flexible course file structure
+
+
+
+
What’s given here is our recommended convention but, if you think your course files would benefit from a different file structure, please let us know.
+
Equally, if you don’t need to distribute scripts or data with your course (e.g. if your course is live-coded and data is downloaded from a public URL), then leave these directories empty as they are.
+
+
+
+
+
3.4.3 Homepage
+
The index.md file (at the root of the directory) will become the homepage for the course.
+This file can be edited towards the end of the material development, following the instructions given there. You can see an example on the homepage of this website.
+
+
+
+
3.5 Sidebar
+
The navigation bar on the left is configured from the materials/_chapters.yml file.
+Here is how the YAML file would look like for the example directory structure shown earlier:
The website can be built using the command quarto render. The website can be previewed from the file _site/index.html.
+
Materials can be written in markdown-based documents (.md, .Rmd, .qmd) or Python notebooks (.ipynb). For the latter the Jupytext package should be used to keep synchronised .qmd and .ipynb files.
+
Files for course materials files should be saved in the materials/ directory and named using a numeric prefix 00- for friendly ordering in the filesystem. Files can be further organised in sub-directories if they are logically grouped by sections.
+
Files to be shared with the participants (scripts and/or data) should be saved in course_files.
+Generally, only course_files/scripts are pushed to the repository, and we will keep a copy of the data files on Dropbox.
+
The navigation sidebar can be configured from the materials/_chapters.yml file.
Summarise the steps involved in contributing new materials and building a course website.
+
Remember the required parts to be included in each section of the materials.
+
Distinguish when to use callout boxes and the syntax used to create them.
+
Understand the convention used for writing exercises, referencing figures and citing works.
+
Remember the recommendations when using executable documents.
+
+
+
+
+
4.1 Introduction
+
This document includes information for writing materials for the Bioinformatics Training Facility, which is then built into a website using Quarto. We encourage you to use markdown-based documents (.md, .Rmd or .qmd), although Python Notebooks (.ipynb) are also supported1.
+
+
+
+
+
+
+Tip
+
+
+
+
One way to learn about the syntax used to develop materials is to look at the source file for this page.
+
+
+
To start, here is a brief list of syntax conventions we use:
+
+
Headings start at level 2 (##).
+
Exercises should be entitled using a level 3 (###) heading - see Exercises section for details.
There are several other markdown tricks that you can use (e.g. equations and mermaid diagrams). See the Quarto Markdown Basics documentation for a reminder of these features.
+
+
We give further details about other features below, but the essential workflow when working on the materials is:
+
+
Edit your markdown/notebook files in materials/.
+
Run quarto render to build the site (open _site/index.html to preview your website locally).
+
Add, commit and push the changes to the repository.
+
+
If you need a reminder of the technical setup for course development, go back to the Course Rendering page.
+
+
+
4.2 Callout Boxes
+
Quarto has several built-in callout boxes available. You can use these to highlight particular content. Note that the colour scheme for our callout boxes is simplified relative to the original Quarto template.
+
Here is an example of each box, with a short description of what you may want to use it for:
+
+
+
+
+
+
+Tip
+
+
+
+
This is a .callout-tip, which is used for learning objectives, key points and exercise answers (each of these is detailed below).
+
+
+
+
+
+
+
+
+Note
+
+
+
+
This is a .callout-note, which you can use to highlight “bonus” tips-and-tricks that complement your materials.
+
These can be thought of as non-essential parts of the materials, which may not be covered in a live workshop. The more muted colour of this box conveys that idea.
+
+
+
+
+
+
+
+
+Important
+
+
+
+
This is a .callout-important, which can be used to highlight important notes that complement the materials.
+
This can be thought of as a more essential idea/concept that is mentioned specifically during a live workshop.
+
+
+
+
+
+
+
+
+Warning
+
+
+
+
This is a .callout-warning, which can be used to highlight common “gotchas” such as unexpected behaviours of the software being used or common mistakes users can make.
+
+
+
+
+
+
+
+
+Caution
+
+
+
+
This is a .callout-caution, which at the moment is only used to highlight readers when materials are under development. You should rarely have to use these.
+
+
+
+
+
4.3 Learning Objectives
+
We advise that every lesson starts with a set of “Learning Objectives” included in a .callout-tip box:
+
::: {.callout-tip}
+## Learning Objectives
+
+- List skills and concepts that learners should grasp after this lesson.
+- See the box at the beggining of this document as an example.
+:::
+
By convention we tend to use an active tense. Bloom’s taxonomy may give you ideas of active verbs to use.
+
+
+
4.4 Key Points
+
Equally, we advise that every lesson ends with a level 2 section named “Summary” with a set of “Key Points”, which summarise the main concepts covered in the lesson:
+
::: {.callout-tip}
+## Key Points
+
+- List key concepts covered in the lesson.
+- See the bottom of this document as an example.
+
This can be thought of as a “cheatsheet” for that lesson, if the user just wanted to quickly remind themselves about the lesson content, they should be able to do so from this section.
+
+
+
4.5 Exercises
+
By convention, we make the exercises under a level 3 header named “Exercises”. This makes it easier to navigate to from the table of contents on the right, which is useful during a workshop. Within this section we then include one or more exercises using the bespoke :::{.callout-exercise} and make use of a collapsible callout box to make the answers hidden by default.
+
Here is an example of how the exercise should look at the end (the answers show the syntax skeleton for an exercise).
+
+
+
+
+
+
+Write an exercise
+
+
+
+
+
+
+
+
What do we use to write an answer to the exercise?
+
+
+
+
+
+
+Answer
+
+
+
+
+
+
+
+
We use the bespoke .callout-answer, which is collapsed by default. Here is a code snippet for a full exercise:
We use a star system to define the difficulty level of an exercise (for example this exercise was marked as level 2).
+The answer shows you how to add these stars.
+
The home page page of the course gives a description of the 3 levels.
+
+
+
+
+
+
+Answer
+
+
+
+
+
+
+
+
We provide a shortcode in the form {{< level X >}} where X is the number of filled stars (1, 2 or 3). You can add this after the exercise title, like so:
The figure legend should be used to explain the figure content.
+
The #fig-X is an identifier for the image, which will automatically add a figure number and can be cross-referenced in the text. For example if you used #fig-unix-terminal you could reference it as @fig-unix-terminal (see example below).
+
The alternative text is for accessibility purposes and should include a short description of what the image portrais (e.g. for individuals using a screen reader).
![The Unix logo.](https://upload.wikimedia.org/wikipedia/commons/thumb/6/6e/UNIX_logo.svg/250px-UNIX_logo.svg.png){#fig-unix-terminal fig-alt="The word 'Unix' appears on the logo in green, with text under it saying 'An Open Group Standard'"}
+
+
+
+
For image files, we encourage you to do things in this order:
+
+
If the image is available online (e.g. HTML of a paper) link to the URL of the image rather thank keep a copy in the repository. Make sure to link to the image source in the figure legend.
+
If it’s a diagram, use a program such as Inkscape to produce a SVG file (these are easier to edit in the future).
+
Otherwise save the figure as a PNG (e.g. software screenshots).
+
+
For saving and naming images:
+
+
Save images in materials/<section_folder>/images (if your materials don’t have higher-level sections save it in materials/images).
+
+
Use short, but descriptive, names for your images.
+
Consider adding a common prefix to all images from a particular lesson file. For example rstudio_interface.png and rstudio_new_project.png could be used to name images in a lesson explaining how to use the RStudio IDE.
+
+
+
+
4.7 References
+
Although Quarto supports citations from BibTeX files, we advise that you keep things simple and simply cite work as First Author et al. (Year), with a link to the relevant publication.
+For example:
+
+
The DESeq2 package is commonly used for differential gene expression analysis (Love et al. 2014).
+
+
+
+
4.8 Executable Documents (.Rmd and .qmd)
+
If you are developing materials using RMarkdown or Quarto Markdown, see the options you can use for your code chunks in the Quarto documentation for the Jupyter and the Knitr engines.
+If you use Jupyter Notebooks, please use jupytext to keep synchronised .qmd and .ipynb files (.ipynb are not pushed to the repo).
+
Here are some recommendations:
+
+
Add alternative text to code chunks producing plots, for accessibility purposes. You can do this by adding the #| fig-alt cell option to your chunk (see documentation pages linked above).
+
To avoid unecessary computations (and save time!), by default only files that were modified are re-rendered when running quarto render. A copy of the computed files (e.g. PNG of plots) are saved in the directory _freeze. Please run quarto render and push the _freze directory when you make changes to your code.
+
+
If you’re using stochastic algorithms in your code (e.g. sampling functions) please set a seed at the start of the document. This will avoid unnecessary changes in the rendered output files.
+
+
+
+
4.9 Summary
+
+
+
+
+
+
+Key Points
+
+
+
+
+
Callout boxes can be used to highlight different types of content the materials. The main ones are:
+
+
{.callout-tip} for learning objectives, key points and exercise answers.
+
{.callout-note} for non-essential “bonus” tips-and-tricks.
+
{.callout-important} for essential concepts that complement the main narrative.
+
{.callout-warning} for common mis-conceptions, unexpected behaviour or common errors.
+
+
Every materials page should start with a set of Learning Objectives and end with a set of Key Points.
+
Exercises are written under a level 3 heading, and the answers written as a collapsible box {.callout-tip collapse=true}.
+
Figures should always include a figure legend and alternative text.
+
+
Images can directly link to a URL, otherwise saved as SVG or PNG files.
+
Files should be saved in materials/<section_folder>/images/.
+
Use a common prefix for image file names that relate to the same topic.
+
+
References to publications/software can be done with a direct link to the source.
+
When working with executable documents (.qmd, .Rmd and .ipynb):
+
+
#fig-alt should be added to chunks producing plots.
+
A random seed should be set if there are stochastic algorithms in the code.
+
The _freeze directory should be pushed when changes are made.
+
+
+
+
+
+
+
+
+
+
+
Python Notebooks are great, and we have nothing against them in principle. But they are not very git-friendly: because they are complex JSON files with results embeded in the file, it makes it harder to see what content changed when a new commit is made.
+
However, if you prefer to develop your materials as Jupyter Notebooks, you can install the jupytertext extension. This will allow you to have synchronised .qmd and .ipynb files - so you can seamlessly work on your materials using the familiar notebook interface.↩︎
+
+
+
+
+
\ No newline at end of file
diff --git a/search.json b/search.json
new file mode 100644
index 0000000..e3079fd
--- /dev/null
+++ b/search.json
@@ -0,0 +1,156 @@
+[
+ {
+ "objectID": "index.html#overview",
+ "href": "index.html#overview",
+ "title": "Course Development Guidelines",
+ "section": "Overview",
+ "text": "Overview\nInclude a one-paragraph summary of the course here.\n\n\n\n\n\n\nLearning Objectives\n\n\n\n\nList course learning objectives here.\nThese describe concepts the learners should grasp and techniques they should be able to use by the end of the course.\nYou can think of these as completing the phrase “after this course, the participant should be able to…”\nThey are not supposed to be as detailed as the learning objectives of each section, but more high-level.\n\n\n\n\nTarget Audience\nBrief description of target audience here.\n\n\nPrerequisites\nDetail any prerequisite skills needed to attend this course, with links to other relevant materials/courses if possible.\n\n\n\nExercises\nExercises in these materials are labelled according to their level of difficulty:\n\n\n\n\n\n\n\nLevel\nDescription\n\n\n\n\n \nExercises in level 1 are simpler and designed to get you familiar with the concepts and syntax covered in the course.\n\n\n \nExercises in level 2 combine different concepts together and apply it to a given task.\n\n\n \nExercises in level 3 require going beyond the concepts and syntax introduced to solve new problems."
+ },
+ {
+ "objectID": "index.html#authors",
+ "href": "index.html#authors",
+ "title": "Course Development Guidelines",
+ "section": "Authors",
+ "text": "Authors\n\nAbout the authors:\n\nHugo Tavares \nAffiliation: Bioinformatics Training Facility, University of Cambridge\nRoles: writing - original draft; conceptualisation; coding\nMartin van Rongen \nAffiliation: Bioinformatics Training Facility, University of Cambridge\nRoles: writing - review & editing; conceptualisation; coding"
+ },
+ {
+ "objectID": "index.html#citation",
+ "href": "index.html#citation",
+ "title": "Course Development Guidelines",
+ "section": "Citation",
+ "text": "Citation\n\nPlease cite these materials if:\n\nYou adapted or used any of them in your own teaching.\nThese materials were useful for your research work. For example, you can cite us in the methods section of your paper: “We carried our analyses based on the recommendations in TODO.”.\n\nYou can cite these materials as:\n\nTODO\n\nOr in BibTeX format:\n@Misc{,\n author = {},\n title = {},\n month = {},\n year = {},\n url = {},\n doi = {}\n}"
+ },
+ {
+ "objectID": "index.html#acknowledgements",
+ "href": "index.html#acknowledgements",
+ "title": "Course Development Guidelines",
+ "section": "Acknowledgements",
+ "text": "Acknowledgements\n\n\nList any other sources of materials that were used.\nOr other people that may have advised during the material development (but are not authors)."
+ },
+ {
+ "objectID": "setup.html#data",
+ "href": "setup.html#data",
+ "title": "2 Data & Setup",
+ "section": "Data",
+ "text": "Data\nThe data used in these materials is provided as a zip file. Download and unzip the folder to your Desktop to follow along with the materials.\n\n Download"
+ },
+ {
+ "objectID": "setup.html#software",
+ "href": "setup.html#software",
+ "title": "2 Data & Setup",
+ "section": "Software",
+ "text": "Software\n\nQuarto\nTo develop and render the course materials website, you will need to install Quarto:\n\nDownload and install Quarto (available for all major OS).\nIf you are developing materials using executable .qmd documents, it is recommended that you also install the extensions for your favourite IDE (e.g. RStudio, VS Code).\nIf you are developing materials using JupyterLab or Jupyter Notebooks, please install Jupytext.\n\nUse the paired notebook feature to have synchronised .ipynb/.qmd files. Only .qmd files should be pushed to the repository (.ipynb files have been added to .gitignore)."
+ },
+ {
+ "objectID": "materials/01-render_guidelines.html#introduction",
+ "href": "materials/01-render_guidelines.html#introduction",
+ "title": "3 Course Rendering",
+ "section": "3.1 Introduction",
+ "text": "3.1 Introduction\nIn the sections below, we detail how files/directories are organised and how you can build the course website locally.\nPlease only edit the files indicated in the instructions below. If you need help with the site configuration, please get in touch with us so we can revise our template.\nIf you just need a reminder, here is a TLDR-summary:\n\nClone the repository git clone <repo> (or run git pull to update your local clone).\nWrite materials in the markdown/notebook files in the materials/ directory. You can organise files in sub-directories (e.g. if they are part of a top-level section).\nEdit the materials/_chapters.yml file to adjust the chapter layout.\nData files and/or scripts for the participants can be saved in course_files/{data,scripts}, respectively.\nBuild the site locally with quarto render. Open the file _site/index.html to view your changes.\nAdd, commit and push changes to the repository.\nIf using executable documents (.Rmd/.qmd), make sure to also push the _freeze directory.\n\nMake sure to also read our content development guidelines."
+ },
+ {
+ "objectID": "materials/01-render_guidelines.html#setup",
+ "href": "materials/01-render_guidelines.html#setup",
+ "title": "3 Course Rendering",
+ "section": "3.2 Setup",
+ "text": "3.2 Setup\n\nDownload and install Quarto.\n\nIf you are developing materials using executable .qmd documents, it is recommended that you also install the extensions for your favourite IDE.\n\nIf you are developing materials using JupyterLab or Jupyter Notebooks, please install Jupytext.\n\nUse the paired notebook feature to have synchronised .ipynb/.qmd files. Only .qmd files should be pushed to the repository (.ipynb files have been added to .gitignore).\n\nClone the course repository with git clone.\n\nYou’re now ready to start editing the course content.\nIf you use either VS Code or RStudio, we’ve included *.code-workspace and *.Rproj files that you can use to open your project in those programs, respectively."
+ },
+ {
+ "objectID": "materials/01-render_guidelines.html#build-the-site",
+ "href": "materials/01-render_guidelines.html#build-the-site",
+ "title": "3 Course Rendering",
+ "section": "3.3 Build the Site",
+ "text": "3.3 Build the Site\nAfter a fresh clone, you may want to render the website locally first, to check that Quarto is setup correctly. You can also follow this workflow thereafter, every time you edit the materials.\n\nRun quarto render to built the site.\nThe local copy of the site will be saved in the _site folder - open the index.html file to open the local copy of your site.\n\nNote that the _site folder is local and not pushed to GitHub (it’s been added to .gitignore). The public site is built automatically by GitHub Actions every time a new push is made.\n\n\nThe website you are reading right now gives an example of how the course website will look like."
+ },
+ {
+ "objectID": "materials/01-render_guidelines.html#file-organisation",
+ "href": "materials/01-render_guidelines.html#file-organisation",
+ "title": "3 Course Rendering",
+ "section": "3.4 File Organisation",
+ "text": "3.4 File Organisation\nThere are three things that you may edit:\n\nFiles in materials/ - this contains all the markdown/notebook files with the written materials (rendered on the site).\nFiles in course_files/ - this contains the files that participants will have on their training machines.\nThe index.md file - this is the homepage for the course.\n\n\n3.4.1 Course Materials\nThe materials can be written as plain markdown .md, Rmarkdown .Rmd, Quarto markdown .qmd or Jupyter notebooks .ipynb. As mentioned in Setup, if you are using Jupyter Notebooks, make sure to use Jupytext to have paired .ipynb/.qmd files.\nThe following conventions should be used:\n\nPlease name your files with a two-digit numeric prefix. For example 01-first_lesson.md. Use relatively descriptive names for the files (unlike this example!).\nAlways include the following YAML header, at the top of each file:\n---\ntitle: Lesson Title # keep this concise\n---\nThis title will appear both on the navigation bar on the left and as the title of the page. For example, the page you are viewing now has title: Course Rendering.\nOrganise your files into sub-directories, if they are all part of a logical section of materials. For example:\ncourse_folder\n |_ materials\n |_ section1\n | |_ 01-first_lesson_in_section1.md\n | |_ 02-second_lesson_in_section1.md\n |_ section2\n |_ 01-first_lesson_in_section2.md\n |_ 02-second_lesson_in_section2.md\nIf you want to create slides using Quarto (documentation), please include them in a directory materials/<section_folder>/slides/.\n\n\n\n3.4.2 Course Files & Data\nWhen we run a workshop, participants will have all the necessary files for the course on the training computers.\nGenerally, there are two types of files we may want to distribute to the participants:\n\nscripts - any scripts for exercises or examples we want to run interactively during the course.\ndata - any data files (CSV, FASTQ, etc.) that are used.\n\nThese course files should be in a directory called course_files and specify all the paths in the materials relative to that. So, this will be the directory structure you end up with:\ncourse_folder\n |_ course_files\n | |_ data\n | |_ scripts\n |_ materials\n |_ ... Markdowns as detailed earlier\nAs you develop the materials and identify suitable data for the workshop, you can place it in the directory course_files/data/ (within that you can set any directory structure you want) and scripts for the participants in course_files/scripts (again you can organise this in any way you think is useful).\nHowever, as a rule, only scripts should be pushed to the repository.\nGenerally, we do not keep data in the repository, unless the files are text-based and/or small. We keep the data files on our Dropbox, so anyone can download them from a stable link (including with wget).\n\n\n\n\n\n\nFlexible course file structure\n\n\n\nWhat’s given here is our recommended convention but, if you think your course files would benefit from a different file structure, please let us know.\nEqually, if you don’t need to distribute scripts or data with your course (e.g. if your course is live-coded and data is downloaded from a public URL), then leave these directories empty as they are.\n\n\n\n\n3.4.3 Homepage\nThe index.md file (at the root of the directory) will become the homepage for the course.\nThis file can be edited towards the end of the material development, following the instructions given there. You can see an example on the homepage of this website."
+ },
+ {
+ "objectID": "materials/01-render_guidelines.html#sidebar",
+ "href": "materials/01-render_guidelines.html#sidebar",
+ "title": "3 Course Rendering",
+ "section": "3.5 Sidebar",
+ "text": "3.5 Sidebar\nThe navigation bar on the left is configured from the materials/_chapters.yml file.\nHere is how the YAML file would look like for the example directory structure shown earlier:\nbook:\n chapters:\n - part: \"One Section\"\n chapters:\n - materials/section1/01-first_lesson_in_section1.md\n - materials/section1/02-second_lesson_in_section1.md\n - part: \"Another Section\"\n chapters:\n - materials/section2/01-first_lesson_in_section2.md\n - materials/section2/02-second_lesson_in_section2.md"
+ },
+ {
+ "objectID": "materials/01-render_guidelines.html#summary",
+ "href": "materials/01-render_guidelines.html#summary",
+ "title": "3 Course Rendering",
+ "section": "3.6 Summary",
+ "text": "3.6 Summary\n\n\n\n\n\n\nKey Points\n\n\n\n\nCourse websites are built using Quarto.\nThe website can be built using the command quarto render. The website can be previewed from the file _site/index.html.\nMaterials can be written in markdown-based documents (.md, .Rmd, .qmd) or Python notebooks (.ipynb). For the latter the Jupytext package should be used to keep synchronised .qmd and .ipynb files.\nFiles for course materials files should be saved in the materials/ directory and named using a numeric prefix 00- for friendly ordering in the filesystem. Files can be further organised in sub-directories if they are logically grouped by sections.\nFiles to be shared with the participants (scripts and/or data) should be saved in course_files.\nGenerally, only course_files/scripts are pushed to the repository, and we will keep a copy of the data files on Dropbox.\nThe navigation sidebar can be configured from the materials/_chapters.yml file."
+ },
+ {
+ "objectID": "materials/02-content_guidelines.html#introduction",
+ "href": "materials/02-content_guidelines.html#introduction",
+ "title": "4 Content Guidelines",
+ "section": "4.1 Introduction",
+ "text": "4.1 Introduction\nThis document includes information for writing materials for the Bioinformatics Training Facility, which is then built into a website using Quarto. We encourage you to use markdown-based documents (.md, .Rmd or .qmd), although Python Notebooks (.ipynb) are also supported1.\n\n\n\n\n\n\nTip\n\n\n\nOne way to learn about the syntax used to develop materials is to look at the source file for this page.\n\n\nTo start, here is a brief list of syntax conventions we use:\n\nHeadings start at level 2 (##).\nExercises should be entitled using a level 3 (###) heading - see Exercises section for details.\nCode blocks should be annotated with the language used, to enable syntax highlighting.\nThere are several other markdown tricks that you can use (e.g. equations and mermaid diagrams). See the Quarto Markdown Basics documentation for a reminder of these features.\n\nWe give further details about other features below, but the essential workflow when working on the materials is:\n\nEdit your markdown/notebook files in materials/.\nRun quarto render to build the site (open _site/index.html to preview your website locally).\nAdd, commit and push the changes to the repository.\n\nIf you need a reminder of the technical setup for course development, go back to the Course Rendering page."
+ },
+ {
+ "objectID": "materials/02-content_guidelines.html#callout-boxes",
+ "href": "materials/02-content_guidelines.html#callout-boxes",
+ "title": "4 Content Guidelines",
+ "section": "4.2 Callout Boxes",
+ "text": "4.2 Callout Boxes\nQuarto has several built-in callout boxes available. You can use these to highlight particular content. Note that the colour scheme for our callout boxes is simplified relative to the original Quarto template.\nHere is an example of each box, with a short description of what you may want to use it for:\n\n\n\n\n\n\nTip\n\n\n\nThis is a .callout-tip, which is used for learning objectives, key points and exercise answers (each of these is detailed below).\n\n\n\n\n\n\n\n\nNote\n\n\n\nThis is a .callout-note, which you can use to highlight “bonus” tips-and-tricks that complement your materials.\nThese can be thought of as non-essential parts of the materials, which may not be covered in a live workshop. The more muted colour of this box conveys that idea.\n\n\n\n\n\n\n\n\nImportant\n\n\n\nThis is a .callout-important, which can be used to highlight important notes that complement the materials.\nThis can be thought of as a more essential idea/concept that is mentioned specifically during a live workshop.\n\n\n\n\n\n\n\n\nWarning\n\n\n\nThis is a .callout-warning, which can be used to highlight common “gotchas” such as unexpected behaviours of the software being used or common mistakes users can make.\n\n\n\n\n\n\n\n\nCaution\n\n\n\nThis is a .callout-caution, which at the moment is only used to highlight readers when materials are under development. You should rarely have to use these."
+ },
+ {
+ "objectID": "materials/02-content_guidelines.html#learning-objectives-1",
+ "href": "materials/02-content_guidelines.html#learning-objectives-1",
+ "title": "4 Content Guidelines",
+ "section": "4.3 Learning Objectives",
+ "text": "4.3 Learning Objectives\nWe advise that every lesson starts with a set of “Learning Objectives” included in a .callout-tip box:\n::: {.callout-tip}\n## Learning Objectives\n\n- List skills and concepts that learners should grasp after this lesson.\n- See the box at the beggining of this document as an example.\n:::\nBy convention we tend to use an active tense. Bloom’s taxonomy may give you ideas of active verbs to use."
+ },
+ {
+ "objectID": "materials/02-content_guidelines.html#key-points",
+ "href": "materials/02-content_guidelines.html#key-points",
+ "title": "4 Content Guidelines",
+ "section": "4.4 Key Points",
+ "text": "4.4 Key Points\nEqually, we advise that every lesson ends with a level 2 section named “Summary” with a set of “Key Points”, which summarise the main concepts covered in the lesson:\n::: {.callout-tip}\n## Key Points\n\n- List key concepts covered in the lesson.\n- See the bottom of this document as an example.\nThis can be thought of as a “cheatsheet” for that lesson, if the user just wanted to quickly remind themselves about the lesson content, they should be able to do so from this section."
+ },
+ {
+ "objectID": "materials/02-content_guidelines.html#sec-exercises",
+ "href": "materials/02-content_guidelines.html#sec-exercises",
+ "title": "4 Content Guidelines",
+ "section": "4.5 Exercises",
+ "text": "4.5 Exercises\nBy convention, we make the exercises under a level 3 header named “Exercises”. This makes it easier to navigate to from the table of contents on the right, which is useful during a workshop. Within this section we then include one or more exercises using the bespoke :::{.callout-exercise} and make use of a collapsible callout box to make the answers hidden by default.\nHere is an example of how the exercise should look at the end (the answers show the syntax skeleton for an exercise).\n\n\n\n\n\n\nWrite an exercise\n\n\n\n\n\n\n\nWhat do we use to write an answer to the exercise?\n\n\n\n\n\n\nAnswer\n\n\n\n\n\n\n\nWe use the bespoke .callout-answer, which is collapsed by default. Here is a code snippet for a full exercise:\n::: {.callout-exercise}\n#### Short Description\n\nQuestion here.\n\n::: {.callout-answer}\nAnswer here.\n:::\n:::\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nExercise levels\n\n\n\n\n\n\n\nLevel: \nWe use a star system to define the difficulty level of an exercise (for example this exercise was marked as level 2).\nThe answer shows you how to add these stars.\nThe home page page of the course gives a description of the 3 levels.\n\n\n\n\n\n\nAnswer\n\n\n\n\n\n\n\nWe provide a shortcode in the form {{< level X >}} where X is the number of filled stars (1, 2 or 3). You can add this after the exercise title, like so:\n::: {.callout-exercise}\n#### Short Description\n{{< level 2 >}}\n\nQuestion here.\n\n::: {.callout-answer}\nAnswer here.\n:::\n:::\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nExercise\n\n\n\n\n\n\n\nSometimes it may be useful to add hints to the exercises. How is this done?\n\n\n\n\n\n\nHint\n\n\n\n\n\n\n\nIf for exercises we had .callout-exercise and for answers we had .callout-answer, for hints we have…\n\n\n\n\n\n\n\n\n\n\n\nAnswer\n\n\n\n\n\n\n\nYou guessed it, you can use .callout-hint (the box is also collapsed by default):\n:::{.callout-hint}\nHint(s) here.\n:::"
+ },
+ {
+ "objectID": "materials/02-content_guidelines.html#figures",
+ "href": "materials/02-content_guidelines.html#figures",
+ "title": "4 Content Guidelines",
+ "section": "4.6 Figures",
+ "text": "4.6 Figures\nFigures should be included in the document as:\n![Figure Legend](link_to_figure_file_or_url){#fig-X fig-alt=\"Alternative text\"}\n\nThe figure legend should be used to explain the figure content.\nThe #fig-X is an identifier for the image, which will automatically add a figure number and can be cross-referenced in the text. For example if you used #fig-unix-terminal you could reference it as @fig-unix-terminal (see example below).\nThe alternative text is for accessibility purposes and should include a short description of what the image portrais (e.g. for individuals using a screen reader).\n\nThere are more advanced figure layouts possible, see the Quarto Figures documentation to learn more.\nHere is the code generating Figure 4.1:\n![The Unix logo.](https://upload.wikimedia.org/wikipedia/commons/thumb/6/6e/UNIX_logo.svg/250px-UNIX_logo.svg.png){#fig-unix-terminal fig-alt=\"The word 'Unix' appears on the logo in green, with text under it saying 'An Open Group Standard'\"}\n\n\n\nFigure 4.1: The Unix logo.\n\n\nFor image files, we encourage you to do things in this order:\n\nIf the image is available online (e.g. HTML of a paper) link to the URL of the image rather thank keep a copy in the repository. Make sure to link to the image source in the figure legend.\nIf it’s a diagram, use a program such as Inkscape to produce a SVG file (these are easier to edit in the future).\nOtherwise save the figure as a PNG (e.g. software screenshots).\n\nFor saving and naming images:\n\nSave images in materials/<section_folder>/images (if your materials don’t have higher-level sections save it in materials/images).\n\nUse short, but descriptive, names for your images.\nConsider adding a common prefix to all images from a particular lesson file. For example rstudio_interface.png and rstudio_new_project.png could be used to name images in a lesson explaining how to use the RStudio IDE."
+ },
+ {
+ "objectID": "materials/02-content_guidelines.html#references",
+ "href": "materials/02-content_guidelines.html#references",
+ "title": "4 Content Guidelines",
+ "section": "4.7 References",
+ "text": "4.7 References\nAlthough Quarto supports citations from BibTeX files, we advise that you keep things simple and simply cite work as First Author et al. (Year), with a link to the relevant publication.\nFor example:\n\nThe DESeq2 package is commonly used for differential gene expression analysis (Love et al. 2014)."
+ },
+ {
+ "objectID": "materials/02-content_guidelines.html#executable-documents-.rmd-and-.qmd",
+ "href": "materials/02-content_guidelines.html#executable-documents-.rmd-and-.qmd",
+ "title": "4 Content Guidelines",
+ "section": "4.8 Executable Documents (.Rmd and .qmd)",
+ "text": "4.8 Executable Documents (.Rmd and .qmd)\nIf you are developing materials using RMarkdown or Quarto Markdown, see the options you can use for your code chunks in the Quarto documentation for the Jupyter and the Knitr engines.\nIf you use Jupyter Notebooks, please use jupytext to keep synchronised .qmd and .ipynb files (.ipynb are not pushed to the repo).\nHere are some recommendations:\n\nAdd alternative text to code chunks producing plots, for accessibility purposes. You can do this by adding the #| fig-alt cell option to your chunk (see documentation pages linked above).\nTo avoid unecessary computations (and save time!), by default only files that were modified are re-rendered when running quarto render. A copy of the computed files (e.g. PNG of plots) are saved in the directory _freeze. Please run quarto render and push the _freze directory when you make changes to your code.\n\nIf you’re using stochastic algorithms in your code (e.g. sampling functions) please set a seed at the start of the document. This will avoid unnecessary changes in the rendered output files."
+ },
+ {
+ "objectID": "materials/02-content_guidelines.html#summary",
+ "href": "materials/02-content_guidelines.html#summary",
+ "title": "4 Content Guidelines",
+ "section": "4.9 Summary",
+ "text": "4.9 Summary\n\n\n\n\n\n\nKey Points\n\n\n\n\nCallout boxes can be used to highlight different types of content the materials. The main ones are:\n\n{.callout-tip} for learning objectives, key points and exercise answers.\n{.callout-note} for non-essential “bonus” tips-and-tricks.\n{.callout-important} for essential concepts that complement the main narrative.\n{.callout-warning} for common mis-conceptions, unexpected behaviour or common errors.\n\nEvery materials page should start with a set of Learning Objectives and end with a set of Key Points.\nExercises are written under a level 3 heading, and the answers written as a collapsible box {.callout-tip collapse=true}.\nFigures should always include a figure legend and alternative text.\n\nImages can directly link to a URL, otherwise saved as SVG or PNG files.\nFiles should be saved in materials/<section_folder>/images/.\nUse a common prefix for image file names that relate to the same topic.\n\nReferences to publications/software can be done with a direct link to the source.\nWhen working with executable documents (.qmd, .Rmd and .ipynb):\n\n#fig-alt should be added to chunks producing plots.\nA random seed should be set if there are stochastic algorithms in the code.\nThe _freeze directory should be pushed when changes are made."
+ },
+ {
+ "objectID": "materials/02-content_guidelines.html#footnotes",
+ "href": "materials/02-content_guidelines.html#footnotes",
+ "title": "4 Content Guidelines",
+ "section": "",
+ "text": "Python Notebooks are great, and we have nothing against them in principle. But they are not very git-friendly: because they are complex JSON files with results embeded in the file, it makes it harder to see what content changed when a new commit is made.\nHowever, if you prefer to develop your materials as Jupyter Notebooks, you can install the jupytertext extension. This will allow you to have synchronised .qmd and .ipynb files - so you can seamlessly work on your materials using the familiar notebook interface.↩︎"
+ }
+]
\ No newline at end of file
diff --git a/setup.html b/setup.html
new file mode 100644
index 0000000..fd36c7e
--- /dev/null
+++ b/setup.html
@@ -0,0 +1,619 @@
+
+
+
+
+
+
+
+
+
+ Data & Setup
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
If you are attending one of our workshops, we will provide a training environment with all of the required software and data.
+If you want to setup your own computer to run the analysis demonstrated on this course, you can follow the instructions below.
+
+
+
+
Data
+
The data used in these materials is provided as a zip file. Download and unzip the folder to your Desktop to follow along with the materials.
+
+
+
+
+
Software
+
+
Quarto
+
To develop and render the course materials website, you will need to install Quarto:
+
+
Download and install Quarto (available for all major OS).
+
If you are developing materials using executable .qmd documents, it is recommended that you also install the extensions for your favourite IDE (e.g. RStudio, VS Code).
+
If you are developing materials using JupyterLab or Jupyter Notebooks, please install Jupytext.
+
+
Use the paired notebook feature to have synchronised .ipynb/.qmd files. Only .qmd files should be pushed to the repository (.ipynb files have been added to .gitignore).