update_bin

Update G4X-viewer .bin file with new metadata

Updates an existing .bin segmentation file with new clustering, embedding, or color metadata from a CSV file.

Usage

Note

Global options --threads/-t & --verbose/-v must be supplied on the main entrypoint before the subcommand:

g4x-helpers --threads 16 -v 2 COMMAND /path/to/g4x_data [OPTIONS]

use g4x-helpers --help for more information

argument descriptions

---

required

G4X-DATA (argument)

Positional path to a G4X sample output directory.
The folder must follow the expected schema (e.g., run_meta.json, segmentation masks, panel files, single-cell outputs).
Provide this argument after command-specific options.

--metadata: (type: str)

Path to a CSV file containing metadata to update the .bin file. This file must include a header row and should contain cell IDs, optional cluster assignments, colors, and embeddings.

optional

--in-place: (flag default: False)

By default, outputs are written to <G4X-DATA>/g4x_helpers/<command>, leaving the source data untouched.
Add --in-place to write results directly into the provided G4X-DATA folder (overwriting existing artifacts for that command).

--cellid-key: (type: str default: cell_id)

Name of the column in the metadata file that contains cell IDs matching those in the .bin file. Defaults to cell_id.

--cluster-key: (type: str default: None)

Column name in the metadata that provides cluster assignments for each cell. Required if --cluster-color-key is used.

--cluster-color-key: (type: str default: None)

Column name in the metadata that provides RGB or hex colors for each cluster. Must be used in conjunction with --cluster-key.

--emb-key: (type: str default: None)

Prefix for embedding coordinates. The command looks for two columns: {emb_key}_1 and {emb_key}_2. Used to embed cells in UMAP/tSNE/etc. space.

⸻