Command Line Interface

usage: vpt [OPTIONS] COMMAND [arguments]

Commands

Possible choices: run-segmentation, prepare-segmentation, run-segmentation-on-tile, compile-tile-segmentation, derive-entity-metadata, partition-transcripts, sum-signals, update-vzg, convert-geometry, convert-to-ome, convert-to-rgb-ome, extract-image-patch, generate-segmentation-metrics

Options

--processes

Number of parallel processes to use when executing locally

--aws-profile-name

Named profile for AWS access

--aws-access-key

AWS access key from key / secret pair

--aws-secret-key

AWS secret from key / secret pair

--gcs-service-account-key

Path to a google service account key json file. Not needed if google authentication is performed using gcloud

--verbose

Display progress messages during execution

--profile-execution-time

Path to profiler output file

--log-level

Log level value. Level is specified as a number from 1 - 5, corresponding to debug, info, warning, error, crit

--log-file

Path to log output file. If not provided, logs are written to standard output

Sub-commands

run-segmentation

Top-level interface for this CLI which invokes the segmentation functionality of the tool. It is intended for users who would like to run the program with minimal additional configuration. Specifically, it executes: prepare-segmentation, run-segmentation-on-tile, and compile-tile-segmentation.

vpt [OPTIONS] run-segmentation [arguments]

Required arguments

--segmentation-algorithm

Path to a json file that fully specifies the segmentation algorithm to use, including algorithm name, any algorithm specific parameters (including path to weights for new model), stains corresponding to each channel in the algorithm.

--input-images

Input images can be specified in one of three ways:

• The path to a directory of tiff files if the files are named by the MERSCOPE convention.

  Example: /path/to/files/

• The path to a directory of tiff files including a python formatting string specifying the file name.

  Example: /path/to/files/image_{stain}_z{z}.tif

• A regular expression matching the tiff files to be used

  Example: /path/to/files/mosaic_(?P<stain>[\w|-]+)_z(?P<z>[0-9]+).tif

If a formatting string or regular expression are used, it must return values for stain and z (as in the examples above).

--input-micron-to-mosaic

Path to the micron to mosaic pixel transformation matrix.

--output-path

Directory where the segmentation specification json file will be saved as segmentation_specification.json and where the final segmentation results will be saved.

Optional arguments

--tile-size

Number of pixels for the width and height of each tile. Each tile is created as a square. Default: 4096.

--tile-overlap

Overlap between adjacent tiles. Default: 10% of tile size.

--max-row-group-size

Maximum number of rows in row groups inside output parquet files. Cannot be less than 1000

--overwrite

Set flag if you want to use non empty directory and agree that files can be over-written.

prepare-segmentation

Generates a segmentation specification json file to be used for cell segmentation tasks. The segmentation specification json includes specification for the algorithm to run, the paths for all images for each stain for each z index, the micron to mosaic pixel transformation matrix, the number of tiles, and the window coordinates for each tile.

vpt [OPTIONS] prepare-segmentation [arguments]

Required arguments

--segmentation-algorithm

Path to a json file that fully specifies the segmentation algorithm to use, including algorithm name, any algorithm specific parameters (including path to weights for new model), stains corresponding to each channel in the algorithm.

--input-images

Input images can be specified in one of three ways:

• The path to a directory of tiff files if the files are named by the MERSCOPE convention.

  Example: /path/to/files/

• The path to a directory of tiff files including a python formatting string specifying the file name.

  Example: /path/to/files/image_{stain}_z{z}.tif

• A regular expression matching the tiff files to be used

  Example: /path/to/files/mosaic_(?P<stain>[\w|-]+)_z(?P<z>[0-9]+).tif

If a formatting string or regular expression are used, it must return values for stain and z (as in the examples above).

--output-path

Path where the segmentation specification json file will be saved.

--input-micron-to-mosaic

Path to the micron to mosaic pixel transformation matrix.

Optional arguments

--tile-size

Number of pixels for the width and height of each tile. Each tile is created as a square. Default is 4096.

--tile-overlap

Overlap between adjacent tiles. Default is 10% of tile-size.

--overwrite

Set flag if you want to use non empty directory and agree that files can be over-written.

run-segmentation-on-tile

Executes the segmentation algorithm on a specific tile of the mosaic images. This functionality is intended both for visualizing a preview of the segmentation (run only one tile), and for distributing jobs using an orchestration tool such as Nextflow.

vpt [OPTIONS] run-segmentation-on-tile [arguments]

Required arguments

--input-segmentation-parameters

Json file generate by --prepare-segmentation that fully specifies the segmentation to run

--tile-index

Index of the tile to run the segmentation on

Optional arguments

--overwrite

Set flag if you want to use non empty directory and agree that files can be over-written.

compile-tile-segmentation

Combines the per-tile segmentation outputs into a single, internally-consistent parquet file containing all of the segmentation boundaries found in the experiment.

vpt [OPTIONS] compile-tile-segmentation [arguments]

Required arguments

--input-segmentation-parameters

