• 家
• 文件
• Ruby SDK概述

BaseSpace Ruby SDK

BaseSpace Ruby SDK是一个基于Ruby的软件开发工具包，用于与Illumina的BaseSpace云计算解决方案一起开发下一代测序数据分析的应用程序和脚本。

SDK的主要目的是提供一个易于使用的Ruby环境，使开发人员能够对用户进行身份验证、检索数据，并从自己的分析中上传数据/结果到BaseSpace。

注意:对于运行以下几个示例，需要（免费）基准空间帐户，并且您需要拥有“客户端ID”代码（参数client_key下面）和“客户机密”代码（参数client_secret.以下）用于您的一个应用程序。

目录

• BaseSpace Ruby SDK
  • 供应和安装
  • 开始
  • 应用触发
  • BaseSpace身份验证
  • 浏览数据
  • 访问和查询文件
  • 创建和上传文件
  • 食谱的用法食谱
  • 特性请求和Bug报告
• SDK开发手册
  • 构建一个新版本的宝石
  • 单元测试
  • 移植
• 作者和贡献者
  • 作者
  • 贡献者
• 复制和许可

供应和安装

要求:Ruby 1.9.3及以上。多部分文件上传当前仅在UNIX设置上运行。

BaseSpace Ruby SDK的生产环境版本是一个Ruby gem:

GEM安装生物Basespace-SDK

根据您的Ruby安装，可能需要使用Superuser权限安装Ruby Gem：

sudo gem安装生物basespace-sdk

要测试所有内容都在预期工作，请启动交互式Ruby并尝试导入“Bio :: Basespace”：

$ IRB >>要求'Bio-Basespace-SDK'>>包括生物:: Basespace

预发布版本

可以在此处签出BaseSpace Ruby SDK的预发布版本：

git克隆https://github.com/basespace/basespace-ruby-sdk.git

或者,

git克隆git@github.com: basespace / basespace-ruby-sdk.git

有关如何构建预发布版本的描述，请参见“SDK开发手册"．

如果您想改进SDK，请抛弃GitHub存储库并向我们发送拉出请求。

开始

用于与BaseSpace进行交互的核心类是生物:BaseSpace:: BaseSpaceAPI．通过将认证和连接详细信息通过参数传递到A的Authentication和Connection详细信息来创建该类的实例新的调用或通过文件credentials.json.．

注意:根据您要执行的操作，您将需要提供APP会话ID（app_session_id或者访问令牌（access_token）， 或两者。您可以将其中一个参数设置为零如果与BaseSpace的交互不需要它的话。

创建一个BaseSpaceAPI物体使用新的：

需要“bio-basespace-sdk”包括生物::BaseSpace #身份验证和连接细节:client_id =我的客户关键的client_secret =“我的客户秘密”app_session_id =“我的应用程序会话id”access_token =“我的访问令牌”basespace_url = ' https://api.basespace.illumina.com/ ' api_version = ' v1pre3 # BaseSpace API对象进行初始化:bs_api = BaseSpaceAPI。新的(client_id, client_secret, basespace_url, api_version, app_session_id, access_token)

创建一个BaseSpaceAPI物体使用credentials.json.：

使用Bio::BaseSpace #初始化一个BaseSpace API对象，并在'凭证'中提供身份验证/连接细节。json': bs_api = BaseSpaceAPI.start . json

该文件credentials.json.中包含身份验证/连接详细信息杰森格式：

{"client_id": "my client id"， "client_secret": "my client secret"， "app_session_id": "my app session id"， "access_token": "my access token"， "basespace_url": "https://api.basespace.illumina.com"， "api_version": "v1pre3"}

应用触发

示例的源代码:例子/ 0 _app_triggering.rb

控件检索AppSession当用户触发Basespace应用程序时产生的对象。此外，我们介绍如何自动生成范围字符串以请求访问数据对象的访问（例如项目或样本），该应用程序被触发到分析。

从BaseSpace到我们的应用程序的初始HTTP请求由AppSession实例。使用这种情况，我们能够获取有关推出应用程序的用户的信息以及应用程序所寻求/分析的数据。

