> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bioptimus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# writers

Streaming writers for persisting tile-level predictions.

Provides a `PredictionWriter` protocol and three concrete implementations (`ZarrWriter`, `HDF5Writer`, `NPZWriter`) that save per-tile outputs and metadata to disk in a memory-efficient way.

Zarr and HDF5 writers stream results row-by-row so that the full output tensor never needs to reside in memory.  The NPZ writer accumulates results in Python lists and flushes on close.

## OutputFormat

```python theme={null}
class OutputFormat(str, enum.Enum)
```

Supported on-disk formats for prediction output.

## PredictionWriter

```python theme={null}
class PredictionWriter(ABC)
```

Abstract base for streaming prediction writers.

#### open

```python theme={null}
@abstractmethod
def open(num_tiles: int, embedding_dim: int) -> None
```

Pre-allocates storage once the embedding dim is known.

<ParamField body="num_tiles" type="int" required>
  Total number of tiles to be written.
</ParamField>

<ParamField body="embedding_dim" type="int" required>
  Dimensionality of each prediction vector.
</ParamField>

#### write

```python theme={null}
@abstractmethod
def write(response: ModelResponse) -> None
```

Writes a single tile's model response.

<ParamField body="response" type="ModelResponse" required>
  The model response to persist.
</ParamField>

#### set\_thumbnail

```python theme={null}
@abstractmethod
def set_thumbnail(thumbnail: NDArray) -> None
```

Stores a slide thumbnail image.

<ParamField body="thumbnail" type="NDArray" required>
  RGB image array of shape `(H, W, 3)`.
</ParamField>

#### set\_metadata

```python theme={null}
@abstractmethod
def set_metadata(metadata: dict[str, Any]) -> None
```

Stores slide-level metadata alongside the arrays.

<ParamField body="metadata" type="dict[str, Any]" required>
  Key-value pairs (slide\_name, tile\_size, etc.).
</ParamField>

#### set\_tissue\_mask

```python theme={null}
@abstractmethod
def set_tissue_mask(mask: NDArray) -> None
```

Stores the tissue mask used during extraction.

<ParamField body="mask" type="NDArray" required>
  Binary mask array of shape `(H, W)`, dtype `uint8`.
</ParamField>

#### set\_gene\_names

```python theme={null}
def set_gene_names(input_genes: list[str] | None = None,
                   output_genes: list[str] | None = None) -> None
```

Stores input and output gene name lists.

Default implementation is a no-op. Subclasses that support gene annotation should override this.

<ParamField body="input_genes" type="list[str] | None">
  Ordered Ensembl IDs for bulk RNA input.
</ParamField>

<ParamField body="output_genes" type="list[str] | None">
  Ordered Ensembl IDs for predicted output.
</ParamField>

#### close

```python theme={null}
@abstractmethod
def close() -> None
```

Flushes and finalises the output file.

## ZarrWriter

```python theme={null}
class ZarrWriter(PredictionWriter)
```

Streams tile predictions into a Zarr directory store.

#### open

```python theme={null}
def open(num_tiles: int, embedding_dim: int) -> None
```

Pre-allocates Zarr datasets for outputs, coordinates, and tissue ratios.

<ParamField body="num_tiles" type="int" required>
  Total number of tiles to be written.
</ParamField>

<ParamField body="embedding_dim" type="int" required>
  Dimensionality of each prediction vector.
</ParamField>

#### write

```python theme={null}
def write(response: ModelResponse) -> None
```

Writes a single tile response into the Zarr datasets.

<ParamField body="response" type="ModelResponse" required>
  The model response to persist.
</ParamField>

#### set\_thumbnail

```python theme={null}
def set_thumbnail(thumbnail: NDArray) -> None
```

Stores a slide thumbnail as a Zarr dataset.

<ParamField body="thumbnail" type="NDArray" required>
  RGB image array of shape `(H, W, 3)`.
</ParamField>

#### set\_metadata

```python theme={null}
def set_metadata(metadata: dict[str, Any]) -> None
```

Stores metadata as Zarr root attributes.

<ParamField body="metadata" type="dict[str, Any]" required>
  Key-value pairs (slide\_name, tile\_size, etc.).
</ParamField>

#### set\_tissue\_mask

```python theme={null}
def set_tissue_mask(mask: NDArray) -> None
```

Stores the tissue mask as a Zarr dataset.

<ParamField body="mask" type="NDArray" required>
  Binary mask array of shape `(H, W)`, dtype `uint8`.
</ParamField>

#### set\_gene\_names

```python theme={null}
def set_gene_names(input_genes: list[str] | None = None,
                   output_genes: list[str] | None = None) -> None
```

Stores gene name arrays as Zarr string datasets.

<ParamField body="input_genes" type="list[str] | None">
  Ordered Ensembl IDs for bulk RNA input.
</ParamField>

<ParamField body="output_genes" type="list[str] | None">
  Ordered Ensembl IDs for predicted output.
</ParamField>

#### close

