Usage

G4X-helpers offers several tools for common post-processing needs, each of which is described in detail in the CLI features section. On this page, we will demonstrate how to execute these tools either from the CLI or through a Docker image (depending on how you installed G4X-helpers).

Quickstart

If you have installed G4X-helpers and your environment is functional, you can get an overview of the basic usage by calling the main entrypoint g4x-helpers --help.
Please refer to the sections below for details on how to run a subcommand.

g4x-helpers --help

CLI usage

Activating your environment

Before getting started, you need to ensure that the environment in which you installed G4X-helpers is activated. How this is done depends on your installation method. We recommend installing it into a Conda environment.

condauv

If you created an environment with the name g4x-helpers_env, you will activate it with the following command:

conda activate g4x-helpers_env

Once activated, your shell prompt should change to include the environment name:

(g4x-helpers_env) $

You can further verify that you’re using the correct interpreter:

(g4x-helpers_env) $ which python
/Users/you/miniconda3/envs/g4x-helpers_env/bin/python

source .venv/bin/activate

Once activated, your shell prompt should change to include the environment name (g4x_helpers is the default):

(g4x-helpers) $

You can further verify that you’re using the correct interpreter:

(g4x-helpers) $ which python
/Users/You/G4X-helpers/.venv/bin/python

Basic command pattern

g4x-helpers [GLOBAL OPTIONS] <command> [OPTIONS] /path/to/g4x_data

Provide global options before the sub-command. Each command then defines its own required and optional arguments, followed by the G4X-DATA positional argument. All workflows assume you have a single-sample G4X output directory and, in some cases, additional input files (e.g. manifests or metadata tables).

Global options

option	default	description
`--threads` / `-t`	half of available CPU cores (minimum 1)	Number of worker threads used by CPU-heavy steps (segmentation, demultiplexing, conversions). Increase to speed up processing or lower it when sharing a server.
`--verbose` / `-v`	`1`	Controls logging detail in the terminal. `0` prints warnings only, `1` shows progress-level logs, `2` enables detailed debugging output.
`--version`	—	Prints the installed `g4x-helpers` version and exits, which is helpful for troubleshooting and documentation.
`--help` / `-h`	—	Standard Click help flag that prints contextual usage information for the command you attach it to.

Tip

Always place global options before the sub-command: g4x-helpers --threads 8 resegment ...

Discovering CLI commands

List every available sub-command and a short description:
```
g4x-helpers --help
```
Show detailed usage and arguments for a specific command (e.g. redemux):
```
g4x-helpers redemux --help
```
Confirm which package version your environment is using:
```
g4x-helpers --version
```

Example: running `resegment` from the CLI

Below we apply a custom cell segmentation to existing data using the resegment sub-command. The command writes results to <G4X-DATA>/g4x_helpers/resegment unless --in-place is set.

g4x-helpers resegment \
    --cell-labels /path/to/custom/segmentation/seg_mask.npz \
    [--labels-key nuclei] \
    [--in-place] \
    /path/to/g4x_output/directory/sample_id

For this run we provide:

argument	value	type
`G4X-DATA`	/path/to/g4x_output/directory/sample_id	directory
`--cell-labels`	/path/to/custom/segmentation/seg_mask.npz	.npz file
`--labels-key`	nuclei (optional)	string
`--in-place`	flag (optional)	—

The full command is:

g4x-helpers resegment \
    --cell-labels /path/to/custom/segmentation/seg_mask.npz \
    --labels-key nuclei \
    /path/to/g4x_output/directory/sample_id

If the command succeeds you'll see the resegment progress log in your terminal.

Docker usage

Pull the G4X-helpers image

If you haven't done so already (maybe you skipped the Docker setup section) you will first need to pull the G4X-helper Docker image. This is done via docker pull, which downloads the image (and all of its layers) from GitHub’s Container Registry ( ghcr.io ) to your local Docker cache.

docker pull ghcr.io/singular-genomics/g4x-helpers:latest

If you want to run a specific version, please refer to the Docker setup section for details.

Basic command pattern

When running via Docker, the pattern is similar to invoking a CLI command, with the exception that all paths and the Docker image need to be specified. Inside the container, always reference the mounted paths (e.g. /data/...), not the host paths (see full example below).

docker run --rm \
  -v /host/path/to/g4x_output:/data/g4x_output \
  [-v /host/path/to/other_inputs:/data/inputs ] \
  ghcr.io/singular-genomics/g4x-helpers:latest \
  g4x-helpers [GLOBAL OPTIONS] <command> [OPTIONS] /data/g4x_output/sample_id

-v host:container mounts your folder to let the container see your files (add additional mounts for manifests or masks as needed).
--rm cleans up the container after it exits.
ghcr.io/singular-genomics/g4x-helpers:latest uses the latest version of G4X-helpers

Example: using `resegment` in Docker

Here we run the same resegment command as in the CLI example above.

docker run --rm \
  -v /path/to/g4x_output/directory:/data/g4x_output \
  -v /path/to/custom/segmentation:/data/inputs \
  ghcr.io/singular-genomics/g4x-helpers:latest \
  g4x-helpers resegment \
    --cell-labels /data/inputs/seg_mask.npz \
    /data/g4x_output/sample_id

Python module

Note

G4X-helpers can also be imported as a Python module, in which case it can provide some convenience functions to access and interact with your data.
Documentation for this will follow in a separate section.

⸻