% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/HDF5Matrix_create.R
\name{hdf5_create_matrix}
\alias{hdf5_create_matrix}
\title{Create an HDF5 dataset and return an HDF5Matrix object}
\usage{
hdf5_create_matrix(
  filename,
  dataset,
  nrow = NULL,
  ncol = NULL,
  data = NULL,
  dtype = c("double", "integer", "logical"),
  overwrite = FALSE,
  compression = NULL
)
}
\arguments{
\item{filename}{Character. Path to the HDF5 file (created if it does not exist).}

\item{dataset}{Character. Full path inside the HDF5 file in
\code{"group/dataset"} or \code{"group/subgroup/dataset"} format.}

\item{nrow}{Integer or NULL. Number of rows. Required when \code{data = NULL}.}

\item{ncol}{Integer or NULL. Number of columns. Required when \code{data = NULL}.}

\item{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.}

\item{dtype}{Character. Element type: \code{"double"} (default),
\code{"integer"}, or \code{"logical"}.}

\item{overwrite}{Logical. If \code{TRUE}, an existing dataset is replaced.}

\item{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{
An \code{HDF5Matrix} object pointing to the created dataset.
}
\description{
Creates a new HDF5 dataset (optionally writing data) and returns an
\code{HDF5Matrix} object pointing to it.
}
\details{
Replaces the legacy \code{bdCreate_hdf5_matrix()} / \code{bdCreate_hdf5_emptyDataset()}
calls in the R6+S3 interface. The legacy functions remain available for
backward compatibility.

Row and column names stored in the \code{dimnames} attribute of \code{data}
are written to the HDF5 file automatically.
}
\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)
}

}
\seealso{
\code{\link{hdf5matrix_options}} to set global compression default.
}
