memory optimizations, format description

Author: pkharchenko

CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to the C++ line of Baysor are documented here.
 
+## [Unreleased]
+
+### Added
+
+- `legacy` and `parquet` output styles for `baysor run`.
+- A documented Xenium workflow based on `experiment.xenium` input plus `xeniumranger import-segmentation`.
+- User-facing documentation pages for installation, CLI usage, inputs, outputs, preview, segfree, configuration, examples, and Xenium workflows.
+- A file-level output reference for the current output bundles.
+
+### Changed
+
+- `run`, `preview`, and `segfree` now resolve `experiment.xenium` automatically.
+- `legacy` output now emits Xenium Ranger-friendly fields automatically for Xenium-origin inputs.
+- NCV color generation in `run` and `preview` now uses an anchor-first streaming path:
+  - learn the NCV basis from anchors
+  - fit UMAP on sampled anchors
+  - stream exact low-dimensional NCV vectors for all molecules
+- Default `n_cells_init` is now prior-aware when a prior segmentation is present.
+- `segmentation_counts.loom` writing now uses a row-oriented path instead of a late sparse-matrix duplication step.
+
+### Fixed
+
+- Reduced clustering memory by removing the per-thread dense gene-by-gene correlation matrix.
+- Reduced segmentation memory by switching persistent component gene counts away from dense `double` storage.
+- Reduced NCV memory by removing global all-molecule neighborhood materialization and the full all-molecule high-dimensional NCV matrix from the `run` and `preview` paths.
+- Reduced Loom write time and memory by avoiding an extra sparse-matrix conversion during output.
+
 ## [0.8.0] — 2026-04-17
 
 ### Added

README.md

@@ -48,13 +48,15 @@ Several header-only dependencies are fetched automatically by CMake.
 ### Configure and build
 
 ```bash
-cmake -S . -B build
-cmake --build build
+cmake -S . -B build -DBAYSOR_WITH_TESTS=OFF
+cmake --build build --target baysor -j"$(nproc)"
 ```
 
 ### Run tests
 
 ```bash
+cmake -S . -B build
+cmake --build build --target baysor baysor_tests -j"$(nproc)"
 ctest --test-dir build --output-on-failure
 ```
 

docs/README.md

@@ -13,6 +13,7 @@ Current pages:
 - [Input Data](inputs.md)
 - [Prior Segmentation Inputs](priors.md)
 - [Outputs](outputs.md)
+- [Output Files](output_files.md)
 - [Xenium Workflow](xenium.md)
 - [Configuration](configuration.md)
 - [Examples](examples.md)

docs/index.md

@@ -29,5 +29,6 @@ It is built with CMake and currently exposes three CLI subcommands:
 - [Segmentation-Free NCVs](segfree.md)
 - [Input Data](inputs.md)
 - [Outputs](outputs.md)
+- [Output Files](output_files.md)
 - [Xenium Workflow](xenium.md)
 - [Examples](examples.md)

docs/installation.md

@@ -15,7 +15,7 @@ Install a C++ toolchain plus the libraries required by
 - HDF5
 - nlohmann_json
 - libtiff
-- GTest for the test target
+- GTest for the optional test target
 
 Several header-only dependencies are fetched automatically by CMake.
 
@@ -49,7 +49,6 @@ sudo apt-get update
 sudo apt-get install -y --no-install-recommends \
   build-essential \
   cmake \
-  ninja-build \
   pkg-config \
   git \
   libeigen3-dev \
@@ -60,41 +59,45 @@ sudo apt-get install -y --no-install-recommends \
   libparquet-dev \
   libhdf5-dev \
   nlohmann-json3-dev \
-  libtiff-dev \
-  libgtest-dev
+  libtiff-dev
 ```
 
-### 3. Configure, Build, And Test
+### 3. Configure And Build The Binary
 
 ```bash
-cmake -S . -B build -GNinja
-cmake --build build
-ctest --test-dir build --output-on-failure
+cmake -S . -B build -DBAYSOR_WITH_TESTS=OFF
+cmake --build build --target baysor -j"$(nproc)"
 ```
 
-If you only need the main binary:
+The main binary will be:
 
-```bash
-cmake -S . -B build -GNinja -DBAYSOR_WITH_TESTS=OFF
-cmake --build build --target baysor
+```text
+./build/baysor
 ```
 
-## Configure And Build
+### 4. Optional: Build And Run Tests
 
 ```bash
+sudo apt-get install -y --no-install-recommends libgtest-dev
 cmake -S . -B build
-cmake --build build
+cmake --build build --target baysor baysor_tests -j"$(nproc)"
+ctest --test-dir build --output-on-failure
 ```
 
-The main binary will be:
+## Configure And Build
 
-```text
-./build/baysor
+If the required libraries are already installed on your system:
+
+```bash
+cmake -S . -B build -DBAYSOR_WITH_TESTS=OFF
+cmake --build build --target baysor -j"$(nproc)"
 ```
 
-## Run Tests
+If you want tests too:
 
 ```bash
+cmake -S . -B build
+cmake --build build --target baysor baysor_tests -j"$(nproc)"
 ctest --test-dir build --output-on-failure
 ```
 
@@ -103,13 +106,13 @@ ctest --test-dir build --output-on-failure
 Show CLI help:
 
 ```bash
-./build/baysor run --help
+./build/baysor --help
 ```
 
-Build just the main binary and tests:
+Show run-specific help:
 
 ```bash
-cmake --build build --target baysor baysor_tests -j4
+./build/baysor run --help
 ```
 
 ## Notes