注意:创建一个BaseSpaceAPI如下所述的对象开始“第一。该实例应该由变量引用bs_api.，就像在“开始“ 部分。

#使用bs_api，我们可以请求对应于AppSession ID的AppSession对象my_app_session = bs_api。一个应用程序会话包含一个或多个AppSessionLaunchObject实例的引用，这些实例引用用户启动应用程序时使用的# data模块。这可以是一个项目列表，样例，或对象的混合物。Inspect # ' Inspect '显示对象内容

输出类似于:

App Session达到600602：Eri Kibukawa  -  ID：<我的App Session ID>  - 状态：在“引用”中可以看到应用程序的完整类型，可以在“引用”中看到：[＃“dict”，“href”=>“str”，“hrefcontent”=>“str”，“rel”=>“str”，“type”=>“str”str“}，@Attributes= {“content”=>＃“str”，“hrefsamples”=>“str”，“hrefaprefesults”=>“str”，“hrefbasespaceui“=>”str“，”dateCreated“=>”datetime“，”id“=>”str“，”href“=>”str“，”userownedby“=>”usercompact“}，@属性= {”名称“=>”ign_wgs_ceph_services_2.0“，”hrefsamples“=> nil，”hrefapreseults“=> nil，”hrefbasespaceui“=> nil，”dateCreated“=>＃，“ID”=>“267267”，“HREF”=>“V1PRE3 / Projects / 267267”，“UserownedBy”=>＃"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"}>]

我们可以向启动的用户获得句柄AppSession和进一步的信息AppSessionLaunchObject：

把my_app_session放到my_app_session中。让我们仔细看看AppSessionLaunchObject类实例:my_reference = my_app_session.references。首先把"href放到启动对象中"href_content将“该对象的类型”放入my_reference。类型了

输出类似于:

由用户创建的应用程序会话：13039：Eri Kibukawa HREF到启动对象：V1PRE3 / Projects / 848850类型的对象：项目

要开始工作，我们将想扩展触发对象的权限范围，以便我们可以读取和写入数据。此过程的详细信息是下一节的主题。本节显示如何轻松获得所谓的“范围字符串”并进行访问请求。更多背景在Basespace Developer文档中可以找到读取范围的背景读数“BaseSpace权限"．

my_reference_content = my_reference。将my_reference_content.get_access_str('write')放到my_reference_content中

输出类似于:

请求对引用对象进行写访问的范围字符串:write Project 848850

我们现在可以请求对引用对象的写入访问，以便我们的应用程序可以开始为分析提供贡献。虽然，请求访问访问权限和其他应用程序（桌面，移动，本机）之间存在区别。

以下调用请求Web应用程序的写权限:

verification_with_code_uri = bs_api。get_access(my_reference_content， 'write')将“在15秒内访问URI并授予访问权限:”放入verification_with_code_uri

输出类似于:

在15秒内访问URI并授予访问权限：https://cloud-hoth.illumina.com//oauth/authorize?authorization paramers>

以下调用请求其他应用程序(桌面、移动、本地)的写权限:

Access_map = bs_api.get_access（my_reference_content，'write'）放置“访问地图：”puts access_map

输出类似于:

访问映射:{"device_code"=>"<我的设备代码>"，"user_code"=>"<我的用户代码>"，"verification_uri"=>"https://basespace.illumina.com/oauth/device"， "verification_with_code_uri"=>"https://basespace.illumina.com/oauth/device?code=<我的用户代码>"，"expires_in"=>1800， "interval"=>1}

访问验证URI并在15秒内授予访问权限：

Puts“在15秒内访问URI并授予访问权限：”验证_with_code_uri = Access_map ['verification_with_code_uri'] puts verification_with_code_uri

输出将是:

在15秒内访问URI并授予访问权限:https://basespace.illumina.com/oauth/device?code=<我的用户代码>

在这两种情况下，可以使用以下可移植的Ruby代码在web浏览器中打开URI:

