BIOMfrom: Convert BIOM data from formal to basic type (export)

Description Usage Arguments Details Value Author(s) References See Also Examples

Description

Convert an object of class biom into a basic type: matrix, list, or character.

Usage

1
2
3
4
5
6
7
8
## S3 method for class 'biom'
as.matrix(x, expand=NULL, ...)

## S3 method for class 'biom'
as.list(x, ...)

## S3 method for class 'biom'
as.character(x, ..., file=NULL)

Arguments

x

an object (biom)

expand

if sparse, force return of not sparse matrix? (logical)

...

unused

file

filename for writing object

Details

BIOM (Biological Observation Matrix) is a simple prescription for storing an annotated table of data. It may be described as a format, standard, or data structure.

The JSON (JavaScript Object Notation) standard for expressing general data objects as text is employed to define BIOM. Therefore the native form of BIOM data is structured text, conforming to the JSON specification in general and the BIOM specification in particular. Familiarity with BIOM is assumed here.

The S3 class biom and its methods facilitate analyses by expressing BIOM data as objects in the R environment. Each function above transforms an object that is already of class biom into a basic R type.

as.matrix() returns the BIOM data table as a matrix. If the object is "dense", then dimnames() of the result are equal to the BIOM row and column ids. Otherwise, the three-column sparse representation matrix is returned, with ids given by attached attributes "rownames" and "colnames".

However, using expand=TRUE expands a sparse representation. (Setting expand=FALSE has no effect when the object is "dense".) Also, see below for an example using class "sparseMatrix" from the R package Matrix.

as.character() returns BIOM properly speaking, that is, data and annotations written in JSON text conforming to the BIOM specification. That text is written to file, if provided.

See below for an example of saving the data table, only, in CSV or TSV format. Of course, it is possible to bring biom objects in and out of the session with save() and load().

as.list() returns a list corresponding closely element-by-element to BIOM. The differences are: list element data is a matrix not list; elements rows and columns hold metadata only, and so do not include ids; instead, additional elements row.ids and column.ids are present; and format_url is missing.

Value

For as.matrix() and as.list(), as described.

For as.character(), a single string of JSON text, or simply file if it is not NULL.

Except that last case, these functions return invisibly.

Author(s)

Daniel T. Braithwaite

References

BIOM format
JSON

See Also

biom

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
tt <- tempfile()
xx <- biom (li3)
yy <- biom (smat, sparse=TRUE, quiet=TRUE)

##  extract objects of basic types:
print (as.matrix (xx))
head (as.matrix (yy, expand=TRUE))
as.character (xx)
as.character (xx, file=tt)
str (as.list (xx))

##  export to a CSV file:
write.table (as.matrix (xx), file=tt, sep=",")

## Not run: 
##  a classed sparse matrix (for computation or what have you):
zz <- as.matrix (yy)
zz[,1:2] <- 1 + zz[,1:2]
Matrix::sparseMatrix (i=zz[,1], j=zz[,2], x=zz[,3])

## End(Not run)

unlink(tt)

Example output

BIOM.utils (0.9 dbcb27)
    AAA BBB CCC DDD EEE
aaa 101 121 141 161 181
bbb 102 122 142 162 182
ccc 103 123 143 163 183
ddd 104 124 144 164 184
eee 105 125 145 165 185
fff 106 126 146 166 186
ggg 107 127 147 167 187
hhh 108 128 148 168 188
iii 109 129 149 169 189
jjj 110 130 150 170 190
kkk 111 131 151 171 191
lll 112 132 152 172 192
mmm 113 133 153 173 193
nnn 114 134 154 174 194
ooo 115 135 155 175 195
ppp 116 136 156 176 196
qqq 117 137 157 177 197
rrr 118 138 158 178 198
sss 119 139 159 179 199
ttt 120 140 160 180 200
     column1 column2 column3 column4
