Methods in ReportingTools
2
0
Entering edit mode
Jerome • 0
@jerome-8885
Last seen 6.1 years ago
United States

I'm looking at using the ReportingTools package to help collate a disparate set of analyses for wider review.  Even out of the box, it has already helped me set up a pretty decent first draft custom report  --- kudos to the authors!

The workhorse function "publish" has a variety of methods defined for different classes. Some of the analyses I am setting up are covered by these methods (e.g., output from the limma package).

Others aren't covered, though.  My options look like:  Coercing to the common denominator of data frame or coercing to one of the other supported classes.

Can I just somehow write my own method and graft it onto the package in my script?  Does that even make sense?

reportingtools • 668 views
ADD COMMENT
1
Entering edit mode
@gabriel-becker-6000
Last seen 6.1 years ago
United States

Jerome,

There are a number of different ways to customize ReportingTools behavior, depending on the level of re-use you intend. And how much control (and thus how much of the work) you want to exert yourself. The overall workflow of transforming an object into HTML to be inserted into your report can be seen in the figure below, which can also be found in ReportingTools/inst/examples:

Object-to-HTML flowchart

As you can see, each step is controllable via arguments to the publish function or the specification of class methods. Here is a "brief" explanation of what each of them do.

There are two ways to take full control of the HTML generation process to generate fully custom HTML representing particular objects or classes of objects:

  1. Specifying .toHTML in publish() - This wrests complete control of HTML generation away from the defaults. The function you specify is responsible for constructing the HTML representing that individual object exactly as it will appear in the final HTML page.
  2. Defining an objectToHTML method (via setMethod) for a class - This permanently changes ReportingTools' behavior for that class (when the method is present). That is, All objects of that class, across multiple calls to publish() will use your method. As above, your method is responsible for generating HTML exactly as it will appear within the final HTML report.

When custom HTML generation is not present, objects are transformed into data.frames, modified to reflect exact desired output (e.g., adding, removing, or transforming columns), and then transformed into HTML.  Both of these steps are also fully customizable, as follows:

  1. Specifying a .toDF function within publish() - This overrides the default behavior ( calling as.data.frame() ) for transforming that individual object into a basic data.frame. Conceptually, this transformation should be about representing the object as a data.frame as exactly as possible. Customization for the purpose of display should happen in the modification step.
  2. Specifying a toReportDF method for a class - as in (1) but the custom behavior will be used for all objects of that class across multiple calls to publish().
  3. Specifying a .modifyDF function or list of functions within publish() - This customizes the "decoration" step of preparing the data.frame representing that individual object for display in your report. If you specify a list of functions, they will be called sequentially in the order that they appear in the list, each function after the first receiving the output from the previous function as input. The first (/only) function specified here will be passed the data.frame created during the (1)/(2) base df creation step.
  4. Specifying a modifyReportDF method for a class - As in (3), but the behavior will be used for all objects of that class (and you can only specify a single function, not a list).

Note that arguments to publish will always override existing S4 methods for objectToHTML, toReportDF and modifyReportDF.

For permanent/often reused customizations, you can create a package which depends on ReportingTools which exports custom, class-specific methods for any or all of these steps. Once such a package is installed, loading it and using ReportingTools normally should "just work" and utilize your customizations by default.

Hope that helps.

ADD COMMENT
0
Entering edit mode

@GabrielBecker That is more flexible and extensible than I could have imagined!

ADD REPLY
0
Entering edit mode

I tend not to mess around regarding extensibility because of how often I run into things I want to extend and can't easily do so.

Glad I could help

ADD REPLY
0
Entering edit mode
@james-w-macdonald-5106
Last seen 1 day ago
United States

See the ReportingTools basics vignette, specifically section 6.

ADD COMMENT

Login before adding your answer.

Traffic: 219 users visited in the last hour
Help About
FAQ
Access RSS
API
Stats

Use of this site constitutes acceptance of our User Agreement and Privacy Policy.

Powered by the version 2.3.6