Json file generated by prepare-segmentation that fully specifies the segmentation to run.

Optional arguments

--max-row-group-size

Maximum number of rows in row groups inside output parquet files. Cannot be less than 1000

--overwrite

Set flag if you want to use non empty directory and agree that files can be over-written.

derive-entity-metadata

Uses the segmentation boundaries to calculate the geometric attributes of each Entity. These attributes include the position, volume, and morphological features.

vpt [OPTIONS] derive-entity-metadata [arguments]

Required arguments

--input-boundaries

Path to a micron-space parquet boundary file.

--output-metadata

Path to the output csv file where the entity metadata will be stored.

Optional arguments

--input-entity-by-gene

Path to an existing entity by gene csv.

--overwrite

Set flag if you want to use non empty directory and agree that files can be over-written.

partition-transcripts

Uses the segmentation boundaries to determine which Entity, if any, contains each detected transcript. Outputs an Entity by gene matrix, and may optionally output a detected transcript csv with an additional column indicating the containing Entity.

vpt [OPTIONS] partition-transcripts [arguments]

Required arguments

--input-boundaries

Path to a micron-space parquet boundary file.

--input-transcripts

Path to an existing transcripts csv or parquet file.

--output-entity-by-gene

Path to output the Entity by gene matrix csv file.

Optional arguments

--chunk-size

Number of transcript file lines to be loaded in memory at once. Default: 10,000,000

--output-transcripts

If a filename is provided, a copy of the detected transcripts file will be written with an additional column with the EntityID of the cell or other Entity that contains each transcript (or -1 if the transcript is not contained by any Entity).

--overwrite

Set flag if you want to use non empty directory and agree that files can be over-written.

sum-signals

Uses the segmentation boundaries to find the intensity of each mosaic image in each Entity. Outputs both the summed intensity of the raw images and the summed intensity of high-pass filtered images (reduces the effect of background fluorescence).

vpt [OPTIONS] sum-signals [arguments]

Required arguments

--input-images

Input images can be specified in one of three ways:

• The path to a directory of tiff files if the files are named by the MERSCOPE convention.

  Example: /path/to/files/

• The path to a directory of tiff files including a python formatting string specifying the file name.

  Example: /path/to/files/image_{stain}_z{z}.tif

• A regular expression matching the tiff files to be used

  Example: /path/to/files/mosaic_(?P<stain>[\w|-]+)_z(?P<z>[0-9]+).tif

If a formatting string or regular expression are used, it must return values for stain and z (as in the examples above).

--input-boundaries

Path to a micron-space .parquet boundary file.

--input-micron-to-mosaic

Path to the micron to mosaic pixel transformation matrix.

--output-csv

Path to the csv file where the sum intensities will be stored.

Optional arguments

--overwrite

Set true if you want to use non empty directory and agree that files can be overwritten.

update-vzg

Updates an existing .vzg file with new segmentation boundaries and the corresponding expression matrix. NOTE: This functionality requires enough disk space to unpack the existing .vzg file.

vpt [OPTIONS] update-vzg [arguments]

Required arguments

--input-vzg

Path to an existing vzg file.

--input-boundaries

Path to a micron-space parquet boundary file.

--input-entity-by-gene

Path to the Entity by gene csv file.

--output-vzg

Path where the updated vzg should be saved.

Optional arguments

--input-metadata

Path to an existing entity metadata file.

--input-entity-type

Entity type name for detections in input boundaries file.

--temp-path

Path for temporary folder for unzipping vzg file.

--overwrite

Set flag if you want to use non empty directory and agree that files can be over-written.

convert-geometry

Converts entity boundaries produced by a different tool into a vpt compatible parquet file. In the process, each of the input entities is checked for geometric validity, overlap with other geometries, and assigned a globally-unique EntityID to facilitate other processing steps.

vpt [OPTIONS] convert-geometry [arguments]

Required arguments

--input-boundaries

Regular expression that matches all input segmentation files (geojson or hdf5) that will be processed.

--output-boundaries

The path to the parquet file where segmentation compatible with vpt will be saved.

Optional arguments

--convert-to-3D

Pass if segmentation should be converted from 2D to 3D by replication. Only possible for geojson and parquet input formats.

--input-micron-to-mosaic

Path to the transformation matrix.

--number-z-planes

The number of z planes that should be produced during the conversion from 2D to 3D. Should be specified only if the "--convert-to-3D" argument is passed

--spacing-z-planes

Step size between z-planes, assuming that z-index 0 is 1 “step” above zero. Should be specified only if the "--convert-to-3D" argument is passed

--output-entity-type

String with entity type name. For example: cell, nuclei. Default: cell

--id-mapping-file

Path to csv file where map from source segmentation entity id to EntityID in result will be saved.

--entity-fusion-strategy

String with entity fusion strategy name. One from list: harmonize, union, larger. Default: harmonize

--max-row-group-size

Maximum number of rows in row groups inside output parquet files. Cannot be less than 1000

--overwrite

