bio-basespace-sdk 0.1.2

data/Rakefile

@@ -0,0 +1,54 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  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.
+
+  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.}
+  gem.email = "joachim.baran@gmail.com"
+  gem.authors = ["Joachim Baran", "Raoul Bonnal", "Eri Kibukawa", "Francesco Strozzi", "Toshiaki Katayama"]
+#  gem.executable = 'basespace-ruby'
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "BaseSpace Ruby SDK #{version}"
+  # rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.2

data/examples/0_app_triggering.rb

@@ -0,0 +1,135 @@
+#!/usr/bin/env ruby
+
+# Copyright 2013 Toshiaki Katayama, Joachim Baran
+#
+#     Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+# 
+#     Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Application triggering
+#   https://developer.basespace.illumina.com/docs/content/documentation/sdk-samples/python-sdk-overview#Application_triggering
+
+require 'basespace'
+
+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!
+  'client_id'       => '<your client key>',
+  'client_secret'   => '<your client secret>',
+  'access_token'    => '<your access token>',
+  'app_session_id'  => '<app session id>',
+  'basespace_url'   => 'https://api.basespace.illumina.com/',
+  'api_version'     => 'v1pre3',
+}
+
+# Test if client variables have been set.
+unless opts.select{|k,v| v[/^<.*>$/]}.empty?
+  opts = Bio::BaseSpace.load_credentials
+  exit 1 unless opts
+end
+
+# First we will initialize a BaseSpace API object using our app information and the appSessionId.
+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.
+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
+
+# 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
+
+# Let's have a closer look at the appSessionLaunchObject.
+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
+puts "and the specific type of that object:"
+puts my_reference.type                   # same as my_reference.get_attr('Type')
+puts
+
+# Now we will want to ask for more permission for the specific reference object.
+my_reference_content = my_reference.content
+
+puts "We can get out the specific project objects by using 'content':" 
+puts my_reference_content
+puts
+
+puts "The scope string for requesting write access to the reference object is:"
+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')
+
+puts "We get the following access map for the write request"
+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).
+
+## 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']
+
+link = access_map['verification_with_code_uri']
+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
+# 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

@@ -0,0 +1,156 @@
+#!/usr/bin/env ruby
+
+# Copyright 2013 Toshiaki Katayama, Joachim Baran
+#
+#     Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+# 
+#     Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# 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
+
+require 'basespace'
+
+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>',
+  'client_secret'   => '<your client secret>',
+  'access_token'    => '<your access token>',
+  'app_session_id'  => '<app session id>',
+  'basespace_url'   => 'https://api.basespace.illumina.com/',
+  'api_version'     => 'v1pre3',
+}
+
+# Test if client variables have been set.
+unless opts.select{|k,v| v[/^<.*>$/]}.empty?
+  opts = Bio::BaseSpace.load_credentials
+  exit 1 unless opts
+end
+
+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')
+
+## 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 device_info['verification_with_code_uri']
+
+link = device_info['verification_with_code_uri']
+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)
+## 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
+

data/examples/2_browsing.rb

@@ -0,0 +1,84 @@
+#!/usr/bin/env ruby
+
+# Copyright 2013 Toshiaki Katayama, Joachim Baran
+#
+#     Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+# 
+#     Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# 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
+
+require 'basespace'
+
+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>',
+  'client_secret'   => '<your client secret>',
+  'access_token'    => '<your access token>',
+  'app_session_id'  => '<app session id>',
+  'basespace_url'   => 'https://api.basespace.illumina.com/',
+  'api_version'     => 'v1pre3',
+}
+
+# Test if client variables have been set.
+unless opts.select{|k,v| v[/^<.*>$/]}.empty?
+  opts = Bio::BaseSpace.load_credentials
+  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'])
+
+# 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"
+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

data/examples/3_accessing_files.rb

@@ -0,0 +1,129 @@
+#!/usr/bin/env ruby
+
+# Copyright 2013 Toshiaki Katayama, Joachim Baran
+#
+#     Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+# 
+#     Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# 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
+
+require 'basespace'
+
+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>',
+  'client_secret'   => '<your client secret>',
+  'access_token'    => '<your access token>',
+  'app_session_id'  => '<app session id>',
+  'basespace_url'   => 'https://api.basespace.illumina.com/',
+  'api_version'     => 'v1pre3',
+}
+
+# Test if client variables have been set.
+unless opts.select{|k,v| v[/^<.*>$/]}.empty?
+  opts = Bio::BaseSpace.load_credentials
+  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')
+
+app_results  = nil
+samples      = nil
+
+# Let's list all the AppResults and samples for these projects.
+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
+
+# 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
+end
+samples.each do |sample|
+  puts "# Sample: #{sample}"
+  files = sample.get_files(my_api)
+  puts files
+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
+#
+# Project: Cancer Sequencing Demo - id=4
+# AppResult: 31193
+#   L2I_S1.bam - id: '5595005', size: '673519149'
+#
+# 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'
+# 
+
+#
+# Working with files.
+#
+
+# 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)
+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
+
+