User report

[lydiayliu]

Set up

1. download package from browser, scp to cluster
2. could not download directly from github using https link since it's a private repo
3. also downloaded the user guide HTML

conda create -n cev r-essentials r-base
conda activate cev

R CMD INSTALL CancerEvolutionVisualization_1.0.0.tar.gz

Thoughts from reading the user guide

Parent Data

1. why the use of row names as node names? I personally think it's much harder to work with rownames than with just another column in the data frame. It would also make more sense from a reading perspective that the parent is listed to the left of the node, so a data frame with the columns c('parent', 'node'). Also this would make it more consistent with the gene label data frames later on.
2. The root node does have a parent and the parent is the germline or normal. Instead of using an NA which can cause various trouble later on, why not use 0?

Branch Lengths

1. There is some typo in this line:

Up to twoIncluding a length1 and/or length2 column will enable this branch scaling behaviour, and automatically add y-axis ticks and labels.

2. Instead of making the user hard code the data frame length1 and length2 (and promptly forgetting what they stand for), why not take 2 arguments that specify which column should be taken as length1 and which column as length2? That way you will also automatically have y-axis titles?

Showing Cellular Prevalence

1. Not that it really matters for the visualization, but cellular prevalence is the proportion of cells that belong to each cluster in the entire sequenced sample. The example shown (where the CP of the root node is 1) is practically impossible in real life (because there is always going to be some stromal contamination in bulk sequencing), and is more reflective of the cancer cell fraction (CCF, the proportion of cells that belong to each cluster in the tumour cells sequenced). Question is, if the root node does not have CP = 1, does the function still work?

Branch Angles

1. Does it mean that setting NA to a particular angle will result it in being determined automatically?

CNAs and SNVs

1. This is cute but seems to introduce some novel conventions to tree plotting. I appreicate the ease where the user can just input a CNA and a SNV column, but is there options for the user to just specify some text, the branch and font / size / colour of the text?
2. Sometimes it's useful to specify text next to the node instead of the branch, could that be a feature request?
3. What's the difference between CNA = 0 and CNA = NA

Plot Width with Horizontal Padding

1. Where is the x-axis? Do you mean the y-axis?

Some plots require more or less horizontal padding between the x-axes and the tree itself.

Branch Scaling

1. I wonder if instead of 1 and 2, left and right might be better for specifying the two branches and the y-axis.

X-Axes

1. Some formating / typo for this section cuz the text is

A y-axis will be added automatically for each branch length column (the left-sided axis corresponding to the first branch length column, and the right with the second length column).

Axis Title

1. Strange use of parent.only as the example figure to demonstrate this section, that's a tree where the branch lines don't mean anything right? So the SNVs left y-axis doesn't make any sence?

Axis Tick Placement

1. This example is a little strange to me, what does the y-axis even mean if the doesn't cover the full length of the tree from to to bottom?

Thoughts from actually using the code

1. I think example code for how to change the colours of the nodes, branches, the CP shadings and the normal little square would be useful in this section. That was my first question anyways.
2. I'm not sure every new user would even know how to save the plot output to a file? Why is there no option to do that automatically? I had to use the pdf() and dev.off()
3. Are the nodes being renumbered? I had a tree like

  parent node length1
1     NA    1    9686
2      1    2     401
4      1    4     263
5      2    5     237
6      1    6    4424

But the plot seems to output nodes 1:5 always. This is actually important since for mult-region SRC, not every cluster is in every sample but you need the node names to be consistent so you can tell which are the same clusters across samples.
5. For horizontal.padding, seems like anything below -1 doesn't do extra?
6. I generated some random length2 that is completely on a different scale as length 1, unfortunately the automatic system completely fell apart for this (SRCGrob(tree, yaxis1.label = 'SNVs', horizontal.padding = -2)), but I wouldn't say this is a completely outrageous example. Since SNV count in the ~10k range is not unheard of, and the number of driver SNVs for example would still be in the integer range

  parent node length1 length2
1     NA    1    9686       5
2      1    2     401       9
4      2    4     263       2
5      2    5     237       9
6      2    6    4424       5

7. If a node has `CP = 0`, this error is outputted which is not the most informative > Error in unit(x, default.units) : 'x' and 'units' must have length > 0 8. If a node has `CP > 1`, the same error is outputted lol > Error in unit(x, default.units) : 'x' and 'units' must have length > 0 9. There might be something wrong with my cluster R environment set up, but the `italicize` of SNV labels didn't work for me

Thoughts to conclude

1. I didn't have much trouble creating the input data required for plotting, since I always worked with data frames in similar formats to represent my trees
2. Would love to see a list of all customizable options, I know lots of stuff is available looking at ?SRCGrob, but an naive user might not know where to look
3. Why the name SRCGrob for the main function of this package? Most people won't know what a grob is right? Maybe include a wrapper function called plotSRC or something and add the support for writing to file by including grid.plot?
4. Is there an ETA on multi-sample SRC plotting?

Well I hope that does it, @dan-knight let me know if there's any specific feedback you are looking for!

[whelena]

Commenting to this discussion to keep track of progress since 2022. Comments that are not specifically addressed are no longer relevant due to changes made to the input formatting or internal working of CEV.

Showing cellular prevalence.

The plotting function works for both CP and CCF (root node does not have to be one) and the x axis label is user defined. Plot below shows that CP > 1 works and even when there are violations, CEV is still able to plot the fish tree.

y-axis

what does the y-axis even mean if the doesn't cover the full length of the tree from top to bottom?
When length.from.node.edge = FALSE the distance from each node to the normal may be used to represent evolutionary distance (number of SNVs/CNAs) otherwise, we have implemented a scale bar option as an alternative (PR #148)

Wrapper function

Opening issue #158 to address the following comments

how to save the plot output to a file?
why not take 2 arguments that specify which column should be taken as length1 and which column as length2?
why the use of row names as node names?

We will add a wrapper function (plotSRC) to optionally convert input files from c(parent, child) data frame to the input taken by SRCgrob. The goal is to support human readable format without introducing too many changes to the internal workings of CEV. It will also automatically save plots to a file.