Class FBM

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. Yet, the implementation is lighter.

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
)

as_FBM(
  x,
  type = c("double", "float", "integer", "unsigned short", "unsigned char", "raw"),
  backingfile = tempfile()
)

Arguments

nrow

Number of rows.
ncol

Number of columns.
type

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.
init

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.
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 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).
x

A matrix or an data frame (2-dimensional data).

Details

An FBM object has many field:

  • $address: address of the external pointer containing the underlying C++ object, to be used as a XPtr<FBM> in C++ code

  • $extptr: use $address instead

  • $nrow

  • $ncol

  • $type

  • $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?

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.

  • $bm.desc(): Get this object as a filebacked.big.matrix descriptor.

See also

big_copy

Examples

mat <- matrix(1:4, 2)
X_from_mat <- as_FBM(mat)

X <- FBM(10, 10)
typeof(X)
#> [1] "double"
X[] <- rnorm(length(X))
X[, 1:6]
#>             [,1]        [,2]       [,3]        [,4]        [,5]       [,6]
#>  [1,] -0.8395478  0.05911866 -0.1130593 -0.18330306  0.12900758  0.2774897
#>  [2,] -0.1214087 -0.29240017  0.9819030  2.55027313  0.37789519 -0.2964008
#>  [3,]  0.1691272 -0.70257240  0.2195934 -0.26112976  0.01959797 -0.3533037
#>  [4,]  1.7690472 -1.01322840  0.9114683 -0.39821783 -0.15551229  0.2728970
#>  [5,] -0.3986912  0.03383893 -1.0396207 -0.90108979 -0.53425061  0.3082629
#>  [6,]  2.0820506  0.37254100 -2.4759738  0.08500260 -0.39318881 -0.8051451
#>  [7,]  0.5696666  0.07009365 -0.7310125  0.30512830  0.31444129 -1.6021685
#>  [8,]  0.2985876  0.05378260 -0.1428284 -0.04228224 -0.49658094 -0.2757861
#>  [9,]  0.9050183 -0.47646816 -0.5425438  1.02368660 -1.68015353  1.3578537
#> [10,] -1.9936528  0.20150012 -0.1125554  0.37465879 -0.42279778  0.4280318
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[]
#>       [,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 (factors -> integers)
X2 <- as_FBM(iris)
identical(X[], X2[])
#> [1] TRUE