Auto axis scaling #165

dan-knight · 2023-10-19T19:09:54Z

Description

Closes #156. These changes improve documentation and refactor internal package code around automatic axis scaling. This functionality has existed in several plotting functions with auto.axis(), but was difficult to discover. These changes focus on a the most straightforward axis scaling use cases - only a handful of plotting functions:

create.scatterplot
create.barplot
create.boxplot
create.hexbinplot
create.manhattanplot

Vignette Section

The scale at which data is viewed is extremely impactful to the insight that can be drawn from a visualization. While linear scaling is perfectly fine, some datasets are more easily interpreted after log transforming the data, for example.

6.4.1 Automatic Axis Scaling

BPG supports automatic axis scaling for several plot types with the auto.axis function. This functionality can be accessed through the xat and yat parameters when calling a plotting function. There are 3 settings to choose from:

auto.log: log10 scaled, with automatically spaced and formatted tick locations.-

auto.linear: Linear scaled, with automatic tick placement based on analysis of the data. ❼ auto: Automatically chooses the most appropriate setting (auto.log or auto.linear).
If nothing is passed, the plot will use lattice’s default axis creation method, which is often less ”pretty” than BPG’s automatic axes.

6.4.2 Manual Axis Scaling

It’s possible to manually scale the axes for use cases not supported by auto.axis. This is a three step process:

Transform the data.

Transform the axis tick locations in xat and yat to match the data transformation.

Override the axis tick labels in xaxis.lab and yaxis.lab to correspond to the pre-transformation values from the data.

Vignette Plot Examples

This also includes a new section in the Plotting Guide vignette about axis scaling, plus examples in some plot sections

Checklist

This PR does NOT contain PHI or germline genetic data. A repo may need to be deleted if such data is uploaded. Disclosing PHI is a major problem.
This PR does NOT contain molecular files, compressed files, output files such as images (e.g. .png, .jpeg), .pdf, .RData, .xlsx, .doc, .ppt, or other non-plain-text files. To automatically exclude such files using a .gitignore file, see here for example.
I have read the code review guidelines and the code review best practice on GitHub check-list.
I have set up or verified the main branch protection rule following the github standards before opening this pull request.
The name of the branch is meaningful and well formatted following the standards, using [AD_username (or 5 letters of AD if AD is too long)]-[brief_description_of_branch].
I have added the major changes included in this pull request to the NEWS under the next release version or unreleased, and updated the date. I have also updated the version number in DESCRIPTION according to semantic versioning rules.
Both R CMD build and R CMD check run successfully.

…ting-general into danknight-setup-testthat

…ic-R-BoutrosLab-plotting-general into shipit-auto-axis

Add parameter `which.arg` to `prep.axis` to disambiguate between `xat` and `yat` in error messages in the event of invalid input.

Correct what data are overwritten in `create.boxplot` when `prep.axis` is called on the x-axis and returns a list.

…trosLab-plotting-general into shipit-auto-axis

Use `prep.axis` in `create.scatterplot` (and `create.lollipopplot`).

auto.axis()

…trosLab-plotting-general into shipit-auto-axis

auto.axis()

aholmes · 2023-10-24T18:27:56Z

DESCRIPTION

 Type: Package
 Title: Functions to Create Publication-Quality Plots
-Date: 2023-10-09
+Date: 2023-10-18


It is now the 24th.

aholmes · 2023-10-24T18:28:21Z

NEWS

@@ -1,3 +1,14 @@
+BoutrosLab.plotting.general 7.1.0 2023-10-18


Date here also.

aholmes · 2023-10-24T18:33:00Z

tests/testthat/test-plotting.functions.R

+        	x = data.frame(test.data$z, rnorm(10))
+        	);
+
+        # # This is the slowest running function


Remove commented code.

aholmes

Looks good to me, just update the release dates.

tyamaguchi-ucla

Nicely done! Looks good to me! I've made some minor corrections/suggestions and added feature requests. Anything else to add @jarbet ?

If nothing is passed, the plot will use lattice’s default axis creation method, which is often less ”pretty” than BPG’s automatic axes.

