how to make comments appear from custom functions - r

using RStudio I have noticed that, when calling a function, I can hit tab and a popup will appear with the possible parameters that can be chosen, e.g. if I type round( and hit tab, x= and digits= will appear as possible choices. This also happens with the custom functions I write. The difference is that built-in functions popups also have comments and explanations regarding the individual parameters. Is it possible to recreate such a behavior with custom functions as well?

I see what you mean. If you write a customised function
foo = function(x,y) { ... }
Then you go foo( and hit tab, the code completion pop-up menu will give you the options x = and y =. However, when you type an existing R function such as round(, not only does tab give you the options, but there's an explanation beneath each variable, telling you its role in the function:
The only way I could think of doing this for your own functions is to package your functions in your own customised package, and to make sure the "help" documentations includes your functions' parameters. This is getting beyond the realm of a stackoverflow question, but I'll point you to a couple of blogs where I learned the basics of R packages.
The Not So Standard Deviation blog explains how to write a simple package with help documentation, which is precisely what you need to see your customised functions appear with explanations inside RStudio's autocomplete. In a nutshell, you'll need to install roxygen2, devtools and, with each customised function, you'll need to thoroughly comment the function like this :
(disclaimer: the goofy cat example is the blogger's, not mine)
Here's a more detailed tutorial on creating R packages, and here's another blog on getting organised with R packages. Good luck!

Related

Should R package functions not include comments?

I'm in the process of creating a small R package containing a set of functions that should be useful in a specialized area of Biology. I currently have the package on GitHub, but want to submit it to CRAN soon. One thing I have noticed when digging around in other packages, is that the code often includes no comments at all (e.g. short comments describing what different parts of the code does), which makes it more difficult to understand. I'm not a programmer or expert in R, so I don't understand why comments are often not included, and Hadley Wickham's "R packages" book makes not mention of this.
Edit: I'm not referring to the object documentation, that one accesses with ?function(), but to comments that are interspersed within the function code, which a normal user wouldn't see, but that could be helpful for people trying to figure out exactly how a function works.
Is there a specific reason to not include comments within the functions of an R package? If so, should I remove all the comments from my code before submitting to CRAN?

Using R's exams package for assignments: Is it possible to add question hints?

The exams package is a really fantastic tool for generating exams from R.
I am interested in the possibilities of using it for (programming) assignments. The main difference from an exam is that besides solutions I'd also like hints to be included in the PDF / HTML output file.
Typically I put the hints for (sub)-questions in a separate section at the end of the PDF assignment (using a separate Latex section), but this requires manual labour. These are for students to consult if they need help getting started on any particular exercise, and it avoids having them look at the solutions directly for hints on how to start.
An assignment might look like:
Question 1
Question 2 ...
Question 10
Hints to all questions
I'd be open to changing the exact format as long it is possible to look up hints without looking up the answer, and it remains optional to read the hints.
So in fact I am looking for an intermediate "hints" section between the between the "question" and "solution" section, which is present for some questions but not for all.
My questions: Is this already possible? If not, how could this be implemented using the exams package?
R/exams does not have dedicated/native support for this kind of assignment so it isn't available out of the box. So if you want to get this kind of processing you have to ensure it yourself using LaTeX for PDF or CSS for HTML.
In LaTeX I think it should be possible to do what you want using the newfloat and endfloat packages in the LaTeX template that you pass to exams2pdf(). Any LaTeX template needs to provide {question} and {solution} environments, e.g., the plain.tex template shipped with the package has
\newenvironment{question}{\item \textbf{Problem}\newline}{}
\newenvironment{solution}{\textbf{Solution}\newline}{}
with the exercises embedded as
\begin{enumerate}
%% \exinput{exercises}
\end{enumerate}
Now instead of the \newenvironment{solution}... you could use
\usepackage{newfloat,endfloat}
\DeclareFloatingEnvironment{hint}
\DeclareDelayedFloat{hint}{Hint}
\DeclareFloatingEnvironment{solution}
\DeclareDelayedFloat{solution}{Solution}
This defines two new floating environments {hint} and {solution} which are then declared delayed floats. And then you would need to customize these environments regarding the text displayed within the questions at the beginning and the listing at the end. I'm not sure if this can get you exactly what you want, though, but hopefully it is a useful place to start from.

Rstudio own Method/Function minihelp [duplicate]

This question already has answers here:
Is it possible to get RStudio to show function arguments and descriptions for custom functions?
(2 answers)
Closed 5 years ago.
If I write a method or function, how can i get that "minihelp" (whose special term I dont know) which is shown while writing a function?
E.g. for "plot" it exists; Type
>plot([TAB]
then the following shows in a kind of "Tooltip"
x=
y=
... =
and if you choose for example "x", then after a second the following tooltip shows:
x
the coordinates of points in the plot. Alternatively, a single plotting
structure, function or any R object with a plot method can be provided.
Some info but not crucial to the problem: I am working with Rstudio and writing multiple S4 generics/methods for the class ExpressionSet.
Sadly I can't manage to find a cool google keyword, so I hope you can help me out!
Edith:
The following question is about the same as mine but i have still the ongoing problem that I already wrote a package, every function is documented with roxygen, I followed hadleys descriptions. Nevertheless, the tooltips do not show up.
In the linked question it is said that "help files must be generated" - which I assume are generated as ?myS4Method is showing the appropriate help pages. Any ideas?
The functionality you are looking for comes from the way RStudio parses the documentation of packages. If you create a package, you can add Roxygen comments to your functions or classes. These comments are then parsed when you create the package into documentation files that you see as the help for a function.
If you run the command ?plot you will see a list of Arguments. These are the parameters that can be passed to the function and that is what the tooltip in RStudio is telling you about.
To get RStudio to give you info about the functions you are using, you should bundle your S4 classes into a package (Hadley Wickham's tutorial) and make sure they are correctly documented. RStudio will take care of the rest.

How to retrieve R function script from a specific package?

I realize there are generic functions like plot, predict for a list of packages. I am wondering how could I get the R script of these generic functions for a specific package, like the lme4::predict. I tried lme4::predict, but it comes with error:
> lme4::predict
Error: 'predict' is not an exported object from 'namespace:lme4'
Since you state that my suggestion above was helpful I will tell you my process. I used my own co-authored package called pacman. This package was developed because we had a hard time remembering all the obscurely named functions to get information on and work with add on packages.
I used this to figure out what you wanted:
library(pacman)
p_funs(lme4, all=TRUE)
I set all = TRUE as predict is a method for a specific class (like print, summary and plot). Generally, these methods are not exported so p_funs won't return them unless you set all = TRUE. Then I scrolled down to the p section and found only a single predict method: predict.merMod
Next I realized it wasn't exported so :: won't show me the stuff and extra colon power is needed, hence: lme4:::predict.merMod
As pointed out by David and rawr above, some functions can be suborn little snippets (methods etc.), thus methods and getAnywhere are helpful.
Here is an example of that:
library(tm)
dissimilarity #The good stuff is hid
methods(dissimilarity) #I want the good stuff
getAnywhere("dissimilarity.DocumentTermMatrix")
Small end note
And of course you don't need pacman to look at functions for packages, it's what I use and helpful but it just wraps base R things. Use THE SOURCE to figure out exactly what.

List of ggplot2 theme options?

After some research I found the way to prevent an uninformative legend from displaying
... + theme(legend.position = "none")
Where can I find all of the available theme options and their default values for ggplot2?
The closest thing to a comprehensive list that I have been able to find is in the ggplot2 wiki on github. I think that most of the options are covered there with examples.
Update
If you would like to see the options that are in use on a current plot, you can use plot_theme(x) to see all of the options that are currently set for the plot named x. It will not be a comprehensive list, but should help if you want to change something like the font size for an axis label.
Update 2
With the transition to version 0.9.0 it's worth noting that the built in documentation has been dramatically improved, and the transition guide from 0.8.9 to 0.9.0 is also worth checking out.
Update 3
There is now a ggplot2 documentation website. Look at the documentation for theme for a complete list. Also, ?theme has a pretty complete list as of 0.9.3.
Update 4
There is now a ggthemes package that has some nice themes and scales to choose from. It might save you from having to create your own. See their github page for more information.
Entering in
theme_get()
will show a comprehensive listing of theme values and options. You can then follow the syntax to modify these attributes in opts().
The ggplot2 package does not contain much reference information-- this is probably because Hadley has put a lot of work into developing and polishing the package, creating a website full of examples and writing an excellent book that describes the system in detail.
The first place I would look for answers would be the ggplot2 website:
http://docs.ggplot2.org/
However, since opts() is not really a geom, stat or scale there are no examples that focus specifically on it. The next place to look would be the section of the website that contains material from the book-- including source code for examples:
http://ggplot2.org/book/
The example code for the chapter "Polishing your plots for publication" contains some well commented examples of using set_theme() and opts() to alter plot appearance.
The ultimate source for information is of course the book it's self. If you find ggplot2 has simplified and streamlined your workflow for producing statistical graphics, buying a copy of the book is a great way to say "thank you" and support the further development of the package.
Update
After some further investigation, you may be able to find a relatively complete list of options by listing out the source of one of the "theme" functions such as theme_bw. The source doesn't provide a description of the possible key=value pairs, but it does at least show most of the key names that have an effect when set via opts().
Besides the obvious references to ggplot2 reference manual and to the graphs section of Cookbook for R, Hadley Wickham provides a nice opts() List on github.
Theme templates:
https://github.com/jrnold/ggthemes
like "The economist", "Stata", "tufte" and more..
I know the answer is not exactly what was asked, but it was what I was looking for when I found this question, so others might too.
All the options I've ever used have been explained in hadley's great ggplot2 book.
Best list I've found for version 0.9.2.1 is here.
?opts
although, this does not display how to finetune its arguments, therefore it's better to check the options given above. If you can get a copy of the ggplot2 reference manual, it will help you a lot.
I made this quick reference for any theme or tasks you might look for. For a more general understanding, this ggplot2 tutorial should help.

Resources