% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/h5_writers.R
\name{write_h5ad}
\alias{write_h5ad}
\title{Write GEDI model to H5AD file}
\usage{
write_h5ad(
  model,
  file_path,
  X_slot = c("imputed", "projection", "original"),
  M = NULL,
  include_embeddings = TRUE,
  include_raw = FALSE,
  compression = 6,
  verbose = TRUE
)
}
\arguments{
\item{model}{GEDI R6 object (must be trained)}

\item{file_path}{Character. Path where the H5AD file should be written.}

\item{X_slot}{Character. Which expression data to save in the main X slot:
\itemize{
\item "imputed": Imputed expression (default, requires M matrix)
\item "projection": ZDB projection (always available)
\item "original": Original M matrix (requires M parameter)
}}

\item{M}{Optional. Original count matrix to save when X_slot="original" or
include_raw=TRUE. Must match the dimensions used during model training.}

\item{include_embeddings}{Logical. Include PCA/UMAP in obsm if cached. Default TRUE.}

\item{include_raw}{Logical. If TRUE, saves original M in raw.X (requires M parameter).
Default FALSE.}

\item{compression}{Integer. Gzip compression level (0-9). Default 6.}

\item{verbose}{Logical. Print progress messages. Default TRUE.}
}
\value{
Invisibly returns the file path
}
\description{
Exports a trained GEDI model to H5AD (AnnData) format for interoperability
with Python tools like scanpy. The file contains expression data, embeddings,
metadata, and GEDI-specific parameters.
}
\details{
The H5AD file structure contains:
\itemize{
\item X: Main expression matrix (based on X_slot parameter)
\item obs: Cell metadata (sample IDs, colData)
\item var: Gene metadata (gene IDs)
\item obsm: Cell embeddings (X_gedi, X_pca, X_umap)
\item varm: Gene loadings (gedi_Z, gedi_Q_mean)
\item uns: Model parameters and metadata
\item raw.X: Original counts (if include_raw=TRUE)
}

The function handles the technical details of HDF5/AnnData compatibility:
\itemize{
\item Writes sparse matrices in CSR format
\item Transposes dense matrices for Python's row-major layout
\item Creates scalar string attributes (not arrays) for AnnData compatibility
\item Validates M matrix identity using fingerprints
}
}
\examples{
\donttest{
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)

  # Write to a temporary file (CRAN policy: never write to the user's
  # working directory in examples).
  tmp <- tempfile(fileext = ".h5ad")
  write_h5ad(model, tmp)
  write_h5ad(model, tmp, X_slot = "projection")
  unlink(tmp)
}
}

}
