added parquet output style, output modifications for xeniumranger

annotation import, docs

Author: pkharchenko

CMakeLists.txt

@@ -95,6 +95,7 @@ add_library(baysor_lib
     # Utils
     src/utils/general.cpp
     src/utils/options.cpp
+    src/utils/xenium.cpp
 
     # Data loading
     src/data_loading/data.cpp

README.md

@@ -23,6 +23,10 @@ Example datasets and runnable commands:
 - [osm-FISH](examples/osm-FISH/README.md)
 - [STARmap](examples/STARmap/README.md)
 
+User-facing documentation for this branch:
+
+- [docs/README.md](docs/README.md)
+
 ## Build
 
 ### Dependencies

docs/README.md

@@ -0,0 +1,26 @@
+# Baysor C++ Branch Documentation
+
+This directory contains the user-facing documentation for the native C++
+implementation.
+
+Current pages:
+
+- [Overview](index.md)
+- [Installation](installation.md)
+- [Running Baysor](run.md)
+- [Dataset Preview](preview.md)
+- [Segmentation-Free NCVs](segfree.md)
+- [Input Data](inputs.md)
+- [Prior Segmentation Inputs](priors.md)
+- [Outputs](outputs.md)
+- [Xenium Workflow](xenium.md)
+- [Configuration](configuration.md)
+- [Examples](examples.md)
+- [Citation](citation.md)
+
+This structure follows the useful parts of the old `master` documentation, but
+it is intentionally narrower:
+
+- it documents the currently implemented C++ CLI surface
+- it treats Xenium Explorer support as a Xenium Ranger handoff workflow rather
+  than direct bundle generation

docs/citation.md

@@ -0,0 +1,12 @@
+# Citation
+
+If you find Baysor useful for your publication, please cite:
+
+```text
+Petukhov V, Xu RJ, Soldatov RA, Cadinu P, Khodosevich K, Moffitt JR & Kharchenko PV.
+Cell segmentation in imaging-based spatial transcriptomics.
+Nat Biotechnol (2021). https://doi.org/10.1038/s41587-021-01044-w
+```
+
+For the method background, see the published paper above. For the current C++
+implementation details, refer to the documentation in this branch.

docs/configuration.md

@@ -0,0 +1,99 @@
+# Configuration
+
+The main protocol presets live under [configs/](../configs/):
+
+- [example_config.toml](../configs/example_config.toml)
+- [xenium.toml](../configs/xenium.toml)
+- [iss.toml](../configs/iss.toml)
+- [starmap.toml](../configs/starmap.toml)
+- [osm_fish.toml](../configs/osm_fish.toml)
+
+Use them with:
+
+```bash
+./build/baysor run -c configs/xenium.toml ...
+```
+
+## Config Structure
+
+The example config is organized into sections such as:
+
+- `[data]`
+- `[segmentation]`
+- `[plotting]`
+
+Common fields include:
+
+### `[data]`
+
+- column names (`x`, `y`, `z`, `gene`)
+- filtering:
+  - `min_molecules_per_gene`
+  - `exclude_genes`
+  - `min_molecules_per_cell`
+- `force_2d`
+
+### `[segmentation]`
+
+- `scale`
+- `scale_std`
+- `estimate_scale_from_centers`
+- `n_clusters`
+- `prior_segmentation_confidence`
+- `iters`
+- `n_cells_init`
+- `nuclei_genes`
+- `cyto_genes`
+- `unassigned_prior_label`
+
+### `[plotting]`
+
+- `gene_composition_neigborhood`
+- `min_pixels_per_cell`
+- `max_plot_size`
+- `ncv_method`
+
+## CLI vs Config
+
+Config values set defaults. CLI flags override them.
+
+Typical pattern:
+
+```bash
+./build/baysor run \
+  -c configs/xenium.toml \
+  --x-min 0 --x-max 2000 \
+  --y-min 0 --y-max 2000 \
+  data/experiment.xenium :cell_id
+```
+
+## Protocol-Specific Notes
+
+### Xenium
+
+[configs/xenium.toml](../configs/xenium.toml) maps Xenium columns:
+
+- `x_location`
+- `y_location`
+- `z_location`
+- `feature_name`
+- `qv`
+
+and sets:
+
+- Xenium-style transcript filtering
+- Xenium prior defaults
+
+### ISS / STARmap / osm-FISH
+
+The protocol config files mainly adjust:
+
+- minimum molecules per gene / cell
+- plotting defaults
+- expected coordinate / gene column layout
+
+## Recommendation
+
+For protocol-specific work, start from the closest existing config and override
+only the values that are truly dataset-specific. For a fuller list of fields and
+comments, use [example_config.toml](../configs/example_config.toml).

docs/examples.md

@@ -0,0 +1,18 @@
+# Examples
+
+Protocol-specific runnable examples live under `examples/`.
+
+Currently documented examples:
+
+- [Xenium pancreas](../examples/Xenium_pancreas_membrane_377/README.md)
+- [ISS](../examples/iss/README.md)
+- [osm-FISH](../examples/osm-FISH/README.md)
+- [STARmap](../examples/STARmap/README.md)
+
+Notes:
+
+- we currently carry one Xenium example README
+- the Xenium example is the main reference for Xenium-aware input handling and
+  Xenium Ranger handoff
+- the other examples remain useful references for non-Xenium protocols and for
+  prior-mask / prior-boundary workflows

docs/index.md

@@ -0,0 +1,33 @@
+# Baysor C++ Branch
+
+Baysor segments imaging-based spatial transcriptomics data using spatial
+position, local gene composition, and optional prior segmentation inputs.
+
+This `cpp` branch is the native C++ implementation of the main Baysor workflow.
+It is built with CMake and currently exposes three CLI subcommands:
+
+- `run`
+- `preview`
+- `segfree`
+
+## What Is Implemented
+
+- `baysor run`
+- `baysor preview`
+- `baysor segfree`
+- CSV / Parquet transcript-table input
+- image-mask and polygon prior segmentation
+- Xenium-aware input resolution through `experiment.xenium`
+- `legacy` and `parquet` output styles
+- HTML plotting / diagnostic outputs from `run`
+
+## Start Here
+
+- [Installation](installation.md)
+- [Running Baysor](run.md)
+- [Dataset Preview](preview.md)
+- [Segmentation-Free NCVs](segfree.md)
+- [Input Data](inputs.md)
+- [Outputs](outputs.md)
+- [Xenium Workflow](xenium.md)
+- [Examples](examples.md)

docs/inputs.md

@@ -0,0 +1,91 @@
+# Input Data
+
+Baysor consumes a molecule table plus an optional prior segmentation input.
+
+## Supported Molecule Inputs
+
+The `coordinates` positional argument may be:
+
+- CSV molecule table
+- Parquet molecule table
+- `experiment.xenium`
+
+When `experiment.xenium` is used, Baysor resolves the adjacent Xenium
+transcript table automatically and keeps enough source context to make the
+legacy outputs compatible with `xeniumranger import-segmentation`.
+
+## Required Molecule Columns
+
+At minimum, Baysor needs:
+
+- `x`
+- `y`
+- `gene`
+
+If the data are 3D, it can also use:
+
+- `z`
+
+Column names are configurable through CLI flags or the config file.
+
+## Common Column Mapping Flags
+
+- `--x-column`
+- `--y-column`
+- `--z-column`
+- `--gene-column`
+- `--qv-column`
+
+For Xenium, [configs/xenium.toml](../configs/xenium.toml) already maps:
+
+- `x_location`
+- `y_location`
+- `z_location`
+- `feature_name`
+- `qv`
+
+## Optional Source Columns
+
+Depending on the workflow, the input table may also carry:
+
+- a transcript-native prior column such as `cell_id`
+- confidence / quality columns
+- Xenium `transcript_id`
+
+For Xenium-origin inputs, Baysor preserves `transcript_id` so it can be written
+back to `legacy` output when appropriate.
+
+## Cropping During Input Load
+
+The C++ branch supports spatial filtering during input loading:
+
+- `--x-min`, `--x-max`
+- `--y-min`, `--y-max`
+- `--z-min`, `--z-max`
+
+This is useful for:
+
+- quick development runs
+- protocol debugging
+- visualization crops
+- testing large datasets without loading the full field of view
+
+## Protocol Notes
+
+### Xenium
+
+Preferred input:
+
+```bash
+./build/baysor run -c configs/xenium.toml data/experiment.xenium :cell_id
+```
+
+### ISS / osm-FISH / STARmap
+
+These usually use CSV molecule tables plus either:
+
+- no prior, with explicit `--scale`
+- an image mask prior
+- a boundary file prior
+
+See [Examples](examples.md) for runnable commands.