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

Arguments / Options

---

G4X-DATA

type : directory
example : path/to/g4x_output

Positional path to a G4X sample output directory.
The folder must follow the expected schema (e.g., contain run_meta.json, segmentation masks, panel files, single-cell outputs).
Provide this argument directly after the specified command, i.e:
g4x-helpers COMMAND G4X-DATA

---

--metadata

type : file path
example : path/to/cell_metadata.csv

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

---

--cellid-key

type : string
default : cell_id

Name of the column in the metadata file that contains cell IDs matching those in the segmentation.bin file.

---

--cluster-key

type : string
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 : string
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 : string
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.

---

--in-place

type : flag
default : not set

By default, commands write their outputs to <G4X-DATA>/g4x_helpers/<command>, leaving the original data untouched. Using --in-place instead writes outputs directly into the specified G4X-DATA directory, which may be required when chaining certain commands.

Note: this will override any existing artifacts modified by the command.
Please refer to each feature’s documentation to see which files may be updated.

⸻