row1      63     140      27      11
row2      11      37       0      75
row3     160    1025     151    2172
row4       0       0       4       0
row5       0      67       6       0
row6       0      38      13       0
[1] "{\n \"id\": \"\",\n\"format\": \"Biological Observation Matrix 1.0\",\n\"type\": \"OTU table\",\n\"generated_by\": \"BIOM.utils (0.9)\",\n\"date\": \"2017-12-14 17:01:08\",\n\"rows\": [\n {\n \"id\": \"aaa\",\n\"metadata\": \"metadata of aaa\" \n},\n{\n \"id\": \"bbb\",\n\"metadata\": \"metadata of bbb\" \n},\n{\n \"id\": \"ccc\",\n\"metadata\": \"metadata of ccc\" \n},\n{\n \"id\": \"ddd\",\n\"metadata\": \"metadata of ddd\" \n},\n{\n \"id\": \"eee\",\n\"metadata\": \"metadata of eee\" \n},\n{\n \"id\": \"fff\",\n\"metadata\": \"metadata of fff\" \n},\n{\n \"id\": \"ggg\",\n\"metadata\": \"metadata of ggg\" \n},\n{\n \"id\": \"hhh\",\n\"metadata\": \"metadata of hhh\" \n},\n{\n \"id\": \"iii\",\n\"metadata\": \"metadata of iii\" \n},\n{\n \"id\": \"jjj\",\n\"metadata\": \"metadata of jjj\" \n},\n{\n \"id\": \"kkk\",\n\"metadata\": \"metadata of kkk\" \n},\n{\n \"id\": \"lll\",\n\"metadata\": \"metadata of lll\" \n},\n{\n \"id\": \"mmm\",\n\"metadata\": \"metadata of mmm\" \n},\n{\n \"id\": \"nnn\",\n\"metadata\": \"metadata of nnn\" \n},\n{\n \"id\": \"ooo\",\n\"metadata\": \"metadata of ooo\" \n},\n{\n \"id\": \"ppp\",\n\"metadata\": \"metadata of ppp\" \n},\n{\n \"id\": \"qqq\",\n\"metadata\": \"metadata of qqq\" \n},\n{\n \"id\": \"rrr\",\n\"metadata\": \"metadata of rrr\" \n},\n{\n \"id\": \"sss\",\n\"metadata\": \"metadata of sss\" \n},\n{\n \"id\": \"ttt\",\n\"metadata\": \"metadata of ttt\" \n} \n],\n\"columns\": [\n {\n \"id\": \"AAA\",\n\"metadata\": \"metadata of AAA\" \n},\n{\n \"id\": \"BBB\",\n\"metadata\": \"metadata of BBB\" \n},\n{\n \"id\": \"CCC\",\n\"metadata\": \"metadata of CCC\" \n},\n{\n \"id\": \"DDD\",\n\"metadata\": \"metadata of DDD\" \n},\n{\n \"id\": \"EEE\",\n\"metadata\": \"metadata of EEE\" \n} \n],\n\"matrix_type\": \"dense\",\n\"matrix_element_type\": \"int\",\n\"shape\": [ 20, 5 ],\n\"data\": [\n [ 101, 121, 141, 161, 181 ],\n[ 102, 122, 142, 162, 182 ],\n[ 103, 123, 143, 163, 183 ],\n[ 104, 124, 144, 164, 184 ],\n[ 105, 125, 145, 165, 185 ],\n[ 106, 126, 146, 166, 186 ],\n[ 107, 127, 147, 167, 187 ],\n[ 108, 128, 148, 168, 188 ],\n[ 109, 129, 149, 169, 189 ],\n[ 110, 130, 150, 170, 190 ],\n[ 111, 131, 151, 171, 191 ],\n[ 112, 132, 152, 172, 192 ],\n[ 113, 133, 153, 173, 193 ],\n[ 114, 134, 154, 174, 194 ],\n[ 115, 135, 155, 175, 195 ],\n[ 116, 136, 156, 176, 196 ],\n[ 117, 137, 157, 177, 197 ],\n[ 118, 138, 158, 178, 198 ],\n[ 119, 139, 159, 179, 199 ],\n[ 120, 140, 160, 180, 200 ] \n],\n\"format_url\": {\n \"Biological Observation Matrix 1.0\": \"http://biom-format.org/documentation/format_versions/biom-1.0.html\" \n} \n}"
[1] "/work/tmp/tmp/RtmpCft7t2/filee0220dec3d4"
List of 14
 $ id                 : chr ""
 $ format             : chr "Biological Observation Matrix 1.0"
 $ type               : chr "OTU table"
 $ generated_by       : chr "BIOM.utils (0.9)"
 $ date               : chr "2017-12-14 17:01:08"
 $ rows               :List of 20
  ..$ : chr "metadata of aaa"
  ..$ : chr "metadata of bbb"
  ..$ : chr "metadata of ccc"
  ..$ : chr "metadata of ddd"
  ..$ : chr "metadata of eee"
  ..$ : chr "metadata of fff"
  ..$ : chr "metadata of ggg"
  ..$ : chr "metadata of hhh"
  ..$ : chr "metadata of iii"
  ..$ : chr "metadata of jjj"
  ..$ : chr "metadata of kkk"
  ..$ : chr "metadata of lll"
  ..$ : chr "metadata of mmm"
  ..$ : chr "metadata of nnn"
  ..$ : chr "metadata of ooo"
  ..$ : chr "metadata of ppp"
  ..$ : chr "metadata of qqq"
  ..$ : chr "metadata of rrr"
  ..$ : chr "metadata of sss"
  ..$ : chr "metadata of ttt"
 $ columns            :List of 5
  ..$ : chr "metadata of AAA"
  ..$ : chr "metadata of BBB"
  ..$ : chr "metadata of CCC"
  ..$ : chr "metadata of DDD"
  ..$ : chr "metadata of EEE"
 $ row.ids            : chr [1:20] "aaa" "bbb" "ccc" "ddd" ...
 $ column.ids         : chr [1:5] "AAA" "BBB" "CCC" "DDD" ...
 $ matrix_type        : chr "dense"
 $ matrix_element_type: chr "int"
 $ shape              : int [1:2] 20 5
 $ data               : int [1:20, 1:5] 101 102 103 104 105 106 107 108 109 110 ...
  ..- attr(*, "dimnames")=List of 2
  .. ..$ : chr [1:20] "aaa" "bbb" "ccc" "ddd" ...
  .. ..$ : chr [1:5] "AAA" "BBB" "CCC" "DDD" ...
 $ comment            : NULL
