Skip to main content

Command Line Scripts/Options

Using rakaia and/or the supported parsers through the Command Line Interface (CLI) will be common for many users. The following article will describe the CLI usage of rakaia, including the various CLI options to configure rakaia sessions at runtime; additionally, we provide dedicated parsers that support rakaia but are not officially part of the API or called through the web-based UI.

rakaia through the CLI​

rakaia can be executed easily from the command line using the following executable once installed:

rakaia

This will enable a local session to be run from http://127.0.0.1:5000/ or http://0.0.0.0:5000/ with the default session parameters. However, rakaia offers a host of customizable runtime configurations that can be enabled, disabled, or changed through the CLI. These options are shown below (note that these are the CLI options as of rakaia v0.23.0). The list of options is also visible with:

rakaia -h

Rakaia CLI Options​

  • -v, --version: Show the current rakaia version then exit.
  • -h, --help: Show the help output and exit.
  • -da, --disable-auto-open: Disable automatically opening the browser when the app is called. Default: auto open
  • -l, --use-local-dialog: Enable a local file dialog with wxPython to browse and read local files. Default: False
  • -p PORT, --port PORT: Set the port for rakaia on local runs. Default: 5000. Other options to consider are 8050, 8080. Setting a custom port will change the local URL to take the form of http://127.0.0.1:{port} such as http://127.0.0.1:8050/
  • -dv --dev-mode: Run the application in dev mode. This will give in-app feedback on errors, but will be slower. Default: not enabled
  • -dt, --disable-threading: Disable threading. By default, threading is enabled. Threading will enable the application to take advantage of multiprocessing on local machines to improve application speed.
  • -dl, --disable-loading: Disable loading on data import and data switching. By default, loading is enabled. rakaia uses dash bootstrap loading for certain inputs to indicate when data are being loaded or manipulated, such as on data import or when large images are being created. The load screens generally help to indicate to users when certain processes have finished, and when the user can proceed with the next input. Disabling load screens will make the application feel smoother for datasets of any size, but it will be more difficult to assess what the application is doing at any specific moment.
  • -dp, --disable-persistence: Disable saving persistent session variable values in the browser. By default, persistence is enabled. Certain input components in the application layout use browser local persistence, where the value is saved in the browser and used in subsequent sessions. This includes certain inputs for canvas appearance such as scalebar and legend parameters. Disabling persistence will result in all components using their default values.
  • -dc, --disable-cache-overwriting: Disable cache overwriting for server side stores. By default, rakaia will overwrite Serverside objects on each callback invocation to save disk space. However, overwriting should be disabled for concurrent sessions that host multiple users, such as containerized or public instances. More information about serverside transformations can be found here
  • -sc SWATCHES, --swatch-colors SWATCHES: Set custom RGB codes for the swatches. rakaia uses default colour swatches with 7 pre-assigned colours that represent the most basic RGB blends, which can be easily selected for channel recolouring:

In certain instances, users may wish to use a custom blend of input swatches to make colour selection more consistent and rapid. The swatches can be specified using a string wrapped in quotations of the form #FF0000,#00FF00,#0000FF,#00FAFF,#FF00FF,#FFFF00,#FFFFFF. The swatches should be in HEX string form.

  • -at {float,int}, --array-type {float,int}: Set the preferred numpy array type for storing arrays in session. Options are float for np.float32, or int for np.uint16. Float arrays will have more precision and may be required for array values between 0 and 1, but uint arrays will likely consume less memory. Default is float

By default, rakaia will store imported data as 32 byte float arrays. Information on numpy dtypes can be found here. To reduce memory consumption and the amount of temporary disk storage required, users can choose to have arrays stored as 16 byte unsigned integers.

In many instances, using integer array types will save up to 50% of the disk space required for storing the same array in float32 format.

This option will work well for the majority of user cases, as arrays are always converted into integers when recoloured and blended in the canvas. However, there are two specific use cases where storing the arrays as float are beneficial or necessary:

  • When the channel array has values between 0 and 1: these values will automatically be converted to 0 or 1 with integer casting, so any decimal precision will be lost for this channel.
  • When the array channel has a maximum value over 65535: Unsigned 16 byte integers in numpy have a maximum positive range of 65535, so any array values that are greater will be clipped to this value

For the use cases above, users are advised to use the default array storage type.

  • -cs --cache-storage: Set the output path for the temporary session caches. Default is the temp directory generated by tempfile. rakaia uses temporary data caches for serverside data transformations to make computations and image manipulation fast and responsive. The temporary caches are stored in the specific cache storage path.
  • -tr THREADS, --threads THREADS: Set the number of threads to use in production mode. Default is 8