link = access_map ['verification_with_code_uri'] host = rbconfig :: config ['host_os']案例主机当/ mswin | mingw | cygwin / system（“启动＃{verifice_with_code_urode_urod_urid_urid_urid_urid_urid_urid_urige_ured）/ darwin / system（”打开＃{verifice_with_code_urei}“）当/ linux / system（”xdg-open＃{verification_with_code_uri}“）结束睡眠（15）

一旦用户授予我们对所请求对象的访问权，我们就可以获得BaseSpace访问令牌，并通过调用开始浏览update_privileges在BaseSpaceAPI实例:

bs_api.update_privileges(Code)

有关访问请求和身份验证的详细信息以及基于web的例子，请参见示例1_authentication.rb

BaseSpace身份验证

示例的源代码:例子/ 1 _authentication.rb和示例/ 2_browsing.rb.

在这里，我们演示了基本的基本存储空间身份验证过程。这里概述的工作流程是

1. 访问特定数据范围的请求
2. 用户对访问请求的批准
3. 浏览数据

如果您在启动本示例之前已经登录到BaseSpace网站，以使访问授权过程更快，那么这将非常有用。

注意:创建一个BaseSpaceAPI如下所述的对象开始“第一。该实例应该由变量引用bs_api.，就像在“开始“ 部分。

请求访问权限

首先，获取作用域“browse global”的验证码和URI:

device_info = bs_api.get_verification_code（'浏览全局'）放置“URI for用户访问和授予访问权限：”Puts Device_Info ['verification_with_code_uri']

此时，用户必须访问验证URI以授予所请求的特权。在Ruby中，可以使用以下方法启动一个指向验证URI的浏览器:

/mswin|mingw|cygwin/ system("start #{link}") when /darwin/ system("open #{link}") when /linux/ system(" xdd -open #{link}") end sleep(15)

输出将是:

用户访问和授权访问的URI: https://basespace.illumina.com/oauth/device?code=<我的代码>

一旦授予了访问权限，我们就可以获得BaseSpaceaccess_token你可以通过打电话来浏览网页update_privileges在baseSpaceApi实例上。

代码= device_info['device_code']

作为参考，可以从中获得提供的访问令牌BaseSpaceAPI对象:

把“访问令牌:# {bs_api.get_access_token}”

输出将是:

访问 - 令牌：<我的Access-token>

浏览数据

一旦获得全局浏览的访问令牌，本节将演示BaseSpace对象的基本浏览。我们将看到如何使用BaseSpaceAPI类或通过使用方法呼叫相关对象实例（例如，用户实例可用于检索属于该用户的所有项目）。

注意:创建一个BaseSpaceAPI如下所述的对象开始“第一。该实例应该由变量引用bs_api.，就像在“开始“ 部分。

首先，我们将尝试检索一个基因组对象:

my_genome = bs_api. get_gene_by_id ('4') puts "Genome: #{my_genome}" puts "Id: #{my_genome. get_genome = bs_api. get_gene_by_id ('4') puts "Genome: #{my_genome}" puts "Id: #{my_genome. my_genome "{my_genome. id}" puts "Href: #{my_genome. id}href}" puts "DisplayName: #{my_genome.display_name}"

输出将是:

基因组:智人Id: 4 Href: v1pre3/基因组/4 DisplayName:智人- UCSC (hg19)

我们可以得到所有可用基因组的列表:

all_genomes = bs_api。get_available_genomes: #{all_genomes. get_available_genomes: #{all_genomes. get_available_genomes。映射{|g| g.to_s}。加入(" ")}”

输出将是:

基因组：拟南芥，博士金牛座，大肠杆菌，母乳植物，亩肌肉，phix，乳菌斯氏菌，rattus norvegicus，酿酒瘤金黄色葡萄球菌

现在,检索用户对象，并列出此用户的所有项目:

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（'，'）}“

输出类似于:

用户——<用户id>: <用户名> project: IGN_WGS_CEPH_Services_2.0 - id=267267

我们也可以通过调用用户实例:

my_projects = user.get_projects(bs_api) puts "Projects: #{my_projects. get_projects(bs_api) "映射{|p| p.to_s}。加入(" ")}”

输出如下所示:

用户——<用户id>: <用户名> project: IGN_WGS_CEPH_Services_2.0 - id=267267

我们也可以列出一个用户的所有运行:

运行= user.get_runs(bs_api) puts "运行:#{运行。映射{|r| r.to_s}。加入(" ")}”

