CytobankAPI quickstart guide

The CytobankAPI package is designed to make interacting with Cytobank API endpoints easy via R. This document is an accompanying overview of the package to learn concepts and see basic examples. View the Cytobank API Endpoint Documentation for a comprehensive list of API endpoints for Cytobank.

This guide will cover all components necessary from installation to using the CytobankAPI package:

  1. Installation: walkthrough for installing the package via CRAN
  2. Authentication: generate an authentication token that must accompany every call to the Cytobank API
  3. Requests: functions for operations and data exchange with Cytobank via the API
  4. Timeouts: information about short and long timeout request times

Installation

To install this package via CRAN, start R and enter:

install.packages("CytobankAPI")

Authentication

Authentication should always be the first step when using the CytobankAPI package. When authenticating, save the returned authentication object to a variable. This variable will be passed as an argument to all other functions that use API endpoints.

To authenticate, first load the CytobankAPI package, then call the authenticate function while providing site name and choice of credentials.

# Load in 'CytobankAPI' package
library(CytobankAPI)

There are two ways to authenticate:

  1. username/password: username (or email) and password combination used to normally login to the site
# Authenticate via username/password combination
cyto_session <- authenticate(site="premium", username="cyril_cytometry", password="cytobank_rocks!")

  1. Authenticate with authentication token: authentication tokens can be generated from the user profile page within the Cytobank web interface

    • SAML/SSO users must generate a token on the profile page after logging into Cytobank.
# Authenticate via authentication token
cyto_session <- authenticate(site="premium", auth_token="secret_auth_token")

The authentication object also holds two variables that control default timeout length for API requests. These variables can be set when calling the authenticate function. Read more about timeouts below.

cyto_session
#> An object of class "UserSession"
#> Slot "auth_token":
#> [1] "secret_auth_token"
#> 
#> Slot "long_timeout":
#> [1] 60
#> 
#> Slot "short_timeout":
#> [1] 30
#> 
#> Slot "site":
#> [1] "https://premium.cytobank.org/cytobank/api/v1"

Requests

Interactions with the Cytobank API are mediated via requests through the CytobankAPI package. Individual requests are organized into different endpoint groups according to similar functionality within Cytobank. The general form of any request is endpoint.method. Current endpoint groups are as follows:

  • attachments
  • authenticate
  • CITRUS
  • compensations
  • DROP
  • experiments
  • FCS files
  • FlowSOM
  • gates
  • panels
  • populations
  • sample tags
  • scales
  • SPADE
  • statistics
  • users
  • viSNE
  • dimensionality_reduction

Each endpoint group and each function within the groups has low level documentation viewable while working with the package in R.

Making a request

Requests to Cytobank API endpoints can only be made after authenticating (see above). The authentication object will be passed as the first parameter of any endpoint request.

# Making a request to the 'experiments' endpoint to create a new experiment
new_experiment <- experiments.new(cyto_session, experiment_name="My New Experiment", purpose="CytobankAPI quickstart vignette")

View(new_experiment)
id version purpose comments public deleted sources experimentName …
1 42 CytobankAPI quickstart vignette FALSE FALSE My New Experiment …

The default return option within this package is a formatted response (usually in the form of a dataframe) that represents the endpoint response. Read more about return types and output options below.

# Raw list endpoint response
new_experiment <- experiments.new(cyto_session, experiment_name="My New Experiment", purpose="For the CytobankAPI quickstart vignette", output="raw")

#> $experiment
#> $experiment$id
#> [1] 22
#> 
#> $experiment$purpose
#> [1] "For the CytobankAPI quickstart vignette"
#> 
#> $experiment$comments
#> NULL
#> 
#> $experiment$public
#> [1] FALSE
#> 
#> $experiment$experimentName
#> [1] "My New Experiment"
#> ...

Note that the new experiment was returned as a list object. The various attributes of the experiment object are named items in the list. See section below for discussion on changing output type.

Return types and output options

Functions within this package return output of dataframes, characters (strings), and lists. Each function will support different output options depending on the type of data it returns. Available output options are specified on a per-function basis within the low-level package documentation.

Default output

Generally, the default return type for most functions in this package is a dataframe object. This object is a formatted conversion from the JSON objects returned from the API over HTTP. Attributes of the dataframe can be accessed by name in typical fashion. An example of information returned by default can be seen directly above with the creation of a new experiment without any output option.

Some functions, such as for downloading an FCS file or attachment, will instead return a logical value if a file has been successfully downloaded. The function also prints out the file path of the downloaded file on the screen.

In other cases, there are special return structures that provide better access to data such as complex lists (i.e. returned via panel endpoints) and class objects (i.e. returned via advanced analyses endpoints).

Dataframes

Special dataframes output mode can be chosen for endpoints that return compensations or statistics.

In the case of compensations, the default return object is a list that contains the compensation matrix, with the addition of extra compensation data. With the ‘dataframe’ output option, only the compensation matrix dataframe is returned.

See section below for more discussion on other return types available from functions within this package.

