Including a new topic
Author(s) | Bérénice Batut |
Editor(s) | Helena Rasche |
OverviewQuestions:Objectives:
How to include a new topic?
Create a new topic
Set up the metadata for a topic
Time estimation: 30 minutesSupporting Materials:Last modification: Oct 18, 2022
Introduction
Each training material is related to a topic. All training materials (slides, tutorials, …) related to a topic are found in a dedicated directory (e.g. transcriptomics
directory contains the material related to exome sequencing analysis).
Directory structure
Each topic has the following structure:
├── README.md
├── metadata.yaml
├── images
├── docker
│ ├── Dockerfile
├── slides
│ ├── index.html
├── tutorials
│ ├── tutorial1
│ │ ├── tutorial.md
│ │ ├── slides.html
│ │ ├── data-library.yaml
│ │ ├── workflows
│ │ │ ├── index.md
│ │ │ ├── workflow.ga
│ │ ├── tours
│ │ │ ├── tour.yaml
images
directory
The images
directory collects all images/pictures needed for the training materials related to the topic, i.e pictures for the slides or the tutorials.
Images shared between several topics are in the shared/images
directory at the root.
All images for the slides must be in images
directory. The images must be in good quality. The sources (svg
or other) of the images must also be added to the images
directory. We encourage you to use yEd to easily generate diagrams and Inkscape for any other images.
slides
directory
This directory contains introduction slide deck. There could be several slide decks, to cover different aspect. The slides are rendered using remark.js
but written in Markdown to facilitate collaboration.
tutorials
directory
This directory collects the tutorials related to the topic, one per subdirectory.
The tutorials are hands-on built for workshop and self-training, with description of the whole infrastructure needed to run the tutorial on any Galaxy instance (tools, data library, etc).
The templates for the tutorials are different from the other pages to help users to focus on the content of the tutorial. To improve the output of the tutorial, several metadata are mandatory for every tutorials, such as the requirements or the objectives of the tutorials. Boxes are also used to highlight some key points as the hands-on or the tips.
The content of each tutorial is generated with Jekyll from a Markdown file and some metadata (e.g. the requirements, the Zenodo link, the questions) defined inside the metadata of the related topic.
Comment: ContributingWant to contribute to a tutorial? Check out our training materials about that.
Sometimes, an hands-on tutorial is not the most appropriate format for a tutorial and slides are better. The content must be then added in the slides
directory.
docker
directory
For each topic, a flavored Docker image must integrate the tools needed for the tutorials. The corresponding image must be based on official Galaxy Docker images.
The docker
image will also integrate the Galaxy tours available for each topics and the workflows.
Creating a new topic
AgendaIn this tutorial, we will deal with:
Defining the topic
When we structured the repository, we decided to use as topics the categories that are used in the ToolShed. The ToolShed assigns a category to each tool. Therefore, to decide where to put your tutorial, have a look at which ToolShed’s category the main tools in your tutorial belong. For example, this tutorial will rely on the NCBI Blast+ tool.
Hands-on: Defining the topic for the tutorial
- Search for NCBI Blast+ on the ToolShed
Check in which category it has been placed
QuestionIn which topic will you put the new tutorial?
If we search for NCBI Blast+ in the ToolShed, it is placed in 2 categories (bottom): “Next Gen Mappers”, and “Sequence Analysis”. We decided to put it in “Sequence analysis” because this is the most general one for this tutorial.
In this tutorial, we want to add a new topic called about “my-favorite-topic”.
Creating the skeleton for the topic
Once the topic name has been chosen, we can create it.
Hands-on: Create all the required files and folders structures automatically
- Open a terminal
Run (by adapting the information between the quotes)
$ planemo training_init \ --topic_name "my-favorite-topic" \ --topic_title "Test" \ --topic_target "use" \ --topic_summary "Summary of the topic"
- Check that a new directory has been generated in
topics
- Check that a YAML file with your topic name has been generated in
metadata
folderMake sure that Jekyll is running
Comment: JekyllWant to learn how to start Jekyll? Check out our tutorial to serve the website locally
- Check if the topic has been correctly added at http://localhost:4000/training-material/
Adapt the metadata for your topic
Several metadata are defined in metadata.yaml
file in your topic folder to :
A dictionary/map
Free Textname
The internal identifier for a topic, it should be the same as the folder name.
Example(s)
name: epigenetics
name: sequence-analysis
name: admin
Required Pattern: Must match the following regular expression
/^[a-z0-9_-]+$/
Free Texttype
The type of topic, some have subtly different behaviours.
admin-dev
- should be used for admin and developer topics that are not scientifically focused.
basics
- Only used for galaxy-interface type topics
data-science
- Topics which are not necessarily Galaxy focused but expand into broader communities
use
- These topics use galaxy for some analysis
instructors
- Specific to topics related to instruction of Galaxy
Possible Values:
admin-dev
basics
data-science
use
instructors
Example(s)
type: "admin-dev"
type: "basics"
type: "data-science"
type: "use"
type: "instructors"
Free Texttitle
Title of the topic, this is displayed for users to see.
Example(s)
title: Proteomics
title: Variant Analysis
Free Textsummary
A longer description of the contents of this topic
Example(s)
summary: Statistical Analyses for omics data and machine learning using Galaxy tools
List of Itemsmaintainers
Free Text
The image ID for an image which contains all of the tools and data for this topic.
Example(s)
docker_image: quay.io/galaxy/sequence-analysis-training
Free Text
An edam ontology id that describes the topic.
Example(s)
edam_ontology: topic_3173
Required Pattern: Must match the following regular expression
/^topic_[0-9]+$/
Boolean
false
to hide your topic from the production GTN. This is useful if you need a topic for a workshop, but have not finished making it up to GTN standards.Free Text
Link to a gitter channel that is more relevant for this topic than the default. E.g. a single cell topic, you could use
Galaxy-Training-Network/galaxy-single-cell
to link to their specific chat room in all of the child tutorials by default.Example(s)
gitter: Galaxy-Training-Network/galaxy-single-cell
gitter: galaxy-genome-annotation/Lobby
List of Items
Example(s)
references: - - | authors: "Vaudel M, et al." title: "Shedding light on black boxes in protein identification." link: "https://www.ncbi.nlm.nih.gov/pubmed/24678044" summary: "An extensive tutorial for peptide and protein identification, available at http://compomics.com/bioinformatics-for-proteomics. The material is completely based on freely available and open-source tools."
A dictionary/mapSequence Value (List of items)
Free Textauthors
Free Texttitle
Free Textlink
Free Text
List of Items
List of resources that the reader of the material should be familiar with before starting this training. The structure is identical to
follow_up_training
.Example(s)
requirements: - type: internal topic_name: statistics tutorials: - age-prediction-with-ml
A dictionary/mapSequence Value (List of items)
Free Texttype
the type of link
Possible Values:
internal
Example(s)
type: "internal"
Free Text
The name of the topic
List of Items
List of required tutorials inside that topic
List of Items
For large topics, we can define subtopics and create multiple tutorial lists, which separates the tutorials to help users find content that interests them more quickly.
A dictionary/map
Free Textid
Subtopic ID, this should match what is used in tutorials.
Example(s)
id: single-cell
Required Pattern: Must match the following regular expression
/^[A-Za-z0-9_-]+$/
Free Texttitle
Subtopic title, which is displayed for users to see.
Example(s)
title: Maintaining a Production Galaxy
title: Single-cell RNA-seq
Free Textdescription
A human readable textual description of a subtopic.
Example(s)
description: - "Start here if you are new to RNA-Seq analysis in Galaxy" - "These tutorials take you from raw sequencing reads to pathway analysis" - "Tutorials about analysis of single-cell RNA-seq data" - "Tutorials using a single published single-cell RNA-seq dataset for a variety of analyses"
Boolean
false
to hide your topic from the production GTN. This is useful if you need a topic for a workshop, but have not finished making it up to GTN standards.
subtopics
: for large topics, we can define subtopics and create multiple tutorial lists:subtopics: singlecell: title: "Single Cell Analysis" description: "These tutorials cover single cell analysis" small: title: "Small RNA" description: "These Tutorial"
tutorials can be assigned to subtopics by adding e.g.
subtopic: singlecell
to the tutorial metadata. An example of this subtopic division can be found in the admin section
Hands-on: Update the new topic to the website
- Open the
metadata.yaml
file in your topic folder- Fill the correct metadata of the topic
Make sure that Jekyll is running
Comment: JekyllWant to learn how to start Jekyll? Check out our tutorial to serve the website locally
- Check how it changes the local website
Conclusion
We just created a new topic. We can now fill it by creating new tutorials
Key points
A new topic can be easily added for new tutorials
Frequently Asked Questions
Have questions about this tutorial? Check out the tutorial FAQ page or the FAQ page for the Contributing to the Galaxy Training Material topic to see if your question is listed there. If not, please ask your question on the GTN Gitter Channel or the Galaxy Help ForumFeedback
Did you use this material as an instructor? Feel free to give us feedback on how it went.
Did you use this material as a learner or student? Click the form below to leave feedback.
Citing this Tutorial
- , 2022 Including a new topic (Galaxy Training Materials). https://training.galaxyproject.org/training-material/topics/contributing/tutorials/create-new-topic/tutorial.html Online; accessed TODAY
- Batut et al., 2018 Community-Driven Data Analysis Training for Biology Cell Systems 10.1016/j.cels.2018.05.012
Congratulations on successfully completing this tutorial!@misc{contributing-create-new-topic, author = "Bérénice Batut", title = "Including a new topic (Galaxy Training Materials)", year = "2022", month = "10", day = "18" url = "\url{https://training.galaxyproject.org/training-material/topics/contributing/tutorials/create-new-topic/tutorial.html}", note = "[Online; accessed TODAY]" } @article{Batut_2018, doi = {10.1016/j.cels.2018.05.012}, url = {https://doi.org/10.1016%2Fj.cels.2018.05.012}, year = 2018, month = {jun}, publisher = {Elsevier {BV}}, volume = {6}, number = {6}, pages = {752--758.e1}, author = {B{\'{e}}r{\'{e}}nice Batut and Saskia Hiltemann and Andrea Bagnacani and Dannon Baker and Vivek Bhardwaj and Clemens Blank and Anthony Bretaudeau and Loraine Brillet-Gu{\'{e}}guen and Martin {\v{C}}ech and John Chilton and Dave Clements and Olivia Doppelt-Azeroual and Anika Erxleben and Mallory Ann Freeberg and Simon Gladman and Youri Hoogstrate and Hans-Rudolf Hotz and Torsten Houwaart and Pratik Jagtap and Delphine Larivi{\`{e}}re and Gildas Le Corguill{\'{e}} and Thomas Manke and Fabien Mareuil and Fidel Ram{\'{\i}}rez and Devon Ryan and Florian Christoph Sigloch and Nicola Soranzo and Joachim Wolff and Pavankumar Videm and Markus Wolfien and Aisanjiang Wubuli and Dilmurat Yusuf and James Taylor and Rolf Backofen and Anton Nekrutenko and Björn Grüning}, title = {Community-Driven Data Analysis Training for Biology}, journal = {Cell Systems} }
Developing GTN training materialThis tutorial is part of a series to develop GTN training material, feel free to also look at:
- Overview of the Galaxy Training Material
- Adding auto-generated video to your slides
- Adding Quizzes to your Tutorial
- Contributing with GitHub via command-line
- Contributing with GitHub via its interface
- Creating a new tutorial
- Creating content in Markdown
- Creating Interactive Galaxy Tours
- Creating Slides
- Design and plan session, course, materials
- Generating PDF artefacts of the website
- GTN Metadata
- Including a new topic
- Principles of learning and how they apply to training and teaching
- Running the GTN website locally
- Running the GTN website online using GitPod
- Teaching Python
- Tools, Data, and Workflows for tutorials
- Updating diffs in admin training