R Script Object

R Shell

The R Shell object imports R scripts and datasets for use in Phoenix.

Note:Phoenix program plugins, such as the R Shell object, assume that the corresponding third party software is installed and running properly.

Note:S-PLUS code must be converted to R for use within Phoenix.

Use one of the following to add the object to a Workflow:

Right-click menu for a Workflow object: New > External Software > R Shell.
Main menu: Insert > External Software > R Shell.
Right-click menu for a worksheet: Send To > External Software > R Shell.

Note:To view the object in its own window, select it in the Object Browser and double-click it or press ENTER. All instructions for setting up and execution are the same whether the object is viewed in its own window or in Phoenix view.

Additional information is available on the following topics:

Setting up preferences
User interface description
Importing/Writing the code to access the external program
Executing a third party tool object
Results

Setting up preferences

Global preferences are available to the user. Some third party tool objects require certain global settings to be specified prior to use. There are optional settings to enable editing of scripts in external programs from within Phoenix. Some optional preferences can streamline the workflow by automatically filling in or setting options in the object’s UI with information entered by the user in the Preferences dialog.

Setup access to the external program
Specify a development environment
Define a default output location

Setup access to the external program

Select Edit > Preferences.
In the Preferences dialog, select the object in the menu tree.
Enter the directory path to the executable in the first field or click Browse to locate and select the directory.

Specify a development environment

There is a Development Environment section available on the preference pages. When the development environment is defined in this section, users can access that environment from the third party tool object’s Options tab with the Start button. This allows users to edit scripts in other specified environments, and then pull the updated scripts back into Phoenix, at which time, the script can be executed from Phoenix and the output processed through the normal Phoenix workflow.

In the Command field, enter the directory path to the executable or click Browse to locate and select the file.
In the Arguments field, enter any arguments/keywords to use when starting up the environment.

Note:Proper development environment setup for Tinn-R requires that $WorkDir\$File be entered in the Arguments field.

Define a default output location

Setting the output folder in the Preferences dialog eliminates the need to enter the information in the Options tab for each run. The fields will automatically be filled with the paths entered here.

Enter the directory path in the Default Output Folder field or use the Browse button.

Note:If the user specifies a default output location, the user must ensure that they have write access.

Turn on the Create a unique subfolder for each run checkbox to generate and then store the output from each run in a new subfolder of the output folder.

User interface description

Setup tab
Options tab
Result Filters tab

Setup tab

The Setup tab allows mapping of scripts to the object. The Mappings panel(s) of the Setup tab displays the column headers specified in the script file. The Text panel allows users to map a script file to the object and view the contents.

Note:Any apostrophe marks in the input data (e.g., 5’-deoxy-) should be removed or substituted, as they can prevent Phoenix from reading the data. Apostrophes are interpreted as quotation marks, so data between two apostrophes is considered to be a single cell value. This can result in the number of columns not being the same for all rows,

Context associations for R Shell objects change depending on the column headers, or input, defined in the script file. Not all R scripts define or use mapping contexts. If the #WNL_IN # statement does not define any mapping contexts, then there are no mapping options available in the Mappings panel.

How dataset Mappings panels are defined in R scripts

Before the script is mapped, there are no data inputs into the R Shell object. The data inputs are defined in the attach() statement in the script. When using an imported dataset or a results worksheet as input for an R script, one or more attach() statements must be in the script in order to map an input dataset or sets.

The attach() statement in the script requires the following format:

attach(dataname) #WNL_IN context1 context2 context3 etc#

Each attach() statement creates a data mappings panel that allow users to map a dataset as input for the script, and users can map study data to the contexts defined in the attach() statement. If the study variable names are the same as the context names, the study variables are automatically mapped to the appropriate contexts. For example,

attach(Eta) #WNL_IN Id nV nCl#

A data input called Eta is created in the object and is listed in the Setup and Diagram tabs. Also, the data mapping contexts Id, nV, and nCl are created in the Eta Mappings panel.

Note:Using the #WNL_IN # comment to create mapping contexts is optional. If it is used, the column names in the comment must be space-delimited.

If the attach() statement does not have #WNL_IN … #, then Phoenix treats the data as an external source specified in the script and not as an imported dataset. Scripts written in this manner would be difficult to share as the sources might not be able to be located on a different computer.

The example R script (plotpredtable.r), available in …\Examples\R, has these lines:

attach(Residuals) #WNL_IN ID IVAR TAD POPPRED INDPRED
OBS IRES WTIRES WRES CWRES PCWRES CdfPCWRES CdfDV#

attach(Eta) #WNL_IN Id nV nCl#

