hdf5_create_matrix

hdf5_create_matrix

HDF5MATRIX_CORE

1 Description

Creates a new HDF5 dataset (optionally writing data) and returns an HDF5Matrix object pointing to it.

2 Usage

hdf5_create_matrix(...)

3 Arguments

Parameter	Description
`filename`	Character. Path to the HDF5 file (created if it does not exist).
`dataset`	Character. Full path inside the HDF5 file in or format.
`nrow`	Integer or NULL. Number of rows. Required when .
`ncol`	Integer or NULL. Number of columns. Required when .
`data`	Numeric matrix, integer matrix, or numeric vector, or NULL. When non-NULL, the data are written to the new dataset. When NULL, an empty (zero-filled) dataset of size is created.
`dtype`	Character. Element type: (default), , or .
`overwrite`	Logical. If , an existing dataset is replaced.
`compression`	Integer (0-9) or NULL. gzip compression level. uses the global option set by (default 6). Use to disable compression.

4 Value

An object pointing to the created dataset.

5 Details

Replaces the legacy bdCreate_hdf5_matrix() / bdCreate_hdf5_emptyDataset() calls in the R6+S3 interface. The legacy functions remain available for backward compatibility.

Row and column names stored in the dimnames attribute of data are written to the HDF5 file automatically.

6 Examples

\donttest{
tmp <- tempfile(fileext = ".h5")

# Create from matrix data
mat <- matrix(rnorm(200), nrow = 20, ncol = 10)
X <- hdf5_create_matrix(tmp, "data/X", data = mat)
dim(X)  # 20 x 10

# Create empty dataset
Y <- hdf5_create_matrix(tmp, "data/Y", nrow = 1000, ncol = 500)
dim(Y)  # 1000 x 500

# No compression (useful for benchmarks or intermediate results)
Z <- hdf5_create_matrix(tmp, "data/Z", data = mat, compression = 0)

X$close(); Y$close(); Z$close()
unlink(tmp)
}

7 See Also

hdf5matrix_options to set global compression default.

---
title: "hdf5_create_matrix"
subtitle: "hdf5_create_matrix"
---

<span class="category-badge hdf5matrix_core">HDF5MATRIX_CORE</span>

## Description

Creates a new HDF5 dataset (optionally writing data) and returns an
`HDF5Matrix` object pointing to it.

## Usage

```r
hdf5_create_matrix(...)
```
## Arguments

::: {.param-table}
| Parameter | Description |
|-----------|-------------|
| `filename` | Character. Path to the HDF5 file (created if it does not exist). |
| `dataset` | Character. Full path inside the HDF5 file in   \code{"group/dataset"} or \code{"group/subgroup/dataset"} format. |
| `nrow` | Integer or NULL. Number of rows. Required when \code{data = NULL}. |
| `ncol` | Integer or NULL. Number of columns. Required when \code{data = NULL}. |
| `data` | Numeric matrix, integer matrix, or numeric vector, or NULL.   When non-NULL, the data are written to the new dataset. When NULL,   an empty (zero-filled) dataset of size \code{nrow x ncol} is created. |
| `dtype` | Character. Element type: \code{"double"} (default),   \code{"integer"}, or \code{"logical"}. |
| `overwrite` | Logical. If \code{TRUE}, an existing dataset is replaced. |
| `compression` | Integer (0-9) or NULL. gzip compression level.   \code{NULL} uses the global option set by \code{\link{hdf5matrix_options}}   (default 6). Use \code{0} to disable compression.  |
:::

## Value

::: {.return-value}
An \code{HDF5Matrix} object pointing to the created dataset.

:::
## Details

Replaces the legacy `bdCreate_hdf5_matrix()` / `bdCreate_hdf5_emptyDataset()`
calls in the R6+S3 interface. The legacy functions remain available for
backward compatibility.

Row and column names stored in the `dimnames` attribute of `data`
are written to the HDF5 file automatically.

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

\donttest{
tmp <- tempfile(fileext = ".h5")

# Create from matrix data
mat <- matrix(rnorm(200), nrow = 20, ncol = 10)
X <- hdf5_create_matrix(tmp, "data/X", data = mat)
dim(X)  # 20 x 10

# Create empty dataset
Y <- hdf5_create_matrix(tmp, "data/Y", nrow = 1000, ncol = 500)
dim(Y)  # 1000 x 500

# No compression (useful for benchmarks or intermediate results)
Z <- hdf5_create_matrix(tmp, "data/Z", data = mat, compression = 0)

X$close(); Y$close(); Z$close()
unlink(tmp)
}

```
## See Also

::: {.see-also}
[hdf5matrix_options](hdf5matrix_options.html) to set global compression default.
:::