Workflow Reports

Overview
Creative Commons License: CC-BY Questions:
  • What are workflow reports?

  • How can I view a workflow report?

  • How can I customize a workflow report?

  • How can I share a workflow report with others?

Objectives:
  • Understanding, viewing and creating workflow reports

Time estimation: 30 minutes
Level: Intermediate Intermediate
Supporting Materials:
Published: Jun 2, 2022
Last modification: Mar 13, 2024
License: Tutorial Content is licensed under Creative Commons Attribution 4.0 International License. The GTN Framework is licensed under MIT
purl PURL: https://gxy.io/GTN:T00165
version Revision: 19

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. Import an example workflow
  2. Run the workflow and view the default report
  3. Customize the workflow report
    1. Add labels to workflow outputs
    2. Make your reports nicer!
  4. 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

    Hands-on: Importing and Launching a workflow
    Click here to run Galaxy 101 for Everyone workflow.

    Or copy the URL (e.g. via right-click) of this workflow, and import the workflow into Galaxy

    • Click on Workflow on the top menu bar of Galaxy. You will see a list of all your workflows.
    • Click on galaxy-upload Import 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

    Below is a short video demonstrating how to import a workflow from GitHub using this procedure:

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 the file iris.csv via link

    https://zenodo.org/record/1319069/files/iris.csv
    
    • Copy the link location
    • Click galaxy-upload Upload Data at the top of the tool panel

    • Select galaxy-wf-edit Paste/Fetch Data
    • Paste the link(s) 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
    • 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:

    screenshot of the workflow invocations menu, with our latest invocation at the top.

  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

    screenshot of the beginning of the default workflow report.

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

    1. In the top menu bar, click on Workflows
    2. Click on the name of the workflow you want to edit Workflow drop down menu showing Edit option
    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 screenshot of the "edit report" button in the workflow editor interface.

  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

    screenshot of the workflow report edit interface. Markdown-formatted editor in the center, with 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.

    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: menu for inserting an image output 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. screenshot of the cross button to return to the workflow editor.
    • Click on galaxy-save (Save Workflow) to save our changes to the report. screenshot of the floppy disk button to save the workflow.
  9. Run the workflow again
    • Select iris.csv as the input
    • 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:

    • 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 workflow invocations list
    • 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.

    screenshot of the workflow report with our edits included.

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

    1. In the top menu bar, click on Workflows
    2. Click on the name of the workflow you want to edit Workflow drop down menu showing Edit option
    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)

    screenshot of the workflow editor to add labels to workflow outputs.

  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 screenshot of menu to add labels to the workflow output.
  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)

    1. In the top menu bar, click on Workflows
    2. Click on the name of the workflow you want to edit Workflow drop down menu showing Edit option
    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”)

      the list of datasets available to add, now includes the outputs we labeled in the workflow.

  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

    • 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 workflow invocations list
    • 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:

    screenshot of the final workflow report, with text, 2 plots, and the table of detected species.

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!

Make your reports nicer!

There are a number of options, specifically for tabular data, that can allow it to render more nicely in your workflow reports and pages and anywhere that GalaxyMarkdown is used.

  • title to give your table a title
  • footer allows you to caption your table
  • show_column_headers=false to hide the column headers
  • compact=true to make the table show up more inline, hiding that it was embedded from a Galaxy dataset.

The existing history_dataset_display directive displays the dataset name and some useful context at the expense of potentially breaking the flow of the document

Input: Galaxy Markdown
```galaxy
history_dataset_display(history_dataset_id=1e8ab44153008be8)
```
Output: Example Screenshot

a tabular dataset rendered, it has a title and a download button and sortable columns

The existing history_dataset_embedded directive was implemented to try to inline results more and make the results more readable within a more… curated document. It is dispatches on tabular types and puts the results in a table but the table doesn’t have a lot of options.

Input: Galaxy Markdown
```galaxy
history_dataset_embedded(history_dataset_id=1e8ab44153008be8)
```
Output: Example Screenshot

the same as before but no title nor download button. just a rendered table with sortable columns

The history_dataset_as_table directive mirrors the history_dataset_as_image directive: it tries harder to coerce the data into a table and provides new table—specific options. The first of these is “show_column_headers which defaults to true`.

Input: Galaxy Markdown
```galaxy
history_dataset_as_table(history_dataset_id=1e8ab44153008be8,show_column_headers=false)
```
Output: Example Screenshot

the same as before but no title nor download button nor column headers

There is also a compact option. This provides a much more inline experience for tabular datasets:

Input: Galaxy Markdown
```galaxy
history_dataset_as_table(history_dataset_id=1e8ab44153008be8,show_column_headers=false,compact=true)
```
Output: Example Screenshot

again the same screenshot, no table metadata, and now it lacks the small margin around it.

Figures in general should have titles and legends — so there is the “title” and “footer” options also.

Input: Galaxy Markdown
```galaxy
history_dataset_as_table(history_dataset_id=1e8ab44153008be8,show_column_headers=false,title='Binding Site Results',footer='Here is a very good figure caption for this table.')
```
Output: Example Screenshot

the same table with now a tasteful title and small caption below it describing that the author would write a caption if he knew what a binding site was.

This applies to any GalaxyMarkdown elements, i.e. the things you’ve clicked in the left panel to embed in your Workflow Report or Page

By adding a collapse="" attribute to a markdown element, you can make it collapsible. Whatever you put in the quotes will be the title of the collapsible box.

```
history_dataset_type(history_dataset_id=3108c91feeb505da, collapse="[TITLE]")
```

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

    • 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 workflow invocations list
    • 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

      galaxy interface for creating a Galaxy page from a workflow report.

    • Click Save galaxy-save

  3. You will see your list of Galaxy pages.
    • Note: this list is always accessible via top menu, User -> Pages

      list of our pages, with our newly created workflow report page on top.

  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