内容

1介绍

目前DelayedArray框架支持少量的磁盘上的后端:HDF5(通过HDF5Array包),GDS(通过GDSArray包),VCF(通过VCFArray包)。这可以扩展为支持其他磁盘上的后端。从理论上讲,它应该可以实现DelayedArray端对任何文件格式,有能力与快速随机存取存储数组数据。

假设广告格式(数组数据存储)是这样的格式(这是一个虚构的格式为目的的这个描述)。实现DelayedArray后台广告文件一般应在专用包(说ADSArray),将取决于DelayedArray包中。

的ADSArray包将需要实现:

本文档的其余部分涵盖了上述主题更多的细节。熟悉写作R包。不犹豫地看看的来源HDF5Array包的一个真实的例子DelayedArray磁盘后端实现。

2实现种子类

2.1类定义

“种子对象”至少可以存储文件或URL的路径。如果文件格式允许存储多个数组每个文件,然后种子对象还应该存储任何额外的信息需要定位一个特定的文件中的数组。

种子类的定义是这样的:

setClass (“ADSArraySeed”=“数组”,包含槽= c (filepath =“字符”,……额外的插槽需要……定位文件中的数组…))

的filepath槽应该是一个字符串,其中包含广告文件的绝对路径的对象不打破当用户更改工作目录(例如setwd ())。

注意,存储一个开放的连接文件应该避免因为连接不正常工作在叉子的背景下(例如并行处理种子对象时)和倾向于打破当序列化对象。

2.2构造函数

强烈建议提供“种子构造函数”例如:

ADSArraySeed < -函数(filepath,其他args){健康检查……filepath < - file_path_as_absolute (filepath)…新(“ADSArraySeed filepath = filepath,其他参数)}

请注意,file_path_as_absolute ()被定义的工具包,所以需要进口通过添加以下文件的名称空间ADSArray包:

file_path_as_absolute importFrom(工具)

和添加工具到进口字段的描述文件包。

2.3种子的合同

种子对象预计将遵守“种子合同”即以支持昏暗的(),dimnames (),extract_array ()。这通常是通过实施这些泛型方法,但是,正如我们将在下面看到,显式地定义昏暗的()或dimnames ()很少需要方法。

2.3.1昏暗的()和dimnames ()

例如,昏暗的()方法ADSArraySeed对象可以是这个样子:

# # #一个实现,从文件提取尺寸# # #每次调用方法。setMethod(“暗”、“ADSArraySeed”功能(x){-打开连接文件。退出(关闭连接)提取整数向量的维度和归还})

注意,上面的昏暗的()方法咨询文件每次叫广告。然而,这可以避免通过添加昏暗的(和dimnames)槽(类型的整数为昏暗的类型的,列表为dimnamesADSArraySeed类),在施工时填充它,所以这些信息从文件中检索一次。使用这种方法昏暗的()和dimnames ()工作的开箱即用ADSArraySeed对象即没有需要定义昏暗的()和dimnames ()这些对象的方法。这是因为昏暗的()和dimnames ()原始的函数在基地R返回这些插槽的内容如果存在。

如果广告格式不允许dimnames存储,然后不需要实现dimnames ()方法或添加dimnames ()槽ADSArraySeed类。调用dimnames (x)然后就会返回零对于任何ADSArraySeed对象x。

如果广告格式允许dimnames存储,确保dimnames ()总是返回他们标准形式,即:

  • dimnames必须作为一个返回零(如果数据集没有dimnames)或作为一个普通的列表和一个元素每个维度的数据集。

  • 返回列表的每个元素零或者一个特征向量长度的数据集的扩展以及相应的维度。这是特别重要的,以确保返回的列表中的向量dimnames ()是特征向量。等其他类型因素或整数向量是不允许的将打破下游代码。

2.3.2extract_array ()

extract_array ()是一个通用的函数中定义的DelayedArray包:

库(DelayedArray) ? extract_array

它需要两个参数:x和指数。x是种子对象提取数组值。指数必须是一个不愿透露姓名的正整数向量的下标列表,每个种子一个向量维度。空和失踪下标(为代表整数(0)和零列表元素,分别)是允许的。下标的指数可以包含重复的指标。他们不能包含NAs或非容积值。

的extract_array ()方法必须返回一个普通数组适当的类型(即。整数,双等…)。例如,如果x是一个ADSArraySeed对象代表一个M x N磁盘上的复数矩阵,extract_array (x,列表(NULL, 2 l))必须返回它的第二列一个M x 1普通的矩阵类型的复杂的。

请注意,extract_array ()方法需要支持空和失踪下标。extract_array (x,列表(NULL,整数(0)))必须返回一个M x的矩阵类型的吗复杂的和extract_array (x,列表(整数(0),整数(0)))0 x 0类型的矩阵复杂的。情况下是很重要的,因为最后一个优势类型()和显示()方法DelayedArray对象依赖它。更准确地说,一旦extract_array ()方法支持一个指数用空整数向量,以下工作:

种子< - ADSArraySeed (…)M < - DelayedArray(种子)类型(M)显示(M)

最后注意,下标可以包含重复的指标等extract_array(种子、列表(c (1:3, 3:1), 2 l))需要支持。

2.4进口什么?

确保文件的名称空间ADSArray包包含至少以下进口:

导入(方法)importFrom(工具、file_path_as_absolute)进口(BiocGenerics)进口(S4Vectors)进口(IRanges)进口(DelayedArray)

