Step 1 - Use the following training material to be able to run the GTN website locally: https://training.galaxyproject.org/training-material/topics/contributing/tutorials/running-jekyll/tutorial.html

As the training material is currently written, following the "Installation of the requirements" section and running the "make create-env" step resulted in the following error:

paigekulzer@Paiges-MBP training-material % make create-env
find: _site/training-material: No such file or directory
find: _site/training-material/*/*/slides/*: No such file or directory
find: _site/training-material: No such file or directory
if /Users/paigekulzer/miniconda3/bin/mamba env list | grep '^galaxy_training_material'; then \
	    /Users/paigekulzer/miniconda3/bin/mamba env update -f environment-osx.yml; \
	else \
	    /Users/paigekulzer/miniconda3/bin/mamba env create -f environment-osx.yml; \
	fi
bash: /Users/paigekulzer/miniconda3/bin/mamba: No such file or directory
bash: /Users/paigekulzer/miniconda3/bin/mamba: No such file or directory
make: *** [create-env] Error 127

After troubleshooting with the GTN team, I've successfully worked through the whole tutorial with some different code. The team is planning to update the training material accordingly, but in the meantime, here is the code I used:

## Clone the training material GitHub repository
$ git clone https://github.com/galaxyproject/training-material.git

## Need to speed up the cloning step? Use the following line of code instead:
# git clone https://github.com/galaxyproject/training-material.git --depth 1 --branch main

## Install mamba since the Makefile will use mamba, and conda alone was causing a lot of problems
$ conda update conda
$ conda install mamba -n base -c conda-forge

## From that point, you can simply follow the tutorial
$ make create-env
$ make install

## Check the website generation
$ make serve-quick

## GTN runs at http://localhost:4000/training-material/
## This can be copied into your browser to see changes to the training materials in real time

With the repository now correctly set-up on my computer, I've created an FAQ by adapting an IGV FAQ already published by the GTN and pushed my commit to GitHub. For review, please take a look at the following branch and let me know if there's any more information we might want to add to this FAQ.

Branch: https://github.com/galaxyproject/training-material/compare/main...pkulzerUNC:training-material:visualize-igb
Link to IGV's FAQ on the GTN: https://training.galaxyproject.org/training-material/faqs/galaxy/visualisations_igv.html

Thank you Paige!

For the next steps, could you add these edits, if you approve the language:

• Change title to: "Open History files in Integrated Genome Browser"
• Change "You can view..." to: "You can open and visualize files from your Galaxy History using Integrated Genome Browser (IGB) from BioViz.org." (hyperlink bioviz.org to "https://bioviz.org"
• Change "1. Install..." to "1. Install IGB on your computer. Get IGB from BioViz.org." (same link as above)
• Change "Select a refer..." to "Open the reference genome associated with your History file using the IGB Current Genome tab or by clicking an image on the image home screen. Look at the top of the window to check the genome name."

After step-by-step instructions, we need something that explains to users what they should see, so that they can know if the technology is working, or not. A big issue for people doing a thing for the first time is figuring out whether or not they did the thing correctly. I would maybe add a new section titled: "Check it worked"

Then explain what the user should see if it all worked the way it is supposed, maybe using the same "step by step" syntax. Or you could write a narrative paragraph that addresses the user directly, using second person "you."

"If the above steps worked correctly, you should see"...etc.

I've incorporated the edits suggested above, as well as a final sentence pointing to our User's Guide. Please let me know what you think about this new version!

See: 8-23-24_IGB-FAQ-commit.png

Branch: https://github.com/galaxyproject/training-material/commit/edbd8167ba2ef1722d297fcb9a45df54bf6fa192

Thanks Paige Kulzer! Sorry, I have more edits!

Please add if you are OK with the language:

1. Can you add a header element: "Check it works" to separate the "check it worked" text from the instructions?
3. Can you insert this a new draft of the "check it works" text?

"When you click "view" in Galaxy, your browser opens a new tab showing a page from BioViz.org. View that newly-opened page for next steps.

If you have any problems or questions, contact the ( IGB Team here )!

Link "IGB Team" to a page where people can get help. Or, even better, make a specialized page just for Galaxy users!

I'm wondering if we need more "steps", however? After the user clicks "view in IGB", they might not know what to do next.

Instead of closing this ticket, let's work on it a bit more next week (Tuesday) to improve the instructions to the best of our ability. For me, it would help if we could walk through the actual steps together, using a real-life Galaxy instance.

Then, on Wednesday, we could ask for a volunteer in the office to try the instructions on a computer with Galaxy and IGB set up.

There's a protocol for this type of usability testing that we need to follow, however. We can talk about it on Tuesday. It isn't hard but you need two people - one person to conduct the test and one person to take notes. Other aspect: team needs to do an ibternal "dry run" of the usability test setup, and iterate based on what you find out.

Today, we met to discuss and follow-up on Dr. Loraine's comments above. Here are some ideas about what to change for the next version:

-Remove “from bioviz.org” from the first line
-Add "Here's how:" after the first line to transition into the tutorial
-Send users to download page instead of bioviz.org, say “Install IGB on your computer (IGB download page)”
-Make sure that all sentences are properly punctuated
-Change “Start IGB” in step 2 to “With IGB running:”
-Switch to a fully-numbered list rather than using both numbers and bullet points
-Remove the "Check it works" section title and instead start that first line after the numbered list with "Having trouble?"

I've created a Google Doc version of the training material which can be accessed here: https://docs.google.com/document/d/1ngjJPDNSe5tb3UwGSJe-hwVY__IkAwH-UCFWbzBKneM/edit?usp=sharing

I've incorporated the above suggestions into this new draft. Please take a look at the Google Doc version linked above and let me know if it needs any further changes.

I've also done some additional investigating and found that IGB does not necessarily require the correct reference genome to be pulled up before files can be pulled over from Galaxy. If that genome is not opened in IGB before pulling the file over from Galaxy, IGB will still let you view that data and it loads all of the scaffolds/chromosomes, but there won't be any annotations to view. This is irregardless of whether a reference genome has been set for that file in Galaxy or not. TL;DR The instructions for step 2 as we have them now are probably best.

Additionally, I am still having issues loading .bed and .bedgraph Galaxy History files in IGB. I think we may want to write this up into a separate "investigate" ticket.

List of questions to follow-up with Saskia Hiltemann (my GTN contact) about:

• How can we embed tips/hands-on materials in future long-form tutorials? Regarding FAQs, to embed them in the tutorial text, they can be anywhere, and you just use {% snippet path/to/faq.md %} to insert it into the tutorial text (see also here in the contributing tutorial for more details about how to use this).
• Where is the “Creating a new history” tip showing up in the training materials? Search "Creating a new history" within the GTN, then sort by "Hands-on". There you'll see a list of training materials that contain that tip!
• How to add symlinks of our training materials to other tutorials? via the command line. See: https://github.com/galaxyproject/training-material/commit/beaae5513ec84268a5e423223316e3aba819db50
• Which tutorials are most popular? How do you know that? Most popular tutorials: you can see this in detail on our Plausible page and as you can tell the Reference-based RNA-Seq tutorial is our most popular tutorial, and also most frequently updated one, and uses a lot of advanced features, so I would say that is the place to start for inspiration for your own future tutorial
• Are FAQs just a collection of tips and hands-on materials that get sprinkled throughout other tutorials? Or are they often referenced on their own without any extra context? They can be referenced on their own like we're doing when we test, but there are also "tutorial FAQ pages", for example this one for for RNAseq tutorial that lists all FAQs related to that tutorial on a single page. To render this page the system looks at the "faqs" folder inside the tutorial folder, so if you want it to show up there as well, then you would make a symlink. The same idea also exists on the topic-level, for the most common questions for the topic as a whole.
• Can we add Genome Browsers as a tutorial topic? Good idea regarding the genome browsers. We try to avoid having topics with only a small number of tutorials, but perhaps we can start with having a "genome browsers" subtopic in the visualisations topic, and then renaming the topic to something less vague, maybe just "Visualisations and Genome Browsers"? (open for suggestions here). What do you think?

*Saskia's answers appear above in RED

Thanks for getting the answers!

I made some edits to the google doc - combining aspects of Paige Kulzer's drafts and the IGV FAQ.

One thing we need to do is check what happens if a dbkey is not set for a dataset or if the dbkey is not recognized by IGB.

For testing, we can use some of the Galaxy Histories we've made and deployed into the Public Histories section of the Galaxy web site. Sorry that I did not mention this before Paige! It probably could have helped a lot

To find ones with and without a dbkey set, search for "Freese" or "Loraine" or "IGB" after opening the Public Histories link on the main Galaxy Web site.

Here's an overview of what I've found:

1. With a dbkey set
With the dbkey set to "mm10" for a BAM file in the public history "ChIP-Seq Alignment and Visualization using Galaxy and IGB (Focus on a Feature)", IGB pulled up the mm10 genome automatically upon clicking the "View in IGB" button in Galaxy.

2. Without a dbkey set
With the dbkey set to "unspecified ", IGB loads the BAM file over a blank coordinates track (i.e., a custom genome). Also, an error/warning message appears from bioviz.org, which reads, "The file you are trying to view does not have a genome version associated with it. Please return to Galaxy and associate a genome version with the file and try again."

3. With a custom dbkey set
A custom dbkey for Hypsibius exemplaris was created by the Galaxy team upon my request, so with that set, IGB loads the BAM file over a blank coordinates track (i.e., a custom genome) like it did when no dbkey was set. However, no error/warning messages appear from bioviz.org in this case.

Ann Loraine, please let me know if I can provide any more information that might be helpful!

Ready for PR

PR: https://github.com/galaxyproject/training-material/pull/5397

As part of the review process, I was asked to add my information to the Contributors file: https://github.com/galaxyproject/training-material/blob/main/CONTRIBUTORS.yaml

I have now done that and updated the PR above accordingly. It's awaiting another round of review.

The PR is now merged, so this ticket is ready for review. Check that you can find the new IGB FAQ on the GTN website (https://training.galaxyproject.org/training-material/)!

I could not find the new IGB FAQ.

I looked at the page above and also the page that appeared when I clicked the link labeled "Visualization" but I did not notice an IGB-related FAQ anywhere.

???

Apologies, my instructions were not very clear!

My GTN contact, Saskia, is working on adding a "genome browsers" subtopic to the visualisations topic where we can then put the IGB-related FAQ, but in the meantime we'll need to stick to searching for the IGB-related FAQ using their search bar or by navigating directly to the FAQ by clicking Help > FAQs > Galaxy FAQs > Visualisation.

Here's a link: https://training.galaxyproject.org/training-material/faqs/galaxy/#tip-open-history-files-in-integrated-genome-browser-igb

I looked on several pages claiming to be "FAQs" and "Visualization" related but did not find it.

The new content appears to be unreachable via any existing hyperlinks on the Galaxy Training Network site.

• I was able to find the Tip: Open History files in Integrated Genome Browser (IGB) page at Help > FAQs > Galaxy FAQs > Visualisation
• When I searched in the "Search Tutorials" bar at the top right of https://training.galaxyproject.org/training-material/ for "IGB" the result was for this page: https://training.galaxyproject.org/training-material/faqs/galaxy/visualisations_igb.html

Ann Loraine, here are two different ways to find the new Galaxy training material:

Option 1:

1. Open the following link in a new tab: https://training.galaxyproject.org/training-material/
2. Click Help near the top of the page
3. In the menu that appears, click FAQs
4. Click the tan/yellow box that says Galaxy FAQs
5. In the list towards the left of the page, click Visualisation
6. Click the blue callout button next to the words Open History files in Integrated Genome Browser (IGB)
   You should see the new training material now

Option 2:

1. Open the following link in a new tab: https://training.galaxyproject.org/training-material/
2. In the search bar at the top right of the page, type IGB
3. Hit Enter on your keyboard
4. Click the search result titled "Open History files in Integrated Genome Browser (IGB)"
   You should see the new training material now