Skip to content

Quick Start

MOLGENIS Armadillo facilitates federated analysis using DataSHIELD. To learn more about DataSHIELD, visit their website or our Basic Concepts page.

First we need to determine what kind of user you are:

  1. Data Manager

  2. System Operator

  3. Researcher

  4. Developer

Data manager

Data management can be done in different ways: the Armadillo User Interface, the MolgenisArmadillo R client, or using DsUpload.

User interface

In the armadillo user interface, data managers can login and manage users, projects and profiles. They can also see the logs (e.g. to understand errors that may have occurred or to monitor use). To get to know more about the UI, visit the usage examples page.

ui-projects.png

Please note that the user interface is only accessible by users with admin rights (i.e. usually data managers and not researchers) only. Users without admin permissions will get the following message:

Warning message for non admin users

You are logged in but you don't have permission to access the Armadillo user interface.

Armadillo R client

Data can also be managed using the MolgenisArmadillo R client. The following code block is an example of how to create a project and upload data. 

# Install and load the package
remotes::install.packages('MolgenisArmadillo')
library('MolgenisArmadillo')

# Login
armadillo.login("https://armadillo-url-example.org")

# Load the iris dataset to upload as test
library(datasets)

# Create a project called "project"
armadillo.create_project("project")

# Upload the data in a folder called "folder"
armadillo.upload_table("project", "folder", iris)

Data is organised in projects. These projects can be compared to folders on the filesystem of your computer. Users can be granted access to specific projects. Within those projects, data are organised in folders.

Project file structure

A typical project structure looks like this.

DsUpload

dsUpload is an R package that aids data managers in the data uploading process. Data uploaded using this package has to fit the dsDictionaries format.

System Operator

System Operators are the people who install the software (Molgenis Armadillo) on the server. Installing is a quick and straightforward process, for full details please view the Install Guide.

Researcher

As a reseracher you will need to arrange access to each Armadillo (or Opal) server that holds the data you want to analyse. This guide shows you how to login, assuming you have been granted access to the server and the data.

Research is conducted using R. To begin with you need install and load the following packages:

install.packages(c("DSI", "DSMolgenisArmadillo", "dsBaseClient"))
library(DSI)
library(DSMolgenisArmadillo)
library(dsBaseClient)
With these libraries, you can now login to Armadillo: 
url <- "https://armadillo-demo.molgenis.net/"
token <- armadillo.get_token(url)
builder <- DSI::newDSLoginBuilder()

builder$append(
  server = "armadillo",
  url = url,
  token = token,
  driver = "ArmadilloDriver",
  profile = "xenon")

logindata <- builder$build()
conns <- DSI::datashield.login(logins = logindata)
To use the data, you first need to 'assign' it. This means to create a temporary copy on the server within your RSsesion. You can use the following code: 
datashield.assign.table(conns, "mtcars", "project/data/cars")
To see the data assigned in your workspace use: 
ds.ls()

If all of this succeeds, your access to Armadillo is setup correctly.

For detailed information on how to use DataSHIELD as a researcher, please visit the DataSHIELD Wiki

For more extensive documentation Armadillo, please visit our documentation for DSMolgenisArmadillo.

Developer

We encourage fellow developers to help us with new features or bugfixes in Armadillo, or help us with our R packages. To run Armadillo locally, first clone the git repository: 

git clone https://github.com/molgenis/molgenis-service-armadillo.git
You first need to configure armadillo in the application.yml. To do that, you first will need to create this file. The easiest way to do that is by copying the application.template.yml and name it application.yml.

If you are using IntelliJ, open the ArmadilloServiceApplication class (press shift twice and type the class name to go there), and press the play button on the main function. You might have to first set the Java version (java 17). Armadillo will initialise up without oAuth configured, so you can login using the username admin and the password specified in application.yml (default: admin).

For more information, see our Developer guides and License.