266 x 4 sparse Matrix of class "dgCMatrix"
                                
  [1,]    63    140    27     11
  [2,]    11     37     .     75
  [3,]   160   1025   151   2172
  [4,]     .      .     4      .
  [5,]     .     67     6      .
  [6,]     .     38    13      .
  [7,]   158     26    55    113
  [8,] 15561   3511  4139  14627
  [9,]   260    631   247    694
 [10,]   109    401   124     95
 [11,]   411    880   174    144
 [12,]    37    255    28      5
 [13,]    31    111    18    168
 [14,]   122    469    71     32
 [15,]     .      .    12      1
 [16,]     .      3     .      .
 [17,]     .      2     2      .
 [18,]     7    127    24    153
 [19,]     .      2     1      5
 [20,]     4      8     7      .
 [21,]   764   3647   909   3559
 [22,]  2256  11759  3915  27659
 [23,]     2     20     .     10
 [24,]     .     11     7      .
 [25,]     .     51     3      .
 [26,]   886    119   230    755
 [27,]   856    443   402   7924
 [28,]     8     52    15     11
 [29,]   122      .     .      .
 [30,]    30    236    48    295
 [31,]    61    236   101     47
 [32,]     .     15     .      .
 [33,]   496     58   209    268
 [34,]    59    106    34     53
 [35,]  1696   4431   881    195
 [36,]   800   2230  1407   2798
 [37,]  1296   1075   836     94
 [38,]  1325   2761  1422   1066
 [39,]   143     33    62    110
 [40,]    15     67    25      5
 [41,]     .      .     1      .
 [42,]   971    103   237    712
 [43,]     .      1     .      .
 [44,]     .      5     5      5
 [45,]    44    337   101    237
 [46,]    30    101    16    164
 [47,]   110    287    27      .
 [48,]     .      .     .     25
 [49,]     .      .     1      .
 [50,]  1320   6762  1628   8768
 [51,]   302   1037   303   1405
 [52,]     .     52     6    111
 [53,]     .     99    17    256
 [54,]     6     59    28      .
 [55,]  1019   1933   364    110
 [56,]     .      .    20      .
 [57,]   244    522   201   4970
 [58,]  2092   2551  8512   2179
 [59,]    29     16    14      9
 [60,]     .     14    13      .
 [61,]     .      .     .      1
 [62,]    30     95    29      .
 [63,]     .      5     .      .
 [64,]    34    752   285    152
 [65,]     .      6     3    102
 [66,]     2     25    17    111
 [67,]     .     43    19     38
 [68,]   432     67   155    314
 [69,]   443     62   185    292
 [70,]     .     34     6     44
 [71,]     .     45    25     28
 [72,]     .     24     2      .
 [73,]     .     45     5      .
 [74,]     .     35     .      .
 [75,]    43    249    75    125
 [76,]     4     10     1      5
 [77,]     6     51     .     45
 [78,]    18     50    13     87
 [79,]     .      .     .      2
 [80,]     .      .     1      .
 [81,]   105    276    60      7
 [82,]     .     41    25      .
 [83,]     4     40     .     27
 [84,]  2530   7101  1832    713
 [85,]   661   1823   662   1071
 [86,]     .      1     1      1
 [87,]     .      3     .      .
 [88,]   103      .     .      .
 [89,]   154    711   169   1041
 [90,]     7      5     5      .
 [91,]     .      5     .      .
 [92,]   296   2559   619   3118
 [93,]     .     45     .      .
 [94,]     .     25     .      .
 [95,]     .     80     .      .
 [96,]     .    199    22      .
 [97,]  5064  20121 10158   2157
 [98,]    20     89    12     29
 [99,]   586     71   116    160
