Frequently Asked Questions

Analysis

---

Results may vary

Results may vary

Your results may be slightly different from the ones presented in this tutorial due to differing versions of tools, reference data, external databases, or because of stochastic processes in the algorithms.

Troubleshooting errors

When you get a red dataset in your history, it means something went wrong. But how can you find out what it was? And how can you report errors?

Tip: Troubleshooting errors

When someting goes wrong in Galaxy, there are a number of things you can do to find out what it was. Error messages can help you figure out whether it was a problem with one of the settings of the tool, or with the input data, or maybe there is a bug in the tool itself and the problem should be reported. Below are the steps you can follow to troubleshoot your Galaxy errors.

1. Expand the red history dataset by clicking on it.
   • Sometime you can already see an error message here

2. View the error message by clicking on the bug icon galaxy-bug

3. Check the logs. Output (stdout) and error logs (stderr) of the tool are available:
   • Expand the history item
   • Click on the details icon
   • Scroll down to the Job Information section to view the 2 logs:
     • Tool Standard Output
     • Tool Standard Error
4. Submit a bug report! If you are still unsure what the problem is.
   • Click on the bug icon galaxy-bug
   • Write down any information you think might help solve the problem
     • See this FAQ on how to write good bug reports
   • Click galaxy-bug Report button
   • In the meantime, you can ask for help in the Galaxy Gitter Channel or the GTN Gitter Channel, or you can browse the Galaxy Help Forum to see if others have encountered the same problem before.

Creating an account

To get access to all features of a Galaxy instance, you need to create an account.

Tip: Creating an account

To create an account:

1. Click Login or Register
2. At the bottom of the form click Register here
3. Fill the form and click Create

Collections

---

Adding a tag to a collection

Tip: Adding a tag to a collection

• Click on the collection

• Add a tag starting with # in the Add tags field

  Tags starting with # will be automatically propagated to the outputs of tools using this dataset.

• Press Enter
• Check that the tag is appearing below the collection name

Creating a dataset collection

Tip: Creating a dataset collection

• Click on Operations on multiple datasets (check box icon) at the top of the history panel
• Check all the datasets in your history you would like to include

• Click For all selected.. and choose Build dataset list

  

• Enter a name for your collection
• Click Create List to build your collection
• Click on the checkmark icon at the top of your history again

Creating a paired collection

Tip: Creating a paired collection

• Click on Operations on multiple datasets (check box icon) at the top of the history panel
• Check all the datasets in your history you would like to include

• Click For all selected.. and choose Build List of Dataset Pairs

• Change the text of unpaired forward to a common selector for the forward reads
• Change the text of unpaired reverse to a common selector for the reverse reads
• Click Pair these datasets for each valid forward and reverse pair.
• Enter a name for your collection
• Click Create List to build your collection
• Click on the checkmark icon at the top of your history again

Renaming a collection

Tip: Renaming a collection

1. Click on the collection
2. Click on the name of the collection at the top
3. Change the name
4. Press Enter

Data upload

---

Importing data from a data library

Tip: Importing data from a data library

As an alternative to uploading the data from a URL or your computer, the files may also have been made available from a shared data library:

• Go into Shared data (top panel) then Data libraries
• Navigate to the correct folder as indicated by your instructor
• Select the desired files
• Click on the To History button near the top and select as Datasets from the dropdown menu
• In the pop-up window, select the history you want to import the files to (or create a new one)
• Click on Import

Importing via links

Tip: Importing via links

• Copy the link location

• Open the Galaxy Upload Manager (galaxy-upload on the top-right of the tool panel)

• Select Paste/Fetch Data

• Paste the link into the text field

• Press Start

• Close the window

• By default, Galaxy uses the URL as the name, so rename the files with a more useful name.

Datasets

---

Adding a custom database/build (dbkey)

Galaxy may have several reference genomes built-in, but you can also create your own.

Tip: Adding a custom database/build (dbkey)

• In the top menu bar, go to the User, and select Custom Builds
• Choose a name for your reference build
• Choose a dbkey for your reference build
• Under Definition, select the option FASTA-file from history
• Under FASTA-file, select your fasta file
• Click the Save button

Upload fastqsanger datasets via links

Tip: Upload fastqsanger datasets via links

1. Click on Upload Data on the top of the left panel:

   

2. Click on Paste/Fetch:

   

3. Paste URL into text box that would appear:

   

4. Set Type (set all) to fastqsanger or, if your data is compressed as in URLs above (they have .gz extensions), to fastqsanger.gz

   :

Adding a tag

Tags can help you to better organize your history and track datasets.

Tip: Adding a tag