When using the R object for accessing the Model Comparer results for NLME or NONMEM, the default csv file generated for importing into R will not work. The columns beginning with “#” prevent the file from loading into R. To avoid this problem, set up Model Comparer so it will not generate these particular output columns, or explicitly state the columns to import by using the commenting mechanism for mapping in the R tool. For example, use a script similar to the following to list the columns to import and then map the columns:

   attach(compare.df) #WNL_IN Hide Compare Name Sort
         Method Description Lineage LogLik -2(LL) AIC
         BIC -2(LL)Delta AICDelta BICDelta NumParms
         NumObs NumSubj pvalue

Options tab

The Options tab is used to define a location for the output, access development environment, and start a remove execution.

Entering an output location is optional. If a directory is not specified then Phoenix places output in a temporary folder that is deleted after Phoenix is closed. This may be preferred when sharing third party tool projects with other users, as the output folder is machine specific and may not exist on other machines. If users want to save the results from a third party tool object run to a disk, then they must either specify an output folder or manually export each result to disk.

The results folder set in the Options tab must match the export folder location set in the script. For example, if the export path in an R script is c:\\local\\, then the R Shell results folder must also be C:\Local. To make sharing projects involving R Shell objects easier, set the results folder in the Options tab to the getwd value and refer to getwd in the code. Files written to the path returned from getwd end up in the output folder and in the results.

Enter the output folder path in the field or click Browse to specify the output folder location.
Turn on the Create a subfolder for each run checkbox to add a new results folder in the specified output location each time the object is executed.

This option prevents the output from being overwritten with each run, especially if the default output folder option, under Edit > Preferences, is being used.
Click Select Sources to include additional files along with the mapped input.
Click the Clear Empty Results to remove any results published by the object that are empty.
Turn on the Include R Workspace checkbox to have Phoenix store the R Workspace with the results.

The R Workspace, called RData in the results, can then be re-used in other R objects by using the Select Sources button to select it as a source for that object.
To start the development environment, click Start in the Development Environment section of the Options tab.

The development environment as configured in the Preferences dialog is started. (See “Specify a development environment”.)
When script work is completed, click Reload Script to bring the modified script into Phoenix for use in the next execution of the object.

Result Filters tab

See the “Result Filters tab” description for the PsN object.

Importing/Writing the code to access the external program

The R Shell object must have code that will allow it to initiate the external program and submit jobs. The code can be stored as a script file, imported into the project, and mapped to the object, or the code can be directly entered into the object.

Import and map file containing code
Write code in the Text panel
Adding shortcuts in scripts
Filtering results by size

Import and map file containing code

The process is the same as for many other Phoenix objects. Refer to “Importing datasets” common task description.

Write code in the Text panel

Instead of importing and mapping a script file, users can write their own code or copy and paste code from another source. (For more information, see the “Write code in the Text panel” section for the PsN object.)

Adding shortcuts in scripts

The input can be defined within the script as a shortcut by adding the following at the beginning of the script.

#PHX_SHORTCUT(Data)

The text entered between the parentheses is used as the variable’s name (e.g., Data).

Phoenix will parse the script and prepend the variable to the script, with the shortcut path being stored assigned as the value.

Data <-”C:\\Path\\To\\File”

In the script, the user can use the variable assigned the path to read or manipulate the file.

To add a shortcut to a script

With the object inserted in the project, click R Shell in the Setup list.
Either type the script directly in the field or click (Select Source icon) and select the script (which has already been imported into the Code folder).
Type the following as the first line in the script:

#PHX_SHORTCUT(Data)

Click Apply.

The following image is the R Shell Setup panel showing the contents of the script. Notice the first line, indicating that a shortcut will be the source of the input data.

Select the new Data item in the list.

The Data panel shows the full path behind the shortcut.

The log file produced from executing the object contains the definition used for the shortcut. Below is an image of the R Log file.

Filtering results by size

See the “Filtering results by size” section for the PsN object.

Executing a third party tool object

Click (Execute icon) or to run the job remotely, click Execute Remotely in the Options tab.

Executing a third party tool object remotely sends the job to the server that is defined in the Preferences dialog (Edit > Preferences > Remote Execution). See “Phoenix Configuration” for instructions. The project is saved automatically.

The project must have been saved at least once prior to executing on RPS, otherwise execution will not pass validation and a validation message will be generated.

At this point, the step being executed on RPS, along with any dependent objects, has been locked. It is now safe to close the project or to continue working in Phoenix.

In Phoenix, some objects in a workflow allow the user to click and execute the last object in a chain and it will re-run any necessary objects earlier in the workflow. This is not true for the R object. Either the workflow or the individual objects must be executed to obtain the current source data for the R object.

Results

The results are displayed on the Results tab. The output falls into the following categories:

Output Data: Datasets in tabular form

Text Output: Settings files, log files, and other text output

Other: Other kinds of files, for example: documents, export files, binary files, etc.

Images: Graphs or other images in recognized image formats (jpg, tiff, emf, etc.)