Add GTEx Image Learner tutorial for tissue classification using expression-derived images

CONTRIBUTORS.yaml

@@ -223,6 +223,11 @@ alliecreason:
     orcid: 0000-0001-5724-1276
     joined: 2023-02
 
+allissadillman:
+    name: Allissa Dillman
+    email: adillman@biodatasage.com
+    joined: 2026-05
+
 almahmoud:
     name: Alex Mahmoud
     joined: 2019-06

topics/statistics/tutorials/GTEx_Tissue_modeling/README.md

@@ -0,0 +1,43 @@
+# Tutorial - GTEx Tissue Modeling with Galaxy Image Learner
+
+A Galaxy tutorial for converting GTEx v11 gene expression profiles into grayscale images and training an Image Learner tissue classifier.
+
+## Overview
+
+This tutorial shows how to classify GTEx tissues with a no-code Galaxy machine learning tool. The recommended path uses prepared metadata and image files from Zenodo that are ready for Galaxy Image Learner. An optional path shows how to rebuild those files from raw GTEx v11 expression and sample metadata.
+
+## Recommended Zenodo Files
+
+- `selected_gtex_v11_tpm_image_tissue_labels.csv`: https://zenodo.org/records/19963477/files/selected_gtex_v11_tpm_image_tissue_labels.csv
+- `selected_gtex_v11_tpm_image_tissue_dataset.zip`: https://zenodo.org/records/19963477/files/selected_gtex_v11_tpm_image_tissue_dataset.zip
+
+## Optional Raw GTEx Files
+
+- `GTEx_Analysis_2025-08-22_v11_RNASeQCv2.4.3_gene_tpm.gct.gz`: https://storage.googleapis.com/adult-gtex/bulk-gex/v11/rna-seq/GTEx_Analysis_2025-08-22_v11_RNASeQCv2.4.3_gene_tpm.gct.gz
+- `GTEx_Analysis_v11_Annotations_SampleAttributesDS.txt`: https://storage.googleapis.com/adult-gtex/annotations/v11/metadata-files/GTEx_Analysis_v11_Annotations_SampleAttributesDS.txt
+
+GTEx Portal source pages:
+
+- Bulk tissue expression: https://gtexportal.org/home/downloads/adult-gtex/bulk_tissue_expression
+- Metadata: https://gtexportal.org/home/downloads/adult-gtex/metadata
+
+## Optional Outputs Created Before Galaxy Upload
+
+- `ludwig_input.csv`
+- `output_images.zip`
+- Optional audit file: `metadata_base.csv`
+
+## Galaxy Task
+
+- **Task**: Multi-class tissue classification
+- **Input image representation**: log-transformed TPM vector padded to a square grayscale image
+- **Label**: `SMTSD` tissue label from GTEx sample attributes, pre-mapped into the metadata table
+- **Tool**: Galaxy Image Learner
+
+## Files
+
+- `tutorial.md` - Main hands-on tutorial
+- `tutorial.bib` - Bibliography
+- `data-library.yaml` - Zenodo and raw GTEx URL references
+- `workflows/` - Image Learner workflow skeleton
+- `faqs/` - Tutorial FAQ

topics/statistics/tutorials/GTEx_Tissue_modeling/data-library.yaml

@@ -0,0 +1,38 @@
+---
+destination:
+  type: library
+  name: GTN - Material
+  description: Galaxy Training Network Material
+  synopsis: Galaxy Training Network Material. See https://training.galaxyproject.org
+items:
+- name: Statistics and Machine Learning
+  description: Statistics and Machine Learning tutorials
+  items:
+  - name: GTEx Tissue Modeling with Image Learner
+    items:
+    - name: Prepared GTEx v11 Image Learner dataset
+      description: Prepared Zenodo files used for the hands-on tutorial
+      items:
+      - url: https://zenodo.org/records/19963477/files/selected_gtex_v11_tpm_image_tissue_labels.csv
+        src: url
+        ext: csv
+        info: selected_gtex_v11_tpm_image_tissue_labels.csv
+        description: Prepared metadata table with image_path and label columns for Image Learner.
+      - url: https://zenodo.org/records/19963477/files/selected_gtex_v11_tpm_image_tissue_dataset.zip
+        src: url
+        ext: zip
+        info: selected_gtex_v11_tpm_image_tissue_dataset.zip
+        description: ZIP archive of generated grayscale images for Image Learner.
+    - name: Optional GTEx v11 raw files
+      description: Direct URLs for rebuilding the prepared dataset
+      items:
+      - url: https://storage.googleapis.com/adult-gtex/bulk-gex/v11/rna-seq/GTEx_Analysis_2025-08-22_v11_RNASeQCv2.4.3_gene_tpm.gct.gz
+        src: url
+        ext: gct.gz
+        info: GTEx_Analysis_2025-08-22_v11_RNASeQCv2.4.3_gene_tpm.gct.gz
+        description: Raw GTEx v11 gene TPM expression matrix used to generate sample images.
+      - url: https://storage.googleapis.com/adult-gtex/annotations/v11/metadata-files/GTEx_Analysis_v11_Annotations_SampleAttributesDS.txt
+        src: url
+        ext: txt
+        info: GTEx_Analysis_v11_Annotations_SampleAttributesDS.txt
+        description: GTEx v11 sample attributes file containing `SMTSD` tissue labels.