I think it would be nice to use the auto as default once we stabilize the feature.

man/auto.axis.Rd

R/auto.axis.R

tyamaguchi-ucla · 2023-10-24T18:49:29Z

R/auto.axis.R

+        }
+
+    return(out);
+    }

 generate.at <- function(min.x, max.x, pretty = TRUE, include.origin = TRUE, num.labels = 4) {


[Feature request] It might be useful to make this function available. (no need to worry about it in this PR)

tyamaguchi-ucla · 2023-10-24T18:50:51Z

R/auto.axis.R

+        }
+
+    return(out);
+    }


 as.power10.expression <- function(x) {


[Feature request] It would be useful to make this function officially available. (no need to worry about it in this PR) I think this issue is related #73

tyamaguchi-ucla · 2023-10-24T18:57:33Z

R/auto.axis.R

+        skewness.x <- skewness(x, na.rm = TRUE);
+        # Handle zero values so that they can still be plotted even log(0) = -Inf
+        zero.i <- which(0 == x);
+        logx <- log(x, 10);


[Feature Request] We might want to accept log2 as well (no need to worry about it in this PR)

We might want to accept log2 as well (no need to worry about it in this PR)

Definitely! We intend to add this, probably by parsing anything after auto.log as the base of the log (so xat = auto.log2).

dan-knight · 2023-10-24T20:19:49Z

I think it would be nice to use the auto as default once we stabilize the feature.

Agree. We didn't want to change any defaults in this release, but we really liked auto and think it should eventually be the default.

Co-authored-by: Takafumi Yamaguchi <62572751+tyamaguchi-ucla@users.noreply.github.com>

…trosLab-plotting-general into shipit-auto-axis

jarbet

Looks good! 3 comments:

How can we view the vignette? devtools::build_vignettes didn't work, and utils::browseVignettes said there are no vignettes
I'm echoing @tyamaguchi-ucla comment about eventually supporting log2, since many people in the lab use log2 for effect sizes
Can the auto.log method be used to make a -log10 p-value barplot? This is a very common application in the lab. I had trouble getting the auto.log to make the right plot, maybe I am using it wrong. Here is the plot I have in mind:

suppressPackageStartupMessages(library(BoutrosLab.plotting.general));

set.seed(123);
n <- 5;
dataset <- data.frame(pvalue = runif(n, 0, 0.0001), gene = letters[1:n]);
dataset$mlog10.pvalue <- -log10(dataset$pvalue);

xat <- 0:max(round(dataset$mlog10.pvalue));

xaxis.lab <- sapply( 
    X = xat, 
    FUN = function(x) { 
        if (x == 0) { 
            return(expression(bold('10'^'0'))); 
        } else { 
            return(as.expression(bquote(bold('10'^-.(as.character(x)))))); 
            }
        }
    ); 

create.barplot(
    formula = gene ~ mlog10.pvalue,
    data = dataset,
    plot.horizontal = TRUE,
    xat = xat,
    xlimits = c(min(xat), max(xat)),
    xaxis.lab = xaxis.lab
    )

^{Created on 2023-10-25 by the reprex package (v2.0.1)}

jarbet · 2023-10-25T16:28:23Z

R/create.boxplot.R

-		}
+        out <- prep.axis(
+                at = xat,
+                data = unlist(data[toString(formula[[3]])]),


I'm not sure what formula is but 3 looks like a magic number, more examples below

Hmm. formula is just the formula argument to the function. These lines just extract the second half of the argument.

Now that you point this out, I don't think this is 100% bulletproof. It will likely break with any formula with a more complex left side. That problem is probably outside the scope of this PR, though. It would require a refactor with some sort of utility function like get.formula.args that accounts for more edge cases.

jarbet · 2023-10-25T16:32:27Z

vignettes/PlottingGuide.pdf

The table of contents and page numbers are not displaying. Is this just a problem with github or an actual bug?

Weird! Fixed.

jarbet · 2023-10-25T16:45:14Z

man/create.barplot.Rd

+    x ~ y,
+    log.data,


Don't mix named and positional arguments, use formula = and data = throughout

Sure, looks like this is enforced across all examples. Fixed.

Sure, looks like this is enforced across all examples. Fixed.

Need to update for create.barplot.Rd, otherwise looks good!

tyamaguchi-ucla · 2023-10-25T17:55:18Z

3. Can the auto.log method be used to make a -log10 p-value barplot? This is a very common application in the lab. I had trouble getting the auto.log to make the right plot, maybe I am using it wrong. Here is the plot I have in mind:

Yeah, we see this application a lot. Alternatively, we could also use -log10(Q or P Value) as xlabel like this https://www.nature.com/articles/nature20788/figures/2

jarbet · 2023-10-26T18:53:33Z

man/create.barplot.Rd

+    x ~ y,
+    log.data,


Sure, looks like this is enforced across all examples. Fixed.

Need to update for create.barplot.Rd, otherwise looks good!

jarbet · 2023-10-26T18:58:39Z

vignettes/PlottingGuide.pdf

Looks like Figure 67 got moved to the wrong section, it should be in 6.1:

This seems to be an issue with the Sweave .Rnw format. This issue occurs in multiple places, and doesn't seem to relate to the placement of the code in the .Rnw file. You can find it in the the current CRAN release. Sweave seems to try to arrange the figures in an "optimal" way rather than just adhering to the order in the code. This is part of the reason I think we should move this to .Rmd format, as it seems to render more consistently.

This seems to be an issue with the Sweave .Rnw format. This issue occurs in multiple places, and doesn't seem to relate to the placement of the code in the .Rnw file. You can find it in the the current CRAN release. Sweave seems to try to arrange the figures in an "optimal" way rather than just adhering to the order in the code. This is part of the reason I think we should move this to .Rmd format, as it seems to render more consistently.

Ahh interesting. Got it!

dan-knight and others added 30 commits October 9, 2023 09:58

Clean up auto.axis() code style

fa54851

Setup existing tests in testthat format

6cd81eb

Add deprecation warning for old test format

f28d07e

Update changelog

638096c

Merge branch 'main' into danknight-setup-testthat

c7892cf

Remove test deprecation warning

f199607

Update changelog

798c6ee

Merge branch 'main' of github.com:uclahs-cds/public-R-BoutrosLab-plot…

e0e1419

…ting-general into danknight-setup-testthat

Merge branch 'danknight-setup-testthat' of github.com:uclahs-cds/publ…

d688495

…ic-R-BoutrosLab-plotting-general into shipit-auto-axis

Axis prep function definition for TDD

b48cd31

convert tabs to spaces

2047fde

Write function prep.axis with default behavior

2c15652

spelling fixes to comments

05fb146

fix line spacing

e4a1bb2

Unit tests for prep.axis

5df60ce

Fix code style

340095a

prep.axis conditions should use at, not data

0c17384

Include input in error message for prep.axis

7f7d4bf

Add parameter which.arg to prep.axis

9623c61

Add parameter `which.arg` to `prep.axis` to disambiguate between `xat` and `yat` in error messages in the event of invalid input.

Use prep.axis in create.boxplot

501349c

Correct data are overwriting in create.boxplot

69bef94

Correct what data are overwritten in `create.boxplot` when `prep.axis` is called on the x-axis and returns a list.

Merge branch 'shipit-auto-axis' of github.com:uclahs-cds/public-R-Bou…

a20d0bc

…trosLab-plotting-general into shipit-auto-axis

update auto.axis documentation

c8ef633

Use prep.axis in create.scatterplot

882b82c

Use `prep.axis` in `create.scatterplot` (and `create.lollipopplot`).

update parameter documentation for use with

bc9ef47

auto.axis()

Merge branch 'shipit-auto-axis' of github.com:uclahs-cds/public-R-Bou…

9397177

…trosLab-plotting-general into shipit-auto-axis

Use prep.axis in create.manhattanplot

a7831c3

Merge branch 'shipit-auto-axis' of github.com:uclahs-cds/public-R-Bou…

dca877e

…trosLab-plotting-general into shipit-auto-axis

update parameter documentation for use with

b47740b

auto.axis()

update parameter documentation for use with

31925c1

auto.axis()

Add self as contributor to DESCRIPTION

c578a32

aholmes reviewed Oct 24, 2023

View reviewed changes

NEWS Outdated

@@ -1,3 +1,14 @@

BoutrosLab.plotting.general 7.1.0 2023-10-18

Copy link

Member

aholmes Oct 24, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Date here also.

aholmes reviewed Oct 24, 2023

View reviewed changes

tyamaguchi-ucla requested a review from jarbet October 24, 2023 18:35

tyamaguchi-ucla assigned tyamaguchi-ucla and jarbet Oct 24, 2023

tyamaguchi-ucla previously approved these changes Oct 24, 2023

View reviewed changes

dan-knight and others added 2 commits October 24, 2023 15:41

Remove commented code in tests

241bfb3

Fix author name

6148616

Co-authored-by: Takafumi Yamaguchi <62572751+tyamaguchi-ucla@users.noreply.github.com>

dan-knight dismissed tyamaguchi-ucla’s stale review via 6148616 October 24, 2023 22:41

dan-knight and others added 4 commits October 24, 2023 15:41

Fix docstring

9b543a5

Co-authored-by: Takafumi Yamaguchi <62572751+tyamaguchi-ucla@users.noreply.github.com>

Merge branch 'shipit-auto-axis' of github.com:uclahs-cds/public-R-Bou…

d159687

…trosLab-plotting-general into shipit-auto-axis

Update deprecated mockr function

4c418bf

Update changelog

b64523f

dan-knight requested a review from aholmes October 24, 2023 23:18

jarbet reviewed Oct 25, 2023

View reviewed changes

dan-knight added 3 commits October 26, 2023 11:17

Update Plotting Guide PDF

7115793

Fix code style in examples

3424a42

Update changelog

8e798d8

jarbet requested changes Oct 26, 2023

View reviewed changes

Fix example code style

02df664

jarbet approved these changes Oct 26, 2023

View reviewed changes

aholmes approved these changes Oct 26, 2023

View reviewed changes

dan-knight merged commit 348a561 into main Oct 26, 2023
3 checks passed

dan-knight deleted the shipit-auto-axis branch October 26, 2023 22:17

dan-knight mentioned this pull request Apr 29, 2024

Setup testthat #158

Closed

7 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Auto axis scaling #165

Auto axis scaling #165

dan-knight commented Oct 19, 2023 •

edited

Loading

aholmes Oct 24, 2023

aholmes Oct 24, 2023

aholmes Oct 24, 2023

aholmes left a comment

tyamaguchi-ucla left a comment

tyamaguchi-ucla Oct 24, 2023

tyamaguchi-ucla Oct 24, 2023

tyamaguchi-ucla Oct 24, 2023

dan-knight Oct 24, 2023 •

edited

Loading

dan-knight commented Oct 24, 2023

jarbet left a comment

jarbet Oct 25, 2023

dan-knight Oct 26, 2023

jarbet Oct 25, 2023

dan-knight Oct 26, 2023

jarbet Oct 25, 2023

dan-knight Oct 26, 2023

jarbet Oct 26, 2023

tyamaguchi-ucla commented Oct 25, 2023

jarbet Oct 26, 2023

jarbet Oct 26, 2023

dan-knight Oct 26, 2023

jarbet Oct 26, 2023

		@@ -1,3 +1,14 @@
		BoutrosLab.plotting.general 7.1.0 2023-10-18

Auto axis scaling #165

Auto axis scaling #165

Conversation

dan-knight commented Oct 19, 2023 • edited Loading

Description

Vignette Section

6.4.1 Automatic Axis Scaling

6.4.2 Manual Axis Scaling

Vignette Plot Examples

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aholmes left a comment

Choose a reason for hiding this comment

tyamaguchi-ucla left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dan-knight Oct 24, 2023 • edited Loading

Choose a reason for hiding this comment

dan-knight commented Oct 24, 2023

jarbet left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tyamaguchi-ucla commented Oct 25, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dan-knight commented Oct 19, 2023 •

edited

Loading

dan-knight Oct 24, 2023 •

edited

Loading