User Guide

Working with files

files icon, grabbed on 17.01.17, using XAP version 1.19.1 2740-8759a, from https://edcvaatest04.aridhiatest.net/#/workspaces/1150Files allow users to import or create files of various types in their workspace. Files can be scripts to work with data, documents, images etc. Files can be created and accessed in the Files tab and can be any type of file, including:

  • SQL (.sql)
  • source code
  • R files (.r)
  • LaTeX markup (.rwn)
  • archives (.zip, 7z, .gz)
  • plain text (.txt)
  • image files (.jpeg, .png)
  • audio files (.wav)
  • Word documents (.docx)
  • PDF documents (.pdf)

Files can be both uploaded and downloaded, and can be renamed once they are in a workspace. You can also create files directly within the workspace, using the built-in editor.

Clicking the Files tab displays the list of available files.
files - scripts, grabbed on 17.01.17, using XAP version 1.19.1 2740-8759a, from https://edcvaatest04.aridhiatest.net/#/workspaces/1152/folders/scripts/annotation assistant

Figure 6: Files tab

You can filter and sort the files list:files - sort, grabbed on 17.01.17, using XAP version 1.19.1 2740-8759a, from https://edcvaatest04.aridhiatest.net/#/workspaces/1152/folders/scripts/annotation assistant

  • by file type, using the Show drop-down
  • by date or alphabetically, using the Sort drop-down
  • by typing into the search box at the top of the list

From this page, you can:

  • create a new file
  • edit a file
  • download files
  • delete files
  • add notes and tags
  • rename files
 

To upload files using sftp (e.g. scripts, reference documents)

The upload method for files via SFTP client is similar to uploading data files [Insert link to uploading data files], with the only difference being that files must be placed into files folder instead of data folder.

  1. Select one or more files from your local machine and drag them to the Files
  2. When the platform has completed the processing of the data, a log file reporting the success or failure of the upload will be created. The file has a name in the following format:

    For example:

    files___.txt
    files_success_20140503_121535.txt

To verify that the file has been successfully uploaded, you will be able to see the file in the web interface for your workspace. From here you can also check that there is the relevant upload event is shown in the activity stream in the ‘Summary’ tab. Also, if you have workspace administrator permissions, you can view audit log in the ‘Audit’ tab detailing the success or failure of the upload. If file was uploaded successfully, you can access file in the ‘Files’ tab.

 

To upload file-based data (e.g. images)

To upload file-based data via SFTP server client:

  1. Select one or more file(s) from your local machine and drag into the Datafiles
  2. Once the files have been copied in full to the Datafiles folder, the platform will start to transfer them into the workspace. The time needed to upload and process the data is dependent on a number of factors, including:
    • The size of the file.
    • The speed of your network connection.
  3. You can now log out of the SFTP server.

The import process pulls new files in the SFTP area every few minutes and transfers them to your workspace’s private file storage area, so a short delay (up to 5 min, or longer for very large files) between uploading the files via SFTP and seeing them appear in the workspace is to be expected.

The uploaded files are available in a timestamped folder in the private file storage area associated with your workspace, whose name is based on the following format: <year><month><day><hours><mins><secs>

 

Creating a new file

To create a new file in the web-based platform:

  • Navigate to the workspace where you want to create the file.
  • new file dropdown, grabbed on 18.01.17, using XAP version 1.19.1 2740-8759a, from https://edcvaatest04.aridhiatest.net/#/workspaces/1152/folders/scripts/annotation%20assistantClick the Add tab and select the type of file you want to create, one of:
    • SQL file (.sql)
    • R file (.r)
    • Report file (.rnw)
    • Text file (.txt)
  • Enter the name for the file then click the Create new File This creates the new file and opens a text editor, allowing you to create the required file directly in your workspace.
  • Once you have added your content, save the file.

new file dialog, grabbed on 18.01.17, using XAP version 1.19.1 2740-8759a, from https://edcvaatest04.aridhiatest.net/#/workspaces/1152/folders/scripts/annotation%20assistant

 

Adding and deleting files

To delete a file:files tools, grabbed on 18.01.17, using XAP version 1.19.1 2740-8759a, from https://edcvaatest04.aridhiatest.net/#/workspaces/1152/folders/scripts/annotation%20assistant

  • Navigate to the workspace containing the file you want to delete.
  • Click on the Files tab to display a list of all files in the workspace, or use the search function to find the require file by name.
  • Select the file by clicking anywhere on the row, other than the file name or icon.
  • At list of available function relating to the selected file will appear in the right hand side of the window. Click the Delete file button and a popup will confirm that the delete operation has been successful.
 

Downloading a file to your computer

