A reference class for storing and accessing matrix-like data stored in files on disk. This is very similar to Filebacked Big Matrices provided by the bigmemory package (see the corresponding vignette).
Convert a matrix (or a data frame) to an FBM.
FBM( nrow, ncol, type = c("double", "float", "integer", "unsigned short", "unsigned char", "raw"), init = NULL, backingfile = tempfile(), create_bk = TRUE, is_read_only = FALSE ) as_FBM( x, type = c("double", "float", "integer", "unsigned short", "unsigned char", "raw"), backingfile = tempfile(), is_read_only = FALSE )
| nrow | Number of rows. |
|---|---|
| ncol | Number of columns. |
| type | Type of the Filebacked Big Matrix (default is
|
| init | Either a single value (e.g. |
| backingfile | Path to the file storing the Big Matrix on disk. An extension ".bk" will be automatically added. Default stores in the temporary directory. |
| create_bk | Whether to create a backingfile (the default) or use an
existing one (which should be named by the |
| is_read_only | Whether the FBM is read-only? Default is |
| x | A matrix or an data frame (2-dimensional data). |
An object of class FBM has many fields:
$address: address of the external pointer containing the underlying
C++ object for read-only mapping, to be used as a XPtr<FBM> in C++ code
$extptr: (internal) use $address instead
$address_rw: address of the external pointer containing the underlying
C++ object for read/write mapping, to be used as a XPtr<FBM_RW> in C++ code
$extptr_rw: (internal) use $address_rw instead
$nrow: number of rows
$ncol: number of columns
$type: (internal) use type_size or type_chr instead
$type_chr: FBM type as character, e.g. "double"
$type_size: size of FBM type in bytes (e.g. "double" is 8 and "float" is 4)
$backingfile or $bk: File with extension 'bk' that stores the numeric
data of the FBM
$rds: 'rds' file (that may not exist) corresponding to the 'bk' file
$is_saved: whether this object is stored in $rds?
$is_read_only: whether it is (not) allowed to modify data?
And some methods:
$save(): Save the FBM object in $rds. Returns the FBM.
add_columns(<ncol_add>): Add some columns to the FBM by appending the
backingfile with some data. Returns the FBM invisibly.
$bm(): Get this object as a filebacked.big.matrix
to be used by package bigmemory.
$bm.desc(): Get this object as a filebacked.big.matrix descriptor
to be used by package bigmemory.
$check_write_permissions(): Error if the FBM is read-only.
mat <- matrix(1:4, 2) X_from_mat <- as_FBM(mat) ## You can save this object in an .rds file to use it in another session X_from_mat$is_saved#> [1] FALSEX_from_mat$save()#> A Filebacked Big Matrix of type 'double' with 2 rows and 2 columns.X_from_mat$is_saved#> [1] TRUE(rds <- X_from_mat$rds)#> [1] "C:\\Users\\au639593\\AppData\\Local\\Temp\\RtmpgxcoNx\\file430054e43468.rds"## Use big_attach() to load the FBM object in another session X_from_mat <- big_attach(rds) ## Standard accessors X <- FBM(10, 10) typeof(X)#> [1] "double"#> [,1] [,2] [,3] [,4] [,5] [,6] #> [1,] -0.6251050 -0.42650040 2.0085900 -0.2615856 -2.0828546 -1.17887937 #> [2,] -0.8751468 -1.70309521 -1.8544195 1.7879817 -1.4171540 0.49559328 #> [3,] 0.1433569 -1.04149736 -0.4627144 0.8673005 0.6107810 -0.17770431 #> [4,] 1.4251896 0.76873496 1.0431038 0.7025809 0.2415208 0.77473394 #> [5,] -1.7347494 -0.74532038 -0.3038375 1.6235322 1.3039648 1.24794638 #> [6,] -0.8374046 -0.48647150 0.3180807 -1.5901587 -0.3345286 -0.41621676 #> [7,] -0.7157526 -0.35303944 -0.6487490 -0.6099912 -0.3845399 -0.42971794 #> [8,] 0.3748210 -0.06230052 -1.8689043 -0.3132811 -0.4211682 -0.04652522 #> [9,] 2.3833280 1.61961511 -1.2069966 -0.9221298 -0.9583552 -0.65859154 #> [10,] -0.4639130 1.24621141 1.8972581 -0.2564806 0.2491163 1.60258408X[] <- 1:100 X[, 1]#> [1] 1 2 3 4 5 6 7 8 9 10X[1, ] # not recommended for large matrices#> [1] 1 11 21 31 41 51 61 71 81 91X[, -1]#> [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9] #> [1,] 11 21 31 41 51 61 71 81 91 #> [2,] 12 22 32 42 52 62 72 82 92 #> [3,] 13 23 33 43 53 63 73 83 93 #> [4,] 14 24 34 44 54 64 74 84 94 #> [5,] 15 25 35 45 55 65 75 85 95 #> [6,] 16 26 36 46 56 66 76 86 96 #> [7,] 17 27 37 47 57 67 77 87 97 #> [8,] 18 28 38 48 58 68 78 88 98 #> [9,] 19 29 39 49 59 69 79 89 99 #> [10,] 20 30 40 50 60 70 80 90 100#> [,1] [,2] [,3] [,4] [,5] #> [1,] 1 21 41 61 81 #> [2,] 2 22 42 62 82 #> [3,] 3 23 43 63 83 #> [4,] 4 24 44 64 84 #> [5,] 5 25 45 65 85 #> [6,] 6 26 46 66 86 #> [7,] 7 27 47 67 87 #> [8,] 8 28 48 68 88 #> [9,] 9 29 49 69 89 #> [10,] 10 30 50 70 90#> [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9] [,10] #> [1,] NA 11 21 31 41 51 61 71 81 91 #> [2,] 2 NA 22 32 42 52 62 72 82 92 #> [3,] 3 13 NA 33 43 53 63 73 83 93 #> [4,] 4 14 24 NA 44 54 64 74 84 94 #> [5,] 5 15 25 35 NA 55 65 75 85 95 #> [6,] 6 16 26 36 46 NA 66 76 86 96 #> [7,] 7 17 27 37 47 57 NA 77 87 97 #> [8,] 8 18 28 38 48 58 68 NA 88 98 #> [9,] 9 19 29 39 49 59 69 79 NA 99 #> [10,] 10 20 30 40 50 60 70 80 90 NAX <- FBM(150, 5) X[] <- iris ## you can replace with a df (but factors -> integers) X2 <- as_FBM(iris) identical(X[], X2[])#> [1] TRUE