bio-basespace-sdk 0.1.3 → 0.1.5

data/Rakefile

@@ -17,12 +17,10 @@ Jeweler::Tasks.new do |gem|
   gem.name = "bio-basespace-sdk"
   gem.homepage = "https://github.com/joejimbo/basespace-ruby-sdk"
   gem.license = "Apache, Version 2.0"
-  gem.summary = %Q{Bio::BaseSpace is a Ruby based SDK 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.}
-  gem.description = %Q{Bio::BaseSpace is a Ruby based SDK ported from the Python based BaseSpacePy SDK 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.
+  gem.summary = %Q{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.}
+  gem.description = %Q{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.
 
-  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.
-
-  If you haven't already done so, you may wish to familiarize yourself with the general BaseSpace developers documentation (https://developer.basespace.illumina.com/) and create a new BaseSpace App to be used when working through the examples provided in 'examples' folder.}
+  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.}
   gem.email = "joachim.baran@gmail.com"
   gem.authors = ["Joachim Baran", "Raoul Bonnal", "Eri Kibukawa", "Francesco Strozzi", "Toshiaki Katayama"]
 #  gem.executable = 'basespace-ruby'

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.1.5

data/examples/0_app_triggering.rb

@@ -14,19 +14,12 @@
 # limitations under the License.
 
 # Application triggering
-#   https://developer.basespace.illumina.com/docs/content/documentation/sdk-samples/python-sdk-overview#Application_triggering
+# https://github.com/joejimbo/basespace-ruby-sdk#application-triggering
 
 require 'bio-basespace-sdk'
 
 include Bio::BaseSpace
 
-# This script demonstrates how to retrieve the AppSession object produced 
-# when a user initiates an app. Further it's demonstrated how to automatically
-# generate the scope strings to request access to the data object (a project or a sample)
-# that the app was triggered to analyze.
-# 
-# NOTE: You will need to fill in client values for your app below
-
 # Initialize an authentication object using the key and secret from your app.
 opts = {
   # FILL IN WITH YOUR APP VALUES HERE!
@@ -44,92 +37,88 @@ unless opts.select{|k,v| v[/^<.*>$/]}.empty?
   exit 1 unless opts
 end
 
-# First we will initialize a BaseSpace API object using our app information and the appSessionId.
+# Initialize a BaseSpace API object:
 bs_api = BaseSpaceAPI.new(opts['client_id'], opts['client_secret'], opts['basespace_url'], opts['api_version'], opts['app_session_id'])
 
-# Using the bmy_app_session.spaceApi we can request the appSession object corresponding to the AppSession id supplied.
+# Using bs_api, we can request the AppSession object corresponding to the AppSession ID supplied
 my_app_session = bs_api.get_app_session
 puts my_app_session
 
-# An app session contains a referal to one or more appLaunchObjects which reference the data module
-# the user launched the app on. This can be a list of projects, samples, or a mixture of objects.
-puts "Type of data the app was triggered on can be seen in 'references'"
-puts my_app_session.references.inspect   # same as my_app_session.get_attr('References') inspect is used to put surrounding [] 
-puts
+# An app session contains a referral to one or more AppSessionLaunchObject instances, which reference the
+# data module the user launched the App on. This can be a list of projects, samples, or a mixture of objects
+puts "Type of data the app was triggered on can be seen in 'references':"
+puts my_app_session.references.inspect  # `inspect` shows the object contents
+
+#
+# We can get a handle to the user who started the `AppSession` and further information on the `AppSessionLaunchObject`:
+#
 
-# We can also get a handle to the user who started the AppSession.
-puts "We can get a handle for the user who triggered the app"
-puts my_app_session.user_created_by      # same as my_app_session.get_attr('UserCreatedBy')
+puts "App session created by user:"
+puts my_app_session.user_created_by
 puts
 
-# Let's have a closer look at the appSessionLaunchObject.
+# Let's have a closer look at the AppSessionLaunchObject class instance:
 my_reference = my_app_session.references.first
 
-puts "We can get out information such as the href to the launch object:"
-puts my_reference.href_content           # same as my_reference.get_attr('HrefContent')
+puts "href to the launch object:"
+puts my_reference.href_content
 puts
-puts "and the specific type of that object:"
-puts my_reference.type                   # same as my_reference.get_attr('Type')
+puts "Type of that object:"
+puts my_reference.type
 puts
 
-# Now we will want to ask for more permission for the specific reference object.
-my_reference_content = my_reference.content
+#
+# 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
+#
 
-puts "We can get out the specific project objects by using 'content':" 
+puts "Project object:"
+my_reference_content =  my_reference.content
 puts my_reference_content
 puts
-
-puts "The scope string for requesting write access to the reference object is:"
+puts "Scope string for requesting write access to the reference object:"
 puts my_reference_content.get_access_str('write')
-puts
 
-# We can easily request write access to the reference object, so that our App can start contributing analysis.
-# By default, we ask for write permission and authentication for a device.
-access_map = bs_api.get_access(my_reference_content, 'write')
-# We may limit our request to read access only if that's all that is needed
-read_access_map  = bs_api.get_access(my_reference_content, 'read')
+#
+# The following call requests write permissions for a Web App:
+#
+
+verification_with_code_uri = bs_api.get_access(my_reference_content, 'write')
+puts "Visit the URI within 15 seconds and grant access:"
+puts verification_with_code_uri
 
-puts "We get the following access map for the write request"
+#
+# The following call requests write permissions for other Apps (Desktop, Mobile, Native):
+#
+
+access_map = bs_api.get_access(my_reference_content, 'write')
+puts "Access map:"
 puts access_map
-puts
 
-# NOTE You'll need to use a writable project for the following code.
-# It will fail if the session is read only (e.g., demo projects).
+#
+# Confirm 'write' privilege request:
+#
 
-## PAUSE HERE
-# Have the user visit the verification uri to grant us access.
-puts "Please visit the following URL within 15 seconds and grant access"
-puts access_map['verification_with_code_uri']
+puts "Visit the URI within 15 seconds and grant access:"
+verification_with_code_uri = access_map['verification_with_code_uri']
+puts verification_with_code_uri
 
 link = access_map['verification_with_code_uri']
 host = RbConfig::CONFIG['host_os']
 case host
 when /mswin|mingw|cygwin/
-  system("start #{link}")
+  system("start #{verification_with_code_uri}")
 when /darwin/
-  system("open #{link}")
+  system("open #{verification_with_code_uri}")
 when /linux/
-  system("xdg-open #{link}")
+  system("xdg-open #{verification_with_code_uri}")
 end
-# BaseSpace exception: authorization_pending - User has not yet approved the access request (RuntimeError).
 sleep(15)
-## PAUSE HERE
 
-# Once the user has granted us the access to the object we requested we can get
-# the basespace access token and start browsing simply by calling updatePriviliges
-# on the BaseSpaceAPI instance.
 code = access_map['device_code']
 bs_api.update_privileges(code)
-puts "The BaseSpaceAPI instance was update with write privileges"
-puts bs_api
-puts
-
-# for more details on access-requests and authentication and an example of the web-based case
-# see example 1_authentication.rb
-
-
-
-
-
-
 

data/examples/1_authentication.rb

@@ -13,21 +13,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Requesting an access-token for data browsing
-#   https://developer.basespace.illumina.com/docs/content/documentation/sdk-samples/python-sdk-overview#Requesting_an_access-token_for_data_browsing
+# BaseSpace Authentication
+# https://github.com/joejimbo/basespace-ruby-sdk#basespace-authentication
 
 require 'bio-basespace-sdk'
 
 include Bio::BaseSpace
 
-# Demonstrates the basic BaseSpace authentication process The work-flow is as follows: 
-# scope-request -> user grants access -> browsing data. The scenario is demonstrated both for device and web-based apps.
-# 
-# Further we demonstrate how a BaseSpaceAPI instance may be preserved across multiple
-# http-request for the same app session using Python's pickle module.
-# 
-# NOTE You will need to fill client values for your app below!
-
 opts = {
   # FILL IN WITH YOUR APP VALUES HERE!
   'client_id'       => '<your client key>',
@@ -44,16 +36,22 @@ unless opts.select{|k,v| v[/^<.*>$/]}.empty?
   exit 1 unless opts
 end
 
+# Initialize a BaseSpace API object:
 bs_api = BaseSpaceAPI.new(opts['client_id'], opts['client_secret'], opts['basespace_url'], opts['api_version'], opts['app_session_id'])
 
-# First, get the verification code and uri for scope 'browse global'.
-device_info = bs_api.get_verification_code('browse global')
+#
+# Get the verification code and uri for scope 'browse global':
+#
 
-## PAUSE HERE
-# Have the user visit the verification uri to grant us access.
-puts "Please visit the following URL within 15 seconds and grant access"
+device_info = bs_api.get_verification_code('browse global')
+puts
+puts "URI for user to visit and grant access:"
 puts device_info['verification_with_code_uri']
 
+#
+# Grant access privileges:
+#
+
 link = device_info['verification_with_code_uri']
 host = RbConfig::CONFIG['host_os']
 case host
@@ -65,92 +63,9 @@ when /linux/
   system("xdg-open #{link}")
 end
 sleep(15)
-## PAUSE HERE
 
-# Once the user has granted us access to objects we requested, we can get
-# the basespace access token and start browsing simply by calling updatePriviliges
-# on the baseSpaceApi instance.
 code = device_info['device_code']
 bs_api.update_privileges(code)
 
-# As a reference the provided access-token can be obtained from the BaseSpaceAPI object.
-puts "My Access-token: #{bs_api.get_access_token}"
-puts
-
-# Let's try and grab all available genomes with our new api! 
-all_genomes  = bs_api.get_available_genomes
-puts "Genomes: #{all_genomes}"
-puts
-
-# If at a later stage we wish to initialize a BaseSpaceAPI object when we already have
-# an access-token from a previous sessions, this may simply be done by initializing the BaseSpaceAPI
-# object using the key-word AccessToken.
-my_token = bs_api.get_access_token
-bs_api = BaseSpaceAPI.new(opts['client_id'], opts['client_secret'], opts['basespace_url'], opts['api_version'], opts['app_session_id'], my_token)
-puts "A BaseSpaceAPI instance initialized with an access-token:"
-puts bs_api
-puts
-
-#################### Web-based verification #################################
-# The scenario where the authentication is done through a web-browser.
-
-bs_api_web = BaseSpaceAPI.new(opts['client_id'], opts['client_secret'], opts['basespace_url'], opts['api_version'], opts['app_session_id'])
-user_url= bs_api_web.get_web_verification_code('browse global', 'http://localhost', 'myState')
-
-puts "Have the user visit:"
-puts user_url
-puts
-
-link = user_url
-host = RbConfig::CONFIG['host_os']
-case host
-when /mswin|mingw|cygwin/
-  system("start #{link}")
-when /darwin/
-  system("open #{link}")
-when /linux/
-  system("xdg-open #{link}")
-end
-
-# Once the grant has been given you will be redirected to a url looking something like this
-# http://localhost/?code=<MY DEVICE CODE FROM REDICRECT>&state=myState&action=oauthv2authorization
-# By getting the code parameter from the above http request we can now get our access-token.
-
-my_code = '<MY DEVICE CODE FROM REDICRECT>'
-#bs_api_web.update_privileges(my_code)
-
-user = bs_api.get_user_by_id('current')
-puts "Get current user"
-puts user
-puts bs_api
-puts
-
-#### Carry on with the work...
-
-# Now we wish to store the API object for the next time we get a request in this session
-# make a file to store the BaseSpaceAPI instance in. For easy identification we will name
-# this by any id that may be used for identifying the session again.
-my_session_id = bs_api.app_session_id + '.marshal'
-File.open(my_session_id, 'w') do |f|
-  Marshal.dump(bs_api, f)
-end
-
-# Imagine the current request is done, we will simulate this by deleting the api instance.
-bs_api = nil
-puts "Try printing the removed API, we get: '#{bs_api}' (<-- should be empty)"
-puts
-
-# Next request in the session with id = id123 comes in.
-# We will check if there is already a BaseSpaceAPI stored for the session.
-if File.exists?(my_session_id)
-  File.open(my_session_id) do |f|
-    bs_api = Marshal.load(f)
-  end
-  puts
-  puts "We got the API back!"
-  puts bs_api
-else
-  puts "Looks like we haven't stored anything for this session yet"
-  # create a BaseSpaceAPI for the first time
-end
+puts "Access-token: #{bs_api.get_access_token}"
 

data/examples/2_browsing.rb

@@ -13,16 +13,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Browsing data with global browse access
-#   https://developer.basespace.illumina.com/docs/content/documentation/sdk-samples/python-sdk-overview#Browsing_data_with_global_browse_access
+# Browsing Data
+# https://github.com/joejimbo/basespace-ruby-sdk#browsing-data
 
 require 'bio-basespace-sdk'
 
 include Bio::BaseSpace
 
-# This script demonstrates basic browsing of BaseSpace objects once an access-token
-# for global browsing has been obtained. 
-
 opts = {
   # FILL IN WITH YOUR APP VALUES HERE!
   'client_id'       => '<your client key>',
@@ -39,46 +36,47 @@ unless opts.select{|k,v| v[/^<.*>$/]}.empty?
   exit 1 unless opts
 end
 
-# First, create a client for making calls for this user session.
-my_api = BaseSpaceAPI.new(opts['client_id'], opts['client_secret'], opts['basespace_url'], opts['api_version'], opts['app_session_id'], opts['access_token'])
+# Initialize a BaseSpace API object:
+bs_api = BaseSpaceAPI.new(opts['client_id'], opts['client_secret'], opts['basespace_url'], opts['api_version'], opts['app_session_id'], opts['access_token'])
+
+#
+# Retrieve a genome object:
+#
 
-# Now let's grab the genome with id=4.
-my_genome = my_api.get_genome_by_id('4')
-puts "The Genome is #{my_genome}"
-puts "We can get more information from the genome object"
+my_genome = bs_api.get_genome_by_id('4')
+puts "Genome: #{my_genome}"
 puts "Id: #{my_genome.id}"
 puts "Href: #{my_genome.href}"
 puts "DisplayName: #{my_genome.display_name}"
-puts
-
-# Get a list of all genomes.
-all_genomes  = my_api.get_available_genomes
-puts "Genomes: #{all_genomes}"
-puts
-
-# Let's have a look at the current user.
-user = my_api.get_user_by_id('current')
-puts "The current user is #{user}"
-puts
-
-# Now list the projects for this user.
-my_projects = my_api.get_project_by_user('current')
-puts "The projects for this user are #{my_projects}"
-puts
-
-# We can also achieve this by making a call using the 'user instance'.
-my_projects2 = user.get_projects(my_api)
-puts "Projects retrieved from the user instance #{my_projects2}"
-puts
-
-# List the runs available for the current user.
-runs = user.get_runs(my_api)
-puts "The runs for this user are #{runs}"
-puts
-
-=begin [NOTE] commented out as this example is same as the above (bug in Python version?)
-# In the same manner we can get a list of accessible user runs
-runs = user.get_runs(my_api)
-print "Runs retrieved from user instance #{runs}"
-puts
-=end
+
+#
+# Get a list of all available genomes:
+#
+
+all_genomes  = bs_api.get_available_genomes
+puts "Genomes: #{all_genomes.map { |g| g.to_s }.join(', ')}"
+
+#
+# Retrieve the `User` object for the current user and list all projects for this user:
+#
+
+user = bs_api.get_user_by_id('current')
+puts "User -- #{user}"
+
+my_projects = bs_api.get_project_by_user('current')
+puts "Projects: #{my_projects.map { |p| p.to_s }.join(', ')}"
+
+#
+# We can also achieve this by making a call to the `User` instance:
+#
+
+my_projects = user.get_projects(bs_api)
+puts "Projects: #{my_projects.map { |p| p.to_s }.join(', ')}"
+
+#
+# List all runs for a user:
+#
+
+runs = user.get_runs(bs_api)
+puts "Runs: #{runs.map { |r| r.to_s }.join(', ')}"
+

data/examples/3_accessing_files.rb

@@ -13,16 +13,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Accessing file-trees and querying BAM or VCF files
-#   https://developer.basespace.illumina.com/docs/content/documentation/sdk-samples/python-sdk-overview#Accessing_file-trees_and_querying_BAM_or_VCF_files
+# Accessing and Querying Files
+# https://github.com/joejimbo/basespace-ruby-sdk#accessing-and-querying-files
 
 require 'bio-basespace-sdk'
 
 include Bio::BaseSpace
 
-# This script demonstrates how to access Samples and AppResults from a projects and
-# how to work with the available file data for such instances. 
-
 opts = {
   # FILL IN WITH YOUR APP VALUES HERE!
   'client_id'       => '<your client key>',
@@ -39,91 +36,89 @@ unless opts.select{|k,v| v[/^<.*>$/]}.empty?
   exit 1 unless opts
 end
 
-# First, create a client for making calls for this user session.
-my_api       = BaseSpaceAPI.new(opts['client_id'], opts['client_secret'], opts['basespace_url'], opts['api_version'], opts['app_session_id'], opts['access_token'])
-user         = my_api.get_user_by_id('current')
-my_projects  = my_api.get_project_by_user('current')
+# Initialize a BaseSpace API object:
+bs_api = BaseSpaceAPI.new(opts['client_id'], opts['client_secret'], opts['basespace_url'], opts['api_version'], opts['app_session_id'], opts['access_token'])
+
+### Accessing Files ###
+
+#
+# Get a project that we can work with:
+#
 
-app_results  = nil
-samples      = nil
+user = bs_api.get_user_by_id('current')
+my_projects = bs_api.get_project_by_user('current')
 
-# Let's list all the AppResults and samples for these projects.
+#
+# List all the analyses and samples for these projects:
+#
+
+# Define 'samples' variable here, so that it can be reused further into the example again:
+samples = nil
 my_projects.each do |single_project|
-  puts "# Project: #{single_project}"
-
-  app_results = single_project.get_app_results(my_api)
-  puts "    The App results for project #{single_project} are"
-  puts "      #{app_results}"
-
-#  app_results.each do |app_res|
-#    puts "      # AppResult: #{app_res.id}"
-#    files = app_res.get_files(my_api)
-#    puts files
-#  end
-
-  samples = single_project.get_samples(my_api)
-  puts "    The samples for project #{single_project} are"
-  puts "      #{samples}"
-
-#  samples.each do |sample|
-#    puts "      # Sample: #{sample}"
-#    files = sample.get_files(my_api)
-#    puts files
-#  end
-end
+  puts "Project: #{single_project}"
 
-# We will take a further look at the files belonging to the sample and 
-# analysis from the last project in the loop above.
-app_results.each do |app_res|
-  puts "# AppResult: #{app_res.id}"
-  files = app_res.get_files(my_api)
-  puts files
+  app_results = single_project.get_app_results(bs_api)
+  puts "  AppResult instances: #{app_results.map { |r| r.to_s }.join(', ')}"
+
+  samples = single_project.get_samples(bs_api)
+  puts "  Sample instances: #{samples.map { |s| s.to_s }.join(', ')}"
 end
+
+#
+# Look at the files belonging to the sample from the last project in the loop above:
+#
+
 samples.each do |sample|
-  puts "# Sample: #{sample}"
-  files = sample.get_files(my_api)
-  puts files
+  puts "Sample: #{sample}"
+  files = sample.get_files(bs_api)
+  puts files.map { |f| "  #{f}" }
 end
 
-# [TODO] We need to identify file IDs for BAM and VCF which can be accessed by everyone (for testing)
-# The BAM file 2150156 and the VCF file 2150158 are not available for public
-# => Forbidden: Sorry but this requires READ access to this  resource.
-#
-# https://basespace.illumina.com/datacentral
+### Querying BAM and VCF Files ###
+
 #
-# Project: Cancer Sequencing Demo - id=4
-# AppResult: 31193
-#   L2I_S1.bam - id: '5595005', size: '673519149'
+# Request privileges
 #
-# Project: ResequencingPhixRun - id=12
-# AppResult: 6522
-#   Indels.1.vcf - id: '3360125', size: '747'
-# Project: BaseSpaceDemo - id=2
-# AppResult: 1031
-#   Indels.1.vcf - id: '535594', size: '5214'
-# 
+
+# NOTE THAT YOUR PROJECT ID (469469 here) WILL MOST LIKELY BE DIFFERENT!
+puts 'NOTE: CHANGE THE PROJECT ID IN THE EXAMPLE TO MATCH A PROJECT OF YOURS!'
+device_info = bs_api.get_verification_code('read project 469469')
+link = device_info['verification_with_code_uri']
+puts "Visit the URI within 15 seconds and grant access:"
+puts link
+host = RbConfig::CONFIG['host_os']
+case host
+when /mswin|mingw|cygwin/
+  system("start #{link}")
+when /darwin/
+  system("open #{link}")
+when /linux/
+  system("xdg-open #{link}")
+end
+sleep(15)
+
+code = device_info['device_code']
+bs_api.update_privileges(code)
 
 #
-# Working with files.
+# Get the coverage for an interval + accompanying meta-data
 #
 
-# We grab a BAM by id and get the coverage for an interval + accompanying meta-data.
-my_bam = my_api.get_file_by_id('5595005')  # [TODO] What file ID to use?
-puts "# BAM: #{my_bam}"
-cov_meta = my_bam.get_coverage_meta(my_api, 'chr2')
-puts cov_meta
-cov = my_bam.get_interval_coverage(my_api, 'chr2', '1', '20000')  # [TODO] What seqname and position to use?
-puts cov
-
-# and a vcf file
-#my_vcf = my_api.get_file_by_id('3360125')  # [TODO] What file ID to use?
-my_vcf = my_api.get_file_by_id('44153695')  # Public data >> Resequencing >> HiSeq 2500 2x150 Human Genome Demo
-puts "# VCF: #{my_vcf}"
-# Let's get the variant meta info 
-var_meta = my_vcf.get_variant_meta(my_api)
+# NOTE THAT YOUR FILE ID (here 7823816) WILL MOST LIKELY BE DIFFERENT!
+# A FILE ID CAN BE OBTAINED, E.G., USING: samples.first.get_files(bs_api).first.id
+puts 'NOTE: CHANGE THE FILE ID IN THE EXAMPLE TO MATCH A BAM FILE OF YOURS!'
+my_bam = bs_api.get_file_by_id('7823816')
+puts "BAM: #{my_bam}"
+cov = my_bam.get_interval_coverage(bs_api, 'chr1', '50000', '60000')
+puts "  #{cov.to_s}"
+cov_meta = my_bam.get_coverage_meta(bs_api, 'chr1')
+puts "  #{cov_meta.to_s}"
+
+# For VCF-files we can filter variant calls based on chromosome and location as well:
+puts 'NOTE: CHANGE THE FILE ID IN THE EXAMPLE TO MATCH A VCF FILE OF YOURS!'
+my_vcf = bs_api.get_file_by_id('7823817')
+var_meta = my_vcf.get_variant_meta(bs_api)
 puts var_meta
-#var = my_vcf.filter_variant(my_api, 'phix', '1', '5386')  # [TODO] What seqname and position to use?
-var = my_vcf.filter_variant(my_api, '2', '1', '11000')
-puts var
-
+var = my_vcf.filter_variant(bs_api, '1', '20000', '30000') # no value. need verification
+puts "  #{var.map { |v| v.to_s }.join(', ')}"