• Click on the dataset
• Click on galaxy-tags Edit dataset tags

• Add a tag starting with #

  Tags starting with # will be automatically propagated to the outputs of tools using this dataset.

• Check that the tag is appearing below the dataset name

Changing the datatype

Galaxy will try to autodetect the datatype of your files, but you may need to manually set this occasionally.

Tip: Changing the datatype

• Click on the galaxy-pencil pencil icon for the dataset to edit its attributes
• In the central panel, click on the galaxy-chart-select-data Datatypes tab on the top
• Select your desired datatype
• Click the Save button

Changing database/build (dbkey)

You can tell Galaxy which dbkey (e.g. reference genome) your dataset is associated with. This may be used by tools to automatically use the correct settings.

Tip: Changing database/build (dbkey)

• Click on the galaxy-pencil pencil icon for the dataset to edit its attributes
• In the central panel, change the Database/Build field
• Select your desired database key from the dropdown list
• Click the Save button

Converting the file format

Some datasets can be transformed into a different format. Galaxy has some built-in file conversion options depending on the type of data you have.

Tip: Converting the file format

• Click on the galaxy-pencil pencil icon for the dataset to edit its attributes
• In the central panel, click on the galaxy-gear Convert tab on the top
• Select the appropriate datatype from the list
• Click the Convert datatype button

Creating a new file

Galaxy allows you to create new files from the upload menu. You can supply the contents of the file.

Tip: Creating a new file

• Open the Galaxy Upload Manager
• Select Paste/Fetch Data
• Paste the file contents into the text field
• Press Start and Close the window

Detecting the datatype (file format)

Tip: Detecting the datatype (file format)

• Click on the galaxy-pencil pencil icon for the dataset to edit its attributes
• In the central panel, click on the galaxy-chart-select-data Datatypes tab on the top
• Click the Detect datatype button to have Galaxy try to autodetect it.

Renaming a dataset

Tip: Renaming a dataset

• Click on the galaxy-pencil pencil icon for the dataset to edit its attributes
• In the central panel, change the Name field
• Click the Save button

Upload few files (1-10)

Tip: Upload few files (1-10)

1. Click on Upload Data on the top of the left panel
2. Click on Choose local file and select the files or drop the files in the Drop files here part
3. Click on Start
4. Click on Close

Upload many files (>10) via FTP

Tip: Upload many files (>10) via FTP

1. Make sure to have an FTP client installed

   There are many options. We can recommend FileZilla, a free FTP client that is available on Windows, MacOS, and Linux.

2. Establish FTP connection to the Galaxy server
   1. Provide the Galaxy server’s FTP server name (e.g. usegalaxy.org, ftp.usegalaxy.eu)
   2. Provide the username (usually the email address) and the password on the Galaxy server
   3. Connect

3. Add the files to the FTP server by dragging/dropping them or right clicking on them and uploading them

   The FTP transfer will start. We need to wait until they are done.

4. Open the Upload menu on the Galaxy server
5. Click on Choose FTP file on the bottom
6. Select files to import into the history
7. Click on Start

Features

---

Using the Scratchbook to view multiple datasets

Tip: Using the Scratchbook to view multiple datasets

If you would like to view two or more datasets at once, you can use the Scratchbook feature in Galaxy:

1. Click on the Scratchbook icon galaxy-scratchbook on the top menu bar.
   • You should see a little checkmark on the icon now
2. View galaxy-eye a dataset by clicking on the eye icon galaxy-eye to view the output
   • You should see the output in a window overlayed over Galaxy
   • You can resize this window by dragging the bottom-right corner
3. Click outside the file to exit the Scratchbook
4. View galaxy-eye a second dataset from your history
   • You should now see a second window with the new dataset
   • This makes it easier to compare the two outputs
5. Repeat this for as many files as you would like to compare
6. You can turn off the Scratchbook galaxy-scratchbook by clicking on the icon again

Why not use Excel?

Excel is a fantastic tool and a great place to build simple analysis models, but when it comes to scaling, Galaxy wins every time.

Tip: Why not use Excel?

You could just as easily use Excel to answer the same question, and if the goal is to learn how to use a tool, then either tool would be great! But what if you are working on a question where your analysis matters? Maybe you are working with human clinical data trying to diagnose a set of symptoms, or you are working on research that will eventually be published and maybe earn you a Nobel Prize?

In these cases your analysis, and the ability to reproduce it exactly, is vitally important, and Excel won’t help you here. It doesn’t track changes and it offers very little insight to others on how you got from your initial data to your conclusions.