[100,]     .      .     4      .
[101,]  3489  29862  2629   7688
[102,]    56    171    49     19
[103,]     .     27     .     24
[104,]    28    354    74    449
[105,]   162     21    51    120
[106,]    90     17     .      .
[107,]    99     49    85     79
[108,]     .    236    30      .
[109,]    17    124    40    177
[110,]     .      3     3      9
[111,]     5     58     .      .
[112,]    62    203    37      .
[113,]    20     44     .      .
[114,]   105    336   173    289
[115,]    79    246    97    554
[116,]     1      .     4      .
[117,]     .     49     .      .
[118,]     .      2     .      .
[119,]     2      .     .      .
[120,]     .     16     1      .
[121,]    69    133    43     23
[122,]     3     82    17     72
[123,]     .     14     4     19
[124,]     7     34     9      .
[125,]    37    141    37      .
[126,]   418     61   160    266
[127,]     .     33     .      .
[128,]   483     89   140    386
[129,]   724     71   193    447
[130,]     .     21     .      .
[131,]  1004   3492   913   4543
[132,]   630   1870   600   2263
[133,]     .      3     .      .
[134,]    20    112    19     19
[135,]     3     21    11      .
[136,]    54      .     .      .
[137,]    24     34    23     38
[138,]   628   9095  1575   2738
[139,]    84    152    69    148
[140,]   228    708   278    478
[141,]     .      .     3      .
[142,]     .      3     .      .
[143,]     .     30     8      .
[144,]     8     80     4    102
[145,]     3     30     .     56
[146,]     2     68     5     41
[147,]     .      .     5      .
[148,]     .     20     8      .
[149,]     4     19     .      .
[150,]    23     57    24      .
[151,]     .     18     3      .
[152,]     7    101     5      .
[153,]    58    184    14      .
[154,]     .      .     3      .
[155,]   134    357    96      8
[156,]     .      .     2      .
[157,]   841    103   336    574
[158,] 15166   1081  9530   2880
[159,]   507     60   208    312
[160,]   361  17893   484    154
[161,]    11     34    10      .
[162,]   993    257   520    715
[163,]    17     75    11     87
[164,]    16    687    28      6
[165,]     .    106    10     32
[166,]   216    117    72    133
[167,]     .      .     3      .
[168,]     .      .     8    108
[169,]     4     14     8     47
[170,]     6     15     .      .
[171,]  6401 137578 45957    426
[172,]   138    382    80     28
[173,]     .     26     8     20
[174,]   727    210   479    514
[175,]   622    121   259    536
[176,]   392     89   129    267
[177,]     .     95    12     41
[178,]    24    324    58      .
[179,]     .     43    28      .
[180,]   260    645   128     19
[181,]   226    660   176    861
[182,]     7     11     2      .
[183,]     .      .     5      .
[184,] 36753  81112 22611    694
[185,]    22     47     .     89
[186,]   184   1007   257   2212
[187,]   371   1910   427   1954
[188,]     .      .     2      .
[189,]    25     94    28     31
[190,]     .      .     .      3
[191,]     .     20     5      .
[192,]    34    128    13      .
[193,]     5     83    10     48
[194,]     .      5     .      .
[195,]     .     20   117    338
[196,]    32      .     .      .
[197,]   869   9181  1891   6238
[198,]  2879   9543  6488 172123
[199,]     2     12     3     19
[200,]   685     93   227    614
[201,]  1426    158   397   1032
[202,]     .      .     1      .
[203,]    55    138    39      4
[204,]   818   2372   414     76
[205,]   497    137   341    417
[206,]    31    125    27      .
[207,]     3     20     6      .
[208,]     .      .     1      .
[209,]     .     41    13      .
[210,]   128    147    42     70
[211,]   210    380   101    105
[212,]   287    729   131      .
[213,]   122    122    50      .
[214,]    29      .     .      .
[215,]     .     13     .      .
[216,]    27    197    52    157
[217,]    15     21     .      .
[218,]   167   1152   304   1926
[219,]     .      .     1     28
[220,]   810    117   273    711
[221,]     .      .     2      .
[222,]     .      2     .      .
[223,]     .      .     4      .
[224,]     .     17    24     31
[225,]   232   1006   222     76
[226,]    74    158    27    263
[227,]     .     19    10      .
[228,]   223    883   267    533
[229,]    52     87    25     36
[230,]   340    613   488   2536
[231,]   182    849   272    521
[232,] 53726  55537 44625  29182
[233,]  2167    369   753   1293
[234,]   206     48    75      .
[235,]    62      2     .      .
[236,]     .      .     1      .
[237,]    55    226    69    384
[238,]     .     32    14     67
[239,]     .     66    17      .
[240,]    18    249    70    321
[241,]     .      2     .      .
[242,]     .      2     .      .
[243,]     3     34     .     44
[244,]   155    830   173   1628
[245,]    36    466    70    589
[246,]     .     17     4     33
[247,]     .     16     .      .
[248,]     .      9    11      .
[249,]   167     26    62    105
[250,]     .      .     .      4
[251,]     .      .     2      .
[252,]     1     81    33     92
[253,]   107     46     3      .
[254,]     .      9     2      .
[255,]     .     16     .      .
[256,]     .     22     .      .
[257,]     .      1     4      .
[258,]   136     23    69     70
[259,]  5095  44147  7578  70276
[260,]     .      .    11      .
[261,]     .     82     .    117
[262,]   647   2017   382    166
[263,]     6     20     .      .
[264,]     .      6     .      .
[265,]     5    174    33      .
[266,]   311    543   115     44

BIOM.utils documentation built on May 1, 2019, 7:32 p.m.