除非你有一个充分的理由,不要试图有选择性地导入的方法,BiocGenerics,S4Vectors,IRanges,DelayedArray包。这只会使维护变得复杂ADSArray包从长远来看并没有真正的好处(与流行的看法相反)。

添加方法,BiocGenerics,DelayedArray到取决于包的描述文件,和工具,S4Vectors,IRanges对其进口字段。

2.5测试

确保出口ADSArraySeed类,它的构造函数,昏暗的,dimnames,extract_array方法。

至此,您应该能够将一个ADSArraySeed对象种子在DelayedArray对象DelayedArray(种子),这应该返回一个功能齐全的DelayedArray对象。

3实现高层类ADSArray和ADSMatrix

这些类并不需要严格但是添加一个好的便利。

3.1ADSArray类定义

ADSArray或ADSMatrix对象是一个DelayedArray导数,还不带延迟操作。一旦用户将开始操作,它将DelayedArray退化实例。

ADSArray和ADSMatrix类应该扩展DelayedArray DelayedMatrix类,分别,没有添加任何插槽。

所以只要:

setClass (“ADSArray”,包含=“DelayedArray”,表示(种子=“ADSArraySeed”))

稍后我们将定义ADSMatrix类。

3.2ADSArray()构造函数

添加一个DelayedArray ()方法ADSArraySeed对象:

setMethod (“DelayedArray”、“ADSArraySeed”功能(种子)new_DelayedArray(种子、类=“ADSArray”))

现在你应该能够构建一个ADSArray对象:

DelayedArray (ADSArraySeed (…))

的ADSArray构造函数应该这样做:

ADSArray < -函数(filepath,其他args) DelayedArray (ADSArraySeed (filepath,其他args))

然而,它也很高兴能够通过这个构造函数(ADSArraySeed对象ADSArray(种子))。这可以很容易地支持类似:

# # #工作直接在一个ADSArraySeed对象,在这种情况下,它肯定是# # #称为一个参数。ADSArray < -函数(filepath,其他args){如果((filepath“ADSArraySeed”)){如果!(失踪(其他__arg1)失踪(其他最长)& & & &……))停止(wmsg (“ADSArray()必须与一个参数”,“当通过了ADSArraySeed对象”))其他种子< - filepath}{种子< - ADSArraySeed (filepath,其他参数)}DelayedArray(种子)}

3.3ADSMatrix类定义

setClass (“ADSMatrix”,包含= c (“ADSArray”、“DelayedMatrix”))

3.4从ADSArray ADSMatrix

定义一个matrixClass ()ADSArray对象作为方法:

setMethod (“matrixClass”、“ADSArray”功能(x)“ADSMatrix”)

matrixClass ()是一个通用的函数中定义的DelayedArray包中。通过一个ADSArraySeed对象时,低级构造函数new_DelayedArray(见下文)通常会返回一个ADSArray实例,除非ADSArraySeed对象是二维的,在这种情况下,它需要返回一个ADSMatrix实例。它将获取返回的对象的类的名称(“ADSMatrix”在这种情况下)通过调用matrixClass。

还强迫从ADSArray ADSMatrix需要支持:

刚毛(“ADSArray”、“ADSMatrix”功能(从)新(从)“ADSMatrix”)

这种强制将确保最终用户得到以下错误当试图强迫一个不二维ADSMatrix ADSArray对象:

(x, ADSMatrix) # validObject误差(.Object):无效类“ADSMatrix”对象:#“x”必须完全二维

没有上面的强制方法,为(x,“ADSMatrix”)会默默地返回无效ADSMatrix对象。

3.5从ADSMatrix ADSArray

用户不应该能够降低ADSMatrix对象ADSArray对象(x,“ADSArray”,严格= TRUE)失败或应该无为法当吗x是一个ADSMatrix对象。最简单的(推荐),实现这一目标的方法是定义以下胁迫方法:

刚毛(“ADSMatrix”、“ADSArray”功能(从))#空操作

3.6实现优化后端特定方法

有可能,enouraged覆盖当前DelayedArray block-processed操作(如马克斯,colSums,% * %用优化后端特定方法等…)。例如,假设广告文件有能力来存储一些预先计算的数据集。然后我们可以定义一个快max ()用类似方法ADSArray对象:

setMethod (“max”、“ADSArraySeed”功能(x, na.rm = FALSE){得到文件的预先计算的最大})setMethod (“max”、“ADSArray”,函数(x, na.rm = FALSE)马克斯(x@seed na.rm = na.rm))

注意,延迟操作,比如设置dimnames ADSArray对象(< - new_dimnames dimnames(一个)()或更换一个ADSMatrix对象M2 < - t (M))将降低DelayedArray或DelayedMatrix对象实例,导致max ()和马克斯(M2)使用高效block-processed少得多max ()方法为DelayedArray定义对象。这里显然是改进的空间和工作将在不久的将来完成进行max ()DelayedArray对象的方法(和其他block-processed方法)试图利用后端特定方法时。

然而与此同时,后端覆盖作者应该抵制诱惑dimnames < - ()和t ()DelayedArray对象方法与特定后台修改种子的方法。这将是一个违反了“从未接触种子”原则是DelayedArray框架的核心。更准确地说,不管什么延迟操作上执行一个DelayedArray对象,结果应该是相同的种子最初的种子(如。种子(t (M))应该是相同的吗种子(M))。

3.7出口什么?

确保出口ADSArray和ADSMatrix类ADSArray构造函数,强迫方法和任何后端特定方法。

4测试

安装ADSArray包装和加载新的R会话:

库(ADSArray)……很快……