Using the Client
Interacting with the server API
To interact with the vantage6 server there is a Python and R client in development. Keep in mind that these Clients are could change with every release and that the Python and R client are quite different.
There are basically two reasons to use the Client:
  • You want to manage users
    ๐Ÿ‘ฅ
    , organizations
    ๐Ÿข
    , collaborations
    ๐Ÿค
    , etc.
    ๐Ÿ–ฑ
  • You want to request a computation ๐Ÿงฎ and collect their results
    ๐Ÿงช
The R client is currently only able to create computation requests and retrieve their results. The Python-client is also able to manage users, roles, collaborations, etc.
Besides using a client, it is also possible to use the API from the server directly. The API docs can be found here.
We are also working on a UI to manage users, roles, rules, etc. at the server, see https://github.com/iknl/vantage6-uiโ€‹

โ€‹
๐Ÿ“”
Administration

You can use the vantage6 server API to manage these. To make this process easier the Python vantage6-client can be used. The R client does not have these tools (yet). Keep in mind that you need permission for all operations you perform.
As the root user you can use the iPython shell to manage users, organizations, collaborations, etc. Regular users do not have access to this shell.

โ€‹
๐Ÿ”ญ
Computation Requests and Results

This is the core task of vantage6. Receiving tasks (computation requests) and collecting the results from the data-station. Both the Python and R client are able to help you perform these tasks. To give you a little bit of intuition what happens under the hood we outline the process here:
  1. 1.
    User requests computation, consisting of:
    • The algorithm to use (as a Docker image
      ๐Ÿณ
      name)
    • Any input you want to provide to the algorithm
    • Which collaboration, and organizations to include
  2. 2.
    Nodes receive and execute the request
    • The algorithm will have access to:
      • The (local) node's data
      • The input provided by the user
    • The node returns the results
  3. 3.
    User collect the results from the server
In step (1) and (3) the user needs to do something. This is where our clients helps.

So how, then?

As a researcher you would normally fire up your (least) favorite programming language and do something like this if you'd want to check which columns are in your data:
R
1
# This assumes the package devtools is installed:
2
devtools::install_github('mellesies/vtg.basic', subdir='src')
3
โ€‹
4
# Load the SEER dataset located in the vtg.basic package
5
data('SEER', package='vtg.basic')
6
โ€‹
7
# Print all the column names in the dataset
8
print( colnames(SEER) )
9
โ€‹
10
# Expected output:
11
# [1] "Age" "Race2" "Race3" "Mar2" "Mar3" "Mar4" "Mar5"
12
# [8] "Mar9" "Hist8520" "hist8522" "hist8480" "hist8501" "hist8201" "hist8211"
13
#[15] "grade" "ts" "nne" "npn" "er2" "er4" "Time"
14
#[22] "Censor" #
Copied!
In a federated situation, you won't have direct access to the data. Instead, you'd have to instruct the nodes to run a docker image that returns the list of column names. Since we'd also have to communicate with the infrastructure, we need two things:
  • A Docker image (with software that returns the column names)
  • A client to facilitate communication
Fortunately, a docker image that returns is already available and using it is not too difficult:
R
1
# This assumes the package 'devtools' is installed and will automatically
2
# install the package 'vtg'.
3
devtools::install_github('mellesies/vtg.basic', subdir='src')
4
โ€‹
5
# Function to create a client
6
setup.client <- function() {
7
# Username/password should be provided by the administrator of
8
# the server.
9
username <- "[email protected]"
10
password <- "password"
11
12
host <- 'https://trolltunga.vantage6.ai'
13
api_path <- ''
14
15
# Create the client & authenticate
16
client <- vtg::Client$new(host, api_path=api_path)
17
client$authenticate(username, password)
18
โ€‹
19
return(client)
20
}
21
โ€‹
22
# Create a client
23
client <- setup.client()
24
โ€‹
25
# Get a list of available collaborations
26
print( client$getCollaborations() )
27
โ€‹
28
# Should output something like this:
29
# id name
30
# 1 1 ZEPPELIN
31
# 2 2 PIPELINE
32
โ€‹
33
# Instruct the client to use collaboration "PIPELINE".
34
client$setCollaborationId(2)
35
โ€‹
36
โ€‹
37
# Since vtg.basic exports function names that collide with built-in functions,
38
# it's probably better to not attach the package, but call functions with a prefix instead.
39
vtg.basic::colnames(client)
40
โ€‹
41
# Should output something like this:
42
# [[1]]
43
# [1] "Age" "Race2" "Race3" "Mar2" "Mar3" "Mar4" "Mar5"
44
# [8] "Mar9" "Hist8520" "hist8522" "hist8480" "hist8501" "hist8201" "hist8211"
45
# [15] "grade" "ts" "nne" "npn" "er2" "er4" "Time"
46
# [22] "Censor"
47
#
48
# [[2]]
49
# [1] "Age" "Race2" "Race3" "Mar2" "Mar3" "Mar4" "Mar5"
50
# [8] "Mar9" "Hist8520" "hist8522" "hist8480" "hist8501" "hist8201" "hist8211"
51
# [15] "grade" "ts" "nne" "npn" "er2" "er4" "Time"
52
# [22] "Censor"
Copied!
Last modified 10mo ago