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(tmpdir = getOption("FBM.dir")),
create_bk = TRUE,
is_read_only = FALSE
)
as_FBM(
x,
type = c("double", "float", "integer", "unsigned short", "unsigned char", "raw"),
backingfile = tempfile(tmpdir = getOption("FBM.dir")),
is_read_only = FALSE
)Number of rows.
Number of columns.
Type of the Filebacked Big Matrix (default is double). Either
"double" (double precision -- 64 bits)
"float" (single precision -- 32 bits)
"integer"
"unsigned short": can store integer values from 0 to 65535.
It has vocation to become the basis for a FBM.code65536.
"raw" or "unsigned char": can store integer values from 0 to 255.
It is the basis for class FBM.code256 in order to
access 256 arbitrary different numeric values.
It is used in package bigsnpr.
Either a single value (e.g. 0) or as many value as the number
of elements of the FBM. Default doesn't initialize the matrix.
Path to the file storing the FBM data on disk. An extension ".bk" will be automatically added. Default stores in the temporary directory, which you can change using global option "FBM.dir".
Whether to create a backingfile (the default) or use an
existing one (which should be named by the backingfile parameter and have
an extension ".bk"). For example, this could be used to convert a
filebacked big.matrix from package bigmemory to a FBM
(see the corresponding vignette).
Whether the FBM is read-only? Default is FALSE.
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] FALSE
X_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\\RtmpSeLJ92\\file577023c9325.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"
X[] <- rnorm(length(X))
X[, 1:6]
#> [,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.60258408
X[] <- 1:100
X[, 1]
#> [1] 1 2 3 4 5 6 7 8 9 10
X[1, ] # not recommended for large matrices
#> [1] 1 11 21 31 41 51 61 71 81 91
X[, -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
X[, c(TRUE, FALSE)]
#> [,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
X[cbind(1:10, 1:10)] <- NA_real_
X[] # access as standard R matrix
#> [,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 NA
X <- FBM(150, 5)
X[] <- iris ## you can replace with a df (but factors -> integers)
X2 <- as_FBM(iris)
identical(X[], X2[])
#> [1] TRUE