Compensations dataframes

Dataframes representing compensation matrices allow for easier viewing and editing compared to the default list return type. It is also useful for combining CytobankAPI with other 3rd party tools such as FlowCore.

compensations.show and fcs_files.file_internal_comp_show are the two endpoints that can return dataframes of a compensation matrix. Use a value of ‘dataframe’ for the output argument in the function call:

# Dataframe representing compensation matrix 8 for experiment 22
compensation_matrix_dataframe <- compensations.show(cyto_session, experiment_id=22, compensation_id=8, output="dataframe")

# Dataframe representing FCS file 8 internal compensation matrix for experiment 22
fi_compensation_matrix_dataframe <- fcs_files.file_internal_comp_show(cyto_session, fcs_file_id=8, output="dataframe")

View(compensation_matrix_dataframe)
channel1 channel2 channel3 channel4 channel5 channel6
channel1 1.0000 0.2986 0.0165 0.0000 0.0000 0.0000
channel2 0.0070 1.0000 0.0726 0.0055 0.0000 0.0017
channel3 0.0000 0.0000 1.0000 0.1340 0.0495 0.0120
channel4 0.0023 0.0703 0.0150 1.0000 0.0000 0.0034
channel5 0.0000 0.0000 0.0039 0.0000 1.0000 0.0000
channel6 0.0026 0.0020 0.0000 0.0000 0.0000 1.0000

Statistics dataframes

There are different output options for each statistics endpoint:

  • statistics.event_counts: use the ‘dataframe’ output option
    • dataframe: visualize all event count statistics for the data provided
  • statistics.general: use either the ‘dataframe_col’ or ‘dataframe_row’ output option
    • dataframe_col: in cases where there are statistics for multiple channels, accumulate serially by column
    • dataframe_row: in cases where there are statistics for multiple channels, accumulate serially by row
View(statistics_dataframe_proliferate_by_row)
File/Population information Channel 1 statistics Channel 2 statistics Channel 3 statistics
File 1/ Population 1 info F1/P1/Ch1 statistics F1/P1/Ch2 statistics F1/P1/Ch3 statistics
File 1/ Population 2 info F1/P2/Ch1 statistics F1/P2/Ch2 statistics F1/P2/Ch3 statistics
File 2/ Population 1 info F2/P1/Ch1 statistics F2/P1/Ch2 statistics F2/P1/Ch3 statistics
File 2/ Population 2 info F2/P2/Ch1 statistics F2/P2/Ch2 statistics F2/P2/Ch3 statistics

Each row represents a file/population combination’s channel statistics for the channels selected.

View(statistics_dataframe_proliferate_by_col)
File/Population information Channel statistics
File 1/ Population 1 info Ch1 statistics
File 1/ Population 1 info Ch2 statistics
File 1/ Population 1 info Ch3 statistics
File 1/ Population 2 info Ch1 statistics
File 1/ Population 2 info Ch2 statistics
File 1/ Population 2 info Ch3 statistics
File 2/ Population 1 info Ch1 statistics
File 2/ Population 1 info Ch2 statistics
File 2/ Population 1 info Ch3 statistics
File 2/ Population 2 info Ch1 statistics
File 2/ Population 2 info Ch2 statistics
File 2/ Population 2 info Ch3 statistics

A set of rows represent a single file/population combination’s channel statistics.

In the examples above, the information and statistics included within the columns has been abridged. Here is a full description of the columns present in a statistics data frame:

  • File/Population information
expId gateVersion compId fcsFileId fcsFileName gateSetId gateSetName eventCounts
22 1 -2 8 il10.fcs 5 CD20+ B cells 10000
22 1 -2 9 il6.fcs 5 CD20+ B cells 20000
22 1 -2 10 lps.fcs 5 CD20+ B cells 30000

File/Population information names are abbreviated to fit table

  • Channel statistics
chId short long mins maxs means medians variances stdDev 2nd 98th
7 PacBlu-A CD4 -143.70 386.65 97.60 94.59 6484.29 80.52 -60.93 273.15

Channel statistics names are abbreviated to fit table

Raw lists

This object is a direct conversion from the JSON objects returned from the API over HTTP. Attributes of the raw list can be accessed by name in typical fashion. An examples of information returned as a raw list can be seen directly above with the creation of a new experiment, using the “raw” output option.

Timeouts

Each function that makes a call to the Cytobank API is bounded by a timeout. If the wait time of the function call exceeds the timeout value, the call will be abandoned. Custom values for timeout can be passed as an argument to each function call, but in the absence of this argument default values are pulled from the authentication object. Each function uses either the short_timeout or the long_timeout attribute from the authentication object as a default value. Simple requests that are expected to return quickly (such as retrieving a list of FCS files in an experiment) use short_timeout. Requests that could take longer to return (such as statistics) use long_timeout.

* **short timeout**: change the default timeout time for short requests (*default = 30 seconds*)
* **long timeout**: change the default timeout time for long requests (*default = 60 seconds*)