```python theme={null}
def close() -> None
```

Logs output path (Zarr stores are flushed on write).

## HDF5Writer

```python theme={null}
class HDF5Writer(PredictionWriter)
```

Streams tile predictions into an HDF5 file.

#### open

```python theme={null}
def open(num_tiles: int, embedding_dim: int) -> None
```

Opens the HDF5 file and pre-allocates datasets.

<ParamField body="num_tiles" type="int" required>
  Total number of tiles to be written.
</ParamField>

<ParamField body="embedding_dim" type="int" required>
  Dimensionality of each prediction vector.
</ParamField>

#### write

```python theme={null}
def write(response: ModelResponse) -> None
```

Writes a single tile response into the HDF5 datasets.

<ParamField body="response" type="ModelResponse" required>
  The model response to persist.
</ParamField>

#### set\_thumbnail

```python theme={null}
def set_thumbnail(thumbnail: NDArray) -> None
```

Stores a slide thumbnail as an HDF5 dataset.

<ParamField body="thumbnail" type="NDArray" required>
  RGB image array of shape `(H, W, 3)`.
</ParamField>

#### set\_metadata

```python theme={null}
def set_metadata(metadata: dict[str, Any]) -> None
```

Stores metadata as HDF5 file-level attributes.

<ParamField body="metadata" type="dict[str, Any]" required>
  Key-value pairs (slide\_name, tile\_size, etc.).
</ParamField>

#### set\_tissue\_mask

```python theme={null}
def set_tissue_mask(mask: NDArray) -> None
```

Stores the tissue mask as an HDF5 dataset.

<ParamField body="mask" type="NDArray" required>
  Binary mask array of shape `(H, W)`, dtype `uint8`.
</ParamField>

#### set\_gene\_names

```python theme={null}
def set_gene_names(input_genes: list[str] | None = None,
                   output_genes: list[str] | None = None) -> None
```

Stores gene name arrays as HDF5 string datasets.

<ParamField body="input_genes" type="list[str] | None">
  Ordered Ensembl IDs for bulk RNA input.
</ParamField>

<ParamField body="output_genes" type="list[str] | None">
  Ordered Ensembl IDs for predicted output.
</ParamField>

#### close

```python theme={null}
def close() -> None
```

Closes the HDF5 file handle and flushes to disk.

## NPZWriter

```python theme={null}
class NPZWriter(PredictionWriter)
```

Accumulates tile predictions in memory, saves as compressed npz.

#### open

```python theme={null}
def open(num_tiles: int, embedding_dim: int) -> None
```

Allocates in-memory arrays for accumulating results.

<ParamField body="num_tiles" type="int" required>
  Total number of tiles to be written.
</ParamField>

<ParamField body="embedding_dim" type="int" required>
  Dimensionality of each prediction vector.
</ParamField>

#### write

```python theme={null}
def write(response: ModelResponse) -> None
```

Writes a single tile response into the in-memory arrays.

<ParamField body="response" type="ModelResponse" required>
  The model response to persist.
</ParamField>

#### set\_thumbnail

```python theme={null}
def set_thumbnail(thumbnail: NDArray) -> None
```

Stores the slide thumbnail for later NPZ serialization.

<ParamField body="thumbnail" type="NDArray" required>
  RGB image array of shape `(H, W, 3)`.
</ParamField>

#### set\_metadata

```python theme={null}
def set_metadata(metadata: dict[str, Any]) -> None
```

Stores metadata for later NPZ serialization.

<ParamField body="metadata" type="dict[str, Any]" required>
  Key-value pairs (slide\_name, tile\_size, etc.).
</ParamField>

#### set\_tissue\_mask

```python theme={null}
def set_tissue_mask(mask: NDArray) -> None
```

Stores the tissue mask for later NPZ serialization.

<ParamField body="mask" type="NDArray" required>
  Binary mask array of shape `(H, W)`, dtype `uint8`.
</ParamField>

#### set\_gene\_names

```python theme={null}
def set_gene_names(input_genes: list[str] | None = None,
                   output_genes: list[str] | None = None) -> None
```

Stores gene name lists for later NPZ serialization.

<ParamField body="input_genes" type="list[str] | None">
  Ordered Ensembl IDs for bulk RNA input.
</ParamField>

<ParamField body="output_genes" type="list[str] | None">
  Ordered Ensembl IDs for predicted output.
</ParamField>

#### close

```python theme={null}
def close() -> None
```

Flushes all accumulated arrays to a compressed `.npz` file.

#### create\_writer

```python theme={null}
def create_writer(fmt: OutputFormat, path: Path) -> PredictionWriter
```

Creates a writer for the requested format.

<ParamField body="fmt" type="OutputFormat" required>
  Output format.
</ParamField>

<ParamField body="path" type="Path" required>
  Destination file or directory path.
</ParamField>

<ResponseField name="returns" type="PredictionWriter">
  An initialised (but not yet opened) `PredictionWriter`.
</ResponseField>