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.

 

To upload files using the web interface

upload file menu, grabbed on 10.03.17, using XAP version 1.19.2 2878-c35a5ee1a, from https://analytixagility.aridhia.net/When in the workspace, navigate to ‘Add’ dropdown menu (shown by a + sign as shown right) and select ‘Upload Files’. In the ‘Upload file’ panel browse and select the file to upload. Select whether the file should be uploaded to ‘Scripts’ or ‘Documents’. Select ‘Upload file’ to process the upload. If you wish to upload to a pre-existing folder in ‘Scripts’ or ‘Documents’ you should navigate to the desired folder and repeat the above process. On this occasion ‘Current folder’ will be an available option as the file destination.upload file dialogue, grabbed on 10.03.17, using XAP version 1.19.2 2878-c35a5ee1a, from https://analytixagility.aridhia.net/

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: The 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’ dropdown
  • by date or alphabetically, using the ‘Sort’ dropdown
  • 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, with the only difference being that files must be placed into the ‘Files’ folder instead of the ‘Data’ folder.

  1. Select one or more files from your local machine and drag them to the ‘Files’ folder.
  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:
    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 the file was uploaded successfully, you can access the 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’ folder.
  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 and the speed of your network connection.
  3. You can now log out of the SFTP server.

The import process pulls new files from 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 folder

new folder menu, grabbed on 10.03.17, using XAP version 1.19.2 2878-c35a5ee1a, from https://analytixagility.aridhia.net/Users can create folders within the Files section of the workspace. To do so, navigate to the ‘Add’ menu and select ‘New folder’. You should then name the folder and choose whether to create this folder in the ‘Scripts’ or ‘Documents’ section of your workspace. Select ‘Create new folder’ to create the folder.new folder dialogue, grabbed on 10.03.17, using XAP version 1.19.2 2878-c35a5ee1a, from https://analytixagility.aridhia.net/

 

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’ dropdown menu and select the type of file you want to create:
    • SQL file (.sql)
    • R file (.r)
    • Report file (.rnw)
    • Text file (.txt)
    • Other file (*.*)
  • Enter the name for the file then click ‘Create new File’. This creates the new file and opens a text editor, allowing you to create the required file directly in your workspace.
  • Choose which folder you’d like your new file to be created in. This can be the ‘Scripts or ‘Documents’ folder, or the folder that you are currently navigated to in the web interface.
  • 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

 

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 functions 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.
  • From the ‘Tools’ menu select ‘Request a download’
  • In the resulting window, enter the reason for the download request.
    request a download, grabbed on 10.03.17, using XAP version 1.19.2 2878-c35a5ee1a, from https://analytixagility.aridhia.net/
  • Select ‘File’or ‘Dataset’to view the list of available files and datasets for download.
    Attach files, grabbed on 10.03.17, using XAP version 1.19.2 2878-c35a5ee1a, from https://analytixagility.aridhia.net/
  • Select ‘Scripts’ or ‘Documents’ to filter the scope of your search.
  • The ‘Attach files/datasets’ window will now appear. Files or datasets can be individually selected by searching via search bar or scrolling using the scroll bar.
  • Multiple files can be added incrementally by clicking on each desired file
  • Click ‘Attach files/datasets’ to add to the download request list.
    Request a download, grabbed on 10.03.17, using XAP version 1.19.2 2878-c35a5ee1a, from https://analytixagility.aridhia.net/
  • Once the desired files/datasets have been selected click ‘Submit request’
  • The workspace administrator will now be notified of the request and will approve or decline.
    Download request, grabbed on 10.03.17, using XAP version 1.19.2 2878-c35a5ee1a, from https://analytixagility.aridhia.net/
  • If the administrator accepts the download request the download will then be made available.
    Download ready, grabbed on 10.03.17, using XAP version 1.19.2 2878-c35a5ee1a, from https://analytixagility.aridhia.net/
  • Select ‘Download’ to download the file to your local machine.
 

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.

  • 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.
  • PDF files open in a viewer where you can view and navigate within 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’ dropdown 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 (see section To upload files using the web interface) or click the ‘Add’ dropdown menu and select ‘New File’. You are then taken to the ‘New file’ page. Enter a filename, select the destination for the new file and ensure you have selected Structured Query Language file (.sql) from the ‘Which type of file?’ dropdown. Finally select ‘Create new .sql File’ and you will proceed 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.

You can also 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.
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

 

Working with R

To start a new R session, navigate to the R 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 package is incompatible with the version of R running in the console.

If you require access to a specific package that fails to install please contact your Service Desk.

 

Running XAP and R commands

Display the list of platform specific functions by typing ls(), 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 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’ menu 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.

You can click on the plot and save it as an image file:

r session plot 1, grabbed on 20.01.17, using XAP version 1.19.1 2740-8759a, from https://analytixagility.aridhia.net/#/workspaces/58/rtools

If your script returns plot outputs it will be displayed in the R Session sidebar under the Plots tab.

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 run an R script or command and notice that it is taking a long time to complete, you can stop it by clicking the ‘Stop’ button to halt its execution.

 

Working with LaTeX 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’ dropdown menu 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 ‘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’.
  • 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 above for details on 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.