Introduction

Workflows are a powerful Galaxy feature that allows you to scale up your analysis by performing an end-to-end analysis with a single click of a button. In order to aid interpretation of workflow results, workflow reports may be configured to combine and display the most important analysis results in a single, customizable view.

This is especially useful if you are configuring a Galaxy workflow to share with others. Not everybody is familiar with Galaxy, and having all the important results shown on a single page can be very useful.

This tutorial will guide you through the steps of defining such a report for your workflow, and how to view workflow reports after running the workflow.

Agenda

In this tutorial, we will cover:

1. Introduction
2. Import an example workflow
3. Run the workflow and view the default report
4. Customize the workflow report
   1. Add labels to workflow outputs
5. Share or publish your workflow report

Import an example workflow

For this tutorial, we will use the workflow from the Galaxy 101 for everyone tutorial. If you have not done this tutorial yet, the only thing you need to know is that this is a workflow that takes as input a table of data about different species of iris plants, this table is subsequently sorted and filtered, and some plots are made. The specifics of the workflow are not important for this tutorial, only that it outputs a number of different kinds of outputs (images, tables, etc).

We will start by importing this workflow into your Galaxy account:

Hands-on: Import the workflow

1. Import the workflow into Galaxy
   • Copy the URL (e.g. via right-click) of this workflow or download it to your computer.
   • Import the workflow into Galaxy

   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

Run the workflow and view the default report

Galaxy will produce a default report for any workflow. This default report shows the workflow inputs, outputs, and a description of the workflow on a single web page. You will usually want to customize this report yourself, but it provides a good starting point.

Let’s run the workflow and view the default report.

Hands-on: Run the workflow

1. Import Tool: upload1 the file iris.csv via link

   https://zenodo.org/record/1319069/files/iris.csv
   

   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

2. Run GTN Training: Galaxy 101 For Everyone workflow using the following parameters:
   • “Send results to a new history”: No
   • param-file “1: Iris Dataset”“: the iris.csv file we just uploaded

   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

3. View the workflow outputs galaxy-eye once the workflow has completed
   • The workflow produces several text and tabular outputs, and two plot (image) outputs

After the workflow has completed, we can access the workflow report. The report does not appear in your history, but can be accessed from the User -> Workflow Invocations menu on the top bar. An invocation of a workflow means one run (execution) of the workflow.

Hands-on: View the default workflow report

1. In the top menu bar, go to User -> Workflow Invocations

2. Our latest workflow run should be listed at the top.
   • Click on it to expand it:

   

3. Click View Report in the expanded view of the workflow invocation.

4. You should see a page like this. It contains:
   • The input file
   • The (text-based) output files
   • A summary of the workflow itself

   

Customize the workflow report

This is a great start, but we might want to customize this report to fit our needs.

Hands-on: Open the workflow report editor

1. Open the workflow in the workflow editor

   Tip: Opening the workflow editor

   1. In the top menu bar, click on Workflows
   2. Click on the name of the workflow you want to edit
   3. Select galaxy-wf-edit Edit from the dropdown menu to open the workflow in the workflow editor

2. Click on Edit Report galaxy-wf-edit in the top-right of the screen

3. You should see something like the image below, you will find
   • Text editor in the center, with the default report specified in Markdown format
   • A list of components that can be added to the report in the left-hand panel

   

4. Scroll down the report and look at all the components
   • notice that there is no plot image output shown, even though we know that was created, we will add this to the report later.
5. To edit this report, we can edit the markdown directly. For example, let’s
   • change the title of the report to # Iris Analysis

   • add a line of introduction text for whoever will read the report, something like:

      # Workflow Execution Report 
      # Iris analysis
      Below are the results for the Iris analysis workflow.

   Tip: Markdown format

   The report is specified in Markdown format, this is a simple markup language that is commonly used. Some basics of the Markdown syntax can be found in this cheatsheet

6. Let’s play around with some components we can add via the left-hand panel
   • Under the Miscellaneous section in the left-hand menu, select
     • “Galaxy version as text” and
     • “Current Time as text”
   • You will see bits of Markdown are added to your report
   • You can add some text around these parts as well

   • Make sure the beginning of your report looks something like this:

     # Iris Analysis
     Below are the results for the Iris analysis workflow.
     
     This workflow was run on:
     
     ```galaxy
     generate_time()
     ```
     
     With Galaxy version:
     
     ```galaxy
     generate_galaxy_version()
     ```
     

7. Let’s try to add the missing plot outputs as well:
   • On the left-hand panel, under the History section, choose Image
   • You should see a list of outputs to insert into the report:
   • Hmmm, no obvious options to insert the plot outputs. We will need to label the outputs in our workflow first, before we can use them here.
8. But before we do that, let’s save our changes and run the workflow again to view their effects.
   • Click on galaxy-cross (Return to Workflow) in the top-right of the screen.
   • Click on galaxy-save (Save Workflow) to save our changes to the report.
9. Run the workflow again
   • Select iris.csv as the input

   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

10. View the new workflow report, you should see your changes, something like:

    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.

    

In the next section, we will add labels to our workflow outputs to more easily add them to our workflow report

Add labels to workflow outputs

As you saw in the previous step, we might need to edit the workflow to add labels outputs so we can easily distinguish between the outputs when adding them to the report. This is especially useful for large workflows with many outputs.

Hands-on: Add output labels to the workflow

1. Open the workflow in the workflow editor

   Tip: Opening the workflow editor

   1. In the top menu bar, click on Workflows
   2. Click on the name of the workflow you want to edit
   3. Select galaxy-wf-edit Edit from the dropdown menu to open the workflow in the workflow editor

