update barplot documentation for plot.horizontal

[jarbet]

Description

A very common plot we make in the lab is a heatmap with a barplot on the right, using plot.horizontal = TRUE.

For the heatmap, I typically use same.as.matrix = TRUE when not clustering, thus I know the order of row/columns of the input data will exactly match the order in the plot. Then I make sure the barplot data rows are in the same order as the heatmap data rows, and use disable.factor.sorting = TRUE.

However, the order of rows in the heatmap and barplot get misaligned in this approach, that's because create.barplot fills in the bars from the bottom to the top of the plot, although I assumed the opposite (i.e. I thought the order of rows in the barplot would match the order of rows in the input data).

Thus I updated the documentation to try and clarify this.

Closes #...

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.

Testing Results

see example in comment below

[jarbet]

Here's a simple example demonstrating the issue:

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

dataset <- data.frame(
    a = 1:3,
    b = 4:6,
    c = 7:9
    );
dataset$id <- factor(1:nrow(dataset));

heat <- create.heatmap(
    x = dataset[, c('a', 'b')],
    same.as.matrix = TRUE,
    clustering.method = 'none'
    );
barplot <- create.barplot(
    formula = id ~ c,
    data = dataset,
    plot.horizontal = TRUE,
    disable.factor.sorting = TRUE
    );

# notice bars are filled in from the bottom to the top, thus the rows of barplot and heatmap are misaligned
barplot;

# to get rows of barplot and heatmap to match, need to reverse order of barplot rows:
barplot.match.heat <- create.barplot(
    formula = id ~ c,
    data = dataset[nrow(dataset):1,], # this makes the rows of the 2 plots match
    plot.horizontal = TRUE,
    disable.factor.sorting = TRUE
    );
create.multipanelplot(
    plot.objects = list(heat, barplot.match.heat),
    layout.width = 2,
    layout.height = 1
    );