Bootstrapper Bootstrapper docs

Commands

bs

bs [OPTIONS] COMMAND [ARGS]...

Make dense 3D segmentations of microscopy volumes from sparse 2D labels.

Write a round with bs prepare, then run it with bs run.

  • --version flag

    Show the version and exit.

bs prepare

bs prepare [OPTIONS] PATH

Write the round PATH from the facts of your data.

Answer a short dialogue, or give the facts as flags. A PATH ending in .toml stores the round in one file. On an existing round, bs prepare rewrites each file's run tail from your edits; with --raw and the other volume flags, it first adds a volume to a round folder.

Example: bs prepare round_01 --raw data.zarr/raw/s0 --labels labels/s0 --labelled sparsely

Options (all text):

  • --raw

    The image to segment: a Zarr array or container, a tif, or a folder of 2D images. A glob makes one volume per match. Example: --raw data.zarr/raw/s0

  • --voxel-size

    The raw's voxel size in nm, z y x, when its metadata has none. Example: --voxel-size 50,4,4

  • --labels

    The traced objects to train on, as a path relative to the raw's container or an absolute path. Without labels, training does not use the volume. Example: --labels labels/s0

  • --labelled

    How the labels cover the raw: sparsely, densely, or a mask path (densely labelled within it). Example: --labelled sparsely

  • --untraced

    With sparse labels, what fills the untraced space next to a traced object: other (objects) or background. Example: --untraced background

  • --target-mask

    Segment, refine and evaluate only inside this mask; predict covers the mask array's extent. Example: --target-mask mask/s0

  • --gt

    The ground truth for the evaluate step; 'labels' reuses the labels. bs prepare adds an evaluate step if any volume has ground truth. Example: --gt labels

  • --name

    The volume's name, used in its table names, such as [segment.apical]. The default is the container's file name, such as data-zarr. Example: --name apical

  • --models

    The models in run order, by name or short form; the default fits the labels. Example: --models 2M,3Af2L

bs run

bs run [OPTIONS] PATH

Run the steps of a config file in file order, or the numbered files of a directory.

Each run writes a receipt into runs/ with the keys each step read. Run bs run on a receipt to repeat its steps. Without --only or --from, bs run starts a directory round at its first unfinished or changed step. Use --from 01 to run all steps. For a single-file round, bs run repeats every selected step.

  • --only text, repeatable

    Run only these steps: a kind, kind.name, or a file prefix in a directory

  • --from text

    Run from this step to the end

  • --dry-run flag

    Check the input paths and print what each selected step reads and writes, without running anything

bs view

bs view [OPTIONS] [PATH]...

View a round, one of its steps, a training snapshot or arrays in Neuroglancer.

bs view round_01 shows a round; bs view round_01 04 shows one step. Use -s for a training snapshot; bs view opens any other path as an array. It prints each layer, then the URL.

  • --snapshot / -s directory

    Path to the Zarr container of a snapshot

  • --bind / -b text; default 0.0.0.0

    The address to serve the viewer on

bs train

bs train [OPTIONS] CONFIG_FILE

Train the model of the [train.*] step of CONFIG_FILE.

The options override the values in the config file. A file with several train steps needs --step.

  • --step / -s text

    The train step to run when the file has several

  • --max-iterations / -n integer

    Number of training iterations

  • --save-checkpoints-every / -ce integer

    Save checkpoints every n iterations

  • --save-snapshots-every integer

    Save snapshots every n iterations

  • --voxel-size / -v text

    Voxel size in nm, z y x (space-separated integers)

bs predict

bs predict [OPTIONS] CONFIG_FILE

Run the [predict.*] steps of CONFIG_FILE in file order, or select one with --step.

  • --step / -s text

    The predict step to run when the file has several

  • --roi-offset / -ro text

    ROI offset in world units, z y x (space-separated integers)

  • --roi-shape / -rs text

    ROI shape in world units, z y x (space-separated integers)

  • --num-workers / -w integer

    Number of workers

  • --num-gpus / -ng integer

    Number of GPUs to use

bs segment

bs segment [OPTIONS] CONFIG_FILE

Segment affinities using the [segment] settings in CONFIG_FILE.

Set the method key to ws, mws or cc, or override it with -ws, -mws or -cc.

  • --step text

    The segment step to run when the file has several

  • --ws / -ws flag

    Watershed segmentation (waterz)

  • --mws / -mws flag

    Mutex watershed segmentation

  • --cc / -cc flag

    Connected components segmentation

  • --roi-offset / -ro text

    ROI offset in world units, z y x (space-separated integers)

  • --roi-shape / -rs text

    ROI shape in world units, z y x (space-separated integers)

  • --blockwise / -b flag

    Run ws or mws over many daisy blocks. Without this flag, the blockwise key of the config applies, and an unset key means one block. cc cannot run blockwise.

  • --num-workers / -w integer

    Number of workers, for blockwise segmentation

  • --block-shape / -bs text

    Block shape in voxels, z y x (space-separated integers). Use 'roi' for one block.

  • --block-context / -bc text

    Block context in voxels, z y x, for blockwise segmentation (space-separated integers)

  • --param / -p text, repeatable

    A method parameter that overrides the config, as key=value. Example: -p 'thresholds=[0.2,0.3]'

