English / Japanese

Introduction

Thank you for using our product. This document guides you through R AnalyticFlow 3 (RAF3). Feedbacks are greatly appreciated: please mail to rflow-support at ef-prime.com.

Note

Some of the contents may be based on development version of the software.

Download and Setup

Download

Download an appropriate package for your system. RAF3 is available for Windows, Mac and Linux.

Install and Launch

Follow the instructions below appropriate for your system.

Windows

1. Install R. Visit CRAN (The Comprehensive R Archive Network) mirrors to obtain R.
2. Install RAF3. Launch the installer and follow the instructions.

Double-click on the application shortcut icon to launch RAF3.

Mac

1. Install R. Visit CRAN (The Comprehensive R Archive Network) mirrors to obtain R.
2. Install rJava package. Launch R and execute: install.packages("rJava")
3. Open the zip archive of RAF3 and drag & drop the application icon into your Applications folder.

Click on the application icon to launch RAF3.

Linux

1. OpenJDK (>= 17) and OpenJFX (>= 11) are required. On Ubuntu, execute the following command to install: apt install openjdk-21-jdk openjfx
2. Install R. Visit CRAN (The Comprehensive R Archive Network) mirrors to obtain R. On Ubuntu, execute the following command: apt install r-base
3. Install rJava package. On Ubuntu, execute the following command: apt install r-cran-rjava
4. Extract the tar.gz archive of RAF3: tar -xzvf RAnalyticFlow_Linux_<VERSION>.tar.gz

rJava package can be installed by install.packages("rJava") on R. You can launch R as R CMD javareconf JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64 -e R to use specific JDK on the package installation.

A directory named RAnalyticFlow_<VERSION> will be created after the process above. Enter into this directory and execute the following command to run RAF3:

./rflow &

To specify the location of Java and JavaFX, set JAVA_HOME and JFX_LIB variables before execution as:

JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64

JFX_LIB=/usr/share/openjfx/lib

It is especially recommended to set JAVA_HOME on the first execution, because you need to install JavaGD package.

Quick Tour

Basic Usage

Quick Start

By launching RAF3 you will see the following dialog after the initial setup. Click on Quick Start button to start your work.

You will be asked to install some of required packages (rJava, JavaGD and codetools) if missing.

Analysis Flow

An analysis flow represents workflow of data analysis. You can create, edit, save and load an analysis flow.

Let’s see an example to understand the concept of analysis flow. Click on Help > Tutorial > 1. Introduction from the menu.

Each node (icon) represents a process of data analysis and contains corresponding R scripts. You can run the flow to execute these processes in order.

Select the X-Y Plot node and click on the Run Flow button to see the result.

You can also run a single node by Run Selection button. Try running Histogram node for example.

Edit Multiple Flows

you can edit multiple analysis flow files in RAF3. In the figure above you can see two flows, New Flow and 1. Introduction, at the same time.

Later we will introduce the concept of project to manage resources like flow files, data, documents and other resources.

Quit

Finally close the window to quit the program.

Analysis with Workflow

Now we are going to introduce how to analyze data, and to create analysis flow with RAF3. Launch RAF3 and follow the instructions below in Quick Start mode.

Operations

Basically data analysis is done using operations on RAF3. Click on the Input icon on the tool bar and select Load Sample Data.

Then you can see the dialog below. Enter iris in the Data text box and you will see the preview of the result.

The preview is generated in a dedicated environment not to affect the current workspace. In RAF3 you can see this preview in various situations. Please be aware that the preview is not always identical to the actual result, since it is usually generated with only a small subset of data.

Click on Run button to actually load the data. Then the PREVIEW sign disappears to indicate this is the actual result. It reports no error and seems successful this time.

Create Nodes

Let’s leave this operation in an analysis flow. Drag Drag to Add button and drop on the working flow.

Then a corresponding icon is added in the flow. This icon is called a node.

You can also add a node by drag and drop of an operation icon. For example click on the Script on the tool bar, and drag the R Script icon and drop it into a blank space of a flow.

Draw Edges

Try dragging the above R Script node, and drop on the Load Sample Data node. Nodes are connected by an arrow, which is called an edge.

The following are alternative ways to draw an edge:

• Select a node and push the Draw Edge button, then click on another node.
• Drag with right-button of the mouse
• Select a node and hold down the Alt key, then click on another node

R Script Node

R script node is a node where you can write R script directly. To create an R script node, drag and drop R Script from Script on the tool bar.

You can also double-click on a blank space of analysis flow to create an R script node.

Selection-based behavior

Lots of operations can reflect your selection of objects.

Let’s see an example. Select the iris object in the R Object tab as the figure below:

Now execute an operation with this object. As an example we are going to output this data to a plain text file. Click on the Output on the tool bar and select Write Text File icon.

Then you will see the dialog below:

Here the name of the selected object (iris as Data) has been automatically entered according to your selection. The name of the output file (File) is iris.txt by default. Parameters such as Separator and Column Names have also been set automatically but you can change them as you like.

Appropriate R code is generated according to these selection of parameters. Select Script tab to review the code generated:

Then Run to execute the code and try Drag to Add.

You can follow the same procedure when loading a text file to R’s data.frame object. Select iris.txt on the File tab :

Then execute an operation with this object. You can do this by:

• Click on the Input on the tool bar, and select Read Text File icon

or one of the following:

• Click on the Operation button on the viewer, and select Input > Read Text File
• Right-click on the object and select Operation > Input > Read Text File

