Reading Hadley's Package chapter about Documentation

Key point:

Use Roxygen comments in the R files - then the documentation takes care of itself!


Cut and pasted from: http://r-pkgs.had.co.nz/man.html

The documentation workflow

In this section, we’ll first go over a rough outline of the complete documentation workflow. Then, we’ll dive into each step individually. There are four basic steps:

1. Add roxygen comments to your .R files.
2. Run devtools::document() (or press Ctrl/Cmd + Shift + D in RStudio) to convert roxygen comments to .Rd files. (devtools::document() calls roxygen2::roxygenise() to do the hard work.)
3. Preview documentation with ?.
4. Rinse and repeat until the documentation looks the way you want.

Roxygen comments start with #'

For functions:

As well as the introduction block, most functions have three tags: @param, @examples and @return.

Introduction is the first part!

Each block includes some text before the first tag.1 This is called the introduction, and is parsed specially:

• The first sentence becomes the title of the documentation. That’s what you see when you look at help(package = mypackage) and is shown at the top of each help file. It should fit on one line, be written in sentence case, and end in a full stop.
• The second paragraph is the description: this comes first in the documentation and should briefly describe what the function does.
• The third and subsequent paragraphs go into the details: this is a (often long) section that is shown after the argument description and should go into detail about how the function works.

All objects must have a title and description. Details are optional.

Well happy days (or evenings), I just completed my first documentation of a function!

Hi res images for blog...

https://xomisse.com/blog/how-to-fix-blurry-images-on-blogger/

and

https://danieljhocking.wordpress.com/2013/03/12/high-resolution-figures-in-r/

aim - get drawProteins on Bioconductor

need unit testing
need vignette

found this style on github

https://github.com/juliangehring/vignettes



This is also very important:

https://bioconductor.org/packages/devel/bioc/vignettes/BiocStyle/inst/doc/AuthoringRmdVignettes.html

https://bioconductor.org/packages/devel/bioc/vignettes/BiocStyle/inst/doc/HtmlStyle.html


Unit Test Guidelines:
https://www.bioconductor.org/developers/how-to/unitTesting-guidelines/

Information on making Bioconductor contributions through Github
https://github.com/Bioconductor/Contributions


This link is important too:
https://cran.r-project.org/web/packages/ggplot2/vignettes/extending-ggplot2.html

Trying to improve resolution of pictures on Blogger...

Key step 1:

Use Original size!

Some advice here:
https://xomisse.com/blog/how-to-fix-blurry-images-on-blogger/

It's a bit frustrating and I really need to find a robust way to do this!!!!

explot_1 
PNG file
Direct export from RStudio - 600 x 300 pixels
Text size = 10
Shown below as original size.

Not too back actually in terms of the text and the line.
Probably not publication standard :-(


explot_2 
PNG file
Direct export from RStudio - 900 x 300 pixels
Text size = 10
Shown below as original size.

Text fills less of the bars.


explot_3 
PNG file
p + ggsave("explot_3.png",
           width = 4, height = 2, units = "in",
           dpi = 600)
Text size = 10
Shown below as original size.

Shown here as x-large

So text fills a lot more of the image as the text size is fixed - 10mm, I guess.


explot_4.png
p + ggsave("explot_4.png",
           width = 2, height = 1, units = "in",
           dpi = 600)

Original size:

Shown here as x-large

However, when I just export my five columns, I get dreadful pixillation of my text...

lines pixillated too. 

Try this:

p + ggsave("five_rect.png",

           width = 10, height = 5, units = "cm",

           dpi = 600)

Adding some text with size = 2 - should be 2mm, I think. 

p + ggsave("five_rect_with_text.png",

           width = 10, height = 5, units = "cm",

           dpi = 600)

Lots of work on adjusting sizes etc... all a bit painful and frustrating but...

BACK TO USING DEFAULTS

Learning about unit testing...

Good info from Steph yesterday at our R-User Group.

1.   Create an R script in the test folder.
Q: do they have to start with "test-"?

2.   Add a context using the context() function.
Gives information about what's been tested and why in broad terms.

3.   Key function is test_that()
The test_that() function has two arguments:
A. description - test name.
B. test code made up of expectation - in curly brackets

Code for my first simplest tests:

test_that("extract_names gives a list",{

  # load data from the package - should I move it into the test folder

  data("protein_json")

  # creates object protein_json in the environment.

  # it's the json data for Q04206 - for the transcription factor RelA

  # Nice simple test

  res <- extract_names(protein_json)

  expect_is(res, "list")

  expect_equal(length(res),6)

})

To run the tests 

- operate within the Rproj for your package.

Use the function: test()

When it doesn't work, output looks like this:

> test()
Loading drawProteins
Testing drawProteins
extract_names: 1

Failed ----------------------------------------------------------------------
1. Error: extract_names gives a list (@test-extract_names.R#12) -------------
object 'sample_protein_json' not found
1: extract_names(sample_protein_json) at /Users/paulbrennan/Documents/drawProteins/tests/testthat/test-extract_names.R:12

DONE ========================================================================

When it works it looks like this:

> test()
Loading drawProteins
Testing drawProteins
extract_names: ..

DONE ========================================================================


That's enough for now...