Set flag if you want to use non empty directory and agree that files can be over-written.

convert-to-ome

Transforms the large 16-bit mosaic tiff images produced by the MERSCOPE into a OME pyramidal tiff.

vpt [OPTIONS] convert-to-ome [arguments]

Required arguments

--input-image

Either a path to a directory or a path to a specific file.

Optional arguments

--output-image

Either a path to a directory or a path to a specific file.

--overwrite

Set flag if you want to use non empty directory and agree that files can be over-written.

convert-to-rgb-ome

Converts up to three flat tiff images into a rgb OME-tiff pyramidal images. If a rgb channel input isn’t specified, the channel will be dark (all 0’s).

vpt [OPTIONS] convert-to-rgb-ome [arguments]

Required arguments

--output-image

Either a path to a directory or a path to a specific file

Optional arguments

--input-image-red

Either a path to a directory or a path to a specific file

--input-image-green

Either a path to a directory or a path to a specific file

--input-image-blue

Either a path to a directory or a path to a specific file

--overwrite

extract-image-patch

Extracts a patch of specified coordinates and channels from the 16-bit mosaic tiff images produced by the MERSCOPE as an 8-bit RGB PNG file

vpt [OPTIONS] extract-image-patch [arguments]

Required arguments

--input-images

Input images can be specified in one of three ways:

• The path to a directory of tiff files if the files are named by the MERSCOPE convention.

  Example: /path/to/files/

• The path to a directory of tiff files including a python formatting string specifying the file name.

  Example: /path/to/files/image_{stain}_z{z}.tif

• A regular expression matching the tiff files to be used

  Example: /path/to/files/mosaic_(?P<stain>[\w|-]+)_z(?P<z>[0-9]+).tif

If a formatting string or regular expression are used, it must return values for stain and z (as in the examples above).

--input-micron-to-mosaic

Path to the micron to mosaic pixel transformation matrix.

--output-patch

Path to the patch PNG file, will append .png to the end if not included in file name.

--center-x

MERSCOPE Vizualizer X coordinate in micron space that will serve as the center of the saved PNG patch

--center-y

MERSCOPE Vizualizer Y coordinate in micron space that will serve as the center of the saved PNG patch

--green-stain-name

The name of the stain that will be used for the green channel of the patch

Optional arguments

--size-x

Number of microns for the width of the patch. Default: 108.

--size-y

Number of microns for the height of the patch. Default: 108.

--input-z-index

The Z plane of the mosaic tiff images to use for the patch. Default: 2.

--red-stain-name

The name of the stain that will be used for the red channel of the patch. Default: None.

--blue-stain-name

The name of the stain that will be used for the blue channel of the patch. Default: None.

--normalization

The name of the normalization method that will be used on each channel of the patch. Default: None.

--overwrite

Set flag if you want to use non empty directory and agree that files can be over-written.

generate-segmentation-metrics

Computes a number of segmentation metrics and figures to assess the quality of cell segmentation

vpt [OPTIONS] generate-segmentation-metrics [arguments]

Required arguments

--input-entity-by-gene

Path to the Entity by gene csv file.

--input-metadata

Path to the output csv file where the entity metadata will be stored.

--input-transcripts

Path to an existing transcripts csv file.

--input-boundaries

Path to a micron-space parquet boundary file.

--input-micron-to-mosaic

Path to the micron to mosaic pixel transformation matrix.

--output-csv

Path to the csv file where segmentation metrics will be stored.

Optional arguments

--input-images

Input images can be specified in one of three ways:

• The path to a directory of tiff files if the files are named by the MERSCOPE convention.

  Example: /path/to/files/

• The path to a directory of tiff files including a python formatting string specifying the file name.

  Example: /path/to/files/image_{stain}_z{z}.tif

• A regular expression matching the tiff files to be used

  Example: /path/to/files/mosaic_(?P<stain>[\w|-]+)_z(?P<z>[0-9]+).tif

If a formatting string or regular expression are used, it must return values for stain and z (as in the examples above).

--experiment-name

The name of the experiment to be used as the index in the output csv and segmentation report. Default: Analysis Timestamp.

--output-report

Path to the output HTML file, will append .html to the end if not included in file name.

--output-clustering

Path where the Cell categories Parquet files with clustering results will be saved.

--input-z-index

The Z plane of the mosaic tiff images to use for the patch. Default: 2.

--red-stain-name

The name of the stain that will be used for the red channel in images. Default: None.

--green-stain-name

The name of the stain that will be used for the red channel in images. Default: PolyT.

--blue-stain-name

The name of the stain that will be used for the blue channel in images. Default: DAPI.

--normalization

The name of the normalization method that will be used on each channel. Default: CLAHE.

--transcript-count-filter-threshold

The cell transcript count threshold used for computing metrics and clustering. Default: 100.

--volume-filter-threshold

The cell volume threshold used for computing metrics and clustering. Default: 200.

--overwrite

Set flag if you want to use non empty directory and agree that files can be over-written.

Run 'vpt COMMAND --help' for more information on a command.