Standard R Page
A Standard R Page is a page on this wiki which is used to create analysis options available from the menus within Q (see Standard R for other ways of creating Standard R). This page describes the structure of a Standard R Page.
Introduction
As soon as you start working on a Standard R Page, you should paste the following code in and save it:
{{UnderConstruction}} <!-- Remove this when the QScript is ready. -->
<span data-hide-from-q="true"></span> <!-- Prevents the script from being available in Q and Displayr. Remove it when script is ready. -->
Then:
- A brief description of what the analysis will do.
- Links to related analyses.
Example
Where helpful, an example of the outputs should be provided. It is usually helpful to show examples for any analysis that produces a graphical output. It is less useful to show outputs from statistical tests.
Options
The controls available on the Standard R Page. E.g., Variables. All possible arguments should be described here. Where the meaning of the arguments is not likely to be obvious to somebody with experience using the type of analysis, a brief explanation should also be provided, along with references. For example:
Robust standard errors Computes standard errors that are robust to violations of the assumption of constant variance, using the HC1 (degrees of freedom) modification of White's (1980) estimator (Long and Ervin, 2000). This is only available with the Linear and Poisson models.
Technical information
An optional description of relevant technical information. For orthodox methods, such as regression, this section will generally not be provided.
Diagnostics
Links to other Standard R options which perform diagnostics on the analysis described on the page.
Acknowledgements
Acknowledgements to any packages or code that are relied upon.
References
References to any materials referred to in the above sections.
Code
The Code section should contain one section of JavaScript code, and one or more sections of R code.
JavaScript code
The JavaScript determines which controls should appear on the Inputs tab of the Object Inspector. Detailed reference material for create controls is at R GUI Controls. Key aspects to take into account are:
- It is surrounded by a syntaxhighlight tag.
- A heading, which appears above the controls, is written using form.setHeading('Heading name');. Headings can be conditional on other controls (e.g., see Regression - Linear Regression for an example).
- Control names should written in camelCase, commencing with the word form (as this makes it easy to recognize the controls in the R code).
- Consistency is important. In general, use the same labels, names, and categories, as used elsewhere. Common examples:
- The name that appears at the top of the controls [[Object Inspector]
- form.dropBox({label: "Outcome", types:["Variable: Numeric, Date, Money, Categorical, OrderedCategorical"], name: "formOutcomeVariable"});. Note that we do not use the term dependent variable.
- form.dropBox({label: "Predictor(s)", types:["Variable: Numeric, Date, Money, Categorical, OrderedCategorical"], name: "formPredictorVariables", multi:true})
- form.comboBox({label: "Output", alternatives: [">tt> ... "], name: "formOutput", default_value: " ... Sankey"})
- form.comboBox({label: "Missing data", alternatives: ["Error if missing data", "Exclude cases with missing data", "Use partial data", "Imputation (replace missing values with estimates)"], name: "formMissing", default_value: "Use partial data"})
- form.checkBox({label: "Variable names", name: "formNames", default_value: false});. Note that when writing the R Code, this argument will need to be negated, as the Standard R Style Guide requires that the parameter be show.labels (i.e., show.labels = !formNames).
- form.checkBox({ name: "binaryCat", label: "Categorical as binary", default_value: false }); (see the example in the R code below).
Detailed information on all the different types of controls is at R GUI Controls.
Example
<syntaxhighlight lang="javascript">
form.setHeading('Classification And Regression Trees (CART)');
form.dropBox({label: "Outcome",
types:["Variable: Numeric, Date, Money, Categorical, OrderedCategorical"],
name: "formOutcomeVariable"})
form.dropBox({label: "Predictor(s)",
types:["Variable: Numeric, Date, Money, Categorical, OrderedCategorical"],
name: "formPredictorVariables",
multi:true})
form.comboBox({label: "Output",
alternatives: ["Sankey", "Tree", "Text"],
name: "formOutput", default_value: "Sankey"})
form.comboBox({label: "Missing data",
alternatives: ["Error if missing data", "Exclude cases with missing data", "Use partial data", "Imputation (replace missing values with estimates)"],
name: "formMissing", default_value: "Use partial data"})
</syntaxhighlight>
R code
Key aspects of the R Code box are:
- It is surrounded by a syntaxhighlight tag.
- Where the analysis uses raw data as an input (i.e., as opposed to aother R Output or a table), it should address:
- Weights, using one or both of QCalibratedWeight or QCalibrationWeight (see Weights in R).
- Filters, using QFilters. See Standard_R_Style_Guide#Filters_and_weights.
- The actual analyses themselves should be performed in an R package. Ideally, there will be an existing R package. However, often it is necessary to create a new function in a new package, as most packages do not adequately address all of missing data, weights, and filters.
- Any transformations of the data required to address how the data is exported from Q should typically occur in this R Code box, and not be wrapped up in functions. For example, if there is a need to convert factors into numeric variables, this should be visible in the code in the R code box.
- It should be relatively easy to understand. The goal is that a user can edit it if they need to.
- All functions parameters in a function's signature should typically be exposed, so that the user has the ability to find and use parameters not hooked up to the GUI.
Example
<syntaxhighlight lang="rsplus">
library(flipRegression)
wgt <- if(formMissing == "Use partial data (pairwise correlations)" | formType == "Ordered Logit" | formType == "Multinomial Logit")
QCalibratedWeight else QPopulationWeight
if(formType == "Multinomial Logit")
formDetailed = TRUE
if(!(formType == "Linear") || formMissing == "Use partial data (pairwise correlations)" || formMissing == "Multiple imputation")
formRobustSE = FALSE
if(formMissing != "Multiple imputation")
formAuxiliaryVariables = NULL
glm <- Regression(QFormula(formOutcomeVariable ~ formPredictorVariables), weights = wgt, subset = QFilter, missing = formMissing, detail = formDetailed, robust.se = formRobustSE, type = formType, show.labels = !formNames, auxiliary = formAuxiliaryVariables)
</syntaxhighlight>
Categories
The categories listed at the bottom of each Standard R Page indicate which products and menus the pages are available in.
The name of the page determines the ultimate name of the item in the menu and any sub-menu(s). Dashes are used as delimiters. For example, Regression - Generalized Linear Model creates an item called Generalized Linear Model in a sub-menu called Regression. There is no limit to the number of sub-menus.
Q remembers the structure of the menus. This means that when new pages are written, the menus may take some time to update. To make them update immediately to recognize a new wiki page or a renamed wiki page:
- Go to https://app.displayr.com/Admin. You need to have admin access to do this.
- Click Clear Automation Library Cache.
- Wait until it says re-indexing is complete.
- Close and re-open Q.
Other categories
Additional categories should be listed at the end of the page (but not in a section) that are relevant from the perspective of allowing users to find information in the wiki. For example:
[[Category: Filters]]
Example categories:
- R Online Library indicates that the Standard R Page is in Displayr.
- Automation Online Library indicates that the Standard R Page is in Automate > Browse Online Library.
- Create Segments indicates that it is in Create > Segments.
- Filters indicates that the page appears in the Filters category on the wiki