Then you can see that iris.txt is selected as the input, with auto-detected parameters.

Project

RAF3 has a simple system for project management. It is a file-based system which can be used with other management systems including Git or RStudio.

To create a new project in RAF3, choose a project home directory first. It can be any directory including existing RStudio project directory. By default project home is also used as the working directory of R session.

Quick Start Mode

In Quick Start mode you can start your work without configuring a project. In the background a temporary directory is created and it is used as the project home.

This temporary home directory will be deleted when you quit the program or start another project (including a new Quick Start session), until you save the project beforehand.

To save the project, click on button on the tool bar. Enter the name of a directory to use as the new project home. All the data including analysis flows are moved to the new project home directory.

Create a project

Launch RAF3 to show the following dialog. If it’s already running, click on the button on the toolbar.

Click on New Project… button. Then you will be asked the Project Name and its Location. In this example the project name is MyProject, and the location is C:\Users\user\Documents\RAnalyticFlow\MyProject.

Default Encoding and Newline are settings for external files, and are used when writing R scripts or data to files. These values are set as default but you can change them in each case.

Click on OK. Then the new project has been made and you can start working on it.

File Structure

Project Home is a directory where you will store any information about the project. A typical data analysis project consists of data, processes (analysis flow / scripts) and documents. It may also contain binary files, property files or meta data files (.git directory for example).

The following diagram is an example of project home directory:

* Project Home/
    |
    +-- *.rflow (Analysis flow files)
    |
    +-- (Data files, documents, scripts, etc.)
    |
    +-- .afp/
        |
        +-- (Project information files)

.afp is a (hidden) directory which contains internal information about the project. It may be invisible depending on your system settings. This directory is not intended to be edited by users, so please be careful if you touch it.

Link

It is not always a good practice to store all resources in a single directory. As a common case you may want to store data files in a remote server while you are working on your local machine.

To support such cases a link to a directory or file can be included in a project. The following diagram shows you the concept:

* (Link to) some directory/
    |
    +-- ...

* (Link to) some file

These links are shown along with the project home directory. See the figure below for example:

Here data directory and file.txt are not in the project home, but can be accessed easily by links.

There are two ways to create a link:

• Right-click on a blank space of file explorer and select Add Link….
• Drag and drop a file / directory into a blank space of file explorer.

Customize

Custom Operations

In RAF3 you can create your own operations. To create a new custom operation, click on Custom on the toolbar and select New….

First specify a function. In this example we have chosen mean. In what follows we will build an interface to control this function.

Instead of using an existing function, you can also define a new function that represents the operation. To do this select User Defined Function and input function definition on the Definition tab.

The Title section will be used as the name of this operation. We named it Compute Average here but you can leave it blank (in that case function name is used as the title).

If the function returns some value, check the Output to Object to let user specify an object to assign the returned value. It can be off if the function returns nothing or you do not need to assign the value.

The next step is to add controls to specify arguments of the function. Click on the button and select x.

Then an entry is added to the list. You can set a title to this argument but leave it blank for now.

Default is the default value for this argument. But there seems to be no natural default value here, so leave it blank too.

You can check Required to force a user to input some value to this argument. Check it since x cannot be missing for mean function.

The preview is shown below. There are two inputs, Output Object and x. Since x is required it shows an error sign when blank.

Let’s add another control about handling NA (Not Available) values. Click on the button again and input na.rm. On the right hand side, select List to add a selection-based control.

Since the name na.rm may not be meaningful, set Igonre Missing Values as the title.

Tick off the Editable checkbox. If it is on a user can input text instead of select an element, but we do not need this feature here. Leave Default blank.

Then add candidate values for the selection in Choices section. There are two candidates; one is TRUE and put a label Igonre to clarify the meaning of this selection. The other is FALSE with a label Do Nothing.

Now review how the new operation works. Input some values in the preview area and select the Script tab to review the code generated:

It seems working well. Try clicking on Preview button to test the behavior of this operation:

Finally close the test window and click on Save as… button to save this operation. It is saved as a .yaml file. Please save it the default directory named custom_ui.

After saving you can access the operation from the Custom menu on the toolbar:

Custom operations can also be added to an analysis flow in the same way as built-in operations. Custom nodes can be saved within a flow, so you can send the flow file to other user to let them use these nodes.

Customizing Toolbar

You can customize the toolbar to make it preferable for you. For example, you may prefer more space-saving toolbar when working on a small screen.

To change the toolbar settings, click on Preferences > Configuration from the menu and select the Appearance tab.

Notes and Acknowledgement

About R Packages

RAF3 depends on some R packages. However, except for those mentioned in the install process, there is no need to care about them in most cases; you will be asked to install missing packages when needed.

However it becomes a problem when you have only a limited, or no Internet access. For such cases install the packages listed below in advance.

The packages listed below are required:

• rJava
• JavaGD
• codetools

You can install all these packages with an R script like below, but please do not try it when RAF is already running:

install.packages(c("rJava", "JavaGD", "codetools"))

Since RAF is dependent on these packages, the installation may fail and can lead to data corruption. As a safer way you can execute it on normal R console before launching RAF, or just launch RAF3 and follow the instructions for installation.

Acknowledgement

We would like to express appreciation for developers of R and other open source libraries, and FatCow for icons used in RAF3 and this document.

Finally we would also like to acknowledge the contributions from our users. Please mail to rflow-support at ef-prime.com for feedbacks.