topics/statistics/tutorials/GTEx_Tissue_modeling/faqs/index.md

@@ -0,0 +1,43 @@
+---
+layout: faq-page
+---
+
+## What GTEx files are used?
+
+The hands-on tutorial uses these prepared Zenodo files:
+
+- `selected_gtex_v11_tpm_image_tissue_labels.csv`: https://zenodo.org/records/19963477/files/selected_gtex_v11_tpm_image_tissue_labels.csv
+- `selected_gtex_v11_tpm_image_tissue_dataset.zip`: https://zenodo.org/records/19963477/files/selected_gtex_v11_tpm_image_tissue_dataset.zip
+
+Optionally, you can rebuild the prepared files from these raw GTEx files:
+
+- `GTEx_Analysis_2025-08-22_v11_RNASeQCv2.4.3_gene_tpm.gct.gz`: https://storage.googleapis.com/adult-gtex/bulk-gex/v11/rna-seq/GTEx_Analysis_2025-08-22_v11_RNASeQCv2.4.3_gene_tpm.gct.gz
+- `GTEx_Analysis_v11_Annotations_SampleAttributesDS.txt`: https://storage.googleapis.com/adult-gtex/annotations/v11/metadata-files/GTEx_Analysis_v11_Annotations_SampleAttributesDS.txt
+
+## What is the label?
+
+The target label is `SMTSD`, the detailed tissue label in the GTEx sample attributes file. In the prepared metadata table, this label is stored in the `label` column and the image filename is stored in the `image_path` column.
+
+## Why convert expression data into images?
+
+Image Learner trains image models. The preprocessing step makes one grayscale image per sample by log-transforming the sample's TPM vector, padding it to a square, and saving it as a JPEG. This preserves the expression values in a fixed-size input format that Image Learner can consume.
+
+## Is this workflow tied to one Galaxy server?
+
+No. This tutorial uses prepared Zenodo files and can run on any Galaxy server with Image Learner installed.
+
+## Which Galaxy server can run it?
+
+Any Galaxy instance can run the tutorial if Image Learner is installed from the ToolShed and the instance has enough compute for the selected sample count and model.
+
+## Can I use more tissues?
+
+Yes. Edit `SELECTED_TISSUES` in the preprocessing script. Start with a small balanced tissue set, confirm the workflow runs, then scale up.
+
+## Why use balanced sampling?
+
+Balanced sampling makes tutorial metrics easier to interpret and prevents highly represented tissues from dominating accuracy. For research, compare balanced and naturally distributed tissue sets.
+
+## What metrics should I inspect?
+
+Use held-out test accuracy, weighted precision, weighted recall, weighted F1, per-class metrics, and the confusion matrix. Per-class metrics are especially important when tissue counts are imbalanced.

topics/statistics/tutorials/GTEx_Tissue_modeling/slides.html

