R: Showing interpretation information for the results of a...

xplain {xplain}

R Documentation

Showing interpretation information for the results of a function

Description

Interprets/explains the results of a function call. Main function of the xplain package.

Usage

xplain(call, xml="", lang = "", level = -1, filename="", sep="\n", title.char="-",
    before=TRUE, addfun="", addfun.args="", addfun.title="")

Arguments

`call`	Function call (as string) to be explained/interpreted.
`xml`	Path to the xplain XML file containing the interpretation/explanation information (optional). Can be either a local path or an URL. See below for more details on how `xplain()` tries to find xplain XML files if no file is specified with `xml`.
`lang`	ISO country code of the language of the interpretations/explanations that shall be shown (optional). If none is specified, `xplain()` tries to determine the language of the user's current work environment. If that is not possible then English is taken as defualt value (same effect as `lang="EN"`).
`level`	Integer number indicating the complexity level of the interpretations/explanations that shall be shown (optional). `level` is cumulative: All interpretations/explanations with a level number up to the number provided are shown. Default: -1, i.e. all interpretations/explanations are shown.
`filename`	File to write the `xplain()` output to (optional). If no file name is provided the `xplain()` output is shown in the console.
`sep`	Separator used to separate the outputs from consecutive XML text elements (<text>...</text>) (optional). Default: `"\n"`.
`title.char`	Character used for underlining titles (optional). Default: `"-"`.
`before`	Indicates if the results of the call of the explained function shall be shown before the xplain interpretations/explanations, or after (optional). Default: `TRUE`, i.e. function output is shown before the interpretations/explanations.
`addfun`	Vector of names of additional functions that shall be called (e.g. `summary()`), without brackets (optional). It is assumed that these functions take the return object of the explained function as their first argument. Further arguments can be specified with `addfun.args`. Results of the additional functions are shown right after the output of the explained function.
`addfun.args`	Vector of arguments (apart from the return object of the explained function) for the additional functions (optional). Example: `addfun.args = "trim = 0, na.rm = FALSE"`. Argument must be of the same length as `addfun`; `addfun.args` must be `""` (empty string) if the respective additional function does not take any additional arguments.
`addfun.title`	Vector of titles that will be shown as headers to the outputs of the addional functions (optional). Argument must be of the same length as `addfun`; `addfun.args` must be `""` (empty string) if the respective the output of the additional function shall have no title.

Details

xplain interprets/explains the results of a function call (argument call) by using the information provided in the xplain XML file specified by the xml argument.

1. xplain XML files

xplain XML files follow a simple structure (here an example for the lm() function from the stats package):

<title> elements contain plain text and can be used to structure the output of xplain(). They are underlined by the character given in the title.char argument.

<text> elements contain the actual explanations and interpretations. They may consist of plain text as well as R code. R code must be enclosed by special opening and closing tags like this: !%% Here comes the R code %%!. The placeholder @ can be used to access the explained function's return object, e.g. !%% summary(@) %%!.

With a <result> block you can interpret specific elements of the explained function's return object. The element of the current <result> block can be accessed with the ## placeholder from within an R code section delimited by !%% and %%!. Example: <text> The mean is: !%% mean(##) %%!</text>.

If you use certain R code expressions multiple times and want to save typing effort and reduce error-proness, you can work with a <define> block. Like a <text> block, <define> can encompass both, plain text and R code, e.g.
<define name="my.summary">The summary is: !%% summary(@) %%! </define>. After having defined an expression this way, you can call it from within an R code section by using its name and placing it between the special placeholder tags !** and **!, like <text>Let us have a lookt at the summary: !** my.summary **! </text>.

Sometimes you will want to apply a <text> block not only to one element of the explained function's return object. Consider, for example, the case in which the return object contains a vector and you want to run through each element of that vector. In this case, you can use a <text> element with the foreach attribute, e.g. <text foreach="rows">. The attribute's value defines how xplain iterates over the object. Possible values are "rows", "columns", "rows, columns", "columns, rows" and "items" for list items. Within R code included in your <text> block you can then refer to the index of the current object with the $ placeholder, e.g. !%% The current element is: @$coefficients[$,1] %%!. If two different indices are in play (e.g. when foreach="rows, columns") then you can work with two index placeholders $, e.g. coefficients[$,$].
Because xplain() needs to know which object to iterate over, you can use <text> with the foreach attribute only form within a <result> block.

xplain() can access XML files both locally and from the internet. xplain XML fiels are not case-sensitive.

2. XML Attributes

<package>, <function>, <result> and <define> blocks always need a name attribute.

<title> and <text> blocks can have lang and level attributes, for the language and the complexity level of the explanations, respectively. lang is an ISO country code and level an integer number (for details, see the explanantion of the corresponding arguments of xplain() above). The values of these two attributes are inherited from higher-level XML elements, e.g. from <package> or <function>. Attributes defined at lower levels (e.g. in an individual <text> element) overrule these inherited attributes.

3. Search paths from xplain XML files

If no path is provided with the xml argument of xplain() or the provided file does not exist then xplain() searches for a suitable XML file in various locations:

in the path of the package containing the function from which xplain() was called for a file of the name "package_of_the_calling_function.xml";
in the same path for a file with the name "package_of_the_explained_function.xml" (the function given in the call argument);
in the path of the package containing the explained function for a file with the name "package_of_the_explained_function.xml";
in the current working directory for a file with the name "package_of_the_explained_function.xml"; and
in the current working directory for a file with the name "explained_function.xml".

4. More information on xplain XML files

For more details on the structure of xplain XML files, please consult the web tutorial on http://www.zuckarelli.de/xplain/index.html.

Value

xplain() returns the return value of the explained function call (argument call) as if the function were called without xplain(). The interpretation/explanation information is either shown on the screen or written to a file (depending on the filename argument).

More material on the internet

Web tutorial on how to work with xplain: http://www.zuckarelli.de/xplain/index.html
xplain cheat sheet: https://www.zuckarelli.de/xplain/xplain_cheatsheet.pdf

Author(s)

Joachim Zuckarelli, joachim@zuckarelli.de

Examples


library(car)

xml.path <- system.file("", "example_lm.xml", package = "xplain")

xplain(call="lm(education ~ young + income + urban, data=Anscombe)",
  xml=xml.path)

[Package xplain version 0.2.2 Index]