Galaxy, on the other hand, automatically records every step of your analysis. And when you are done, you can share your analysis with anyone. You can even include a link to it in a paper (or your acceptance speech). In addition, you can create a reusable workflow from your analysis that others (or yourself) can use on other datasets.

Another challenge with spreadsheet programs is that they don’t scale to support next generation sequencing (NGS) datasets, a common type of data in genomics, and which often reach gigabytes or even terabytes in size. Excel has been used for large datasets, but you’ll often find that learning a new tool gives you significantly more ability to scale up, and scale out your analyses.

Histories

---

Copy a dataset to a new history

Sometimes you may want to use a dataset in multiple histories. You do not need to re-upload the data, but you can copy datasets from one history to another.

Tip: Copy a dataset to a new history

1. Click on the galaxy-gear icon (History options) on the top of the history panel
2. Click on Copy Dataset

3. Select the desired files

4. Give a relevant name to the “New history”

5. Click on the new history name in the green box that have just appear to switch to this history

Creating a new history

Histories are an important part of Galaxy, most people use a new history for every new analysis. Always make sure to give your histories good names, so you can easily find your results back later.

Tip: Creating a new history

Click the new-history icon at the top of the history panel.

If the new-history is missing:

1. Click on the galaxy-gear icon (History options) on the top of the history panel
2. Select the option Create New from the menu

Import an history

Tip: Import an history

1. Open the link to the shared history
2. Click on the new-history Import history button on the top right
3. Enter a title for the new history
4. Click on Import

Renaming a history

Tip: Renaming a history

1. Click on Unnamed history (or the current name of the history) (Click to rename history) at the top of your history panel
2. Type the new name
3. Press Enter

Searching your history

Tip: Searching your history

To make it easier to find datasets in large histories, you can filter your history by keywords as follows:

1. Click on the search datasets box at the top of the history panel.

   

2. Type a search term in this box
   • For example a tool name, or sample name
3. To undo the filtering and show your full history again, press on the clear search button galaxy-clear next to the search box

Sharing your History

You can share your work in Galaxy. There are various ways you can give access one of your histories to other users.

Tip: Sharing your History

Sharing your history allows others to import and access the datasets, parameters, and steps of your history.

1. Share via link
   • Open the History Options galaxy-gear menu (gear icon) at the top of your history panel
     • galaxy-toggle Make History accessible
     • A Share Link will appear that you give to others
   • Anybody who has this link can view and copy your history
2. Publish your history
   • galaxy-toggle Make History publicly available in Published Histories
   • Anybody on this Galaxy server will see your history listed under the Shared Data menu
3. Share only with another user.
   • Click the Share with a user button at the bottom
   • Enter an email address for the user you want to share with
   • Your history will be shared only with this user.
4. Finding histories others have shared with me
   • Click on User menu on the top bar
   • Select Histories shared with me
   • Here you will see all the histories others have shared with you directly

Note: If you want to make changes to your history without affecting the shared version, make a copy by going to galaxy-gear History options icon in your history and clicking Copy

Undeleting history

undelete your deleted histories

Tip: Undeleting history

• Click on User then select Histories
• Click on Advanced search on the top left side below Saved Histories
• On Status click Deleted
• Select the history you want to undelete using the checkbox on the left side
• Click Undelete button below the deleted histories

Interactive tools

---

Launch JupyterLab

Hands-on: Launch JupyterLab

tip Tip: Launch JupyterLab in Galaxy

Currently JupyterLab in Galaxy is available on Live.useGalaxy.eu, usegalaxy.org and usegalaxy.eu.

hands_on Hands-on: Run JupyterLab

1. Interactive Jupyter Notebook Tool: interactive_tool_jupyter_notebook :
2. Click Execute
3. The tool will start running and will stay running permanently
4. Click on the User menu at the top and go to Active Interactive Tools and locate the JupyterLab instance you started.
5. Click on your JupyterLab instance

tip Tip: Launch Try JupyterLab if not available on Galaxy

If JupyterLab is not available on the Galaxy instance:

1. Start Try JupyterLab

Open a Terminal in Jupyter

Hands-on: Open a Terminal in Jupyter

This tutorial will let you accomplish almost everything from this view, running code in the cells below directly in the training material. You can choose between running the code here, or opening up a terminal tab in which to run it.Here are some instructions for how to do this on various environments.

Jupyter on UseGalaxy.* and MyBinder.org

1. Use the File → New → Terminal menu to launch a terminal.

   

2. Disable “Simple” mode in the bottom left hand corner, if it activated.

   

3. Drag one of the terminal or notebook tabs to the side to have the training materials and terminal side-by-side

   

CoCalc

1. Use the Split View functionality of cocalc to split your view into two portions.

   

2. Change the view of one panel to a terminal

   

