bio-basespace-sdk 0.1.3 → 0.1.5
Sign up to get free protection for your applications and to get access to all the features.
Potentially problematic release.
This version of bio-basespace-sdk might be problematic. Click here for more details.
- checksums.yaml +4 -4
- data/README.md +479 -482
- data/Rakefile +3 -5
- data/VERSION +1 -1
- data/examples/0_app_triggering.rb +51 -62
- data/examples/1_authentication.rb +14 -99
- data/examples/2_browsing.rb +42 -44
- data/examples/3_accessing_files.rb +72 -77
- data/examples/4_app_result_upload.rb +97 -54
- data/examples/5_purchasing.rb +4 -10
- data/lib/basespace/api/api_client.rb +11 -5
- data/lib/basespace/api/base_api.rb +3 -3
- data/lib/basespace/api/basespace_api.rb +9 -9
- data/lib/basespace/model/project.rb +1 -1
- data/lib/basespace/model/sample.rb +6 -5
- metadata +6 -8
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 787f724197d43b2d56adde33a53c98d3427e9652
|
|
4
|
+
data.tar.gz: be721a907c1328d98e2e82b99c85296042c47a8e
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 309eeb554a9920c28cfb31e3bc368e1a7b081ace3f017002ec5e014c879d29b529907aa4569e01cae92b6abc92587a7e5fe2a02268b8930b8e12a871771b953b
|
|
7
|
+
data.tar.gz: 710c3fd200ef48c16028ec8353469c70cf924b6588ba7d8fbae8ef202557428796588a6febd8070ce34a76cd24f8e6ea13d5e563e8a55bb39fb64abf59dbec4b
|
data/README.md
CHANGED
|
@@ -1,644 +1,628 @@
|
|
|
1
1
|
# BaseSpace Ruby SDK
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
BaseSpace Ruby SDK is a Ruby based Software Development Kit to be used in the development of Apps and scripts for working with Illumina's BaseSpace cloud-computing solution for next-gen sequencing data analysis.
|
|
4
4
|
|
|
5
5
|
The primary purpose of the SDK is to provide an easy-to-use Ruby environment enabling developers to authenticate a user, retrieve data, and upload data/results from their own analysis to BaseSpace.
|
|
6
6
|
|
|
7
|
-
*Note:*
|
|
7
|
+
*Note:* For running several of the example below a (free) BaseSpace account is required and you need to have the "Client Id" code (parameter `client_key` below) and "Client Secret" code (parameter `client_secret` below) for one of your Apps available.
|
|
8
|
+
|
|
9
|
+
**Table of Contents**
|
|
10
|
+
|
|
11
|
+
* [BaseSpace Ruby SDK](#basespace-ruby-sdk)
|
|
12
|
+
* [Availability and Installation](#availability-and-installation)
|
|
13
|
+
* [Getting Started](#getting-started)
|
|
14
|
+
* [Application Triggering](#application-triggering)
|
|
15
|
+
* [BaseSpace Authentication](#basespace-authentication)
|
|
16
|
+
* [Browsing Data](#browsing-data)
|
|
17
|
+
* [Accessing and Querying Files](#accessing-and-querying-files)
|
|
18
|
+
* [Creating an AppResult and Uploading Files](#creating-an-appresult-and-uploading-files)
|
|
19
|
+
* [Cookbook of Usage Recipes](#cookbook-of-usage-recipes)
|
|
20
|
+
* [Feature Requests and Bug Reporting](#feature-requests-and-bug-reporting)
|
|
21
|
+
* [SDK Development Manual](#sdk-development-manual)
|
|
22
|
+
* [Building a New Version of the Gem](#building-a-new-version-of-the-gem)
|
|
23
|
+
* [Unit Testing](#unit-testing)
|
|
24
|
+
* [Porting](#porting)
|
|
25
|
+
* [Authors and Contributors](#authors-and-contributors)
|
|
26
|
+
* [Authors](#authors)
|
|
27
|
+
* [Contributors](#contributors)
|
|
28
|
+
* [Copying and License](#copying-and-license)
|
|
29
|
+
|
|
30
|
+
## Availability and Installation
|
|
8
31
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
*Note:* We are still testing our code. Please take the production-ready gem with a pinch of salt.
|
|
32
|
+
*Requirements:* Ruby 1.9.3 and above. The multi-part file upload will currently only run on a Unix setup.
|
|
12
33
|
|
|
13
|
-
The production environment version of
|
|
34
|
+
The production environment version of BaseSpace Ruby SDK is available as a Ruby gem:
|
|
14
35
|
|
|
15
|
-
|
|
36
|
+
gem install bio-basespace-sdk
|
|
16
37
|
|
|
17
38
|
Depending on your Ruby installation, it might be necessary to install the Ruby gem with superuser permissions:
|
|
18
39
|
|
|
19
|
-
|
|
40
|
+
sudo gem install bio-basespace-sdk
|
|
41
|
+
|
|
42
|
+
To test that everything is working as expected, launch a Interactive Ruby and try importing 'Bio::BaseSpace':
|
|
43
|
+
|
|
44
|
+
$ irb
|
|
45
|
+
>> require 'bio-basespace-sdk'
|
|
46
|
+
>> include Bio::BaseSpace
|
|
20
47
|
|
|
21
|
-
### Pre-Release Version
|
|
48
|
+
### Pre-Release Version [](https://travis-ci.org/joejimbo/basespace-ruby-sdk)
|
|
22
49
|
|
|
23
|
-
The pre-release version of
|
|
50
|
+
The pre-release version of BaseSpace Ruby SDK can be checked out here:
|
|
24
51
|
|
|
25
|
-
|
|
52
|
+
git clone https://github.com/joejimbo/basespace-ruby-sdk.git
|
|
26
53
|
|
|
27
54
|
or by,
|
|
28
55
|
|
|
29
|
-
|
|
56
|
+
git clone git@github.com:joejimbo/basespace-ruby-sdk.git
|
|
30
57
|
|
|
31
|
-
|
|
58
|
+
For a description on how to build the pre-release version see "[SDK Development Manual](#sdk-development-manual)".
|
|
32
59
|
|
|
33
|
-
|
|
60
|
+
Please fork the GitHub repository and send us a pull request if you would like to improve the SDK.
|
|
34
61
|
|
|
35
|
-
|
|
62
|
+
## Getting Started
|
|
36
63
|
|
|
37
|
-
|
|
64
|
+
The core class for interacting with BaseSpace is `Bio::BaseSpace::BaseSpaceAPI`. An instance of the class is created by passing authentication and connection details either via arguments to a `new` call or via the file `credentials.json`.
|
|
38
65
|
|
|
39
|
-
|
|
66
|
+
*Note:* Depending on the actions that you want to carry out, you will either need to provide an App session ID (`app_session_id`) or an access token (`access_token`), or both. You can set one of these parameters to `nil`, if it is not required for your interactions with BaseSpace.
|
|
40
67
|
|
|
41
|
-
|
|
68
|
+
Creating a `BaseSpaceAPI` object using `new`:
|
|
42
69
|
|
|
43
|
-
|
|
70
|
+
require 'bio-basespace-sdk'
|
|
71
|
+
|
|
72
|
+
include Bio::BaseSpace
|
|
73
|
+
|
|
74
|
+
# Authentication and connection details:
|
|
75
|
+
client_id = 'my client key'
|
|
76
|
+
client_secret = 'my client secret'
|
|
77
|
+
app_session_id = 'my app session id'
|
|
78
|
+
access_token = 'my access token'
|
|
79
|
+
basespace_url = 'https://api.basespace.illumina.com/'
|
|
80
|
+
api_version = 'v1pre3'
|
|
81
|
+
|
|
82
|
+
# Initialize a BaseSpace API object:
|
|
83
|
+
bs_api = BaseSpaceAPI.new(client_id, client_secret, basespace_url, api_version, app_session_id, access_token)
|
|
44
84
|
|
|
45
|
-
|
|
85
|
+
Creating a `BaseSpaceAPI` object using `credentials.json`:
|
|
46
86
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
87
|
+
require 'bio-basespace-sdk'
|
|
88
|
+
|
|
89
|
+
include Bio::BaseSpace
|
|
90
|
+
|
|
91
|
+
# Initialize a BaseSpace API object with authentication/connection details in 'credentials.json':
|
|
92
|
+
bs_api = BaseSpaceAPI.start
|
|
50
93
|
|
|
51
|
-
|
|
94
|
+
The file `credentials.json` contains the authentication/connection details in [JSON](http://json.org) format:
|
|
52
95
|
|
|
53
|
-
|
|
54
|
-
|
|
96
|
+
{
|
|
97
|
+
"client_id": "my client id",
|
|
98
|
+
"client_secret": "my client secret",
|
|
99
|
+
"app_session_id": "my app session id",
|
|
100
|
+
"access_token": "my access token",
|
|
101
|
+
"basespace_url": "https://api.basespace.illumina.com",
|
|
102
|
+
"api_version": "v1pre3"
|
|
103
|
+
}
|
|
55
104
|
|
|
56
|
-
|
|
57
|
-
we are able to obtain information about the user who launched the App and the data that is sought analyzed by the App.
|
|
58
|
-
First, we instantiate a BaseSpaceAPI object using the ``client_key`` and ``client_secret`` codes provided on the BaseSpace developer's website when registering our App, as well as the ``AppSessionId`` generated from the app-triggering:
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
require 'bio-basespace-sdk'
|
|
62
|
-
|
|
63
|
-
include Bio::BaseSpace
|
|
64
|
-
|
|
65
|
-
# initialize an authentication object using the key and secret from your app
|
|
66
|
-
# Fill in with your own values
|
|
67
|
-
|
|
68
|
-
client_id = 'my client key'
|
|
69
|
-
client_secret = 'my client secret'
|
|
70
|
-
app_session_id = 'my app session id'
|
|
71
|
-
basespace_url = 'https://api.basespace.illumina.com/'
|
|
72
|
-
api_version = 'v1pre3'
|
|
73
|
-
|
|
74
|
-
# First we will initialize a BaseSpace API object using our app information and the appSessionId
|
|
75
|
-
bs_api = BaseSpaceAPI.new(client_id, client_secret, basespace_url, api_version, app_session_id)
|
|
76
|
-
|
|
77
|
-
# Using the bmy_app_session.spaceApi we can request the appSession object corresponding to the AppSession id supplied
|
|
78
|
-
my_app_session = bs_api.get_app_session
|
|
79
|
-
puts my_app_session
|
|
80
|
-
|
|
81
|
-
# An app session contains a referal to one or more appLaunchObjects which reference the data module
|
|
82
|
-
# the user launched the app on. This can be a list of projects, samples, or a mixture of objects
|
|
83
|
-
puts "Type of data the app was triggered on can be seen in 'references'"
|
|
84
|
-
puts my_app_session.references.inspect # .inspect is used to put surrounding []
|
|
85
|
-
puts
|
|
105
|
+
## Application Triggering
|
|
86
106
|
|
|
87
|
-
|
|
107
|
+
**Example Source Code:** [examples/0\_app\_triggering.rb](https://github.com/joejimbo/basespace-ruby-sdk/blob/master/examples/0_app_triggering.rb)
|
|
88
108
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
[Project]
|
|
109
|
+
This section demonstrates how to retrieve the `AppSession` object produced when a user triggers a BaseSpace App.
|
|
110
|
+
Further, we cover how to automatically generate the scope strings to request access to the data object (be it a project or a sample) that the App was triggered to analyze.
|
|
92
111
|
|
|
93
|
-
|
|
112
|
+
The initial HTTP request to our App from BaseSpace is identified by an `AppSession` instance. Using this instance, we are able to obtain information about the user who launched the App and the data that is sought/analyzed by the App.
|
|
113
|
+
|
|
114
|
+
*Note:* Create a `BaseSpaceAPI` object as described under "[Getting Started](#getting-started)" first. The instance should be referenced by the variable `bs_api`, just as in the examples of the "[Getting Started](#getting-started)" section.
|
|
115
|
+
|
|
116
|
+
# Using bs_api, we can request the AppSession object corresponding to the AppSession ID supplied
|
|
117
|
+
my_app_session = bs_api.get_app_session
|
|
118
|
+
puts my_app_session
|
|
119
|
+
|
|
120
|
+
# An app session contains a referral to one or more AppSessionLaunchObject instances, which reference the
|
|
121
|
+
# data module the user launched the App on. This can be a list of projects, samples, or a mixture of objects
|
|
122
|
+
puts "Type of data the app was triggered on can be seen in 'references':"
|
|
123
|
+
puts my_app_session.references.inspect # `inspect` shows the object contents
|
|
124
|
+
|
|
125
|
+
The output will be similar to:
|
|
126
|
+
|
|
127
|
+
App session by 600602: Eri Kibukawa - Id: <my app session id> - status: Complete
|
|
128
|
+
Type of data the app was triggered on can be seen in 'references':
|
|
129
|
+
[#<Bio::BaseSpace::AppSessionLaunchObject:0x007fc21a1ae0f8 @swagger_types={"Content"=>"dict", "Href"=>"str", "HrefContent"=>"str", "Rel"=>"str", "Type"=>"str"}, @attributes={"Content"=>#<Bio::BaseSpace::Project:0x007fc21a1ae378 @swagger_types={"Name"=>"str", "HrefSamples"=>"str", "HrefAppResults"=>"str", "HrefBaseSpaceUI"=>"str", "DateCreated"=>"datetime", "Id"=>"str", "Href"=>"str", "UserOwnedBy"=>"UserCompact"}, @attributes={"Name"=>"IGN_WGS_CEPH_Services_2.0", "HrefSamples"=>nil, "HrefAppResults"=>nil, "HrefBaseSpaceUI"=>nil, "DateCreated"=>#<DateTime: 2013-04-19T18:21:50+00:00 ((2456402j,66110s,0n),+0s,2299161j)>, "Id"=>"267267", "Href"=>"v1pre3/projects/267267", "UserOwnedBy"=>#<Bio::BaseSpace::UserCompact:0x007fc21a1ac758 @swagger_types={"Name"=>"str", "Id"=>"str", "Href"=>"str"}, @attributes={"Name"=>"Illumina Inc", "Id"=>"3004", "Href"=>"v1pre3/users/3004"}>}>, "Href"=>"v1pre3/projects/267267", "HrefContent"=>"v1pre3/projects/267267", "Rel"=>"Input", "Type"=>"Project"}>]
|
|
130
|
+
|
|
131
|
+
We can get a handle to the user who started the `AppSession` and further information on the `AppSessionLaunchObject`:
|
|
132
|
+
|
|
133
|
+
puts "App session created by user:"
|
|
134
|
+
puts my_app_session.user_created_by
|
|
135
|
+
puts
|
|
136
|
+
|
|
137
|
+
# Let's have a closer look at the AppSessionLaunchObject class instance:
|
|
138
|
+
my_reference = my_app_session.references.first
|
|
139
|
+
|
|
140
|
+
puts "href to the launch object:"
|
|
141
|
+
puts my_reference.href_content
|
|
142
|
+
puts
|
|
143
|
+
puts "Type of that object:"
|
|
144
|
+
puts my_reference.type
|
|
145
|
+
puts
|
|
146
|
+
|
|
147
|
+
The output will be similar to:
|
|
148
|
+
|
|
149
|
+
App session created by user:
|
|
150
|
+
13039: Eri Kibukawa
|
|
151
|
+
|
|
152
|
+
href to the launch object:
|
|
153
|
+
v1pre3/projects/848850
|
|
154
|
+
|
|
155
|
+
Type of that object:
|
|
156
|
+
Project
|
|
94
157
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
puts my_app_session.user_created_by
|
|
98
|
-
puts
|
|
99
|
-
|
|
100
|
-
# Let's have a closer look at the appSessionLaunchObject
|
|
101
|
-
my_reference = my_app_session.references.first
|
|
102
|
-
|
|
103
|
-
puts "We can get out information such as the href to the launch object:"
|
|
104
|
-
puts my_reference.href_content
|
|
105
|
-
puts
|
|
106
|
-
puts "and the specific type of that object:"
|
|
107
|
-
puts my_reference.type
|
|
108
|
-
puts
|
|
158
|
+
To start working, we will want to expand our permission scope for the trigger object so we can read and write data. The details of this process is the subject of the next section.
|
|
159
|
+
This section shows how one can easily obtain the so-called "scope string" and make the access request. More background reading on scope strings can be found in the BaseSpace developer documentation under "[BaseSpace Permissions](https://developer.basespace.illumina.com/docs/content/documentation/authentication/using-scope)".
|
|
109
160
|
|
|
161
|
+
puts "Project object:"
|
|
162
|
+
my_reference_content = my_reference.content
|
|
163
|
+
puts my_reference_content
|
|
164
|
+
puts
|
|
165
|
+
puts "Scope string for requesting write access to the reference object:"
|
|
166
|
+
puts my_reference_content.get_access_str('write')
|
|
110
167
|
|
|
111
|
-
The output will be:
|
|
168
|
+
The output will be similar to:
|
|
112
169
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
and the specific type of that object:
|
|
120
|
-
Project
|
|
170
|
+
Project object:
|
|
171
|
+
MyProject - id=848850
|
|
172
|
+
|
|
173
|
+
Scope string for requesting write access to the reference object:
|
|
174
|
+
write project 848850
|
|
121
175
|
|
|
176
|
+
We can request write access to the reference object now, so that our App can start contributing to an analysis. There is a distinction between requesting access for Web-Apps and other Apps (Desktop, Mobile, Native) though.
|
|
122
177
|
|
|
123
|
-
|
|
124
|
-
We end this section by demonstrating how one can easily obtain the so-called "scope string" and make the access request:
|
|
178
|
+
The following call requests write permissions for a Web App:
|
|
125
179
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
puts "\nThe scope string for requesting write access to the reference object is:"
|
|
130
|
-
puts my_reference_content.get_access_str('write')
|
|
180
|
+
verification_with_code_uri = bs_api.get_access(my_reference_content, 'write')
|
|
181
|
+
puts "Visit the URI within 15 seconds and grant access:"
|
|
182
|
+
puts verification_with_code_uri
|
|
131
183
|
|
|
132
|
-
The output will be:
|
|
133
|
-
We can get out the specific project objects by using 'content':
|
|
134
|
-
MyProject - id=848850
|
|
184
|
+
The output will be similar to:
|
|
135
185
|
|
|
136
|
-
|
|
137
|
-
|
|
186
|
+
Visit the URI within 15 seconds and grant access:
|
|
187
|
+
https://cloud-hoth.illumina.com//oauth/authorize?<authorization paramers>
|
|
138
188
|
|
|
139
|
-
|
|
140
|
-
by default we ask for write permission to and authentication for a device:
|
|
189
|
+
The following call requests write permissions for other Apps (Desktop, Mobile, Native):
|
|
141
190
|
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
191
|
+
access_map = bs_api.get_access(my_reference_content, 'write')
|
|
192
|
+
puts "Access map:"
|
|
193
|
+
puts access_map
|
|
145
194
|
|
|
146
|
-
The output will be:
|
|
195
|
+
The output will be similar to:
|
|
147
196
|
|
|
148
|
-
|
|
149
|
-
|
|
197
|
+
Access map:
|
|
198
|
+
{"device_code"=>"<my device code>", "user_code"=>"<my user code>", "verification_uri"=>"https://basespace.illumina.com/oauth/device", "verification_with_code_uri"=>"https://basespace.illumina.com/oauth/device?code=<my user code>", "expires_in"=>1800, "interval"=>1}
|
|
150
199
|
|
|
151
|
-
|
|
200
|
+
Visit the verification URI and grant access within 15 seconds:
|
|
152
201
|
|
|
153
|
-
|
|
154
|
-
|
|
202
|
+
puts "Visit the URI within 15 seconds and grant access:"
|
|
203
|
+
verification_with_code_uri = access_map['verification_with_code_uri']
|
|
204
|
+
puts verification_with_code_uri
|
|
155
205
|
|
|
156
206
|
The output will be:
|
|
157
207
|
|
|
158
|
-
|
|
159
|
-
|
|
208
|
+
Visit the URI within 15 seconds and grant access:
|
|
209
|
+
https://basespace.illumina.com/oauth/device?code=<my user code>
|
|
160
210
|
|
|
161
|
-
|
|
211
|
+
In both cases, the URI can be opened in a web browser using this portable Ruby code:
|
|
162
212
|
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
213
|
+
link = access_map['verification_with_code_uri']
|
|
214
|
+
host = RbConfig::CONFIG['host_os']
|
|
215
|
+
case host
|
|
216
|
+
when /mswin|mingw|cygwin/
|
|
217
|
+
system("start #{verification_with_code_uri}")
|
|
218
|
+
when /darwin/
|
|
219
|
+
system("open #{verification_with_code_uri}")
|
|
220
|
+
when /linux/
|
|
221
|
+
system("xdg-open #{verification_with_code_uri}")
|
|
222
|
+
end
|
|
223
|
+
sleep(15)
|
|
174
224
|
|
|
175
|
-
Once the user has granted us access to objects we requested we can get the BaseSpace access-token and start browsing simply by calling
|
|
225
|
+
Once the user has granted us access to objects we requested we can get the BaseSpace access-token and start browsing simply by calling `update_privileges` on the `BaseSpaceAPI` instance:
|
|
176
226
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
puts "The BaseSpaceAPI instance was update with write privileges"
|
|
227
|
+
code = access_map['device_code']
|
|
228
|
+
bs_api.update_privileges(code)
|
|
180
229
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
The BaseSpaceAPI instance was update with write privileges
|
|
230
|
+
For more details on access-requests and authentication and an example of the web-based case see example 1\_authentication.rb
|
|
184
231
|
|
|
185
|
-
|
|
232
|
+
## BaseSpace Authentication
|
|
186
233
|
|
|
187
|
-
|
|
234
|
+
**Example Source Code:** [examples/1\_authentication.rb](https://github.com/joejimbo/basespace-ruby-sdk/blob/master/examples/1_authentication.rb) and [examples/2\_browsing.rb](https://github.com/joejimbo/basespace-ruby-sdk/blob/master/examples/2_browsing.rb)
|
|
188
235
|
|
|
189
|
-
Here we demonstrate the basic BaseSpace authentication process. The
|
|
236
|
+
Here we demonstrate the basic BaseSpace authentication process. The workflow outlined here is
|
|
190
237
|
|
|
191
238
|
1. Request of access to a specific data-scope
|
|
192
239
|
2. User approval of access request
|
|
193
240
|
3. Browsing data
|
|
194
241
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
Again, we will start out by initializing a ``BaseSpaceAPI`` object:
|
|
198
|
-
|
|
199
|
-
require 'bio-basespace-sdk'
|
|
200
|
-
include Bio::BaseSpace
|
|
201
|
-
|
|
202
|
-
client_id = 'my client key'
|
|
203
|
-
client_secret = 'my client secret'
|
|
204
|
-
app_session_id = 'my app session id'
|
|
205
|
-
basespace_url = 'https://api.basespace.illumina.com/'
|
|
206
|
-
api_version = 'v1pre3'
|
|
207
|
-
|
|
208
|
-
# First we will initialize a BaseSpace API object using our app information and the appSessionId
|
|
209
|
-
bs_api = BaseSpaceAPI.new(client_id, client_secret, basespace_url, api_version, app_session_id)
|
|
210
|
-
|
|
211
|
-
First, get the verification code and uri for scope 'browse global'
|
|
212
|
-
|
|
213
|
-
device_info = bs_api.get_verification_code('browse global')
|
|
214
|
-
puts
|
|
215
|
-
puts "URL for user to visit and grant access: "
|
|
216
|
-
puts device_info['verification_with_code_uri']
|
|
217
|
-
|
|
218
|
-
At this point the user must visit the verification uri to grant us access
|
|
219
|
-
|
|
220
|
-
## PAUSE HERE
|
|
221
|
-
# Have the user visit the verification uri to grant us access
|
|
222
|
-
puts "\nPlease visit the uri within 15 seconds and grant access"
|
|
223
|
-
puts device_info['verification_with_code_uri']
|
|
224
|
-
|
|
225
|
-
link = device_info['verification_with_code_uri']
|
|
226
|
-
host = RbConfig::CONFIG['host_os']
|
|
227
|
-
case host
|
|
228
|
-
when /mswin|mingw|cygwin/
|
|
229
|
-
system("start #{link}")
|
|
230
|
-
when /darwin/
|
|
231
|
-
system("open #{link}")
|
|
232
|
-
when /linux/
|
|
233
|
-
system("xdg-open #{link}")
|
|
234
|
-
end
|
|
235
|
-
sleep(15)
|
|
236
|
-
## PAUSE HERE
|
|
237
|
-
|
|
238
|
-
The output will be:
|
|
242
|
+
It will be useful if you are logged in to the BaseSpace web-site before launching this example to make the access granting procedure faster.
|
|
239
243
|
|
|
240
|
-
|
|
241
|
-
https://basespace.illumina.com/oauth/device?code=<my code>
|
|
244
|
+
*Note:* Create a `BaseSpaceAPI` object as described under "[Getting Started](#getting-started)" first. The instance should be referenced by the variable `bs_api`, just as in the examples of the "[Getting Started](#getting-started)" section.
|
|
242
245
|
|
|
243
|
-
|
|
244
|
-
https://basespace.illumina.com/oauth/device?code=<my code>
|
|
246
|
+
### Requesting Access Privileges
|
|
245
247
|
|
|
246
|
-
|
|
248
|
+
First, get the verification code and URI for scope 'browse global':
|
|
247
249
|
|
|
248
|
-
|
|
249
|
-
|
|
250
|
+
device_info = bs_api.get_verification_code('browse global')
|
|
251
|
+
puts
|
|
252
|
+
puts "URI for user to visit and grant access:"
|
|
253
|
+
puts device_info['verification_with_code_uri']
|
|
250
254
|
|
|
251
|
-
|
|
255
|
+
At this point the user must visit the verification URI to grant the requested privilege. From Ruby, it is possible to launch a browser pointing to the verification URI using:
|
|
252
256
|
|
|
253
|
-
|
|
254
|
-
|
|
257
|
+
link = device_info['verification_with_code_uri']
|
|
258
|
+
host = RbConfig::CONFIG['host_os']
|
|
259
|
+
case host
|
|
260
|
+
when /mswin|mingw|cygwin/
|
|
261
|
+
system("start #{link}")
|
|
262
|
+
when /darwin/
|
|
263
|
+
system("open #{link}")
|
|
264
|
+
when /linux/
|
|
265
|
+
system("xdg-open #{link}")
|
|
266
|
+
end
|
|
267
|
+
sleep(15)
|
|
255
268
|
|
|
256
269
|
The output will be:
|
|
257
270
|
|
|
258
|
-
|
|
259
|
-
|
|
271
|
+
URI for user to visit and grant access:
|
|
272
|
+
https://basespace.illumina.com/oauth/device?code=<my code>
|
|
273
|
+
|
|
274
|
+
Once access has been granted, we can get the BaseSpace `access_token` and start browsing simply by calling `update_privileges` on the baseSpaceApi instance.
|
|
275
|
+
|
|
276
|
+
code = device_info['device_code']
|
|
277
|
+
bs_api.update_privileges(code)
|
|
260
278
|
|
|
261
|
-
|
|
279
|
+
As a reference the provided access-token can be obtained from the `BaseSpaceAPI` object:
|
|
262
280
|
|
|
263
|
-
|
|
264
|
-
all_genomes = bs_api.get_available_genomes
|
|
265
|
-
puts "Genomes: #{all_genomes}"
|
|
281
|
+
puts "Access-token: #{bs_api.get_access_token}"
|
|
266
282
|
|
|
267
283
|
The output will be:
|
|
268
284
|
|
|
269
|
-
|
|
270
|
-
[Arabidopsis thaliana, Bos Taurus, Escherichia coli, Homo sapiens, Mus musculus, Phix,\
|
|
271
|
-
Rhodobacter sphaeroides, Rattus norvegicus, Saccharomyces cerevisiae, Staphylococcus aureus]
|
|
272
|
-
|
|
273
|
-
## Browsing data with global browse access
|
|
274
|
-
|
|
275
|
-
This section demonstrates basic browsing of BaseSpace objects once an access-token for global browsing has been obtained. We will see how
|
|
276
|
-
objects can be retrieved using either the ``BaseSpaceAPI`` class or by use of method calls on related object instances (for example once
|
|
277
|
-
a ``user`` instance we can use it to retrieve all project belonging to that user).
|
|
278
|
-
|
|
279
|
-
First we will initialize a ``BaseSpaceAPI`` using our access-token for ``global browse``:
|
|
280
|
-
|
|
281
|
-
require 'bio-basespace-sdk'
|
|
282
|
-
include Bio::BaseSpace
|
|
283
|
-
|
|
284
|
-
# REST server information and user access_token
|
|
285
|
-
|
|
286
|
-
client_id = 'my client key'
|
|
287
|
-
client_secret = 'my client secret'
|
|
288
|
-
access_token = 'your access token'
|
|
289
|
-
app_session_id = 'my app session id'
|
|
290
|
-
basespace_url = 'https://api.basespace.illumina.com/'
|
|
291
|
-
api_version = 'v1pre3'
|
|
292
|
-
|
|
293
|
-
# First, create a client for making calls for this user session
|
|
294
|
-
my_api = BaseSpaceAPI.new(client_id, client_secret, basespace_url, api_version, app_session_id, access_token)
|
|
295
|
-
|
|
296
|
-
First we will try to retrieve a genome object:
|
|
297
|
-
|
|
298
|
-
# Now grab the genome with id=4
|
|
299
|
-
my_genome = my_api.get_genome_by_id('4')
|
|
300
|
-
puts "The Genome is #{my_genome}"
|
|
301
|
-
puts "We can get more information from the genome object"
|
|
302
|
-
puts "Id: #{my_genome.id}"
|
|
303
|
-
puts "Href: #{my_genome.href}"
|
|
304
|
-
puts "DisplayName: #{my_genome.display_name}"
|
|
285
|
+
Access-token: <my access-token>
|
|
305
286
|
|
|
306
|
-
|
|
287
|
+
## Browsing Data
|
|
307
288
|
|
|
308
|
-
|
|
309
|
-
We can get more information from the genome object
|
|
310
|
-
Id: 4
|
|
311
|
-
Href: v1pre3/genomes/4
|
|
312
|
-
DisplayName: Homo Sapiens - UCSC (hg19)
|
|
289
|
+
This section demonstrates basic browsing of BaseSpace objects once an access-token for global browsing has been obtained. We will see how objects can be retrieved using either the `BaseSpaceAPI` class or by use of method calls on related object instances (for example, `User` instances can be used to retrieve all projects belonging to that user).
|
|
313
290
|
|
|
314
|
-
|
|
291
|
+
*Note:* Create a `BaseSpaceAPI` object as described under "[Getting Started](#getting-started)" first. The instance should be referenced by the variable `bs_api`, just as in the examples of the "[Getting Started](#getting-started)" section.
|
|
315
292
|
|
|
316
|
-
|
|
317
|
-
all_genomes = my_api.get_available_genomes
|
|
318
|
-
puts "Genomes: #{all_genomes}"
|
|
293
|
+
First, we will try to retrieve a genome object:
|
|
319
294
|
|
|
320
|
-
|
|
295
|
+
my_genome = bs_api.get_genome_by_id('4')
|
|
296
|
+
puts "Genome: #{my_genome}"
|
|
297
|
+
puts "Id: #{my_genome.id}"
|
|
298
|
+
puts "Href: #{my_genome.href}"
|
|
299
|
+
puts "DisplayName: #{my_genome.display_name}"
|
|
321
300
|
|
|
322
|
-
Genomes
|
|
323
|
-
[Arabidopsis thaliana, Bos Taurus, Escherichia coli, Homo sapiens, Mus musculus, Phix,\
|
|
324
|
-
Rhodobacter sphaeroides, Rattus norvegicus, Saccharomyces cerevisiae, Staphylococcus aureus]
|
|
325
|
-
|
|
326
|
-
Now, let us retrieve the ``User`` objects for the current user, and list all projects for this user:
|
|
327
|
-
|
|
328
|
-
# Take a look at the current user
|
|
329
|
-
user = my_api.get_user_by_id('current')
|
|
330
|
-
puts "The current user is #{user}"
|
|
331
|
-
puts
|
|
332
|
-
|
|
333
|
-
# Now list the projects for this user
|
|
334
|
-
my_projects = my_api.get_project_by_user('current')
|
|
335
|
-
puts "The projects for this user are #{my_projects}"
|
|
336
|
-
puts
|
|
337
|
-
|
|
338
301
|
The output will be:
|
|
339
302
|
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
The projects for this user are
|
|
346
|
-
[BaseSpaceDemo - id=2, Cancer Sequencing Demo - id=4, HiSeq 2500 - id=7, ResequencingPhixRun - id=12, TSChIP-Seq - id=14042, BCereusDemoData_Illumina - id=34061]
|
|
303
|
+
Genome: Homo sapiens
|
|
304
|
+
Id: 4
|
|
305
|
+
Href: v1pre3/genomes/4
|
|
306
|
+
DisplayName: Homo Sapiens - UCSC (hg19)
|
|
347
307
|
|
|
348
|
-
We can
|
|
349
|
-
priviliges to complete the transaction as parameter, this true for all retrieval method calls made on data objects:
|
|
308
|
+
We can get a list of all available genomes:
|
|
350
309
|
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
puts my_projects2
|
|
354
|
-
|
|
355
|
-
# List the runs available for the current user
|
|
356
|
-
runs = user.get_runs(my_api)
|
|
357
|
-
puts "The runs for this user are"
|
|
358
|
-
puts runs
|
|
310
|
+
all_genomes = bs_api.get_available_genomes
|
|
311
|
+
puts "Genomes: #{all_genomes.map { |g| g.to_s }.join(', ')}"
|
|
359
312
|
|
|
360
313
|
The output will be:
|
|
361
314
|
|
|
362
|
-
|
|
363
|
-
[BaseSpaceDemo - id=2, Cancer Sequencing Demo - id=4, HiSeq 2500 - id=7, ResequencingPhixRun - id=12, TSChIP-Seq - id=14042, BCereusDemoData_Illumina - id=34061]
|
|
364
|
-
|
|
365
|
-
The runs for this user are
|
|
366
|
-
[BacillusCereus, Genome-in-a-Day, TSCA_test, 2x151PhiX, TruSeq Amplicon_Cancer Panel, CancerDemo]
|
|
367
|
-
|
|
368
|
-
In the same manner we can get a list of accessible user runs:
|
|
315
|
+
Genomes: Arabidopsis thaliana, Bos Taurus, Escherichia coli, Homo sapiens, Mus musculus, Phix, Rhodobacter sphaeroides, Rattus norvegicus, Saccharomyces cerevisiae, Staphylococcus aureus
|
|
369
316
|
|
|
370
|
-
|
|
371
|
-
puts "Runs retrieved from user instance"
|
|
372
|
-
puts runs
|
|
317
|
+
Now, retrieve the `User` object for the current user and list all projects for this user:
|
|
373
318
|
|
|
374
|
-
|
|
319
|
+
user = bs_api.get_user_by_id('current')
|
|
320
|
+
puts "User -- #{user}"
|
|
321
|
+
|
|
322
|
+
my_projects = bs_api.get_project_by_user('current')
|
|
323
|
+
puts "Projects: #{my_projects.map { |p| p.to_s }.join(', ')}"
|
|
375
324
|
|
|
376
|
-
|
|
377
|
-
[BacillusCereus, Genome-in-a-Day, TSCA_test, 2x151PhiX, TruSeq Amplicon_Cancer Panel, CancerDemo]
|
|
325
|
+
The output will be similar to:
|
|
378
326
|
|
|
379
|
-
|
|
327
|
+
User -- <user id>: <user name>
|
|
328
|
+
Projects: IGN_WGS_CEPH_Services_2.0 - id=267267
|
|
380
329
|
|
|
381
|
-
|
|
382
|
-
In addition, we take a look at some of the special queuring methods associated with BAM- and VCF-files.
|
|
330
|
+
We can also achieve this by making a call to the `User` instance:
|
|
383
331
|
|
|
384
|
-
|
|
332
|
+
my_projects = user.get_projects(bs_api)
|
|
333
|
+
puts "Projects: #{my_projects.map { |p| p.to_s }.join(', ')}"
|
|
385
334
|
|
|
386
|
-
|
|
387
|
-
require 'bio-basespace-sdk'
|
|
388
|
-
include Bio::BaseSpace
|
|
335
|
+
The output will be as above:
|
|
389
336
|
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
access_token = 'your access token'
|
|
393
|
-
app_session_id = 'my app session id'
|
|
394
|
-
basespace_url = 'https://api.basespace.illumina.com/'
|
|
395
|
-
api_version = 'v1pre3'
|
|
337
|
+
User -- <user id>: <user name>
|
|
338
|
+
Projects: IGN_WGS_CEPH_Services_2.0 - id=267267
|
|
396
339
|
|
|
397
|
-
|
|
398
|
-
user = my_api.get_user_by_id('current')
|
|
399
|
-
my_projects = my_api.get_project_by_user('current')
|
|
340
|
+
We can also list all runs for a user:
|
|
400
341
|
|
|
401
|
-
|
|
402
|
-
|
|
342
|
+
runs = user.get_runs(bs_api)
|
|
343
|
+
puts "Runs: #{runs.map { |r| r.to_s }.join(', ')}"
|
|
403
344
|
|
|
404
|
-
|
|
345
|
+
The output will be similar to:
|
|
405
346
|
|
|
406
|
-
|
|
347
|
+
Runs: BaseSpaceDemo - id=2, Cancer Sequencing Demo - id=4, HiSeq 2500 - id=7, ResequencingPhixRun - id=12, TSChIP-Seq - id=14042, BCereusDemoData_Illumina - id=34061
|
|
348
|
+
|
|
349
|
+
## Accessing and Querying Files
|
|
407
350
|
|
|
408
|
-
|
|
409
|
-
puts "# Project: #{single_project}"
|
|
410
|
-
|
|
411
|
-
app_results = single_project.get_app_results(my_api)
|
|
412
|
-
puts " The App results for project #{single_project} are"
|
|
413
|
-
puts " #{app_results}"
|
|
414
|
-
|
|
415
|
-
samples = single_project.get_samples(my_api)
|
|
416
|
-
puts " The samples for project #{single_project} are"
|
|
417
|
-
puts " #{samples}"
|
|
418
|
-
end
|
|
351
|
+
**Example Source Code:** [examples/3\_accessing\_files.rb](https://github.com/joejimbo/basespace-ruby-sdk/blob/master/examples/3_accessing_files.rb)
|
|
419
352
|
|
|
420
|
-
|
|
353
|
+
In this section we demonstrate how to access samples and analysis from a projects and how to work with the available file data for such instances. In addition, we take a look at some of the special queuring methods associated with BAM- and VCF-files.
|
|
421
354
|
|
|
422
|
-
|
|
423
|
-
The App results for project BaseSpaceDemo - id=2 are
|
|
424
|
-
[Resequencing, Resequencing, Resequencing, Resequencing, Resequencing, Resequencing, Resequencing, Resequencing, Resequencing, Resequencing]
|
|
425
|
-
The samples for project BaseSpaceDemo - id=2 are
|
|
426
|
-
[BC_1, BC_2, BC_3, BC_4, BC_5, BC_6, BC_7, BC_8, BC_9, BC_10]
|
|
427
|
-
# Project: Cancer Sequencing Demo - id=4
|
|
428
|
-
The App results for project Cancer Sequencing Demo - id=4 are
|
|
429
|
-
[Amplicon, Amplicon]
|
|
430
|
-
The samples for project Cancer Sequencing Demo - id=4 are
|
|
431
|
-
[L2I]
|
|
432
|
-
# Project: HiSeq 2500 - id=7
|
|
433
|
-
The App results for project HiSeq 2500 - id=7 are
|
|
434
|
-
[Resequencing]
|
|
435
|
-
The samples for project HiSeq 2500 - id=7 are
|
|
436
|
-
[NA18507]
|
|
437
|
-
......
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
We'll take a further look at the files belonging to the sample from the last project in the loop above:
|
|
355
|
+
*Note:* Create a `BaseSpaceAPI` object as described under "[Getting Started](#getting-started)" first. The instance should be referenced by the variable `bs_api`, just as in the examples of the "[Getting Started](#getting-started)" section.
|
|
441
356
|
|
|
442
|
-
|
|
443
|
-
puts "# Sample: #{sample}"
|
|
444
|
-
files = sample.get_files(my_api)
|
|
445
|
-
puts files
|
|
446
|
-
end
|
|
357
|
+
### Accessing Files
|
|
447
358
|
|
|
448
|
-
|
|
359
|
+
First, we get a project that we can work with:
|
|
449
360
|
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
Bcereus-1_S1_L001_R2_001.fastq.gz - id: '14235853', size: '193698522'
|
|
453
|
-
# Sample: Bcereus_2
|
|
454
|
-
Bcereus-2_S2_L001_R1_001.fastq.gz - id: '14235871', size: '126164153'
|
|
455
|
-
Bcereus-2_S2_L001_R2_001.fastq.gz - id: '14235872', size: '137077949'
|
|
456
|
-
......
|
|
457
|
-
|
|
458
|
-
Now, have a look at some of the methods calls specific to ``Bam`` and ``VCF`` files. First, we will get a ``Bam``-file and then retrieve the coverage information available for chromosome 2 between positions 1 and 20000:
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
device_info = my_api.get_verification_code('read project 183184')
|
|
462
|
-
link = device_info['verification_with_code_uri']
|
|
463
|
-
host = RbConfig::CONFIG['host_os']
|
|
464
|
-
case host
|
|
465
|
-
when /mswin|mingw|cygwin/
|
|
466
|
-
system("start #{link}")
|
|
467
|
-
when /darwin/
|
|
468
|
-
system("open #{link}")
|
|
469
|
-
when /linux/
|
|
470
|
-
system("xdg-open #{link}")
|
|
471
|
-
end
|
|
472
|
-
sleep(15)
|
|
473
|
-
|
|
474
|
-
code = device_info['device_code']
|
|
475
|
-
my_api.update_privileges(code)
|
|
476
|
-
|
|
477
|
-
# Now do some work with files
|
|
478
|
-
# we'll grab a BAM by id and get the coverage for an interval + accompanying meta-data
|
|
479
|
-
|
|
480
|
-
my_bam = my_api.get_file_by_id('44154664')
|
|
481
|
-
puts "# BAM: #{my_bam}"
|
|
482
|
-
cov = my_bam.get_interval_coverage(my_api, 'chr1', '50000', '60000')
|
|
483
|
-
puts cov
|
|
484
|
-
cov_meta = my_bam.get_coverage_meta(my_api, 'chr1')
|
|
485
|
-
puts cov_meta
|
|
361
|
+
user = bs_api.get_user_by_id('current')
|
|
362
|
+
my_projects = bs_api.get_project_by_user('current')
|
|
486
363
|
|
|
487
|
-
|
|
364
|
+
Now we can list all the analyses and samples for these projects:
|
|
488
365
|
|
|
489
|
-
#
|
|
490
|
-
|
|
491
|
-
|
|
366
|
+
# Define 'samples' variable here, so that it can be reused further into the example again:
|
|
367
|
+
samples = nil
|
|
368
|
+
my_projects.each do |single_project|
|
|
369
|
+
puts "Project: #{single_project}"
|
|
370
|
+
|
|
371
|
+
app_results = single_project.get_app_results(bs_api)
|
|
372
|
+
puts " AppResult instances: #{app_results.map { |r| r.to_s }.join(', ')}"
|
|
373
|
+
|
|
374
|
+
samples = single_project.get_samples(bs_api)
|
|
375
|
+
puts " Sample instances: #{samples.map { |s| s.to_s }.join(', ')}"
|
|
376
|
+
end
|
|
492
377
|
|
|
493
|
-
|
|
378
|
+
The output will be similar to:
|
|
494
379
|
|
|
495
|
-
|
|
496
|
-
|
|
380
|
+
Project: BaseSpaceDemo - id=2
|
|
381
|
+
AppResult instances: Resequencing, Resequencing, Resequencing, Resequencing, Resequencing, Resequencing, Resequencing, Resequencing, Resequencing, Resequencing
|
|
382
|
+
Sample instances: BC_1, BC_2, BC_3, BC_4, BC_5, BC_6, BC_7, BC_8, BC_9, BC_10
|
|
383
|
+
Project: Cancer Sequencing Demo - id=4
|
|
384
|
+
AppResult instances: Amplicon, Amplicon
|
|
385
|
+
Sample instances: L2I
|
|
386
|
+
Project: HiSeq 2500 - id=7
|
|
387
|
+
AppResult instances: Resequencing
|
|
388
|
+
Sample instances: NA18507
|
|
497
389
|
|
|
498
|
-
|
|
390
|
+
We will take a further look at the files belonging to the sample from the last project in the loop above:
|
|
499
391
|
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
392
|
+
samples.each do |sample|
|
|
393
|
+
puts "Sample: #{sample}"
|
|
394
|
+
files = sample.get_files(bs_api)
|
|
395
|
+
puts files.map { |f| " #{f}" }
|
|
396
|
+
end
|
|
397
|
+
|
|
398
|
+
The output will be similar to:
|
|
399
|
+
|
|
400
|
+
Sample: Bcereus_1
|
|
401
|
+
Bcereus-1_S1_L001_R1_001.fastq.gz - id: '14235852', size: '179971155'
|
|
402
|
+
Bcereus-1_S1_L001_R2_001.fastq.gz - id: '14235853', size: '193698522'
|
|
403
|
+
Sample: Bcereus_2
|
|
404
|
+
Bcereus-2_S2_L001_R1_001.fastq.gz - id: '14235871', size: '126164153'
|
|
405
|
+
Bcereus-2_S2_L001_R2_001.fastq.gz - id: '14235872', size: '137077949'
|
|
406
|
+
|
|
407
|
+
### Querying BAM and VCF Files
|
|
408
|
+
|
|
409
|
+
Now, we have a look at some of the methods calls specific to BAM and VCF files. First, we will get a BAM-file and then retrieve the coverage information available for chromosome 2 between positions 1 and 20000:
|
|
410
|
+
|
|
411
|
+
# Request privileges:
|
|
412
|
+
# NOTE THAT YOUR PROJECT ID (469469 here) WILL MOST LIKELY BE DIFFERENT!
|
|
413
|
+
device_info = bs_api.get_verification_code('read project 469469')
|
|
414
|
+
link = device_info['verification_with_code_uri']
|
|
415
|
+
puts "Visit the URI within 15 seconds and grant access:"
|
|
416
|
+
puts link
|
|
417
|
+
host = RbConfig::CONFIG['host_os']
|
|
418
|
+
case host
|
|
419
|
+
when /mswin|mingw|cygwin/
|
|
420
|
+
system("start #{link}")
|
|
421
|
+
when /darwin/
|
|
422
|
+
system("open #{link}")
|
|
423
|
+
when /linux/
|
|
424
|
+
system("xdg-open #{link}")
|
|
425
|
+
end
|
|
426
|
+
sleep(15)
|
|
427
|
+
|
|
428
|
+
code = device_info['device_code']
|
|
429
|
+
bs_api.update_privileges(code)
|
|
430
|
+
|
|
431
|
+
# Get the coverage for an interval + accompanying meta-data:
|
|
432
|
+
# NOTE THAT YOUR FILE ID (here 7823816) WILL MOST LIKELY BE DIFFERENT!
|
|
433
|
+
# A FILE ID CAN BE OBTAINED, E.G., USING: samples.first.get_files(bs_api).first.id
|
|
434
|
+
my_bam = bs_api.get_file_by_id('7823816')
|
|
435
|
+
puts "BAM: #{my_bam}"
|
|
436
|
+
cov = my_bam.get_interval_coverage(bs_api, 'chr1', '50000', '60000')
|
|
437
|
+
puts " #{cov.to_s}"
|
|
438
|
+
cov_meta = my_bam.get_coverage_meta(bs_api, 'chr1')
|
|
439
|
+
puts " #{cov_meta.to_s}"
|
|
440
|
+
|
|
441
|
+
The output will be similar to:
|
|
442
|
+
|
|
443
|
+
BAM: sorted_S1.bam - id: '44154664', size: '105789387933', status: 'complete'
|
|
444
|
+
Chrom chr1: 1-1792, BucketSize=2
|
|
445
|
+
CoverageMeta: max=1158602 gran=128
|
|
446
|
+
|
|
447
|
+
For VCF-files we can filter variant calls based on chromosome and location as well:
|
|
448
|
+
|
|
449
|
+
my_vcf = bs_api.get_file_by_id('7823817')
|
|
450
|
+
var_meta = my_vcf.get_variant_meta(bs_api)
|
|
451
|
+
puts var_meta
|
|
452
|
+
var = my_vcf.filter_variant(bs_api, '1', '20000', '30000') # no value. need verification
|
|
453
|
+
puts " #{var.map { |v| v.to_s }.join(', ')}"
|
|
504
454
|
|
|
505
455
|
The output will be:
|
|
506
456
|
|
|
507
457
|
VariantHeader: SampleCount=1
|
|
508
|
-
|
|
458
|
+
Variant - chr2: 10236 id=['.'], Variant - chr2: 10249 id=['.']
|
|
509
459
|
|
|
510
|
-
## Creating an AppResult and
|
|
460
|
+
## Creating an AppResult and Uploading Files
|
|
511
461
|
|
|
512
|
-
|
|
513
|
-
and upload result files to it as well as retrieve files from it.
|
|
462
|
+
**Example Source Code:** [4\_app\_result\_upload.rb](https://github.com/joejimbo/basespace-ruby-sdk/blob/master/examples/4_app_result_upload.rb)
|
|
514
463
|
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
myBaseSpaceAPI = BaseSpaceAPI(client_key, client_secret, BaseSpaceUrl, version, AppSessionId,AccessToken=accessToken)
|
|
464
|
+
In this section we will see how to create a new `AppResult` object, change the state of the related AppSession,
|
|
465
|
+
and upload result files to it as well as retrieve files from it.
|
|
518
466
|
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
467
|
+
*Note:* Create a `BaseSpaceAPI` object as described under "[Getting Started](#getting-started)" first. The instance should be referenced by the variable `bs_api`, just as in the examples of the "[Getting Started](#getting-started)" section.
|
|
468
|
+
|
|
469
|
+
### Creating an AppResult
|
|
470
|
+
|
|
471
|
+
First we get a project to work on. We will need write permissions for the project we are working on -- meaning that we will need to update our privileges accordingly:
|
|
472
|
+
|
|
473
|
+
device_info = bs_api.get_verification_code('browse global')
|
|
474
|
+
link = device_info['verification_with_code_uri']
|
|
475
|
+
puts "Visit the URI within 15 seconds and grant access:"
|
|
476
|
+
puts link
|
|
477
|
+
host = RbConfig::CONFIG['host_os']
|
|
478
|
+
case host
|
|
479
|
+
when /mswin|mingw|cygwin/
|
|
480
|
+
system("start #{link}")
|
|
481
|
+
when /darwin/
|
|
482
|
+
system("open #{link}")
|
|
483
|
+
when /linux/
|
|
484
|
+
system("xdg-open #{link}")
|
|
485
|
+
end
|
|
486
|
+
sleep(15)
|
|
487
|
+
|
|
488
|
+
code = device_info['device_code']
|
|
489
|
+
bs_api.update_privileges(code)
|
|
490
|
+
|
|
491
|
+
# NOTE THAT YOUR PROJECT ID WILL MOST LIKELY BE DIFFERENT!
|
|
492
|
+
# YOU CAN GET IT VIA THE SDK OR FROM THE BASESPACE WEB INTERFACE!
|
|
493
|
+
# FOR EXAMPLE: my_projects.first.id
|
|
494
|
+
prj = bs_api.get_project_by_id('469469')
|
|
523
495
|
|
|
524
496
|
Assuming we have write access for the project, we will list the current analyses for the project:
|
|
525
497
|
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
The output will be:
|
|
498
|
+
statuses = ['Running']
|
|
499
|
+
app_res = prj.get_app_results(bs_api, {}, statuses)
|
|
500
|
+
puts "AppResult instances: #{app_res.map { |r| r.to_s }.join(', ')}"
|
|
530
501
|
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
The current running AppResults are
|
|
534
|
-
[Results for sample 123, Results for sample 124 ...]
|
|
502
|
+
The output will be similar to:
|
|
535
503
|
|
|
504
|
+
AppResult instances: BWA GATK - HiSeq 2500 NA12878 demo 2x150, HiSeq 2500 NA12878 demo 2x150 App Result
|
|
536
505
|
|
|
537
|
-
To create an
|
|
506
|
+
To create an `AppResult` for a project, request 'create' privileges, then simply give the name and description:
|
|
538
507
|
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
508
|
+
device_info = bs_api.get_verification_code("create project #{prj.id}")
|
|
509
|
+
link = device_info['verification_with_code_uri']
|
|
510
|
+
puts "Visit the URI within 15 seconds and grant access:"
|
|
511
|
+
puts link
|
|
512
|
+
host = RbConfig::CONFIG['host_os']
|
|
513
|
+
case host
|
|
514
|
+
when /mswin|mingw|cygwin/
|
|
515
|
+
system("start #{link}")
|
|
516
|
+
when /darwin/
|
|
517
|
+
system("open #{link}")
|
|
518
|
+
when /linux/
|
|
519
|
+
system("xdg-open #{link}")
|
|
520
|
+
end
|
|
521
|
+
sleep(15)
|
|
522
|
+
|
|
523
|
+
code = device_info['device_code']
|
|
524
|
+
bs_api.update_privileges(code)
|
|
546
525
|
|
|
547
|
-
|
|
526
|
+
# NOTE THAT THE APP SESSION ID OF A RUNNING APP MUST BE PROVIDED!
|
|
527
|
+
app_result = prj.create_app_result(bs_api, "testing", "this is my results", bs_api.app_session_id)
|
|
528
|
+
puts "AppResult ID: #{app_result.id}"
|
|
529
|
+
puts "AppResult's AppSession: #{app_result.app_session}"
|
|
548
530
|
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
Some info about our new app results
|
|
552
|
-
AppResult: testing
|
|
553
|
-
153153
|
|
531
|
+
The output will be similar to:
|
|
554
532
|
|
|
555
|
-
|
|
556
|
-
|
|
533
|
+
AppResult ID: 939946
|
|
534
|
+
AppResult's AppSession: App session by 159159: Eri Kibukawa - Id: <app session id> - status: Running
|
|
557
535
|
|
|
558
|
-
We can change the status of our AppSession and add a status-summary as follows
|
|
536
|
+
We can change the status of our `AppSession` and add a status-summary as follows:
|
|
559
537
|
|
|
560
|
-
|
|
561
|
-
print "\nAfter a change of status of the app sessions we get\n" + str(myAppSession)
|
|
562
|
-
# we'll set our appSession back to running so we can do some more work
|
|
563
|
-
myAppSession.setStatus(myBaseSpaceAPI,'running',"Back on track")
|
|
538
|
+
app_result.app_session.set_status(bs_api, 'needsattention', "We worked hard, but encountered some trouble.")
|
|
564
539
|
|
|
565
|
-
|
|
540
|
+
# Updated status:
|
|
541
|
+
puts "AppResult's AppSession: #{app_result.app_session}"
|
|
566
542
|
|
|
567
|
-
|
|
543
|
+
# Set back to running:
|
|
544
|
+
app_result.app_session.set_status(bs_api, 'running', "Back on track")
|
|
568
545
|
|
|
569
|
-
|
|
570
|
-
App session by 152152: Morten Kallberg - Id: <my appSession Id> - status: NeedsAttention
|
|
571
|
-
|
|
572
|
-
Now we will make another AppResult and try to upload a file to it
|
|
546
|
+
The output will be similar to:
|
|
573
547
|
|
|
574
|
-
|
|
575
|
-
appResults2.uploadFile(myBaseSpaceAPI, '/home/mkallberg/Desktop/testFile2.txt', 'BaseSpaceTestFile.txt', '/mydir/', 'text/plain')
|
|
576
|
-
print "\nMy AppResult number 2 \n" + str(appResults2)
|
|
577
|
-
|
|
578
|
-
## let's see if our new file made it
|
|
579
|
-
appResultFiles = appResults2.getFiles(myBaseSpaceAPI)
|
|
580
|
-
print "\nThese are the files in the appResult"
|
|
581
|
-
print appResultFiles
|
|
582
|
-
f = appResultFiles[-1]
|
|
548
|
+
AppResult's AppSession: App session by 159159: Eri Kibukawa - Id: <app session id> - status: NeedsAttention
|
|
583
549
|
|
|
584
|
-
|
|
550
|
+
### Uploading Files
|
|
585
551
|
|
|
586
|
-
|
|
552
|
+
Attach a file to the `AppResult` object and upload it:
|
|
587
553
|
|
|
588
|
-
|
|
589
|
-
|
|
554
|
+
app_result.upload_file(bs_api, '/tmp/testFile.txt', 'BaseSpaceTestFile.txt', '/mydir/', 'text/plain')
|
|
555
|
+
|
|
556
|
+
# Let's see if our new file made it into the cloud:
|
|
557
|
+
app_result_files = app_result.get_files(bs_api)
|
|
558
|
+
puts "Files: #{app_result_files.map { |f| f.to_s }.join(', ')}"
|
|
590
559
|
|
|
591
|
-
|
|
592
|
-
[BaseSpaceTestFile.txt]
|
|
593
|
-
|
|
594
|
-
We can even download our newly uploaded file in the following manner:
|
|
560
|
+
The output will be:
|
|
595
561
|
|
|
596
|
-
|
|
597
|
-
f.downloadFile(myBaseSpaceAPI,'/home/mkallberg/Desktop/')
|
|
562
|
+
Files: BaseSpaceTestFile.txt - id: '7819953', size: '5'
|
|
598
563
|
|
|
599
|
-
|
|
564
|
+
Of course, we can download our newly uploaded file too:
|
|
600
565
|
|
|
601
|
-
|
|
566
|
+
f = bs_api.get_file_by_id(app_result_files.last.id)
|
|
567
|
+
f.download_file(bs_api, '/tmp/')
|
|
602
568
|
|
|
603
|
-
|
|
569
|
+
## Cookbook of Usage Recipes
|
|
604
570
|
|
|
605
|
-
|
|
571
|
+
This section contains useful code snippets, which are demonstrating frequent use-cases in App development.
|
|
606
572
|
|
|
607
|
-
|
|
608
|
-
Out[10]: [sorted.bam, sorted.bam.bai, genome.vcf]
|
|
573
|
+
### Filtering File-Lists and AppResult-Lists using Query Parameter Dictionaries
|
|
609
574
|
|
|
610
|
-
|
|
611
|
-
Out[11]: [sorted.bam]
|
|
575
|
+
Given a sample "a\_sample" we can retrieve a subset of the full file-list using a query parameter dictionary:
|
|
612
576
|
|
|
613
|
-
|
|
577
|
+
*Note:* Create a `BaseSpaceAPI` object as described under "[Getting Started](#getting-started)" first. The instance should be referenced by the variable `bs_api`, just as in the examples of the "[Getting Started](#getting-started)" section.
|
|
614
578
|
|
|
615
|
-
|
|
616
|
-
|
|
579
|
+
# With a BaseSpace API object created as shown above, retrieve a list of our projects,
|
|
580
|
+
# pick the first available project, get its samples, and then assign the first sample
|
|
581
|
+
# to the variable `a_sample`.
|
|
582
|
+
my_projects = bs_api.get_project_by_user('current')
|
|
583
|
+
a_project = my_projects.first
|
|
584
|
+
my_samples = a_project.get_samples(bs_api)
|
|
585
|
+
|
|
586
|
+
# Get a brief sample representation from the point of a project:
|
|
587
|
+
a_sample = my_samples.first
|
|
588
|
+
|
|
589
|
+
# Get the full version via direct BaseSpace API call (for demonstration, not required below):
|
|
590
|
+
full_sample = bs_api.get_sample_by_id(a_sample.id)
|
|
591
|
+
|
|
592
|
+
# Get a list of files associated with the sample:
|
|
593
|
+
# Possible output: ["s_G1_L001_I1_001.fastq.1.gz - id: '535642', size: '7493990'", "s_G1_L001_I1_002.fastq.1.gz - id: '535643', size: '7525743'"]
|
|
594
|
+
a_sample.get_files(bs_api).map { |file| file.to_s }
|
|
595
|
+
|
|
596
|
+
# Get a listing of ".gz" files:
|
|
597
|
+
a_sample.get_files(bs_api, { 'Extensions' => 'gz' })
|
|
598
|
+
|
|
599
|
+
# Get a listing with multiple extension filter (".bam" and ".vcf" files):
|
|
600
|
+
a_sample.get_files(bs_api, { 'Extensions' => 'bam,vcf' })
|
|
617
601
|
|
|
618
602
|
You can provide all other legal sorting/filtering keyword in this dictionary to get further refinement of the list:
|
|
619
603
|
|
|
620
|
-
|
|
621
|
-
Out[13]: [genome.vcf, sorted.bam]
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
You can supply a dictionary of query parameters when you retrieving appresults, in the same way you filter file lists. Below is an example of how to limit the number of results from 100 (default value for “Limit”) to 10.
|
|
625
|
-
|
|
626
|
-
In [3]: res = p.getAppResults(myBaseSpaceAPI)
|
|
627
|
-
|
|
628
|
-
In [4]: len(res)
|
|
629
|
-
Out[4]: 100
|
|
604
|
+
a_sample.get_files(bs_api, { 'Extensions' => 'bam,vcf', 'SortBy' => 'Path', 'Limit' => 1 })
|
|
630
605
|
|
|
631
|
-
|
|
606
|
+
You can supply a dictionary of query parameters when retrieving App results, in the same way you filter file lists. Below is an example of how to limit the number of results from 100 (default value for "Limit") to 10.
|
|
632
607
|
|
|
633
|
-
|
|
634
|
-
|
|
608
|
+
results = a_project.get_app_results(bs_api)
|
|
609
|
+
|
|
610
|
+
# Possible output: 100
|
|
611
|
+
results.length
|
|
612
|
+
|
|
613
|
+
# Restrict the returned list of results to 10 items.
|
|
614
|
+
# New length of `results`: 10
|
|
615
|
+
results = a_project.get_app_results(bs_api, { 'Limit' => '10' })
|
|
616
|
+
results.length
|
|
635
617
|
|
|
636
|
-
## Feature Requests and
|
|
618
|
+
## Feature Requests and Bug Reporting
|
|
637
619
|
|
|
638
|
-
Please
|
|
620
|
+
Please report any feedback regarding the BaseSpace Ruby SDK directly to the [GitHub repository](https://github.com/joejimbo/basespace-ruby-sdk). We appreciate any and all feedback about the SDKs and we will do anything we can to improve the functionality and quality of the SDK to make it the best SDK for developers to use.
|
|
639
621
|
|
|
640
622
|
# SDK Development Manual
|
|
641
623
|
|
|
624
|
+
This section focuses on development aspects of the BaseSpace Ruby SDK gem. It also provides information on how to build the pre-release version of the SDK, but unless you are actually planning to contribute to the SDK source code or documentation, we strongly suggest to follow the official release installation instruction under "[Availability and Installation](#availability-and-installation)".
|
|
625
|
+
|
|
642
626
|
## Building a New Version of the Gem
|
|
643
627
|
|
|
644
628
|
bundle exec rake gemspec
|
|
@@ -672,11 +656,24 @@ BaseSpace Ruby SDK was initially ported by translating the BaseSpace Python SDK
|
|
|
672
656
|
* Python `dict`, Ruby `Hash`
|
|
673
657
|
* Python `file`, Ruby `File`
|
|
674
658
|
|
|
675
|
-
# Authors
|
|
659
|
+
# Authors and Contributors
|
|
660
|
+
|
|
661
|
+
## Authors
|
|
676
662
|
|
|
677
663
|
Joachim Baran, Raoul Bonnal, Eri Kibukawa, Francesco Strozzi, Toshiaki Katayama
|
|
678
664
|
|
|
679
|
-
|
|
665
|
+
## Contributors
|
|
666
|
+
|
|
667
|
+
In alphabetical order (last name):
|
|
668
|
+
|
|
669
|
+
* Joachim Baran
|
|
670
|
+
* Raoul Bonnal
|
|
671
|
+
* Naohisa Goto
|
|
672
|
+
* Toshiaki Katayama
|
|
673
|
+
* Eri Kibukawa
|
|
674
|
+
* Francesco Strozzi
|
|
675
|
+
|
|
676
|
+
# Copying and License
|
|
680
677
|
|
|
681
678
|
See [License.txt](https://raw.github.com/joejimbo/basespace-ruby-sdk/master/License.txt) for details on licensing and distribution.
|
|
682
679
|
|