Add help text

[vincerubinetti]

Using the app itself as an interface should be self-explanatory. What is not self-explanatory is what the biological meaning behind all of the app's functionality is. @ajlee21 Suggested a while ago that we add some help text explaining what things do and what they can be useful for. My vision of this would be 2-3 sentences on biological meaning and insight, right before each section.

It might look something like this:

Or maybe I would hide it as a tooltip on a little (?) icon, or maybe click to show it. But the general gist would be the same.

---

@cgreene @ajlee21 @georgiadoing @debhogan-208 If you get some free time, please write some description text for one of the sections in the app and post it in this issue. I think it would help adoption of the app. The descriptions should probably be pretty high level... aimed at someone who has some sort of scientific background, but who doesn't know the specifics of the work the Hogan lab has done with the app for example.

[ajlee21]

Personally when using the website, the sections I would get a little confused by were the signatures and experiment activities. Not sure if it makes sense to add a description on just some of the sections as opposed to all the sections.

Here are my rough proposal for review

Signature Search or Enriched Signature section:

• Weighted sum of expression using high weight genes (i.e. weighted activity of genes that most contribute to a given node)
• positive signatures use high positive weight genes while negative signatures use high negative weight genes

Experiment activities:

• Is the black bar representing the average gene expression (averaged across genes) for all samples in the compendium?
• Then the green bars represent the average gene expression activity for each sample in the experiment?
• What does the "Activities" column represent?

[cgreene]

Genes page:

Enriched Signatures:

See which signatures have more genes from the search list than we would expect by chance. The FDR-corrected p-value for each significantly-associated signature is provided.

Gene Network:

See which genes are present in similar signatures across the machine learning model. Edges presented are the Pearson correlation over gene-signatures connections. Genes with high correlation are contributing to the same signatures.

[cgreene]

Experiments page:

Samples:

Divide samples into two groups to identify signatures that are differentially expressed between them and to annotate the heatmap below.

Activity Heatmap:

Explore which samples share signature activities by clustering by signatures. Explore which signatures share activity in samples by clustering by samples. This can reveal groups of signatures that are especially active or inactive in certain sets of samples. It can also reveal how groupings made based on the annotations above cluster.

Volcano Plot:

This plot shows which signatures differ most between the groups selected above. A volcano plot displays fold change, which captures magnitude, and p-value, which captures how unexpected something is under the null. Clicking a signature will show the signature summary page for that signature.

[cgreene]

Signatures page:

Participating Genes:

This shows the genes that contribute most to the signature. A high magnitude (absolute value) indicates a stronger contribution. A negative direction indicates that the gene reduces the activity of the signature. A positive direction indicates that the gene increases the activity of the signature.

Experiment Activities:

Explore the experiments in which this signature varies the most. This can suggest experiments that might reveal treatments that alter the expression of this block of genes for further investigation, especially if differences fall along treatment/control lines.

Enriched Gene Sets:

These annotations can reveal processes that may underlie the gene expression patterns captured in the signature. The p-value presented is FDR corrected for multiple testing.

[cgreene]

These are a start - maybe Alex could take a pass at incorporating her thoughts and then we could put them up and ask deb/georgia for feedback. What do you think?

[ajlee21]

• Really like the definition for Enriched Signature!
• For Gene Network I thought the correlation was based on the latent space features (i.e. nodes) instead of signatures..? Not sure if that gets too confusing to mention the difference. How is this?

See which genes have similar low-dimensional representation, which was generated by training the machine learning model on genome-scale gene expression data. Edges presented are the Pearson correlation over low dimensional gene representation. Genes with high correlation are contributing to the same signatures.

• Like all the definitions on the Experiments page

• A possible suggestion for Participating Genes if it makes sense:

This shows the genes that contribute most to the signature. A high weight magnitude (abs value weight) indicates a stronger contribution. A negative direction indicates that the gene reduces the activity of the signature. A positive direction indicates that the gene increases the activity of the signature.

I just thought it would be good to use the term weight here since that is what is on the table.

• For Experiment Activities I like the description. Do you think it is more confusing to add what the black vs green represents?