输出类似于:

运行命令:BaseSpaceDemo - id=2, Cancer Sequencing Demo - id=4, HiSeq 2500 - id=7, ResequencingPhixRun - id=12, TSChIP-Seq - id=14042, BCereusDemoData_Illumina - id=34061

访问和查询文件

示例的源代码:示例/ 3_accessing_files.rb.

在本节中，我们演示了如何从项目访问样本和分析以及如何处理此类实例的可用文件数据。此外，我们要查看与BAM和VCF文件相关的一些特殊Queing方法。

注意:创建一个BaseSpaceAPI如下所述的对象开始“第一。该实例应该由变量引用bs_api.，就像在“开始“ 部分。

访问文件

首先，我们得到一个我们可以使用的项目：

my_projects = bs_api.get_project_by_user('current')

现在我们可以列出这些项目的所有分析和样本：

#在这里定义'samples'变量，以便在示例中进一步重用:each do |single_project| puts "Project: #{single_project}" app_results = single_project.get_app_results(bs_api) puts " apsult实例:#{app_results. get_app_results(bs_api) puts " appsult实例:#{single_project .get_app_results(bs_api) puts " appsult实例:#{single_project .get_app_results(bs_api) puts "映射{|r| r.to_s}。加入(" ")}”samples = single_project.get_samples(bs_api) puts " Sample instances: #{samples.map { |s| s.to_s }.join(', ')}" end

输出类似于:

样本实例:BC_1、BC_2、BC_3、BC_4、BC_5、BC_6、BC_7、BC_8、BC_9、BC_10 Project: Cancer Sequencing Demo - id=4Amplicon, Amplicon样本实例:L2I项目:HiSeq 2500 - id=7 apsult实例:重测序样本实例:NA18507

我们将进一步查看属于上面循环中最后一个项目样本的文件:

样本。处理|样品|将“示例：＃{sample}”文件= sample.get_files（bs_api）puts files.map {| f |“＃{f}”}结束

输出类似于:

Bcereus_1 Bcereus-1_S1_L001_R1_001.fastq.gz - id: '14235852'， size: '179971155' Bcereus-1_S1_L001_R2_001.fastq.gz - id: '14235871'， size: '126164153' Bcereus-2_S2_L001_R1_001.fastq.gz - id: '14235872'， size: '137077949'

查询BAM和VCF文件

现在，我们来看看特定于BAM和VCF文件的一些方法调用。首先，我们获取bami -file，然后检索2号染色体在1 - 20000位置之间的覆盖信息:

#请求权限:#注意你的项目ID(这里是469469)很可能是不同的!device_info = bs_api。get_verification_code(“读469469项目”)链接= device_info(“verification_with_code_uri”)将“15秒内访问URI和授权访问:“把链接主机= RbConfig::配置(“host_os”)情况下主机当是否是/ mswin | mingw | cygwin /系统(“开始#{链接}”)当达尔文/系统(“开放#{链接}”)当/ linux /系统(“xdg-open #{链接}”)结束睡眠(15)code = device_info['device_code'] bs_api.update_privileges(code) #获取一个时间间隔+伴随的元数据:#注意你的文件ID(这里7823816)将很可能是不同的!可以使用以下方法获取文件ID: samples.first.get_files(bs_api).first。id my_bam = bs_api.get_file_by_id('7823816') puts "BAM: #{my_bam}" cov = my_bam. get_file_by_id('7823816')Get_interval_coverage (bs_api， 'chr1'， '50000'， '60000') puts " #{cov. Get_interval_coverage (bs_api， 'chr1'， '50000'， '60000')cov_meta = my_bam。Get_coverage_meta (bs_api， 'chr1') puts " #{cov_meta.to_s}"

输出类似于:

BAM: sorted_S1。Chrom chr1: 1-1792, BucketSize=2 CoverageMeta: max=1158602 gran=128

对于VCF文件，我们也可以根据染色体和位置过滤变体调用：

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 (bs_api， '1'， '20000'， '30000') #没有值。需要验证" #{var. "映射{|v| v.to_s}。加入(" ")}”

输出将是:

variantheader：samplecount = 1变量 -  chr2：10236 id = ['。']，变体 -  chr2：10249 id = ['。']

创建和上传文件

示例的源代码:4_app_result_upload.rb.

在本节中，我们将看到如何创建一个新的AppResult对象，将相关AppSession的状态更改为它，并将结果文件上传以及从中检索文件。

注意:创建一个BaseSpaceAPI如下所述的对象开始“第一。该实例应该由变量引用bs_api.，就像在“开始“ 部分。

创造一个评估者

首先，我们获得一个项目来工作。我们将需要我们正在努力的项目的写权限 - 这意味着我们需要相应地更新我们的特权：

device_info = bs_api。get_verification_code(浏览全球)链接= device_info(“verification_with_code_uri”)所说的“访问URI在15秒和授权访问:“把链接主机= RbConfig::配置(“host_os”)情况下主机当是否是/ mswin | mingw | cygwin /系统(“开始#{链接}”)当达尔文/系统(“开放#{链接}”)当/ linux /系统(“xdg-open #{链接}”)结束睡眠=(15)代码bs_api.update_privileges(code) #注意你的项目ID很可能是不同的!#你可以通过SDK或从basespace web界面获得它!#例如:my_projects.first。Id PRJ = bs_api.get_project_by_id('469469')

假设我们为该项目编写了写访问，我们将列出项目的当前分析：

app_res = prj. status = ['Running']get_app_results(bs_api， {}， status)将" apsult实例:#{app_res. get_app_results(bs_api， {}， status)映射{|r| r.to_s}。加入(" ")}”

输出类似于:

Appsetult实例：BWA GATK  -  Hiseq 2500 Na12878演示2x150，Hiseq 2500 Na12878演示2x150应用结果

创造一个AppResult对于项目，请求'创建'权限，然后只需提供名称和描述：

device_info = bs_api.get_verification_code（“创建项目＃{prj.id}”）link = device_info ['verification_with_code_uri'] puts“在15秒内访问URI并授予访问权限：”Puts Link Host = RBConfig :: config ['host_os']案例主机当/ mswin | mingw | cygwin / system（“开始＃{link}”）时/ darwin / system（“打开＃{link}”）时/ linux / system（“xdg-open＃{link}”）结束睡眠（15）代码= device_info ['device_code'] bs_api.update_privileges（代码）＃注意必须提供运行应用程序的应用程序会话ID！app_result = prj.create_app_result（bs_api，“testing”，“这是我的结果”，bs_api.app_session_id）puts“appsult ID：＃{app_result.id}”puts“appsult的appsession：＃{app_result.app_session}”

输出类似于:

Appesult ID：939946 Appsesult的AppSession：App Session达到159159：Eri Kibukawa  -  ID：  - 状态：运行

我们可以改变我们的状态AppSession并添加状态摘要，如下所示：

app_result.app_session.set_status（bs_api，'castattentent'，“我们努力工作，但遇到了一些麻烦。”）＃更新状态：Puts“appsult的appsession：＃{app_result.app_session}”＃设置返回运行：app_result.app_session。set_status（bs_api，'运行'，“回到轨道”）

输出类似于:

AppSession: App session by 159159: Eri Kibukawa - Id: < App session Id > - status: NeedsAttention

上传文件

控件附加一个文件到AppResult对象并上传它：

app_result。upload_file(bs_api， '/tmp/testFile.txt'， 'BaseSpaceTestFile.txt'， '/mydir/'， 'text/plain') #让我们看看我们的新文件是否已经进入云:映射{|f| f.to_s}。加入(" ")}”

输出将是:

文件:BaseSpaceTestFile.txt - id: '7819953'， size: '5'

当然，我们也可以下载我们新上传的文件:

F = bs_api.get_file_by_id(app_result_files.last.id)

食谱的用法食谱

本节包含有用的代码片段，它们演示了应用程序开发中的常见用例。

使用查询参数字典过滤文件-列表和appult -列表

给定示例“a_sample”我们可以使用查询参数字典检索完整文件列表的子集：

注意:创建一个BaseSpaceAPI如下所述的对象开始“第一。该实例应该由变量引用bs_api.，就像在“开始“ 部分。

使用如上所示创建的BaseSpace API对象，检索我们的项目列表，选择第一个可用的项目，获取它的样本，然后将第一个样本#赋值给变量' a_sample '。My_projects = bs_api.get_project_by_user('current')首先my_samples = a_project.get_samples(bs_api) #从项目的角度获取一个简短的示例表示:第一个#通过直接获得完整版BaseSpace API调用(演示,下面不需要):full_sample = bs_api.get_sample_by_id (a_sample.id) #有关联的文件列表示例:#可能的输出:[" s_G1_L001_I1_001.fastq.1.gz - id:“535642”,大小:7493990”,“s_G1_L001_I1_002.fastq.1.gz - id:“535643”,大小:“7525743”]a_sample.get_files (bs_api)。地图{|文件|文件。to_s} #获取“.gz”文件列表:get_files(bs_api， {'Extensions' => 'gz'}) #获取一个包含多个扩展过滤器的列表(". get_files(bs_api， {'Extensions' => 'gz'})。bam”和“。vcf”文件):a_sample。get_files(bs_api， {'Extensions' => 'bam,vcf'})

你可以在这个字典中提供所有其他合法的排序/过滤关键字来进一步细化列表:

a_sample。get_files (bs_api{“扩展”= >“bam, vcf”、“SortBy”= >“路径”,“限制”= > 1})

您可以在检索应用程序结果时提供查询参数的字典，以相同的方式过滤文件列表。下面是如何将默认值为“限制”）到10中的100（默认值为“）到10的示例。

结果= a_project.get_app_results（bs_api）＃可能输出：100个结果.Length＃将返回的结果列表限制为10项。＃新的`结果：10结果= a_project.get_app_results（bs_api，{'limit'=>'10'}）结果.Length

特性请求和Bug报告

请将任何关于BaseSpace Ruby SDK的反馈直接报告给GitHub库．我们欣赏任何关于SDK的所有反馈，我们都会做任何我们可以提高SDK的功能和质量，使其成为开发人员使用的最佳SDK。

SDK开发手册

本节重点介绍BaseSpace Ruby SDK gem的开发方面。它还提供了关于如何构建SDK的预发布版本的信息，但除非你确实打算贡献SDK源代码或文档，我们强烈建议遵循官方发布安装说明下的“供应和安装"．

构建一个新版本的宝石

Bundle exec rake gemspec Bundle exec gem build bio-basespace。Gemspec sudo gem安装bio-basespace

单元测试

首先，如上所述安装宝石。然后使用rspec.用于单位测试：

Rspec -c -f

移植

BaseSpace Ruby SDK最初通过将Basespace Python SDK转换为Ruby而移植。如果有必要从Python SDK端口进一步的代码，则应观察到以下移植指南：

• 缩进：Python 4空格，Ruby 2空格
• 多龙字：Pythonexamplabel.，红宝石example_label
• 构造函数：Python.def __init __（self）：，红宝石def初始化
• Python类变量:自我。swaggerTypes = {"Key":"value"}，红宝石@swagger_types = {“key”=>“值”}
• 孔隙类型:Python没有任何，红宝石零
• Python字符串表示:__str __（self），红宝石to_s (@val.to_s)返回
• 对象转储：Python__repr__(自我)，红宝石to_str(返回self.inspect)或self.attributes.inspect对属性值
• 例外：python.foob​​arexception.->foob​​arerror.
• 类型:
  • Pythonstr，红宝石字符串
  • Pythonint，红宝石整数
  • Python漂浮，红宝石浮动
  • PythonBOOL.，红宝石真正的/错误的
  • Python列表<>，红宝石数组
  • Pythond，红宝石哈希
  • Python文件，红宝石文件

作者和贡献者

作者

Joachim Baran, Raoul Bonnal, Eri Kibukawa, Francesco Strozzi, Toshiaki Katayama

贡献者

按字母顺序(姓):

• 约阿希姆Baran
• 拉尔博恩
• Naohisa Goto.
• Toshiaki片
• 伊西·斯波瓦
• Francesco Strozzi.

复制和许可

看到License.txt有关授权及发行的详情。