bs refine

bs refine [OPTIONS] COMMAND [ARGS]...

Refine a segmentation: filter objects, remove or merge ids, mask, or apply morphology.

Each command reads one label array and writes another, block by block.

bs refine mask

bs refine mask [OPTIONS]

Zero every label outside a mask, blockwise.

  • --in-array / -i path, required

    The label array to read.

  • --mask / -m path, required

    The mask array, at the labels' voxel size. Labels become 0 where the mask is 0.

  • --out-array / -o path

    The label array to write. Default: the input path with the suffix _masked.

  • --num-workers / -w integer; default 20

    The number of daisy workers that process the blocks.

bs refine morph

bs refine morph [OPTIONS]

Apply a morphological operation to a labelled volume, blockwise.

Each operation keeps the label ids (multilabel). With --xy, the operation runs on each z-section by itself; otherwise it runs in 3D over the block.

The halo (--context) adds the data around each block, up to the volume edge. Labels agree across block faces when the halo is at least the minimum in the --context help.

  • --in-array / -i path, required

    The label array to read.

  • --out-array / -o path

    The label array to write. Default: append the operation to the input path, such as labels_fill_holes.

  • --op dilate or erode or opening or closing or fill-holes, required

    The morphological operation. fill-holes gives each region that one object encloses that object's id. It always fills background; it absorbs enclosed objects when the region has at most --max-area voxels.

  • --iterations / -n integer; default 1

    The number of iterations for dilate, erode, opening and closing.

  • --max-area integer; default 0

    The largest enclosed region in which fill-holes absorbs objects, in voxels (pixels with --xy), such as 84000. A value of 0 keeps every object.

  • --exclude-ids text

    Label ids that dilate never grows and fill-holes never absorbs, such as 1,4,8. In config files, use exclude_ids = [1, 4, 8].

  • --xy flag

    Apply the operation to each z-section in 2D instead of in 3D.

  • --context / -c integer; default 64

    The halo in voxels, in xy with --xy and otherwise in xy and z. The minimum is the iteration count for dilate and erode, twice the iteration count for opening and closing, and the width of the largest hole plus its wall for fill-holes.

  • --block-size / -b integer; default 2048

    The write-block size in xy, in voxels, rounded to a multiple of the chunk size. In z, each block is one chunk deep.

  • --num-workers / -w integer; default 20

    The number of daisy workers that process the blocks.

bs refine outlier-filter

bs refine outlier-filter [OPTIONS]

Remove objects whose size is an outlier, large or small, blockwise.

The command removes an object when its voxel count differs from the mean by more than num_std standard deviations. The mean and the standard deviation include only the objects of at least min_size voxels.

  • --in-array / -i path, required

    The label array to read.

  • --out-array / -o path

    The label array to write. Default: the input path with the suffix _outlier_filtered.

  • --num-std / -n float; default 3.0

    Remove objects whose size differs from the mean by more than this many standard deviations.

  • --min-size integer; default 0

    Compute the mean and standard deviation from the objects with at least this many voxels.

  • --num-workers / -w integer; default 20

    The number of daisy workers that process the blocks.

  • --dry-run flag

    Print the size cutoffs and the number of objects to remove without writing.

bs refine remap

bs refine remap [OPTIONS]

Remove label ids, merge groups of ids, or both, blockwise.

  • --in-array / -i path, required

    The label array to read.

  • --out-array / -o path

    The label array to write. Default: the input path with the suffix _remapped.

  • --remove-ids / -r text

    Comma-separated label ids to remove (set to 0)

  • --merge-ids / -m text, repeatable

    Comma-separated label ids to merge into the first id of the group. Repeat the option for more groups.

  • --num-workers / -w integer; default 20

    The number of daisy workers that process the blocks.

bs refine size-filter

bs refine size-filter [OPTIONS]

Remove objects outside a [min_size, max_size] voxel-count range, blockwise.

An object is one label id, and its size is its voxel count over the whole volume, even when the object spans blocks. A first pass counts the sizes, and a second pass removes the out-of-range ids block by block.

  • --in-array / -i path, required

    The label array to read.

  • --out-array / -o path

    The label array to write. Default: the input path with the suffix _size_filtered.

  • --min-size integer; default 0

    Remove objects smaller than this many voxels (dust)

  • --max-size integer

    Remove objects larger than this many voxels. With 0 or no value, the command keeps large objects.

  • --num-workers / -w integer; default 20

    The number of daisy workers that process the blocks.

  • --dry-run flag

    Print size statistics and the number of objects to remove without writing.

bs refine z-filter

bs refine z-filter [OPTIONS]

Remove thin objects that span few z-slices, blockwise.

A read-only pass finds the z-extent of each label over the whole volume (max z - min z + 1). A second pass removes the ids whose extent is min_z or less.

  • --in-array / -i path, required

    The label array to read.

  • --out-array / -o path

    The label array to write. Default: the input path with the suffix _z_filtered.

  • --min-z / -z integer; default 1

    Remove objects whose z-extent is this many slices or fewer

  • --num-workers / -w integer; default 20

    The number of daisy workers that process the blocks.

  • --dry-run flag

    Print the total object count and the number of objects to remove without writing.