Supporting CLI parsers​

The rakaia github has supporting CLI parsers that are not directly part of the web-based application and rakaia API. These scripts are available at https://github.com/camlab-bioml/rakaia/tree/main/cli.

Briefly, this collection of CLI parsers assist with certain CLI-based tasks such headless image blending, autoscaling ROIs, and converting between common annotation formats. Below is a description of each script and its usage:

apply_blend.py​

apply_blend.py takes a series of input files as well as a rakaia-generated session JSON with a compatible panel, and creates a blended image output in either tiff or png format. The script accepts the same raw file extensions as rakaia for imaging files (.mcd, .txt, .tiff, and .h5ad).

Options and usage:

usage: Example:
python apply_blend.py -i first.mcd second.mcd -o out_images/ -p param.json -t tiff

Parse a series of files and apply additive blending with a headless version of rakaia, outputting each file as a tiff.

options:
  -i INPUT [INPUT ...], --input INPUT [INPUT ...]
                        Series of paths to mcd, tiff, txt, or h5ad files
  -o OUTDIR, --outdir OUTDIR
                        Set the output directory where blended tiffs will be written.
  -p PARAMS, --params PARAMS
                        Path to a channel blend parameter JSON in rakaia-compatible output format.
  -v, --verbose         If using verbose, print the current ROI parsing to the console.
  -t TYPE, --type TYPE  Set the type of image output (either png or tiff). Default: tiff.
  -h, --help            Show the help/options menu and exit. Does not execute the script.

autoscale_roi.py​

autoscale_blend.py accepts either .mcd or .txt IMC files and performs per-marker intensity thresholding based on all the ROIs passed. Specifically, it will take a random subset of pixels from every ROI and compute the 99th percentile upper bound for intensity adjustment, thereby giving a more balanced visual scaling parameter in rakaia to better differentiate positive and negative marker expression by region.

Example usage:

usage: Example:
python autoscale_roi.py -i first-mcd second.mcd -o autoscale.json -m mean -v -ex "laser,test,Start,End"

Parse a list input of mcd or tiff files with a common panel and provides a JSON output of auto-scaled intensity values on the upper bound

options:
  -i INPUT [INPUT ...], --input INPUT [INPUT ...]
                        Series of paths to mcd or tiff files
  -h, --help            Show the help/options menu and exit. Does not execute the application.
  -pr PERCENTILE, --percentile PERCENTILE
                        Set the percentile of pixel intensities to use for the upper bound
  -o OUTFILE, --outfile OUTFILE
                        Set the output tiff file. Default is geojson.tiff written to the current directory
  -v, --verbose         If using verbose, print the current ROI parsing to the console.
  -ex EXCLUDE, --keywords-exclude EXCLUDE
                        Pass a string of comma separated keywords to identify ROIs to exclude.
  -s SIZE_LIMIT, --size SIZE_LIMIT
                        Integer dimension threshold. ROIs with an x or y dimension below this value are not considered. Default is 100 pixels
  -ss SUBSAMPLE_SIZE, --subsample-size SUBSAMPLE_SIZE
                        Integer for the number of pixels to subsample per array to compute the percentile.

geojson_to_tiff.py​

geojson_to_tiff.py enables conversion of geoJSON files into a tiff mask, where objects are encoded by integer IDs.
Important: the script requires to user to set the tiff output dimensions, as the geoJSON file does not capture this information.

The script also requires an installation of geopandas:

pip install geopandas==1.1.1

Example usage:

usage: Example:
python geojson_to_tiff.py -i input.geojson -o output.tiff -x 1500 -y 1200 -ht "Lumen"

Convert a geojson file into a greyscale tiff mask array. Requires the user to set the output dimensions of the tiff. Certain annotations can be ignored as holes/blank
in the final output mask.

options:
  -i INPUT, --input INPUT
                        Path input to a geoJSON file
  -h, --help            Show the help/options menu and exit. Does not execute the application.
  -x WIDTH, --width WIDTH
                        Set the width of the output tiff. Default: 1000 pixels
  -y HEIGHT, --height HEIGHT
                        Set the height of the output tiff. Default: 1000 pixels
  -o OUTFILE, --outfile OUTFILE
                        Set the output tiff file. Default is geojson.tiff written to the current directory
  -ht HOLE_TYPES, --hole-types HOLE_TYPES
                        A list of comma separated annotations to treat as holes (i.e. 0 in the final mask)