as.matrix.HDF5Matrix

as.matrix.HDF5Matrix

OTHER

1 Description

Reads entire HDF5 dataset into memory as a standard R matrix. WARNING: This loads all data into RAM. For large datasets (>1GB), this may cause memory exhaustion.

2 Usage

as.matrix.HDF5Matrix(x, force = FALSE, max_size_mb = NULL, ...)

3 Arguments

Parameter	Description
`x`	An object
`force`	Logical. If , skip size warnings. Default .
`max_size_mb`	Numeric. Maximum size in MB to convert without warning. Default is (auto-detect based on system RAM). Use to disable.

4 Value

Standard R matrix with data from HDF5 file

5 Details

Size thresholds and behavior:

Memory estimation: The function estimates memory usage as: nrow * ncol * 8 bytes (for numeric)

Actual memory usage may be higher due to: - R’s internal overhead - Temporary copies during conversion - Other objects in memory

Recommendations:

6 Examples

\donttest{
    fn <- tempfile(fileext = ".h5")
    X <- hdf5_create_matrix(fn, "data/X", data = matrix(rnorm(500), 100, 5))
    mat <- as.matrix(X)
    head(mat)

    # Subsetting is more efficient for large datasets
    subset <- X[1:10, 1:3]

    hdf5_close_all()
    unlink(fn)
}

7 See Also

[.HDF5Matrix for subsetting, as.data.frame.HDF5Matrix for data frame conversion

---
title: "as.matrix.HDF5Matrix"
subtitle: "as.matrix.HDF5Matrix"
---

<span class="category-badge other">OTHER</span>

## Description

Reads entire HDF5 dataset into memory as a standard R matrix.
**WARNING**: This loads all data into RAM. For large datasets (>1GB),
this may cause memory exhaustion.

## Usage

```r
as.matrix.HDF5Matrix(x, force = FALSE, max_size_mb = NULL, ...)
```
## Arguments

::: {.param-table}
| Parameter | Description |
|-----------|-------------|
| `x` | An \code{HDF5Matrix} object |
| `force` | Logical. If \code{TRUE}, skip size warnings. Default \code{FALSE}. |
| `max_size_mb` | Numeric. Maximum size in MB to convert without warning.   Default is \code{NULL} (auto-detect based on system RAM). Use \code{Inf} to disable. |
:::

## Value

::: {.return-value}
Standard R matrix with data from HDF5 file

:::
## Details

**Size thresholds and behavior:**

\describe{
  \item{Small datasets (< max_size_mb):}{Convert silently}
  \item{Medium datasets (max_size_mb to 2GB):}{Show warning, require confirmation}
  \item{Large datasets (> 2GB):}{Show error, require force=TRUE}
  \item{Huge datasets (> 8GB):}{Block conversion even with force=TRUE}
}

**Memory estimation:**
The function estimates memory usage as:
`nrow * ncol * 8 bytes (for numeric)`

Actual memory usage may be higher due to:
- R's internal overhead
- Temporary copies during conversion
- Other objects in memory

**Recommendations:**
\itemize{
  \item For large datasets, use subsetting instead: `X[1:1000, ]`
  \item For analysis, use HDF5Matrix methods directly (they work on-disk)
  \item Only convert to memory when absolutely necessary
}

## Examples
```{r}
#| eval: false
#| warning: false

\donttest{
    fn <- tempfile(fileext = ".h5")
    X <- hdf5_create_matrix(fn, "data/X", data = matrix(rnorm(500), 100, 5))
    mat <- as.matrix(X)
    head(mat)

    # Subsetting is more efficient for large datasets
    subset <- X[1:10, 1:3]

    hdf5_close_all()
    unlink(fn)
}

```
## See Also

::: {.see-also}
[[.HDF5Matrix]([.HDF5Matrix.html) for subsetting,
[as.data.frame.HDF5Matrix](as.data.frame.HDF5Matrix.html) for data frame conversion

:::