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:
To install this package via CRAN, start R and enter:
install.packages("CytobankAPI")
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:
r {eval=FALSE} # Authenticate via username/password combination cyto_session <- authenticate(site="premium", username="cyril_cytometry", password="cytobank_rocks!")
Authenticate with authentication token: authentication tokens can be generated from the user profile page within the Cytobank web interface
r {eval=FALSE} # 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"
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:
Each endpoint group and each function within the groups has low level documentation viewable while working with the package in R.
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.
```r {eval=FALSE} # 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](cytobank-advanced-analyses.html)).
### 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](http://bioconductor.org/packages/release/bioc/html/flowCore.html).
`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:
```r {eval=FALSE}
# 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 |
There are different output options for each statistics endpoint:
statistics.event_counts
: use the ‘dataframe’ output
option
statistics.general
: use either the ‘dataframe_col’ or
‘dataframe_row’ output option
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:
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
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
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.
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*)