How to generate reports in plain text or markdown format

• Difficulty level: easy
• Time need to lean: 10 minutes or less
• Key points:
  • report action generate plain text output

Action report

Action report writes some content to an output stream. The input can either be a string or content of one or more files specified by option input. The output is determined by parameter output, and command line option -r.

• If output='filename', the content will be written to a file.
• If output=obj and obj has a write function (e.g. a file handle), the content will be passed to the write function
• If output is unspecified and no filename is specified from option -r, the content will be written to standard output.
• If output is unspecified and a filename is specified with option -r, the content will be appended to specified file.

For example, the content of report actions is printed to standard output if no output is specified.

We can specify an output file with option output, but the output will be overwritten if multiple actions write to the same file

Action report can also take the content of one or more input files and write them to the output stream, after the script content (if specified). For example, the report action in the following example writes the content of out.txt to the default report stream (which is the standard output in this case).

A summarization step

You can write a report at the end of the workflow that summarizes the results of previous steps. For example, in the following example, the report action summarizes previous steps and writes a report to the standard output.

It is a pretty bad idea to write report to standard output because other actions can also write to it. You should therefore use the output option of the report action to specify an output file of the report action.

Instead of outputting reports in .md format and rendering them outside of SoS, you can also render them inside SoS using action pandoc or Rmarkdown. For example,

Reporting to multiple output files

If you have a large workflow with several steps or modules, it makes sense to write several reports and join them at last. For example, in the following example, an output file is specified for each report and a summary step is used at the end to collect and process them.

You will notice that both script and input are specified to action pandoc. In this case the script is put before the content of each input files, making it a perfect place to write headers and summaries.

Action pandoc

Action pandoc uses command pandoc to convert specified input to output. This input to this action can be specified from option script (usually specified in script format) and input.

First, if a script is specified, pandoc assumes it is in markdown format and convert it by default to 'HTML' format. For example,

You can specify an output with option output

You can convert input file to another file type using a different file extension

Or you can add more options to the command line by modifying args,

The second usage of the pandoc action is to specify one or more input filenames. You have to use the function form of this action as follows

If multiple files are specified, the content of these input files will be concatenated. This is very useful for generating a single pandoc output with input from different steps. We will demonstrate this feature in the Generating Reports tutorial.

If both script and input parameters are specified, the content of input files would be appended to script. So

Action Rmarkdown

Action Rmarkdown shares the same user interface with action pandoc. The only big difference is that it used R's rmarkdown package to render R-flavored Markdown language.

For example, the Rmarkdown action of the following example collects input files A_10.md and A_20.md and use R's rmarkdown package to convert it to out.html.

Further reading

*