Open interactive tool

Tip: Open interactive tool

1. Go to User > Active InteractiveTools
2. Wait for the to be running (Job Info)
3. Click on

Launch RStudio

Hands-on: Launch RStudio

Depending on which server you are using, you may be able to run RStudio directly in Galaxy. If that is not available, RStudio Cloud can be an alternative.

tip Tip: Launch RStudio in Galaxy

Currently RStudio in Galaxy is only available on UseGalaxy.eu and UseGalaxy.org

1. Open the Rstudio tool tool by clicking here
2. Click Execute
3. The tool will start running and will stay running permanently
4. Click on the “User” menu at the top and go to “Active InteractiveTools” and locate the RStudio instance you started.

tip Tip: Launch RStudio Cloud if not available on Galaxy

If RStudio is not available on the Galaxy instance:

1. Register for RStudio Cloud, or login if you already have an account
2. Create a new project

Stop RStudio

Hands-on: Stop RStudio

When you have finished your R analysis, it’s time to stop RStudio.

1. First, save your work into Galaxy, to ensure reproducibility:
   1. You can use gx_put(filename) to save individual files by supplying the filename
   2. You can use gx_save() to save the entire analysis transcript and any data objects loaded into your environment.
2. Once you have saved your data, you can proceed in 2 different ways:
   • Deleting the corresponding history dataset named RStudio and showing a “in progress state”, so yellow, OR
   • Clicking on the “User” menu at the top and go to “Active InteractiveTools” and locate the RStudio instance you started, selecting the corresponding box, and finally clicking on the “Stop” button at the bottom.

Sequencing

---

Illumina MiSeq sequencing

Illumina MiSeq sequencing

Illumina MiSeq sequencing is based on sequencing by synthesis. As the namesuggests, fluorescent labels are measured for every base that bind at aspecific moment at a specific place on a flow cell. These flow cells arecovered with oligos (small single strand DNA strands). In the librarypreparation the DNA strands are cut into small DNA fragments (differs perkit/device) and specific pieces of DNA (adapters) are added, which arecomplementary to the oligos. Using bridge amplification large amounts ofclusters of these DNA fragments are made. The reverse string is washed away,making the clusters single stranded. Fluorescent bases are added one by one,which emit a specific light for different bases when added. This is happeningfor whole clusters, so this light can be detected and this data is basecalled(translation from light to a nucleotide) to a nucleotide sequence (Read). Forevery base a quality score is determined and also saved per read. Thisprocess is repeated for the reverse strand on the same place on the flowcell, so the forward and reverse reads are from the same DNA strand. Theforward and reversed reads are linked together and should always be processedtogether!

For more information watch this video from Illumina

Nanopore sequencing

Nanopore sequencing

Nanopore sequencing has several properties that make it well-suited for our purposes

1. Long-read sequencing technology offers simplified and less ambiguous genome assembly
2. Long-read sequencing gives the ability to span repetitive genomic regions
3. Long-read sequencing makes it possible to identify large structural variations

When using Oxford Nanopore Technologies (ONT) sequencing, the change inelectrical current is measured over the membrane of a flow cell. Whennucleotides pass the pores in the flow cell the current change is translated(basecalled) to nucleotides by a basecaller. A schematic overview is given inthe picture above.

When sequencing using a MinIT or MinION Mk1C, the basecalling software ispresent on the devices. With basecalling the electrical signals are translatedto bases (A,T,G,C) with a quality score per base. The sequenced DNA strand willbe basecalled and this will form one read. Multiple reads will be stored in afastq file.

Tools

---

Re-running a tool

Tip: Re-running a tool

1. Expand one of the output datasets of the tool (by clicking on it)
2. Click re-run galaxy-refresh the tool

This is useful if you want to run the tool again but with slightly different paramters, or if you just want to check which parameter setting you used.

Selecting a datast collection as input

Tip: Selecting a datast collection as input

1. Click on param-collection Dataset collection in front of the input parameter you want to supply the collection to.
2. Select the collection you want to use from the list

Select multiple datasets

Tip: Select multiple datasets

1. Click on param-files Multiple datasets
2. Select several files by keeping the Ctrl (orCOMMAND) key pressed and clicking on the files of interest

User preferences

---

Getting your API key

Tip: Getting your API key

1. In your browser, open your Galaxy homepage
2. Log in, or register a new account, if it’s the first time you’re logging in
3. Go to User -> Preferences in the top menu bar, then click on Manage API key
4. If there is no current API key available, click on Create a new key to generate it
5. Copy your API key to somewhere convenient, you will need it throughout this tutorial

Workflows

---

Annotate a workflow