2. Click on one of the Scatterplot tool boxes
   • On the right-hand panel, you should see the settings for the tool
   • Scroll to the bottom and find the Configure Output: .. sections
   • From the box we can see that output1 (the first) is a png output, and output2 is a pdf output of the plot.
   • Let’s use the png output for our report.
   • Also take note of the plot title, since we have 2 runs of the scatterplot tool in this workflow. One plot is about the petals of the iris, and one about the sepals (in this screenshot it is the sepal plot)

   

3. Add an output label for the png output
   • Click on “Configure output: output1”
   • Add a descriptive label (e.g. “Sepal plot (PNG)”)
   • Notice that the label on the box changs as well
4. Repeat this process and add an output label for the other plot as well
   • Label it something like “Petal plot (PNG)”
5. Click on the Unique tool toolbox
   • This tool gives a list of all the unique Iris species found in the dataset
   • Let’s add this to our report as well
   • Add a label to this output (e.g. “Iris Species”)
6. Save galaxy-save the workflow (Important!)

Now that we have added our output labels, let’s go back to our report editor and add these outputs

Hands-on: Open the workflow report editor

1. Open the workflow in the workflow editor (if not already open)

   Tip: Opening the workflow editor

   1. In the top menu bar, click on Workflows
   2. Click on the name of the workflow you want to edit
   3. Select galaxy-wf-edit Edit from the dropdown menu to open the workflow in the workflow editor

2. Click on Edit Report galaxy-wf-edit in the top-right of the screen
   • You should see the report with the changes you made earlier
3. Add the plots and the unique species list outputs to the report
   • Use “Images” in the left-hand panel for the plot outputs
   • Use “Dataset” for the unique species list

   • You should see more options now after the labels we added to the workflow outputs (“Sepal Plot (PNG)”, “Petal Plot (PNG)”, and “Iris Species”)

     

4. Add some text and/or headers before each included output
   • Play around here, add other component you think look interesting and see what happens!

   • The final result may look something like this:

     # Results
     
     ## Species detected
     
     ```galaxy
     history_dataset_display(output="Iris Species")
     ```
     
     ## Sepal plot
     
     ```galaxy
     history_dataset_as_image(output="Sepal Plot (PNG)")
     ```
     
     ## Petal Plot
     
     ```galaxy
     history_dataset_as_image(output="Petal Plot (PNG)")
     ```
     

5. Exit galaxy-cross the report editor

6. Save galaxy-save the workflow

7. Run the workflow once more
   • Use iris.csv as input again

8. View the workflow report

   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.

9. It should look something like:

   

Well done! You have created a customized workflow report with text and workflow outputs. There are a lot more options to explore, for example you can also include:

• links to datasets for easy downloading
• index files (e.g. for BAM or VCF files)
• visualisations
• job metrics
• peeks into dataset (useful for large files that cannot be included in their entirety in the report)
• ..and more!

Share or publish your workflow report

If you share this workflow with others, they will get the same report every time they run the workflow.

If you would like to share the workflow report of a specific run, you can do so by creating a Galaxy page for it. This page can then be shared (either via link or with specific users), or published for all to see under Shared Data -> Pages in the top menu.

Hands-on: Share the workflow report as a Galaxy page

1. Open the workflow report

   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.

2. Click on Edit Markdown galaxy-wf-edit button at the top right (next to “Galaxy Report”)

   • Here you can edit the title and the report itself, if desired

     

   • Click Save galaxy-save

3. You will see your list of Galaxy pages.

   • Note: this list is always accessible via top menu, User -> Pages

     

4. Click on the dropdown icon galaxy-dropdown next to the page title
   • Select “Share or Publish”
   • Here you can make the page public or share with individual users
   • If you make the page public, anybody will be able to see it under Shared Data -> Pages from the top menu bar

Great work! You have viewed, customized and shared a workflow report. This makes it easy to view the most important results of a workflow in a single view. Here is an example of a final workflow from this tutorial

Key points

• Workflow reports help you display the most important results of a workflow in an organized fashion.

• Workflow reports are configured as part of the workflow definition, for every run of the workflow, a report will be automatically created

• Workflow reports can be viewed from the top menu, User -> Workflow Invocations.

• Labels must be added to workflow outputs before they can be included

• Many different components can be added to a workflow report (datasets, images, links to datasets, job metrics, text and sections, visualisations, and much more!)

• Workflow reports can be shared as Galaxy Pages.

Frequently Asked Questions

Have questions about this tutorial? Check out the FAQ page for the Using Galaxy and Managing your Data topic to see if your question is listed there. If not, please ask your question on the GTN Gitter Channel or the Galaxy Help Forum

Feedback

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

1. , 2022 Workflow Reports (Galaxy Training Materials). https://training.galaxyproject.org/training-material/topics/galaxy-interface/tutorials/workflow-reports/tutorial.html Online; accessed TODAY
2. Batut et al., 2018 Community-Driven Data Analysis Training for Biology Cell Systems 10.1016/j.cels.2018.05.012

BibTeX

@misc{galaxy-interface-workflow-reports,
author = "Saskia Hiltemann",
title = "Workflow Reports (Galaxy Training Materials)",
year = "2022",
month = "10",
day = "18"
url = "\url{https://training.galaxyproject.org/training-material/topics/galaxy-interface/tutorials/workflow-reports/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}
}
                   

Congratulations on successfully completing this tutorial!