Some file types cannot be directly viewed within your workspace (e.g. video, audio), but can be downloaded to your computer. To download a file from a workspace, typically to your PC:

  • Navigate to the workspace containing the file you want to download.
  • Click the Files tab to display the list of available files.
  • Click the file you want to download; this will display the contents of the file.
  • Click the Download button from the Tools sidebar menu.

This downloads the file from your workspace.

 

Opening, editing, and saving files

In the Files tab, clicking a file name or icon opens the file. The behaviour depends on the file type:

  • SQL files open in an editor page where you can write, modify, run, and save SQL. These files can be saved as a Custom View: see the Custom Views and Database Views sections for more information.
  • Text (.txt) files open in an editor where you can edit and save the file.
  • Image files will be displayed.

You can open and save multiple versions of some types of files like documents and programming scripts.

  • To open a particular version of a file, click the file in the Files tab to open it, then use the Version drop‑down link to select the version to use.
  • To save a new version of a file, click the Save as button and select Save as new version.

save file, grabbed on 18.01.17, using XAP version 1.19.1 2740-8759a, from https://edcvaatest04.aridhiatest.net/#/workspaces/1152/workfiles/36202

 

Working with SQL files

add icon, grabbed on 17.01.17, using XAP version 1.19.1 2740-8759a, from https://edcvaatest04.aridhiatest.net/#/workspaces/1150
When in the Files tab, you can either upload a SQL file or click the Add tab and select New SQL File. You are then taken to the editor page, from where you can edit the SQL file.

Once you have created a file containing SQL, you can run either individual statements or the entire file. When on the SQL editor page, highlight the SQL file then click the Run File button. Note that you do not need to save the SQL file before running it.
sql file, grabbed on 19.01.17, using XAP version 1.19.1 2740-8759a, from https://edcvaatest04.aridhiatest.net/#/workspaces/1152/workfiles/36540

files buttons, grabbed on 19.01.17, using XAP version 1.19.1 2740-8759a, from https://edcvaatest04.aridhiatest.net/#/workspaces/1152/workfiles/36540

Users can save fetched output as a new Custom View, save as a new file, and open data in the new tab using buttons displayed in the top-right of the results output section.

 

Working with R

To start a new R session, navigate to R console tab.r icon, grabbed on 19.01.17, using XAP version 1.19.1 2740-8759a, from https://edcvaatest04.aridhiatest.net/#R console, grabbed on 19.01.17, using XAP version 1.19.1 2740-8759a, from https://edcvaatest04.aridhiatest.net/#/workspaces/1152/rtools

 

Accessing specific R packages

R packages that are available from CRAN can also be installed and used within your R session. The packages are installed using the usual R commands. The built-in R console also allows users to install packages from CRAN repository and are updated on a weekly basis.

To list the packages available for installation:

  • Type the command: available.packages()
  • then press the Return key

To install a package from the list:

  • Type the command: install.packages(‘[PACKAGE NAME]’)
  • then press the Return key

More detailed information on these commands are available from the R manuals at CRAN found here https://cran.r-project.org/. In some circumstances, packages may fail to install. There are several possible reasons for this:

  • The necessary system requirements aren’t available.
  • The version of R is incompatible with the package.

If you require access to a specific package that fails to install please contact the AnalytiXagility administrator by emailing servicedesk@aridhia.com

 

Running XAP and R commands

Display the list of platform specific functions by typing ls(). In the R console AnalytiXagility is shortened to XAP, which delivers a list of functions as shown below.
R console ls(), grabbed on 19.01.17, using XAP version 1.19.1 2740-8759a, from https://analytixagility.aridhia.net/#/workspaces/58/rtools

Check that your uploaded data table exists. In this example we’ll look for a data table named my_iris, using the function xap.table_exist(“your_table name”) to see if R console can find it.
R console table_exists, grabbed on 19.01.17, using XAP version 1.19.1 2740-8759a, from https://analytixagility.aridhia.net/#/workspaces/58/rtools

Use xap.read_table(“your_table name”) to read data from the database.
R console read_table, grabbed on 19.01.17, using XAP version 1.19.1 2740-8759a, from https://analytixagility.aridhia.net/#/workspaces/58/rtools

Now you can use standard R commands and syntax to interact with your data, just like you would do it in a standard R editor, e.g. view summary data.

add icon, grabbed on 17.01.17, using XAP version 1.19.1 2740-8759a, from https://edcvaatest04.aridhiatest.net/#/workspaces/1150
You can upload or create R files from the Add tab using the New R File command. A new file editor tab will open. You will be requested to insert a file name, e.g. ‘iris_model’. Once you have created the R file you can place your code in the editor.
view summary data, grabbed on 19.01.17, using XAP version 1.19.1 2740-8759a, from https://analytixagility.aridhia.net/#/workspaces/58/rtools
iris_model.r, grabbed on 19.01.17, using XAP version 1.19.1 2740-8759a, from https://analytixagility.aridhia.net/#/workspaces/58/rtools