Tip: Annotate a workflow

• Open the workflow editor for the workflow
• Click on galaxy-pencil Edit Attributes on the top right
• Write a description of the worklow in the Annotation box
• Add a tag (which will help to search for the workflow) in the Tags section

Creating a new workflow

You can create a Galaxy workflow from scratch in the Galaxy workflow editor.

Tip: Creating a new workflow

1. Click Workflow on the top bar
2. Click the new workflow galaxy-wf-new button
3. Give it a clear and memorable name
4. Clicking Save will take you directly into the workflow editor for that workflow
5. Need more help? Please see the How to make a workflow subsection here

Opening the workflow editor

Tip: Opening the workflow editor

1. Click on the name of the imported workflow
2. Select the Edit workflow to open the workflow in the workflow editor

Extracting a workflow from your history

Galaxy can automatically create a workflow based on the analysis you have performed in a history. This means that once you have done an analysis manually once, you can easily extract a workflow to repeat it on different data.

Tip: Extracting a workflow from your history

1. Clean up your history: remove any failed (red) jobs from your history by clicking on the galaxy-cross button.

   This will make the creation of the workflow easier.

2. Click on galaxy-gear (History options) at the top of your history panel and select Extract workflow.

   

   The central panel will show the content of the history in reverse order (oldest on top), and you will be able to choose which steps to include in the workflow.

3. Replace the Workflow name to something more descriptive.

4. Rename each workflow input in the boxes at the top of the second column.

5. If there are any steps that shouldn’t be included in the workflow, you can uncheck them in the first column of boxes.

6. Click on the Create Workflow button near the top.

   You will get a message that the workflow was created.

Hiding intermediate steps

Tip: Hiding intermediate steps

When a workflow is executed, the user is usually primarily interested in the final product and not in all intermediate steps.By default all the outputs of a workflow will be shown, but we can explicitly tell Galaxy which outputs to show and which to hide for a given workflow.This behaviour is controlled by the little checkbox in front of every output dataset:

Importing a workflow

Tip: Importing a workflow

• Click on Workflow on the top menu bar of Galaxy. You will see a list of all your workflows.
• Click on the upload icon galaxy-upload at the top-right of the screen
• Provide your workflow
  • Option 1: Paste the URL of the workflow into the box labelled “Archived Workflow URL”
  • Option 2: Upload the workflow file in the box labelled “Archived Workflow File”
• Click the Import workflow button

Importing a workflow using the search

Tip: Importing a workflow using the search

• Click on Workflow on the top menu bar of Galaxy. You will see a list of all your workflows.
• Click on the galaxy-upload Import icon at the top-right of the screen

• Click on search form in Import a Workflow from Configured GA4GH Tool Registry Servers (e.g. Dockstore)

• Select the relevant TRS Server

• Type the query

• Expand the correct workflow

• Click on the wanted version

  The workflow will be imported in your workflows

Setting parameters at run-time

Tip: Setting parameters at run-time

1. Open the workflow editor
2. Click on the tool in the workflow to get the details of the tool on the right-hand side of the screen.
3. Scroll down to the parameter you want users to provide every time they run the workflow
4. Click on the arrow in front of the name workflow-runtime-toggle to toggle to set at runtime

Make a workflow public

Tip: Make a workflow public

• Click on Workflow on the top menu bar of Galaxy. You will see a list of all your workflows
• Click on the interesting workflow
• Click on Share
• Clik on *Make Workflow Accessible and Publish**

Renaming workflow outputs

Tip: Renaming workflow outputs

1. Open the workflow editor
2. Click on the tool in the workflow to get the details of the tool on the right-hand side of the screen.
3. Scroll down to the Configure Output section of your desired parameter, and click it to expand it.

   • Under Rename dataset, give it a meaningful name

     

Viewing a workflow report

When creating a workflow in Galaxy, you can also define an output report page that should be created. Here you can display certain outputs of the pipeline (e.g. output files, tables, images, etc.) and other information about the run.

Tip: Viewing a workflow report

• Go to User on the top menu bar of Galaxy.
• Click on Workflow invocations
  • Here you will find a list of all the workflows you have run
• Click on the name of a workflow invocation to expand it
• Click on View Report to go to the workflow report page
• Note: The report can also be downloaded in PDF format by clicking on the galaxy-wf-report-download icon.

Running a workflow

Tip: Running a workflow

• Click on Workflow on the top menu bar of Galaxy. You will see a list of all your workflows.
• Click on the workflow-run (Run workflow) button next to your workflow
• Configure the workflow as needed
• Click the Run Workflow button at the top-right of the screen
• You may have to refresh your history to see the queued jobs