@@ -0,0 +1,135 @@
+---
+layout: tutorial_slides
+logo: GTN
+title: "GTEx Tissue Modeling with Galaxy Image Learner"
+
+questions:
+  - "How can GTEx gene expression profiles be transformed into image-like inputs for Image Learner?"
+  - "How do GTEx sample annotations provide tissue labels for supervised classification?"
+  - "How can this workflow be run on any Galaxy server with Image Learner installed?"
+
+objectives:
+  - "Import a prepared GTEx v11 Image Learner metadata table and image ZIP archive."
+  - "Optionally rebuild the prepared files from GTEx v11 gene TPM and sample annotation files."
+  - "Train and evaluate a multi-class tissue classifier in Galaxy."
+
+contributors:
+  - paulocilasjr
+  - jgoecks
+---
+
+# GTEx Tissue Modeling
+
+- GTEx v11 gene TPM profiles are used as model inputs.
+- GTEx sample attributes provide tissue labels.
+- Image Learner trains a multi-class tissue classifier in Galaxy.
+
+???
+
+This tutorial builds a GTEx tissue classifier from expression-derived image inputs on a Galaxy server with Image Learner.
+
+---
+
+# Recommended Files
+
+- `selected_gtex_v11_tpm_image_tissue_labels.csv`
+- `selected_gtex_v11_tpm_image_tissue_dataset.zip`
+
+Zenodo URLs:
+
+- https://zenodo.org/records/19963477/files/selected_gtex_v11_tpm_image_tissue_labels.csv
+- https://zenodo.org/records/19963477/files/selected_gtex_v11_tpm_image_tissue_dataset.zip
+
+---
+
+# Optional Raw Files
+
+- `GTEx_Analysis_2025-08-22_v11_RNASeQCv2.4.3_gene_tpm.gct.gz`
+- `GTEx_Analysis_v11_Annotations_SampleAttributesDS.txt`
+
+- https://storage.googleapis.com/adult-gtex/bulk-gex/v11/rna-seq/GTEx_Analysis_2025-08-22_v11_RNASeQCv2.4.3_gene_tpm.gct.gz
+- https://storage.googleapis.com/adult-gtex/annotations/v11/metadata-files/GTEx_Analysis_v11_Annotations_SampleAttributesDS.txt
+
+---
+
+# Workflow Steps
+
+1. Import the prepared Zenodo metadata CSV and image ZIP.
+2. Use `label` as the target column.
+3. Use `image_path` as the image column.
+4. Train Image Learner to classify tissue.
+5. Review test metrics and confusion patterns.
+
+---
+
+# Expression as Image
+
+- Apply `log1p` to TPM values.
+- Pad each sample vector to a square length.
+- Reshape the vector into a 2D array.
+- Save each array as a grayscale JPEG.
+
+This is an engineered representation for Image Learner, not a claim that gene order encodes biological image neighborhoods.
+
+---
+
+# Prepared Galaxy Inputs
+
+| File | Purpose |
+|---|---|
+| `selected_gtex_v11_tpm_image_tissue_labels.csv` | Metadata table with `image_path` and `label`. |
+| `selected_gtex_v11_tpm_image_tissue_dataset.zip` | ZIP archive containing one JPEG per sample. |
+
+The `image_path` values must match filenames inside the ZIP archive. The `label` values are derived from `SMTSD` in the GTEx sample attributes file.
+
+---
+
+# Example Tissue Set
+
+- Brain - Cortex
+- Heart - Left Ventricle
+- Liver
+- Lung
+- Muscle - Skeletal
+- Adipose - Subcutaneous
+- Skin - Sun Exposed (Lower leg)
+
+Use balanced sampling for a clear tutorial task, then scale up once the workflow runs.
+
+---
+
+# Image Learner Setup
+
+| Parameter | Value |
+|---|---|
+| Task | Multi-class classification |
+| Label column | `label` |
+| Image column | `image_path` |
+| Model | CAFormer S18 384 |
+| Split | 70/10/20 |
+| Random seed | 42 |
+
+---
+
+# Galaxy Scope
+
+- Works on any Galaxy instance with Image Learner installed.
+- Input preparation can happen locally, on a workstation, or on any compute environment with Python.
+
+---
+
+# Results to Inspect
+
+- Dataset composition by tissue and split.
+- Training and validation curves.
+- Held-out test accuracy and weighted F1.
+- Per-class precision, recall, and F1.
+- Confusion matrix for tissue pairs that are difficult to separate.
+
+---
+
+# Takeaways
+
+- GTEx sample-level expression profiles can be converted into Image Learner-compatible image inputs.
+- `SMTSD` provides detailed tissue labels for supervised classification.
+- The workflow is portable across Galaxy servers that provide Image Learner.

topics/statistics/tutorials/GTEx_Tissue_modeling/tutorial.bib

@@ -0,0 +1,17 @@
+@article{GTEx2020,
+  title = {The GTEx Consortium atlas of genetic regulatory effects across human tissues},
+  volume = {369},
+  issn = {1095-9203},
+  doi = {10.1126/science.aaz1776},
+  number = {6509},
+  journal = {Science},
+  author = {{GTEx Consortium}},
+  year = {2020}
+}
+
+@online{GTExPortal,
+  author = {{GTEx Portal}},
+  title = {GTEx Portal Downloads},
+  url = {https://gtexportal.org/home/downloads/adult-gtex},
+  urldate = {2026-05-01}
+}