You must save the R file before running it in the R console.
r session sidebar, grabbed on 19.01.17, using XAP version 1.19.1 2740-8759a, from https://analytixagility.aridhia.net/#/workspaces/58/rtools

To run your R script from R console, open the console and find your newly created file in the R session Files tab, located in the sidebar. You can use Search to find your file and execute file by clicking action button, grabbed on 19.01.17, using XAP version 1.19.1 2740-8759a, from https://analytixagility.aridhia.net/#/workspaces/58/rtools the on the right of the file name. This will call xap.source() function on your script and execute it in the R console.

r session plot 1, grabbed on 20.01.17, using XAP version 1.19.1 2740-8759a, from https://analytixagility.aridhia.net/#/workspaces/58/rtoolsIf your script returns plot outputs it will be displayed in the R Session sidebar under the Plots tab.

You can click on the plot and save it as image file.
r session plot 2, grabbed on 20.01.17, using XAP version 1.19.1 2740-8759a, from https://analytixagility.aridhia.net/#/workspaces/58/rtools

 

Stopping an r script

stop, grabbed on 20.01.17, using XAP version 1.19.1 2740-8759a, from https://analytixagility.aridhia.net/#/workspaces/58/rtoolsIf you enter an R script or command and notice that it is taking a long time to complete, you can stop it by clicking the Stop bottom of the screen to halt the execution of the script or command.

 

Working with LaTeX markdown files .rnw

The R console provides the ability to generate high-quality PDF reports using the LaTeX document formatting language. These reports can include the following:

  • fragments of R code
  • the output from R commands and scripts
  • high-quality plots generated from R

Document scripts are written in files with the extension .rnw. These files, which contain LaTeX code and, optionally, embedded R, are processed by the ‘knitr’ R package before being further processed to create the final PDF which may then be saved as a file.

 

Creating a report script

A report script consists of LaTeX with optional embedded R code. To create a report script:

  • Navigate to the workspace where you want to create the script.
  • Click the Add tab icon then select the New RNW File command and enter a filename.
  • You are taken to the editor page – enter the script content and save the file.
  • The new script is saved as a file in your workspace.
 

Editing a report script

When you navigate to the Files tab, you can see and filter all of the report scripts in the current workspace. To edit an existing report script:

  • Click the name of the report script you want to edit.
  • The content of the script is loaded into the text editor.
  • Make the required changes to the script.
  • Click the Save button to save the changes to the script.

Alternatively you can save the altered script as a new version of the file; to do this, click the Save as button.

 

Loading the ‘knitr’ library

To generate reports you must load the ‘knitr’ package. To do this:

  • Open an R console, if one is not already open.
  • Enter the command: ‘library(knitr)’
  • Press the Return

You can include this command in your ‘local.r‘ file, but note that changes to local.r apply only to subsequent sessions and do not affect an existing R console session.

 

Generating a report from a script

To generate a report from a script:

  • Navigate to the workspace containing the report script and go to the R Session tab.
  • Click Start console to open the Console
  • In the right hand sidebar, under Files, hover over the report script you want to run.
  • Click the Run in console button for the script. action button, grabbed on 19.01.17, using XAP version 1.19.1 2740-8759a, from https://analytixagility.aridhia.net/#/workspaces/58/rtools
  • Press the Return key to process the script.

If the script runs successfully a new PDF report will be generated, with the name of the report (for example, Rreport000.pdf’) appearing in the Reports tab in the right-hand pane.

NOTE: the xap.knit function will fail if the ‘knitr’ R package has not been loaded. See Loading the ‘knitr’ Library section for how to load this package.

 

Viewing a generated report and optionally saving it to the workspace

After generating the report, its temporary name will appear in the Reports tab in the right-hand pane. Click on the name to:

  • view the report
  • rename the report
  • add a description of the report
  • save the report as a file
 

Making an image file available to a report script

xap.image, grabbed on 20.01.17, using XAP version 1.19.1 2740-8759a, from https://edcvaatest04.aridhiatest.net/#If you have an image file in your workspace, you can make it available when generating a report, for use in LaTeX, by using the function ‘xap.image’. You can do this in the R session at any time prior to generating the report, or within the .rnw file itself.

This will automatically include the required image in the generated PDF report.

 

To contact support, send an email to the Aridhia service desk: servicedesk@aridhia.com.