% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/h5_readers.R
\name{read_h5ad}
\alias{read_h5ad}
\title{Read H5AD file and convert to sparse matrix}
\usage{
read_h5ad(
  file_path,
  layer = NULL,
  use_raw = FALSE,
  transpose = TRUE,
  return_metadata = FALSE,
  feature_format = "gene_name",
  verbose = FALSE
)
}
\arguments{
\item{file_path}{Character. Path to the H5AD file.}

\item{layer}{Character. The layer to extract from the H5AD file.
Default is NULL, which reads from X (the main expression matrix).
Common alternatives include "counts", "data", "scaled", etc.}

\item{use_raw}{Logical. If TRUE, reads from the raw.X slot instead of X.
Default is FALSE.}

\item{transpose}{Logical. If TRUE, transposes the matrix so genes are rows
and cells are columns (gedi format). Default is TRUE.}

\item{return_metadata}{Logical. If TRUE, returns a list with the expression
matrix, cell metadata (obs), and gene metadata (var). If FALSE, returns
only the expression matrix. Default is FALSE.}

\item{feature_format}{Character. Which feature identifier to use for gene names
when return_metadata = FALSE. Options: "gene_name" (default, uses var rownames)
or "gene_ids" (uses var$gene_ids column). Default is "gene_name".}

\item{verbose}{Logical. If TRUE, prints detailed progress messages. Default is FALSE.}
}
\value{
If return_metadata = FALSE, returns a sparse matrix (dgCMatrix) with
genes as rows and cells as columns. If return_metadata = TRUE, returns a
list with components:
\itemize{
\item X: sparse expression matrix (genes x cells)
\item obs: data.frame of cell metadata
\item var: data.frame of gene metadata
}
}
\description{
Reads an H5AD file (AnnData format) and extracts the expression matrix
as a sparse dgCMatrix suitable for use with gedi R6 object.
}
\details{
This function reads H5AD files, which are the standard format for AnnData
objects in Python. Compatible with gedi R6 class for seamless integration.
}
\examples{
\donttest{
# Round-trip: write a tiny H5AD via write_h5ad(), then read it back.
if (requireNamespace("hdf5r", quietly = TRUE) &&
    requireNamespace("SeuratObject", quietly = TRUE)) {
  pbmc_small <- SeuratObject::pbmc_small
  model <- CreateGEDIObject(
    Samples = pbmc_small@meta.data$orig.ident,
    M       = pbmc_small@assays$RNA@counts,
    K       = 3,
    verbose = 0
  )
  model$train(iterations = 5)

  tmp <- tempfile(fileext = ".h5ad")
  write_h5ad(model, tmp)
  expr_matrix <- read_h5ad(tmp)
  unlink(tmp)
}
}

}