bs evaluate

bs evaluate [OPTIONS] CONFIG_FILE

Evaluate segmentations using the [evaluate] settings in CONFIG_FILE.

  • --step text

    The evaluate step to run when the file has several

  • --gt / -gt flag

    Evaluate only against ground truth

  • --pred / -p flag

    Evaluate only against predictions

  • --out-result / -o path

    Result JSON path. Each volume gets its own file, and with several checks each file name also gets the check name.

bs utils

bs utils [OPTIONS] COMMAND [ARGS]...

Utility commands for arrays and segmentations.

bs utils bbox

bs utils bbox [OPTIONS]

Crop an array to the bounding box of its positive voxels.

Add padding with --padding. The default output is the input path with the suffix _bbox.

  • --in-array / -i path, required

    Path to the input Zarr array.

  • --out-array / -o path

    Path to the output array

  • --padding / -p integer; default 0

    Padding in voxels on each side of the bounding box, clipped to the input array.

bs utils convert

bs utils convert [OPTIONS]

Convert a 3D image or a directory of 2D images to a Zarr array.

  • --in-path / -i path, required

    Path to the input 3D image, or to a directory of 2D images

  • --out-array / -o path, required

    Path to the output Zarr array

  • --dtype / -d text; default uint8

    Output data type

  • --voxel-size / -vs integer x 3; default 1 1 1

    Size of each voxel in physical units (space-separated integers)

  • --voxel-offset / -vo integer x 3; default 0 0 0

    Offset in voxels (space-separated integers)

  • --axis-names / -ax text x 3; default z y x

    Names of the axes (space-separated strings)

  • --units / -u text x 3; default nm nm nm

    Physical units of the axes (space-separated strings)

  • --crop / -c flag

    Crop to the bounding box of positive voxels

bs utils download-ckpts

bs utils download-ckpts [OPTIONS]

Download the checkpoints of the shipped models.

Use --model-name to select models and --setup-dir to select their destination. Without these options, the command downloads each shipped model's checkpoint to its folder in bootstrapper/models.

Options (all text):

  • --model-name / -m

    The models to download, by name or short form, separated by commas. Example: -m 3Af2M

  • --setup-dir / -s

    The directory to download the checkpoints to

bs utils mask

bs utils mask [OPTIONS]

Write a mask of a Zarr image or labels array, blockwise.

With --mode raw, the mask is the nonzero voxels of the image, closed in xy. With --mode labels, it is labels > 0. The default output of raw/s0 is raw_mask/s0.

  • --in-array / -i path, required

    The path of the input Zarr array

  • --out-array / -o path

    The path of the output mask Zarr array

  • --mode / -m raw or labels, required

    raw masks an image, and labels masks objects

bs utils merge

bs utils merge [OPTIONS]

Apply the merges of a LUTs file to a segmentation, blockwise.

The LUTs file is JSON. Its "merges" maps each new id to the list of ids that merge into it.

  • --in-seg / -i path, required

    The path of the input segmentation Zarr array

  • --out-seg / -o path

    The path of the output segmentation Zarr array

  • --luts / -l path, required

    Path to the LUTs file

bs utils scale-pyramid

bs utils scale-pyramid [OPTIONS]

Create a scale pyramid of a Zarr array, in place.

An array that is not a scale level moves into a group of the same name. It becomes s0 for --mode down, or sN for N upscaling levels. A scale-level input such as raw/s1 keeps its level, unless upscaling needs levels below s0. Downscaling writes higher levels and upscaling writes lower levels, so a lower level is always finer.

  • --in-array / -i path, required

    The path of the input Zarr array, which may already end in a scale level

  • --scales / -s text, repeatable, required

    Spatial scale factors for one level. Repeat -s for each level. Example: -s 2,2,2

  • --chunk-shape / -c text

    Spatial chunk shape in voxels. The default is the input's. Example: -c 64,64,64

  • --mode / -m up or down, required

  • --labels / --image flag

    --labels samples ids. --image averages intensities to downscale and interpolates them to upscale. The default is --labels for uint32, uint64, or a name with label, lbl, ids, mask or seg

bs utils tissue-mask

bs utils tissue-mask [OPTIONS] RAW OUT

Write a tissue mask of a raw array, with no holes.

On each section the mask is raw > 0, closed with a disk of --radius, with its holes filled. A section below half the median tissue coverage takes the OR of its nearest valid sections above and below. Folds and black sections thus stay inside the mask, so bs refine mask keeps their labels.

Example: bs utils tissue-mask vol.zarr/raw/s1 vol.zarr/masks/tissue/s1

  • --radius / -r integer; default 24

    Disk radius in voxels: 24 at 4 nm (about 100 nm), 12 at 8 nm

  • --num-workers / -w integer; default 8

    The number of worker processes. Allow about 80 bytes per voxel of one section (3.8 GB at 4926 x 9750).