diff --git a/_config.yml b/_config.yml
index 457902b1243e9b..035824b89278a1 100644
--- a/_config.yml
+++ b/_config.yml
@@ -137,7 +137,11 @@ icon-tag:
galaxy-eye: far fa-eye
galaxy-gear: fas fa-cog
galaxy-history: fas fa-columns
+ galaxy-dataset-collapse: fa fa-compress
galaxy-history-archive: fas fa-archive
+ galaxy-history-size: fas fa-database
+ galaxy-history-storage-choice: fas fa-hard-drive
+ galaxy-history-refresh: fas fa-arrows-rotate
galaxy-history-input: fas fa-sign-in-alt
galaxy-history-answer: fas fa-sign-out-alt
galaxy-home: fas fa-home
@@ -173,6 +177,7 @@ icon-tag:
help: far fa-question-circle
history-annotate: fas fa-comment
history-share: fas fa-share-alt
+ history-select-multiple: fas fa-check-square
instances: fas fa-globe
interactive_tour: fas fa-magic
keypoints: fas fa-key
@@ -237,6 +242,14 @@ icon-tag:
zenodo_link: far fa-copy
version: fas fa-code-commit
rating: far fa-star
+ dataset-rerun: fas fa-arrow-rotate-right
+ dataset-related-datasets: fas fa-sitemap
+ dataset-visualize: fas fa-chart-bar
+ dataset-save: fas fa-save
+ dataset-link: fas fa-link
+ dataset-question: fas fa-question
+ dataset-info: fas fa-info-circle
+ dataset-undelete: fas fa-trash-can-arrow-up
# To exclude in _site
exclude:
@@ -279,7 +292,7 @@ plugins:
- jekyll-feed
- jekyll-redirect-from
-# An announcement to display on the home page
+# An announcement to play on the home page
#announcement:
# class: success
# title: GTN Celebrates Pride Month
diff --git a/faqs/galaxy/datasets_add_tag.md b/faqs/galaxy/datasets_add_tag.md
index c82834a62a9560..fab7fb6bf33611 100644
--- a/faqs/galaxy/datasets_add_tag.md
+++ b/faqs/galaxy/datasets_add_tag.md
@@ -4,13 +4,37 @@ description: Tags can help you to better organize your history and track dataset
area: datasets
layout: faq
box_type: tip
-contributors: [bebatut,wm75,hexylena,shiltemann]
+contributors: [bebatut,wm75,hexylena,shiltemann,nekrut]
---
+Datasets can be tagged. This simplifies the tracking of datasets across the Galaxy interface. Tags can contain any combination of letters or numbers but cannot contain spaces.
+
+**To tag a dataset**:
+
1. Click on the dataset to expand it
2. Click on **Add Tags** {% icon galaxy-tags %}
-3. Add a tag {% if include.tag %}named `{{include.tag}}` {% else %} starting with `#` {% endif %}
- - Tags starting with `#` will be automatically propagated to the outputs of tools using this dataset.
+3. Add {% if include.tag %} a tag named `{{include.tag}}`{% else %} tag text{% endif %}. Tags starting with `#` will be automatically propagated to the outputs of tools using this dataset (see below).
4. Press Enter
5. Check that the tag appears below the dataset name
+**Tags beginning with `#` are special!**
+
+They are called **Name tags**. The unique feature of these tags is that they *propagate*: if a dataset is labelled with a name tag, all derivatives (children) of this dataset will automatically inherit this tag (see below).
+The figure below explains why this is so useful. Consider the following analysis (numbers in parenthesis correspond to dataset numbers in the figure below):
+
+1. a set of forward and reverse reads (datasets 1 and 2) is mapped against a reference using {% tool Bowtie2 %} generating dataset 3;
+1. dataset 3 is used to calculate read coverage using {% tool BedTools Genome Coverage %} *separately* for `+` and `-` strands. This generates two datasets (4 and 5 for plus and minus, respectively);
+1. datasets 4 and 5 are used as inputs to {% tool Macs2 broadCall %} datasets generating datasets 6 and 8;
+1. datasets 6 and 8 are intersected with coordinates of genes (dataset 9) using {% tool BedTools Intersect %} generating datasets 10 and 11.
+
+
+
+Now consider that this analysis is done without name tags. This is shown on the left side of the figure. It is hard to trace which datasets contain "plus" data versus "minus" data. For example, does dataset 10 contain "plus" data or "minus" data? Probably "minus" but are you sure? In the case of a small history like the one shown here, it is possible to trace this manually but as the size of a history grows it will become very challenging.
+
+The right side of the figure shows exactly the same analysis, but using name tags. When the analysis was conducted datasets 4 and 5 were tagged with `#plus` and `#minus`, respectively. When they were used as inputs to Macs2 resulting datasets 6 and 8 automatically inherited them and so on... As a result it is straightforward to trace both branches (plus and minus) of this analysis.
+
+More information is in a [dedicated #nametag tutorial]({% link topics/galaxy-interface/tutorials/name-tags/tutorial.md %}).
+
+
+
+
diff --git a/faqs/galaxy/datasets_deleting.md b/faqs/galaxy/datasets_deleting.md
new file mode 100644
index 00000000000000..b960de7e1971c5
--- /dev/null
+++ b/faqs/galaxy/datasets_deleting.md
@@ -0,0 +1,41 @@
+---
+title: How to delete datasets?
+area: datasets
+box_type: tip
+layout: faq
+contributors: [nekrut]
+---
+
+**Deleting datasets individually**
+
+To delete datasets individually simply click the {% icon galaxy-delete %} button with dataset's box. That's it! This action is reversible: datasets can be undeleted.
+
+**Deleting datasets in bulk**
+
+To delete multiple datasets at once:
+
+- Click {% icon history-select-multiple %} icon at the top of the history pane;
+- Select datasets you want to delete;
+- Click the dropdown that would appear at the top of the history;
+- Select **"Delete"** option.
+
+This action is also reversible: datasets can be undeleted.
+
+
+
+**Deleting datasets permanently** {% icon warning %} Danger zone!
+
+> Permanent is ... PERMANENT!
+> Datasets deleted in this fashion CANNOT be undeleted!
+{: .warning}
+
+To delete multiple datasets PERMANENTLY:
+
+- Click {% icon history-select-multiple %} icon at the top of the history pane;
+- Select datasets you want to delete;
+- Click the dropdown that would appear at the top of the history;
+- Select **"Delete (permanently)"** option.
+
+
+
+
diff --git a/faqs/galaxy/datasets_hidden.md b/faqs/galaxy/datasets_hidden.md
index f47cf47a07cb99..f44550ac4ba508 100644
--- a/faqs/galaxy/datasets_hidden.md
+++ b/faqs/galaxy/datasets_hidden.md
@@ -1,15 +1,18 @@
---
-title: How to unhide "hidden datasets"?
+title: How to hide datasets?
area: datasets
box_type: tip
layout: faq
-contributors: [jennaj, beachyesh]
+contributors: [jennaj, beachyesh, nekrut]
---
-If you have run a workflow with hidden datasets, in your History:
-- Click the **gear icon** {% icon galaxy-gear %} → Click **Unhide Hidden Datasets**
-- Or use the toggle ``hidden`` to view them
+To hide datasets:
+
+- Click {% icon history-select-multiple %} icon at the top of the history pane;
+- Select datasets you want to hide;
+- Click the dropdown that would appear at the top of the history;
+- Select **"Hide"** option.
+
+
+
-When using the [Copy Datasets]({% link faqs/galaxy/histories_copy_dataset.md %}) feature, hidden datasets will not be available to transfer from the **Source History** list of datasets. To include them:
-1. Click the **gear icon** {% icon galaxy-gear %} → Click **Unhide Hidden Datasets**
-2. Click the **gear icon** {% icon galaxy-gear %} → Click **Copy Datasets**
diff --git a/faqs/galaxy/datasets_multiple.md b/faqs/galaxy/datasets_multiple.md
new file mode 100644
index 00000000000000..877f870e637cb0
--- /dev/null
+++ b/faqs/galaxy/datasets_multiple.md
@@ -0,0 +1,18 @@
+---
+title: Manipulating multiple history datasets
+description: Explains how to manipulate multiple history datasets at once
+area: histories
+layout: faq
+box_type: tip
+contributors: [nekrut]
+---
+
+You can also hide, delete, and purge multiple datasets at once by **multi-selecting datasets**:
+
+1. {% icon galaxy-selector %} Click the multi-select button containing the checkbox just below the history size.
+2. Checkboxes will appear inside each dataset in the history.
+3. Scroll and click the checkboxes next to the datasets you want to manage.
+4. Click the 'n of N selected' to choose the action. The action will be performed on all selected datasets, except for the ones that don't support the action. That is, if an action doesn't apply to a selected dataset, like deleting a deleted dataset, nothing will happen to that dataset, while all other selected datasets will be deleted.
+6. You can click the multi-select button again to hide the checkboxes.
+
+
diff --git a/faqs/galaxy/datasets_undelete.md b/faqs/galaxy/datasets_undelete.md
new file mode 100644
index 00000000000000..635e032743f4cb
--- /dev/null
+++ b/faqs/galaxy/datasets_undelete.md
@@ -0,0 +1,24 @@
+---
+title: How to un-delete datasets?
+area: datasets
+box_type: tip
+layout: faq
+contributors: [nekrut]
+---
+
+If your history contains deleted datasets you will see {% icon galaxy-delete %} **"Include deleted"** button directly above dataset display.
+
+To un-delete datasets:
+
+- Type `deleted:true` in the search box
+- Select datasets you want to un-delete
+- Click the dropdown that would appear at the top of the history;
+- Select **"Undelete"** option.
+
+
+
+Alternatively, you can:
+
+- click {% icon galaxy-delete %} **"Include deleted"** button directly above dataset display. This will cause deleted datasets to appear in history along with normal (un-deleted) datasets;
+- deleted datasets are distinguished by having {% icon dataset-undelete %} within dataset box. Clicking on this icon will un-delete a given dataset;
+
diff --git a/faqs/galaxy/datasets_unhidden.md b/faqs/galaxy/datasets_unhidden.md
new file mode 100644
index 00000000000000..9c4b766419beb7
--- /dev/null
+++ b/faqs/galaxy/datasets_unhidden.md
@@ -0,0 +1,24 @@
+---
+title: How to un-hide datasets?
+area: datasets
+box_type: tip
+layout: faq
+contributors: [nekrut]
+---
+
+If your history contains hidden datasets you will see {% icon galaxy-show-hidden %} **"Include hidden"** button directly above the dataset display.
+
+To un-hide datasets:
+
+- Type `visible:hidden` in the search box
+- Select datasets you want to un-hide
+- Click the dropdown that would appear at the top of the history;
+- Select **"Unhide"** option.
+
+
+
+Alternatively, you can:
+
+- click {% icon galaxy-show-hidden %} **"Include hidden"** button directly above dataset display. This will cause hidden datasets to appear in history along with normal (un-hidden) datasets;
+- hidden datasets are distinguished by having {% icon galaxy-show-hidden %} within dataset box. Clicking on this icon will un-hide a given dataset;
+
diff --git a/faqs/galaxy/histories_annotation.md b/faqs/galaxy/histories_annotation.md
new file mode 100644
index 00000000000000..94d52c21104ed4
--- /dev/null
+++ b/faqs/galaxy/histories_annotation.md
@@ -0,0 +1,24 @@
+---
+title: History annotation
+description: Explains how to annotate a history
+area: histories
+box_type: tip
+layout: faq
+contributors: [nekrut]
+---
+
+Sometimes tags and names are not enough to describe the work done within a history. Galaxy allows you to create history
+annotations: longer text entries that allow for more formatting options. The formatting of the text is preserved. Later, if
+you publish or share the history, the annotation will be displayed automatically - allowing you to share additional
+notes about the analysis. Multiple lines, spaces, and emoji! 😹🏳️⚧️🌈 can be used while writing annotations.
+
+To annotate a history:
+
+1. Click on {% icon galaxy-pencil %} (**Edit**) next to the history name. A larger text section will appear displaying any
+ existing annotation or `Annotation (optional)` if empty.
+2. Add your text. Enter will move the cursor to the next line. (Tabs cannot be
+ entered since the 'Tab' button is used to switch between controls on the page - tabs can be pasted in, however).
+3. Click on **Save** {% icon galaxy-save %}.
+4. To cancel, click the {% icon galaxy-undo %} "Cancel" button.
+
+
diff --git a/faqs/galaxy/histories_create_new.md b/faqs/galaxy/histories_create_new.md
index 6fca7a69eb9500..697d460606b4ec 100644
--- a/faqs/galaxy/histories_create_new.md
+++ b/faqs/galaxy/histories_create_new.md
@@ -7,9 +7,8 @@ layout: faq
contributors: [bebatut,wm75,shiltemann,hexylena,nomadscientist,nsoranzo,nekrut]
---
-Click the {% icon new-history %} icon at the top of the history panel:
+To create a new history simply click the {% icon new-history %} icon at the top of the history panel:
-
-
\ No newline at end of file
+
diff --git a/faqs/galaxy/histories_dataset_colors.md b/faqs/galaxy/histories_dataset_colors.md
new file mode 100644
index 00000000000000..1e52f6bf891b7f
--- /dev/null
+++ b/faqs/galaxy/histories_dataset_colors.md
@@ -0,0 +1,33 @@
+---
+title: Dataset colors
+description: Explains meaning of dataset colors in Galaxy's history
+area: histories
+box_type: tip
+layout: faq
+contributors: [nekrut]
+---
+
+There are several different "states" a dataset can be in. These states are indicated by colors:
+
+
+
+- **ok**: everything is fine, life is good;
+- **new**: the dataset was just created. Galaxy does not yet know when it is;
+- **queued**: indicates that the job generating this dataset is scheduled for execution but not running yet;
+- **running**: job generating this dataset is running;
+- **setting metadata**: when a new dataset is uploaded Galaxy examines it to understand what kind of data it is (e.g., BAM, FASTQ, fasta, BED, etc.). This is called "setting metadata";
+- **deferred**: sometimes it does not make sense to upload the dataset until it is needed for an analysis. Galaxy will download **deferred** datasets later during the job execution. Those datasets do not count toward your quota;
+- **paused**: in some cases as, for example, workflow executions, upstream errors prevent subsequent jobs from starting creating datasets in "paused" state;
+- **discarded**: something went wrong such as, for example, a job producing this dataset might have been cancelled;
+- **error**: everything is not fine; life is bad!
+- **placeholder**: similar to "new"; we know something will be there but are not yet sure what;
+- **failed populated state**: this refers to collections (not individual datasets). Here a collection has failed to be populated with datasets;
+- **new populated state**: this refers to collections (not individual datasets). A collection was created but not populated yet.
+
+
+
+
diff --git a/faqs/galaxy/histories_dataset_item.md b/faqs/galaxy/histories_dataset_item.md
new file mode 100644
index 00000000000000..69dcb30da23020
--- /dev/null
+++ b/faqs/galaxy/histories_dataset_item.md
@@ -0,0 +1,52 @@
+---
+title: Dataset snippet
+description: Describes features of a single dataset element in the history
+area: histories
+box_type: tip
+layout: faq
+contributors: [nekrut]
+---
+
+A single Galaxy dataset can either be "collapsed" or "expanded".
+
+**Collapsed dataset view**
+
+Datasets in the panel are initially shown in a "collapsed" view:
+
+
+
+It contains the following elements:
+
+- **Dataset number**: ("1") order of dataset in the history;
+- **Dataset name**: ("M117-bl_1.fq.gz") its name;
+- {% icon galaxy-eye %}: click this to view the dataset contents;
+- {% icon galaxy-pencil %}: click this to edit dataset properties;
+- {% icon galaxy-delete %}: click this to delete the dataset from the history (*don't worry*, you can undo this action!).
+
+Clicking on a collapsed dataset will expand it.
+
+> Some buttons can be disabled.
+> Some of the buttons above may be disabled if the dataset is in a state that doesn't allow the
+> action. For example, the 'edit' button is disabled for datasets that are still queued or running
+>
+{: .details}
+
+**Expanded dataset view**
+
+Expanded dataset view adds a preview element and many additional controls.
+
+
+
+In addition to the elements described above for the collapsed dataset, its expanded view contains:
+
+- **Add tags** {% icon galaxy-tags %}: click on this to tag this dateset;
+- **Dataset size**: ("2 variants, 18 comments") lists the size of the dataset. When datasets are small (like in this example) the exact size is shown. For large datasets, Galaxy gives an approximate estimate.
+- **format**: ("VCF") lists the datatype;
+- **database**: ("?") lists which genome built this dataset corresponds to. This usually lists "?" unless the genome build is set explicitly or the dataset is derived from another dataset with defined genome build information;
+- **info field**: ("INFO [2024-03-26 12:08:53,435]...") displays information provided by the tool that generated this dataset. This varies widely and depends on the type of job that generated this dataset.
+- {% icon dataset-save %}: Saves dataset to disk;
+- {% icon dataset-link %}: Copies dataset link into clipboard;
+- {% icon dataset-info %}: Displays additional details about the dataset in the center pane;
+- {% icon dataset-rerun %}: Reruns job that generated this dataset. This button is unavailable for datasets uploaded into history because they were not produced by a Galaxy tool;
+- {% icon dataset-visualize %}: Displays visualization options for this dataset. The list of options is dependent on the datatype;
+- {% icon dataset-related-datasets %}: Shows datasets related to this dataset. This is useful for tracking down parental datasets - those that were used as inputs into a job that produced this particular dataset.
diff --git a/faqs/galaxy/histories_datasets_vs_collections.md b/faqs/galaxy/histories_datasets_vs_collections.md
new file mode 100644
index 00000000000000..75066db99e67e1
--- /dev/null
+++ b/faqs/galaxy/histories_datasets_vs_collections.md
@@ -0,0 +1,33 @@
+---
+title: Datasets versus collections
+description: Explanation of why collections are needed and what they are
+area: collections, histories
+box_type: tip
+layout: faq
+contributors: [nekrut]
+---
+
+**Datasets versus collections**
+
+In Galaxy's history datasets can be present as individual entries or they can be combined into *Collections*. Why do we need collections? Collections combine multiple individual
+datasets into a single entity which is easy to manage. Galaxy tools can use collections directly as inputs. Collection can be **simple** or **nested**.
+
+**Simple collections**
+
+Imagine that you've uploaded a hundred FASTQ files corresponding to a hundred samples. These will appear as a hundred individual datasets in your history making it very long.
+But the chances are that when you analyze these data you will do the same thing on each dataset.
+
+To simplify this process you can combine all hundred datasets into a single entity called a *dataset collection* (or simply a *collection* or a *list*). It will appear as a single box in your history making it much easier to understand. Galaxy tools are designed to take collections as inputs. So, for example, if you want to map each of these datasets against a reference genome using, say, {% tool Minimap2 %}, you will need to provide `minmap2` with just one input, the collection, and it will automatically start 100 jobs behind the scenes and will combine all outputs into a single collection containing BAM files.
+
+
+
+There is a number of situations when simple collections are not sufficient to reflect the complexity of the data. To deal with this situation Galaxy allows for **nested** collections.
+
+**Nested collections**
+
+Probably the most common example of this is pared end data when each sample is represented by two files: one containing forward reads and another containing reverse reads. In Galaxy you can create **nested** collection that reflects the hierarchy of the data. In the case of paired data Galaxy supports **paired** collections.
+
+
+
+
+
diff --git a/faqs/galaxy/histories_options.md b/faqs/galaxy/histories_options.md
new file mode 100644
index 00000000000000..e16c299dbd03f9
--- /dev/null
+++ b/faqs/galaxy/histories_options.md
@@ -0,0 +1,25 @@
+---
+title: History options
+description: Explains different history options
+area: histories
+box_type: tip
+layout: faq
+contributors: [nekrut]
+---
+
+Clicking the {% icon galaxy-history-options %} button will open a drop-down menu with several options:
+
+- **Show histories side-by-side** - brings up a view in which multiple histories can be viewed and manipulated simultaneously. Datasets can be dragged between histories in this view.
+- **Resume Paused Jobs** - restarts paused jobs in history.
+- **Copy this history** - creates an exact copy of the current history in the current account.
+- **Delete this history** - deletes the current history.
+- **Export tool citations** - export citations for tools that were used in the current history.
+- **Export history to File** - creates a compressed archive containing data from the current history.
+- **Archive history** - moves history to a non-active, archived, state.
+- **Extract workflow** - converts the current history into a workflow
+- **Show invocations** - shows a list of all workflows that were run in the current history
+- **Share or Publish** - allows controlling access to history. It can be made public or shared with a specific user.
+- **Set Permissions** - allows to set the rules on who can access daysets in the current history.
+- **Make Private** - resets all permission and makes the current history private.
+
+
diff --git a/faqs/galaxy/histories_rename.md b/faqs/galaxy/histories_rename.md
index a80aa0240548b6..2277c2c59a7dc6 100644
--- a/faqs/galaxy/histories_rename.md
+++ b/faqs/galaxy/histories_rename.md
@@ -1,17 +1,18 @@
---
title: Renaming a history
+description: Explains how to rename a history
area: histories
box_type: tip
layout: faq
-contributors: [bebatut,wm75,shiltemann,hexylena]
+contributors: [bebatut,wm75,shiltemann,hexylena,nekrut]
---
-
1. Click on {% icon galaxy-pencil %} (**Edit**) next to the history name (which by default is "Unnamed history")
2. Type the new name{% if include.name %}: `{{ include.name }}`{% endif %}
3. Click on **Save**
+4. To cancel renaming, click the {% icon galaxy-undo %} "Cancel" button
-If you do not have the {% icon galaxy-pencil %} (**Edit**) next to the history name:
+If you do not have the {% icon galaxy-pencil %} (**Edit**) next to the history name (which can be the case if you are using an older version of Galaxy) do the following:
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{% if include.name %}: `{{ include.name }}`{% endif %}
diff --git a/faqs/galaxy/histories_switch.md b/faqs/galaxy/histories_switch.md
new file mode 100644
index 00000000000000..c7889c9faa5a8d
--- /dev/null
+++ b/faqs/galaxy/histories_switch.md
@@ -0,0 +1,12 @@
+---
+title: Switching to an existing history
+description: Shows how to switch to another existing history in your account
+area: histories
+box_type: tip
+layout: faq
+contributors: [nekrut]
+---
+
+To switch to an existing history simply click the {% icon switch-histories %} icon at the top of the history panel. This opens a list of histories existing in a given Galaxy account in the middle part of the interface.
+
+
diff --git a/faqs/galaxy/histories_tagging.md b/faqs/galaxy/histories_tagging.md
new file mode 100644
index 00000000000000..d19747160f8e15
--- /dev/null
+++ b/faqs/galaxy/histories_tagging.md
@@ -0,0 +1,28 @@
+---
+title: History tagging
+description: Explains how to add tags to a history
+area: histories
+box_type: tip
+layout: faq
+contributors: [nekrut]
+---
+
+Tags are short pieces of text used to describe the thing they're attached to and many things in Galaxy can be tagged.
+Each item can have many tags and you can add new tags or remove them at any time. Tags can be another useful way to
+organize and search your data. For instance, you might tag a history with the type of analysis you did in it: `assembly`
+or `variants`. Or you may tag them according to data sources or some other metadata: `long-term-care-facility` or
+`yellowstone-park:2014`.
+
+**To tag a history:**
+
+1. Click on {% icon galaxy-pencil %} (**Edit**) next to the history name (which by default is "Unnamed history").
+2. Click on **Add tags** {% icon galaxy-tags %} and start typing. Any tags that you've used previously will show below your partial entry -
+ allowing you to use this 'autocomplete' data to re-use your previous tags without typing them in full.
+3. Click on **Save** {% icon galaxy-save %}.
+4. To cancel, click the {% icon galaxy-undo %} "Cancel" button.
+
+> Do not use spaces
+> It is strongly recommended to replace spaces in tags with `_` or `-`, as spaces will automatically be removed when the tag is saved.
+{: .warning}
+
+
\ No newline at end of file
diff --git a/faqs/galaxy/histories_top_control_buttons.md b/faqs/galaxy/histories_top_control_buttons.md
new file mode 100644
index 00000000000000..4c51c311591632
--- /dev/null
+++ b/faqs/galaxy/histories_top_control_buttons.md
@@ -0,0 +1,18 @@
+---
+title: Top level history controls
+description: Description of three history buttons for creating a new histiory, switching histories, and opening history options dropdown
+area: histories
+box_type: tip
+layout: faq
+contributors: [nekrut]
+---
+
+Above the current history panel are three buttons:
+
+- The {% icon new-history %} "**Create new history**" button will create an empty history.
+- The {% icon switch-histories %} "**Switch to history**" will open a window letting you easily swap to any of your other histories.
+- The {% icon galaxy-history-options %} "**History options**" (formerly the {% icon galaxy-gear %} "Gear menu") gives you access to advanced options to work with your history.
+
+
+
+
diff --git a/faqs/galaxy/histories_undelete.md b/faqs/galaxy/histories_undelete.md
index b5dabef7e6d931..f50afc4adc64ec 100644
--- a/faqs/galaxy/histories_undelete.md
+++ b/faqs/galaxy/histories_undelete.md
@@ -4,10 +4,14 @@ description: Undelete your deleted histories
area: histories
box_type: tip
layout: faq
-contributors: [gatwirival]
+contributors: [gatwirival,nekrut]
---
-* 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
+
+Deleted histories can be **undeleted**:
+
+1. Select "Histories" from the activity bar on the left
+2. Toggle "Advanced search"
+3. Click "Deleted"
+4. Click on the title of the history you want to un-delete and un-delete it!
+
+
diff --git a/faqs/galaxy/images/histories_undelete.gif b/faqs/galaxy/images/histories_undelete.gif
new file mode 100644
index 00000000000000..2a8a299f666950
Binary files /dev/null and b/faqs/galaxy/images/histories_undelete.gif differ
diff --git a/faqs/galaxy/images/multiselect.gif b/faqs/galaxy/images/multiselect.gif
new file mode 100644
index 00000000000000..2d960cf02c7909
Binary files /dev/null and b/faqs/galaxy/images/multiselect.gif differ
diff --git a/faqs/gtn/gtn_faq_create.md b/faqs/gtn/gtn_faq_create.md
index 6d489619e3309c..876bfcf6fa798b 100644
--- a/faqs/gtn/gtn_faq_create.md
+++ b/faqs/gtn/gtn_faq_create.md
@@ -1,5 +1,6 @@
---
title: Creating a GTN FAQ
+description: An explanation on how to create a GTN faq
area: contributors
layout: faq
box_type: tip
@@ -27,7 +28,7 @@ box_type: tip
layout: faq
contributors: [jennaj, Melkeb]
---
-{% endraw %}
+
- To review all active Datasets in your account, go to **User > Datasets**.
@@ -36,3 +37,4 @@ Notes:
- If you have more than one browser window open, each with a different Galaxy History loaded, the Upload tool will load data into the most recently used history.
- Click on refresh icon {% icon galaxy-refresh %} at the top of the History panel to display the current active History with the datasets.
```
+{% endraw %}
diff --git a/shared/images/datasets_deleting.gif b/shared/images/datasets_deleting.gif
new file mode 100644
index 00000000000000..d5a36baab27fde
Binary files /dev/null and b/shared/images/datasets_deleting.gif differ
diff --git a/shared/images/datasets_hide.gif b/shared/images/datasets_hide.gif
new file mode 100644
index 00000000000000..93665527a3b6a2
Binary files /dev/null and b/shared/images/datasets_hide.gif differ
diff --git a/shared/images/datasets_undeleting.gif b/shared/images/datasets_undeleting.gif
new file mode 100644
index 00000000000000..3a5a041039a6a8
Binary files /dev/null and b/shared/images/datasets_undeleting.gif differ
diff --git a/shared/images/datasets_unhide.gif b/shared/images/datasets_unhide.gif
new file mode 100644
index 00000000000000..6252e5ef0193bb
Binary files /dev/null and b/shared/images/datasets_unhide.gif differ
diff --git a/shared/images/galactic_colors.svg b/shared/images/galactic_colors.svg
new file mode 100644
index 00000000000000..13c4af488c15e2
--- /dev/null
+++ b/shared/images/galactic_colors.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/shared/images/histories_why_nametags.svg b/shared/images/histories_why_nametags.svg
new file mode 100644
index 00000000000000..8f1961f4faa411
--- /dev/null
+++ b/shared/images/histories_why_nametags.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/topics/galaxy-interface/images/annotations.png b/shared/images/history_annotations.png
similarity index 100%
rename from topics/galaxy-interface/images/annotations.png
rename to shared/images/history_annotations.png
diff --git a/shared/images/history_item_collapsed.png b/shared/images/history_item_collapsed.png
new file mode 100644
index 00000000000000..fb80b7d94f60e4
Binary files /dev/null and b/shared/images/history_item_collapsed.png differ
diff --git a/shared/images/history_item_expanded.png b/shared/images/history_item_expanded.png
new file mode 100644
index 00000000000000..1fc71794d46de1
Binary files /dev/null and b/shared/images/history_item_expanded.png differ
diff --git a/shared/images/history_size_storage_views.png b/shared/images/history_size_storage_views.png
new file mode 100644
index 00000000000000..ee32b84a77ac80
Binary files /dev/null and b/shared/images/history_size_storage_views.png differ
diff --git a/topics/galaxy-interface/images/tags.png b/shared/images/history_tags.png
similarity index 100%
rename from topics/galaxy-interface/images/tags.png
rename to shared/images/history_tags.png
diff --git a/shared/images/history_top_level_buttons.svg b/shared/images/history_top_level_buttons.svg
new file mode 100644
index 00000000000000..74878620909360
--- /dev/null
+++ b/shared/images/history_top_level_buttons.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/shared/images/list_of_histories.png b/shared/images/list_of_histories.png
new file mode 100644
index 00000000000000..002ffd80991a8f
Binary files /dev/null and b/shared/images/list_of_histories.png differ
diff --git a/shared/images/paired_collection.svg b/shared/images/paired_collection.svg
new file mode 100644
index 00000000000000..dee7ffcc686bf4
--- /dev/null
+++ b/shared/images/paired_collection.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/shared/images/simple_collection.svg b/shared/images/simple_collection.svg
new file mode 100644
index 00000000000000..b5af01297da75a
--- /dev/null
+++ b/shared/images/simple_collection.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/topics/galaxy-interface/images/details.png b/topics/galaxy-interface/images/details.png
deleted file mode 100644
index 80a524d19d9465..00000000000000
Binary files a/topics/galaxy-interface/images/details.png and /dev/null differ
diff --git a/topics/galaxy-interface/images/history.svg b/topics/galaxy-interface/images/history.svg
new file mode 100644
index 00000000000000..53218f209d69ed
--- /dev/null
+++ b/topics/galaxy-interface/images/history.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/topics/galaxy-interface/images/history_options.png b/topics/galaxy-interface/images/history_options.png
new file mode 100644
index 00000000000000..274f090703cd7d
Binary files /dev/null and b/topics/galaxy-interface/images/history_options.png differ
diff --git a/topics/galaxy-interface/images/summary.png b/topics/galaxy-interface/images/summary.png
deleted file mode 100644
index c77f16df319134..00000000000000
Binary files a/topics/galaxy-interface/images/summary.png and /dev/null differ
diff --git a/topics/galaxy-interface/tutorials/history/tutorial.md b/topics/galaxy-interface/tutorials/history/tutorial.md
index 00cced02e613b5..94a5d90fc7875e 100644
--- a/topics/galaxy-interface/tutorials/history/tutorial.md
+++ b/topics/galaxy-interface/tutorials/history/tutorial.md
@@ -5,6 +5,7 @@ redirect_from:
title: "Understanding Galaxy history system"
zenodo_link: ""
+level: Introductory
questions:
- "How do Galaxy histories work?"
objectives:
@@ -43,19 +44,19 @@ recordings:
---
-{% snippet faqs/gtn/galaxy_tested_with.md version="23.0" %}
+{% snippet faqs/gtn/galaxy_tested_with.md version="24.0" %}
When data is uploaded from your computer or analysis is done on existing data using Galaxy, each output from those steps
generates a dataset. These datasets (and the output datasets from later analysis on them) are stored by Galaxy in
**Histories**.
-## The History
+# The history panel
All users have one 'current' history, which can be thought of as **a workspace** or **a current working directory** in
bioinformatics terms. Your current history is displayed in the right hand side of the main 'Analyze Data' Galaxy page in
what is called the history panel.
-
+
The history panel displays output datasets in the order in which they were created, with the oldest/first shown at the
bottom. As new analyses are done and new output datasets are generated, the newest datasets are added to the top of the
@@ -65,203 +66,127 @@ the history panel. In this way, the history panel displays the history of your *
between them and creating new ones. This can be useful to organize different analyses.
**Anonymous users** (if your Galaxy allows them) are users that have not registered an account. Anonymous users are
-only allowed one history. On our main, public Galaxy server, users are encouraged to register and log in with the
-benefit that they can work on many histories and switch between them.
+only allowed one history. Users are encouraged to register and log in with the benefit that they can work on many histories and switch between them.
> Anonymous Users: Beware
> The histories of anonymous users are only associated through your browser's session. **If you close the browser or
> clear you sessions - that history will be lost!** We can not recover it for you if it is.
{: .warning}
-### History controls
+## Global history controls
-
+{% snippet faqs/galaxy/histories_top_control_buttons.md box_type="none"%}
-Above the current history panel are three buttons: create a new history, history quick switcher, and the history options.
+### {% icon new-history %} "**Create new history**"
-- The {% icon new-history %} 'create new history' button will create an empty history.
-- The {% icon switch-histories %} 'history quick switcher' will open a dialog letting you easily swap to any of your other histories.
-- The {% icon galaxy-history-options %} 'history menu' (formerly the {% icon galaxy-gear %} "Gear menu") gives you access to advanced options to work with your history.
+{% snippet faqs/galaxy/histories_create_new.md box_type="none"%}
-## History Information
+### {% icon switch-histories %} "**Switch to history**"
-Histories also store information in addition to the datasets they contain. They can be named/re-named, tagged, and
-annotated.
+{% snippet faqs/galaxy/histories_switch.md box_type="none"%}
-### Renaming a history
+### {% icon galaxy-history-options %} "**History options**"
-All histories begin with the name 'Unnamed history'. Non-anonymous users can rename the history as they see fit:
-
-1. Click the {% icon galaxy-pencil %} pencil icon next to the history's name
-2. Enter a new name or edit the existing one.
-3. Press Enter, or click "Save" to save the new name. The input field will disappear and the new history name will display.
-4. To cancel renaming, click the {% icon galaxy-undo %} "Cancel" button
-
-### Tagging a history
-
-Tags are short pieces of text used to describe the thing they're attached to and many things in Galaxy can be tagged.
-Each item can have many tags and you can add new tags or remove them at any time. Tags can be another useful way to
-organize and search your data. For instance, you might tag a history with the type of analysis you did in it: `assembly`
-or `variants`. Or you may tag them according to data sources or some other metadata: `long-term-care-facility` or
-`yellowstone park:2014`.
+{% snippet faqs/galaxy/histories_options.md box_type="none"%}
-> Best Practices for Tagging
-> It is strongly recommended to replace spaces in tags with `_` or `-`, as spaces will automatically be removed when the tag is saved.
-{: .comment}
+# History manipulation
-To tag a history:
+## Renaming a history
-1. Click the tag button at the top of the history panel. An input field showing existing tags (if any) will appear.
-2. Begin typing your new tag in the field. Any tags that you've used previously will show below your partial entry -
- allowing you to use this 'autocomplete' data to re-use your previous tags without typing them in full.
-3. Press enter or select one of the previous tags with your arrow keys or mouse.
-4. To remove an existing tag, click the small 'X' on the tag or use the backspace key while in the input field.
+All histories begin with the name 'Unnamed history'. Non-anonymous users can rename the history as they see fit:
-
+{% snippet faqs/galaxy/histories_rename.md box_type="none"%}
-### Annotating a history
+## Tagging a history
-Sometimes tags and names are not enough to describe the work done within a history. Galaxy allows you to create history
-annotations: longer text entries that allow for more formatting options. The formatting of the text is preserved. Later, if
-you publish or share the history, the annotation will be displayed automatically - allowing you to share additional
-notes about the analysis.
+{% snippet faqs/galaxy/histories_tagging.md box_type="none"%}
-To annotate a history:
+## Annotating a history
-1. Click the annotation button at the top of the history panel. A larger text section will appear displaying any
- existing annotation (or, if there's none, italic text saying you can click on the control to create an annotation).
-2. Click the annotation section. A larger input field will appear.
-3. Add your annotations. Enter will move the cursor to the next line. (Tabs cannot be
- entered since the 'Tab' button is used to switch between controls on the page - tabs can be pasted in however).
-4. To save the annotation, click the 'Done' button.
+{% snippet faqs/galaxy/histories_annotation.md box_type="none"%}
-
+## Undeleting ... deleted histories
-### History size
+{% snippet faqs/galaxy/histories_undelete.md box_type="none"%}
-As datasets are added to a history, Galaxy will store them on the server. The total size of these files,
-for all the datasets in a history, is displayed underneath the history name. For example, if a history has 200 megabytes
-of dataset data on Galaxy's filesystem, '{% icon galaxy-chart-select-data %} 200 MB' will be displayed underneath the history name.
-If your Galaxy server uses quotas, the total combined size of all your histories will be compared to your quota. If you're using more than the quota allows, Galaxy will prevent you from running any new jobs until you've deleted some
-datasets and brought that total below the quota.
-## History Panel Datasets
+## History size, storage selection, and views
-Datasets in the history panel show the state of the job that has generated or will generate the data.
+The lower part of the history header contains a number of buttons:
-There are several different 'states' a dataset can be in:
+
-1. When you first upload a file or run a tool, the dataset will be in the **queued** state. This indicates that the
- job that will create this dataset has not yet started and is in line to begin.
-1. When the job starts, the dataset will be in the **running** state. The job that created these datasets is now
- running on Galaxy's cluster.
-1. When the job has completed successfully, the datasets it generated will be in the **ok** state.
-1. If there's been an error while running the tool, the datasets will be in the **error** state.
-1. If a previously running or queued job has been paused by Galaxy, the dataset will be in the **paused** state.
- You can re-start/resume paused jobs using the options menu above the history panel and selecting 'Resume Paused Jobs'.
+> Some buttons are instance-specific
+> The list of buttons shown above may vary depending on which Galaxy instance you are using. For example, at the time of writing the **Preferred storage** {% icon galaxy-history-storage-choice %} button is only available on https://usegalaxy.org.
+{: .warning}
-
+- {% icon galaxy-history-size %} **History size** - shows history storage overview in the central pane of the interface.
+- {% icon galaxy-history-storage-choice %} **Preferred storage location** - allows users to specify where history datasets will be stored. This button is only available on Galaxy instances with scratch storage such as usegalaxy.org. Scratch storage allows users to much larger storage allocation for a limited amount time.
+- {% icon galaxy-show-active %} **Show active** - shows active (non-deleted and non-hidden) datasets in the history.
+- {% icon galaxy-delete %} **Include deleted** - include deleted datasets into the history view. If you delete a dataset is does not disappear unless you explicitly purge it.
+- {% icon galaxy-show-hidden %} **Include hidden** - include hidden datasets into the history view. Any dataset in history can be hidden. For example, workflow executions frequently hide intermediate datasets so that they do now complicate history view. It is a way to hide non-importnat datasets from the view.
-Datasets in the panel are initially shown in a 'summary' view, that only displays:
+# History datasets
-1. A **number** indicating in what order (or what step) this dataset was created,
-2. The dataset **name**.
-3. {% icon galaxy-eye %} **view** button: click this to view the dataset contents in raw format in the browser.
-4. {% icon galaxy-pencil %} **edit** button: click this to edit dataset properties.
-5. {% icon galaxy-delete %} **delete** button: click this to delete the dataset from the history (*don't worry*, you can undo this action).
+So far we only discussed functions and controls affecting the *entrire* history. Yet history is a collection of datasets. Now it is time to discuss interfacse elements of individual datasets.
-
+## Datasets can be individual or bundled into collections
-> Disabled buttons?
-> some of the buttons above may be disabled if the dataset is in a state that doesn't allow the
-> action. For example, the 'edit' button is disabled for datasets that are still queued or running
-{: .tip}
+A history dataset can exist by itself, as an independent entity, or as a part of a **collection**. Collections make it possible to analyze datasets with hundreds of thousands of samples.
-You can click the dataset name and the view will expand to show more details:
+{% snippet faqs/galaxy/histories_datasets_vs_collections.md box_type="none"%}
-1. A short description of the data.
-2. The file **format** (Bed in this case) and the reference sequence (or **database**) for the data (`?` here)
-4. (Optionally) some information/output from the job that produced this dataset.
-5. A row of buttons that allow further actions on the dataset.
-6. A **peek** of the data: a couple of rows of data with the column headers (if available).
+## United Colors of Galaxy: Dataset states
-
+{% snippet faqs/galaxy/histories_dataset_colors.md box_type="none"%}
-> Where are the details?
-> Many of these details are only displayed if the dataset has finished running, is in the 'ok' state, and
-> is not deleted. Otherwise, you may only see a shorter message describing the dataset's state (e.g. 'this dataset
-> is waiting to run')
-{: .tip}
+## Dataset snippet in detail
+{% snippet faqs/galaxy/histories_dataset_item.md box_type="none"%}
## Managing Datasets Individually
### Hiding and unhiding datasets
-Some procedures in Galaxy such as workflows will often **hide** history datasets in order to simplify the history
-and hide intermediate steps of an automated analysis. These hidden datasets won't normally appear in the history panel
-but theyre still mentioned in the history subtitle (the smaller, grey text that appears below the history name). If
-your history has hidden datasets, the number will appear there (e.g. '3 hidden') as a clickable link. If you click this link,
-the hidden datasets are shown. Each hidden dataset has a link in the top of the summary view that allows you to unhide
-it. You can click that link again (which will now be 'hide hidden') to make them not shown again.
+Datasets in Galaxy history can be hidden. This is useful for reducing complexity of history. For example, some intermediate datasets generating during an analysis of workflow execution are not important and there is no need to see them.
-
+#### Hiding datasets
-### Deleting and undeleting datasets
+{% snippet faqs/galaxy/datasets_hidden.md box_type="none"%}
-You can **delete** any dataset in your history by clicking the delete button. This does not immediately remove the
-dataset's data from Galaxy and **it is reversible**. When you delete a dataset from the history, it will be removed
-from the panel but (like hidden datasets) the total number of deleted datasets is shown in the history subtitle as a
-link. Clicking this link (e.g. '3 deleted') will make the deleted datasets visible and each deleted dataset will have a
-link for manually undeleting it, above its title. You can click that link again (which will now be 'hide deleted') to
-make them not shown again.
+#### Unhiding datasets
-
+{% snippet faqs/galaxy/datasets_unhidden.md box_type="none"%}
-### Admins may purge your deleted datasets
+### Deleting and undeleting datasets
-Depending on the policy of your Galaxy server, administrators will often run scripts that search for and purge the
-datasets you've marked as deleted. Often, deleted datasets and histories are purged based on the age of the deletion
-(e.g. datasets that have been marked as deleted for 90 days or more). Check with the administrators of your Galaxy instance to
-find out the policy used.
+You can **delete** any dataset in your history. Unless you explicitly tell Galaxy to delete a dataset permanently (see below) this does not immediately remove the dataset from Galaxy" **it is reversible**. When you delete a dataset from the history, it will be removed from the panel but (just like hidden datasets).
-### Tagging datasets
+#### Deleting datasets
-There are two types of tags that can be used as an additional level of labeling for datasets: **standard tags** and **hashtags**. The standard tags work similarly to history tags described above - they add another level of description to datasets making them easier to find. **Hashtags** (also known as **name tags** or **propagating tags**) are much more powerful as they **propagate** through the analysis:
+{% snippet faqs/galaxy/datasets_deleting.md box_type="none"%}
-
+#### Undeleting datasets
-For more information on name tags, a [dedicated nametag tutorial is available]({% link topics/galaxy-interface/tutorials/name-tags/tutorial.md %}).
+{% snippet faqs/galaxy/datasets_undelete.md box_type="none"%}
-## Managing Multiple Datasets Easily
+> Admins may purge your deleted datasets
+> Depending on the policy of your Galaxy server, administrators may run scripts that search for and purge the
+> datasets you've marked as deleted. Often, deleted datasets and histories are purged based on the age of the deletion
+> (e.g. datasets that have been marked as deleted for 90 days or more). Check with the administrators of your Galaxy instance to
+> find out the policy used.
+{: .comment}
-### Multi-selection
+## Tagging datasets
-You can also hide, delete, and purge multiple datasets at once by **multi-selecting datasets**:
+{% snippet faqs/galaxy/datasets_add_tag.md box_type="none"%}
-1. {% icon galaxy-selector %} Click the multi-select button containing the checkbox just below the history size.
-2. Checkboxes will appear inside each dataset in the history.
-3. Scroll and click the checkboxes next to the datasets you want to manage.
-4. Click the 'n of N selected' to choose the action. The action will be performed on all selected datasets, except for the ones that don't support the action. That is, if an action doesn't apply to a selected dataset - like deleting a deleted dataset - nothing will happen to that dataset, while all other selected datasets will be deleted.
-5. You can click the multi-select button again to hide the checkboxes again.
+## Managing Multiple Datasets Easily
-
+{% snippet faqs/galaxy/datasets_multiple.md box_type="none"%}
{% include topics/galaxy-interface/tutorials/search/search.md %}
-### Undeleting ... deleted histories
-
-If you have not purged a history and have only deleted it, it is possible to 'undelete' it and reverse or undo the deletion.
-Since one of the purposes of deleting histories is to remove them from view, we'll use the interface to specifically
-search for deleted histories and then to undelete the one we're interested in.
-
-There is one way to do this currently: via the saved histories page.
-
-1. Go to the "User" menu at the top
-2. Select "Histories"
-3. Click "Advanced Search" below the search box.
-4. Click "Deleted"
-5. Click on the title of the history you want to un-delete, and un-delete it.