diluvian package

Submodules

diluvian.config module

Global configuration objects.

This module contains boilerplate configuration objects for storing and loading configuration state.

class diluvian.config.BaseConfig

Bases: object

Base class for configuration objects.

String representation yields TOML that should parse back to a dictionary that will initialize the same configuration object.

class diluvian.config.Config(settings_collection=None)

Bases: object

A complete collection of configuration objects.

Attributes

random_seed

(int) Seed for initializing the Python and NumPy random generators.

Methods

from_toml(\*filenames)	Reinitializes this Config from a list of TOML configuration files.
to_toml(filename)

from_toml(*filenames)

Reinitializes this Config from a list of TOML configuration files.

Existing settings are discarded. When multiple files are provided, configuration is overridden by later files in the list.

Parameters:

filenames : interable of str

Filenames of TOML configuration files to load.

to_toml(filename)

class diluvian.config.ModelConfig(settings)

Bases: diluvian.config.BaseConfig

Configuration for non-network aspects of the flood filling model.

Attributes

input_fov_shape	(sequence or ndarray of int) Input field of view shape in voxels for each flood filling move.
output_fov_shape	(sequence or ndarray of int) Output field of view shape in voxels for each flood filling move. Can not be larger than input_fov_shape.
output_fov_move_fraction	(int) Move size as a fraction of the output field of view shape.
v_true, v_false	(float) Soft target values for in-object and out-of-object mask voxels, respectively.
t_move	(float) Threshold mask probability in the move check plane to queue a move to that position.
t_final	(float, optional) Threshold mask probability to produce the final segmentation. Defaults to t_move.
move_check_thickness	(int) Thickness of move check plane in voxels. Setting this greater than 1 is useful to make moves more robust even if the move grid aligns with missing sections or image artifacts.
move_priority	(str) How to prioritize the move queue. Either ‘descending’ to order by descending mask probability in the move check plane (default), ‘proximity’ to prioritize moves minimizing L1 path distance from the seed, or ‘random’.
move_recheck	(bool) If true, when moves are retrieved from the queue a cube in the probability mask will be checked around the move location. If no voxels in this cube are greater than the move threshold, the move will be skipped. The cube size is one move step in each direction.
training_subv_shape	(sequence or ndarray of int, optional) Shape of the subvolumes used during moving training.
validation_subv_shape	(sequence or ndarray of int, optional) Shape of the subvolumes used during training validation.

Methods

subv_moves(shape)

move_step

subv_moves(shape)

training_subv_moves

validation_subv_moves

class diluvian.config.NetworkConfig(settings)

Bases: diluvian.config.BaseConfig

Configuration for the flood filling network architecture.

Attributes

factory	(str) Module and function name for a factory method for creating the flood filling network. This allows a custom architecture to be provided without needing to modify diluvian.
transpose	(bool) If true, any loaded networks will reverse the order of axes for both inputs and outputs. Data is assumed to be ZYX row-major, but old versions of diluvian used XYZ, so this is necessary to load old networks.
rescale_image	(bool) If true, rescale the input image intensity from [0, 1) to [-1, 1).
num_modules	(int) Number of convolution modules to use, each module consisting of a skip link in parallel with num_layers_per_module convolution layers.
num_layers_per_module	(int) Number of layers to use in each organizational module, e.g., the number of convolution layers in each convolution module or the number of convolution layers before and after each down- and up-sampling respectively in a U-Net level.
convolution_dim	(sequence or ndarray of int) Shape of the convolution for each layer.
convolution_filters	(int) Number of convolution filters for each layer.
convolution_activation	(str) Name of the Keras activation function to apply after convolution layers.
convolution_padding	(str) Name of the padding mode for convolutions, either ‘same’ (default) or ‘valid’.
initialization	(str) Name of the Keras initialization function to use for weight initialization of all layers.
output_activation	(str) Name of the Keras activation function to use for the final network output.
dropout_probability	(float) Probability for dropout layers. If zero, no dropout layers will be included.
batch_normalization	(bool) Whether to apply batch normalization. Note that in included networks normalization is applied after activation, rather than before as in the original paper, because this is now more common practice.
unet_depth	(int) For U-Net models, the total number of downsampled levels in the network.
unet_downsample_rate	(sequence or ndarray of int) The frequency in levels to downsample each axis. For example, a standard U-Net downsamples all axes at each level, so this value would be all ones. If data is anisotropic and Z should only be downsampled every other level, this value could be [2, 1, 1]. Axes set to 0 are never downsampled.
unet_downsample_mode: string	The mode to use for downsampling. The two options are “fixed_rate”, which will use the downsample rate previously defined, and “isotropy_approximating”, which will downsample on lower resolution axes until the volume is as isotropic as possible. For example given a volume with resolution [40,4,4] and 4 unet layers, would downsample to [40,8,8],[40,16,16],[40,32,32],[80,64,64]
resolution: sequence or ndarray of int	The resolution of the input image data. This is necessary if you want to use “isotropy_approximating” for unet_downsampling_mode

class diluvian.config.OptimizerConfig(settings)

Bases: diluvian.config.BaseConfig

Configuration for the network optimizer.

Any settings dict entries passed to this initializer will be added as configuration attributes and passed to the optimizer initializer as keyword arguments.

Attributes

klass	(str) Class name of the Keras optimizer to use.
loss	(str) Name of the Keras loss function to use.

class diluvian.config.PostprocessingConfig(settings)

Bases: diluvian.config.BaseConfig

Configuration for segmentation processing after flood filling.

Attributes

closing_shape

(sequence or ndarray of int) Shape of the structuring element for morphological closing, in voxels.

class diluvian.config.TrainingConfig(settings)

Bases: diluvian.config.BaseConfig

Configuration for model training.

Attributes

num_gpus	(int) Number of GPUs to use for data-parallelism.
num_workers	(int) Number of worker queues to use for generating training data.
gpu_batch_size	(int) Per-GPU batch size. The effective batch size will be this times num_gpus.
training_size	(int) Number of samples to use for training from each volume.
validation_size	(int) Number of samples to use for validation from each volume.
total_epochs	(int) Maximum number of training epochs.
reset_generators	(bool) Reset training generators after each epoch, so that the training examples at each epoch are identical.
fill_factor_bins	(sequence of float) Bin boundaries for filling fractions. If provided, sample loss will be weighted to increase loss contribution from less-frequent bins. Otherwise all samples are weighted equally.
partitions	(dict) Dictionary mapping volume name regexes to a sequence of int indicating number of volume partitions along each axis. Only one axis should be greater than 1. Each volume should match at most one regex.
training_partition, validation_partition	(dict) Dictionaries mapping volume name regexes to a sequence of int indicating index of the partitions to use for training and validation, respectively. Each volume should match at most one regex.
validation_metric	(dict) Module and function name for a metric function taking a true and predicted region mask (‘metric’). Boolean of whether to threshold the mask for the metric (true) or use the mask and target probabilities (‘threshold’). String ‘min’ or ‘max’for how to choose best validation metric value (‘mode’).
patience	(int) Number of epochs after the last minimal validation loss to terminate training.
early_abort_epoch	(int) If provided, training will check at the end of this epoch whether validation loss is less than early_abort_loss. If not, training will be aborted, and may be restarted with a new seed depending on CLI options. By default this is disabled.
early_abort_loss	(float) See early_abort_epoch.
label_erosion	(sequence or ndarray of int) Amount to erode label mask for each training subvolume in each dimension, in pixels. For example, a value of [0, 1, 1] will result in erosion with a structuring element of size [1, 3, 3].
relabel_seed_component	(bool) Relabel training subvolumes to only include the seeded connected component.
augment_validation	(bool) Whether validation data should also be augmented.
augment_use_both	(bool) Whether to sequentially use both the augmented and unaugmented version of each subvolume.
augment_mirrors	(sequence of int) Axes along which to mirror for data augmentation.
augment_permute_axes	(sequence of sequence of int) Axis permutations to use for data augmentation.
augment_missing_data	(list of dict) List of dictionaries with axis and prob keys, indicating an axis to perform data blanking along, and the probability to blank each plane in the axis, respectively.
augment_noise	(list of dict) List of dictionaries with axis, mul and add` keys, indicating an axis to perform independent Gaussian noise augmentation on, and the standard deviations of 1-mean multiplicative and 0-mean additive noise, respectively.
augment_contrast	(list of dict) List of dictionaries with axis, prob, scaling_mean, scaling_std, center_mean and center_std keys. These specify the probability to alter the contrast of a section, the mean and standard deviation to draw from a normal distribution to scale contrast, and the mean and standard deviation to draw from a normal distribution to move the intensity center multiplicatively.
augment_missing_data	(list of dict) List of dictionaries with axis, prob and volume_file keys, indicating an axis to perform data artifacting along, the probability to add artifacts to each plane in the axis, and the volume configuration file from which to draw artifacts, respectively.

class diluvian.config.VolumeConfig(settings)

Bases: diluvian.config.BaseConfig

Configuration for the use of volumes.

Attributes

resolution	(sequence or ndarray of float) Resolution to which volumes will be downsampled before processing.
label_downsampling	(str) Method for downsampling label masks. One of ‘majority’ or ‘conjunction’.

diluvian.diluvian module

diluvian.diluvian.evaluate_volume(volumes, gt_name, pred_name, partition=False, border_threshold=None, use_gt_mask=True, relabel=False)

diluvian.diluvian.fill_region_with_model(model_file, volumes=None, partition=False, augment=False, bounds_input_file=None, bias=True, move_batch_size=1, max_moves=None, remask_interval=None, sparse=False, moves=None)

diluvian.diluvian.fill_volume_with_model(model_file, volume, resume_prediction=None, checkpoint_filename=None, checkpoint_label_interval=20, seed_generator='sobel', background_label_id=0, bias=True, move_batch_size=1, max_moves=None, max_bodies=None, num_workers=1, worker_prequeue=1, filter_seeds_by_mask=True, reject_non_seed_components=True, reject_early_termination=False, remask_interval=None, shuffle_seeds=True)

diluvian.diluvian.fill_volumes_with_model(model_file, volumes, filename, resume_filename=None, partition=False, viewer=False, **kwargs)

diluvian.diluvian.generate_subvolume_bounds(filename, volumes, num_bounds, sparse=False, moves=None)

diluvian.diluvian.view_volumes(volumes, partition=False)

Display a set of volumes together in a neuroglancer viewer.

Parameters:

volumes : dict

Dictionary mapping volume name to diluvian.volumes.Volume.

partition : bool

If true, partition the volumes and put the view origin at the validaiton partition origin.

diluvian.network module

Flood-fill network creation and compilation using Keras.

diluvian.network.add_convolution_module(model, network_config)

diluvian.network.add_unet_layer(model, network_config, remaining_layers, output_shape, n_channels=None, resolution=None)

diluvian.network.compile_network(model, optimizer_config)

diluvian.network.load_model(model_file, network_config)

diluvian.network.make_flood_fill_network(input_fov_shape, output_fov_shape, network_config)

Construct a stacked convolution module flood filling network.

diluvian.network.make_flood_fill_unet(input_fov_shape, output_fov_shape, network_config)

Construct a U-net flood filling network.

diluvian.network.make_parallel(model, gpus=None)

diluvian.octrees module

Simple octree data structures for block sparse 3D arrays.

class diluvian.octrees.BranchNode(parent, bounds, **kwargs)

Bases: diluvian.octrees.Node

Methods

count_leaves()
get_child_bounds(i, j, k)
get_children_mask(key)
get_intersection(key)
get_size()
get_volume()
iter_leaves()
map_copy(copy_parent, leaf_map, uniform_map)
populate_child(i, j, k)
replace(replacement)
replace_child(child, replacement)

count_leaves()

get_child_bounds(i, j, k)

get_children_mask(key)

iter_leaves()

map_copy(copy_parent, leaf_map, uniform_map)

populate_child(i, j, k)

replace_child(child, replacement)

class diluvian.octrees.LeafNode(parent, bounds, data)

Bases: diluvian.octrees.Node

Methods

count_leaves()
get_intersection(key)
get_size()
get_volume()
iter_leaves()
map_copy(copy_parent, leaf_map, uniform_map)
replace(replacement)

count_leaves()

iter_leaves()

map_copy(copy_parent, leaf_map, uniform_map)

class diluvian.octrees.Node(parent, bounds, clip_bound=None)

Bases: object

Methods

count_leaves()
get_intersection(key)
get_size()
get_volume()
replace(replacement)

count_leaves()

get_intersection(key)

get_size()

get_volume()

replace(replacement)

class diluvian.octrees.OctreeVolume(leaf_shape, bounds, dtype, populator=None)

Bases: object

Octree-backed block sparse 3D array.

This is a trivial implementation of an octree with NumPy ndarray leaves for block sparse volume access. This allows oblivious in-memory access of dense regions spanning out-of-memory volumes by providing read leaves via a populator. For writing, the octree supports uniform value terminal nodes at every level, so that only non-uniform data must be written to leaf level.

Parameters:

leaf_shape : tuple of int or ndarray

Shape of tree leaves in voxels.

bounds : tuple of tuple of int or ndarray

The lower and upper coordinate bounds of the volume, in voxels.

dtype : numpy.data-type

populator : function, optional

A function taking a tuple of ndarray bounds for the coordinates of the subvolume to populate and returning the data for that subvolume.

Attributes

shape

Methods

fullness()
get_checked_np_key(key)
get_leaf_bounds()
get_volume()
iter_leaves()	Iterator over all non-uniform leaf nodes.
map_copy(dtype, leaf_map, uniform_map)	Create a copy of this octree by mapping node data.
replace_child(child, replacement)

fullness()

get_checked_np_key(key)

get_leaf_bounds()

get_volume()

iter_leaves()

Iterator over all non-uniform leaf nodes.

Yields:LeafNode

map_copy(dtype, leaf_map, uniform_map)

Create a copy of this octree by mapping node data.

Note that because leaves and uniform nodes can have separate mapping, the ranges of this tree and the copied tree may not be bijective.

Populators are not copied.

Parameters:

dtype : numpy.data-type

Data type for the constructed copy

leaf_map : function

Function mapping leaf node data for the constructed copy.

uniform_map : function

Function mapping uniform node values.

Returns:

OctreeVolume

Copied octree with the same structure as this octree.

replace_child(child, replacement)

shape

class diluvian.octrees.UniformBranchNode(parent, bounds, dtype, value, **kwargs)

Bases: diluvian.octrees.UniformNode

Methods

count_leaves()
get_intersection(key)
get_size()
get_volume()
map_copy(copy_parent, leaf_map, uniform_map)
replace(replacement)

class diluvian.octrees.UniformLeafNode(parent, bounds, dtype, value, **kwargs)

Bases: diluvian.octrees.UniformNode

Methods

count_leaves()
get_intersection(key)
get_size()
get_volume()
map_copy(copy_parent, leaf_map, uniform_map)
replace(replacement)

count_leaves()

class diluvian.octrees.UniformNode(parent, bounds, dtype, value, **kwargs)

Bases: diluvian.octrees.Node

Methods

count_leaves()
get_intersection(key)
get_size()
get_volume()
map_copy(copy_parent, leaf_map, uniform_map)
replace(replacement)

map_copy(copy_parent, leaf_map, uniform_map)

diluvian.postprocessing module

Segmentation processing and skeletonization after flood filling.

class diluvian.postprocessing.Body(mask, seed)

Bases: object

Methods

get_largest_component([closing_shape])
get_seeded_component([closing_shape])
is_seed_in_mask()
to_swc(filename)

get_largest_component(closing_shape=None)

get_seeded_component(closing_shape=None)

is_seed_in_mask()

to_swc(filename)

diluvian.postprocessing.skeleton_to_swc(skeleton, offset, resolution)

diluvian.postprocessing.skeletonize_component(component)

diluvian.preprocessing module

Volume preprocessing for seed generation and data augmentation.

diluvian.preprocessing.grid_seeds(image_data, _, grid_step_spacing=1)

Create seed locations in a volume on a uniform grid.

Parameters:image_data : ndarray Returns:list of ndarray

diluvian.preprocessing.intensity_distance_seeds(image_data, resolution, axis=0, erosion_radius=16, min_sep=24, visualize=False)

Create seed locations maximally distant from a Sobel filter.

Parameters:

image_data : ndarray

resolution : ndarray

axis : int, optional

Axis along which to slices volume to generate seeds in 2D. If None volume is processed in 3D.

erosion_radius : int, optional

L_infinity norm radius of the structuring element for eroding components.

min_sep : int, optional

L_infinity minimum separation of seeds in nanometers.

Returns:

list of ndarray

diluvian.preprocessing.make_prewitt(size)

Construct a separable Prewitt gradient convolution of a given size.

Adapted from SciPy’s ndimage prewitt.

Parameters:

size : int

1-D size of the filter (should be odd).

diluvian.regions module

class diluvian.regions.Region(image, target=None, seed_vox=None, mask=None, sparse_mask=False, block_padding=None)

Bases: object

A region (single seeded body) for flood filling.

This object contains the necessary data to perform flood filling for a single body.

Parameters:

image : ndarray or diluvian.octrees.OctreeVolume

Raw image data. If it is an octree, it is assumed all volumetric storage should also operate block-sparsely and there is no ground truth available.

target : ndarray, optional

Target mask probabilities (ground truth converted to network targets).

seed_vox : ndarray, optional

Coordinates of the seed voxel.

mask : ndarray, optional

Object prediction mask for output. Provided as an argument here in case resuming or extending an existing result.

sparse_mask : bool, optional

If true, force the predicted mask to be a block-sparse array instead of a dense ndarray. Note that if image is a diluvian.octrees.OctreeVolume, the mask will be sparse regardless of this parameter.

block_padding : str, optional

Method to use to pad data when the network’s input field of view extends outside the region bounds. This is passed to numpy.pad. Defaults to None, which indicates attempts to operate outside the region bounds are erroneous.

Attributes

bias_against_merge	(bool) Whether to bias against merge by never overwriting mask probabilities less than 0.5 once they have been written.
move_based_on_new_mask	(bool) Whether to generate moves based on the probabilities only in the newly predicted mask block (if true), or on the mask block once combined with the existing probability mask (if false).
move_check_thickness	(int) Thickness in voxels to check around the move plane in each direction when determining which moves to queue. See get_moves method.

Methods

EarlyFillTermination
add_mask(mask_block, mask_pos)
check_move_neighborhood(mask)	Given a mask block, check if any central voxels meet move threshold.
fill(model[, progress, move_batch_size, ...])	Flood fill this region.
fill_animation(movie_filename, \*args, \*\*kwargs)	Create an animated movie of the filling process for this region.
fill_render(model[, save_movie])
from_subvolume(subvolume, \*\*kwargs)
from_subvolume_generator(subvolumes, \*\*kwargs)
get_block_bounds(vox, shape[, offset])	Get the bounds of a block by center and shape, accounting padding.
get_move_priority(pos, value[, proximity])
get_moves(mask)	Given a mask block, get maximum probability in each move direction.
get_next_block()
get_viewer([transpose])
pos_in_bounds(pos)
pos_to_vox(pos)
prediction_metric(metric[, threshold])
remask()	Reset the mask based on the seeded connected component.
render_body()
to_body()
unfilled_copy()	Clone this region in an initial state without any filling.
vox_to_pos(vox)

exception EarlyFillTermination

Bases: exceptions.Exception

Region.add_mask(mask_block, mask_pos)

Region.check_move_neighborhood(mask)

Given a mask block, check if any central voxels meet move threshold.

Checks whether a cube one move in each direction from the mask center contains any probabilities greater than the move threshold.

Parameters:

mask : ndarray

Block of mask probabilities, usually of the shape specified by the configured output_fov_shape.

Returns:

bool

Region.fill(model, progress=False, move_batch_size=1, max_moves=None, stopping_callback=None, remask_interval=None, generator=False)

Flood fill this region.

Note this returns a generator, so must be iterated to start filling.

Parameters:

model : keras.models.Model

Model to use for object prediction.

progress : bool or int, optional

Whether to display a progress bar. If an int, indicates the progress bar is nested and should appear at that level.

move_batch_size : int, optional

Number of moves to process in parallel. Note that in the algorithm as originally described this is 1, because otherwise moves’ outputs may affect each other or the queue. Setting this higher can increase throughput.

max_moves : int, optional

Terminate filling after this many moves even if the queue is not empty.

stopping_callback : function, optional

Function periodical called that will terminate filling if it returns true.

remask_interval : int, optional

Frequency in moves to reset the mask to be based on the morphological seed connected component. This is useful to discourage long-running fills due to runaway merging. Only sensible when using move rechecking, proximity priority, and rejecting non-seeded connected components.

generator : bool

If true, each tuple of batch inputs and outputs will be yielded.

Yields:

tuple

Batch inputs and outputs if generator is true.

Raises:

Region.EarlyFillTermination

If filling was terminated early due to either exceeding the maximum number of moves or the stopping callback.

Region.fill_animation(movie_filename, *args, **kwargs)

Create an animated movie of the filling process for this region.

Parameters:

movie_filename : str

File name of the MP4 movie to be saved.

*args, **kwargs

Passed to fill.

Region.fill_render(model, save_movie=True, **kwargs)

static Region.from_subvolume(subvolume, **kwargs)

static Region.from_subvolume_generator(subvolumes, **kwargs)

Region.get_block_bounds(vox, shape, offset=None)

Get the bounds of a block by center and shape, accounting padding.

Returns the voxel bounds of a block specified by shape and center in the region, clamping the bounds to be in the volume but returning padding margins that extend outside the region bounds.

Parameters:

vox : ndarray

Center of the block in voxel coordinates.

shape : ndarray

Shape of the block.

offset : ndarray, optional

If provided, offset of coordinates from the volume where these bounds where be used. This is needed if the volume has a margin (i.e., is smaller than the main region volume), such as the target volume for contracted output shapes.

Returns:

block_min, block_max : ndarray

Extents of the block in voxel coordinates clamped to the region bounds.

padding_pre, padding_post : ndarray

How much the block extends outside the region bounds.

Region.get_move_priority(pos, value, proximity=None)

Region.get_moves(mask)

Given a mask block, get maximum probability in each move direction.

Checks each of six planes comprising a centered cube half the shape of the provided block. For each of these planes, the maximum probability in the mask block is returned along with the move direction.

Unlike the original implementation, this will check an n-voxel thick slab of voxels around each pane specified by this region’s move_check_thickness property. This is useful for overcoming artifacts that may only affect a single plane that happens to align with the move grid.

Parameters:

mask : ndarray

Block of mask probabilities, usually of the shape specified by the configured output_fov_shape.

Returns:

list of dict

Each dict should include a move ndarray unit vector indicating the move direction and a v indicating the max probability in the move plane in that direction.

Region.get_next_block()

Region.get_viewer(transpose=False)

Region.pos_in_bounds(pos)

Region.pos_to_vox(pos)

Region.prediction_metric(metric, threshold=True, **kwargs)

Region.remask()

Reset the mask based on the seeded connected component.

Region.render_body()

Region.to_body()

Region.unfilled_copy()

Clone this region in an initial state without any filling.

Returns:Region

Region.vox_to_pos(vox)

diluvian.regions.mask_to_output_target(mask)

diluvian.training module

Functions for generating training data and training networks.

class diluvian.training.DataGenerator

Bases: tuple

Attributes

callbacks	Alias for field number 2
data	Alias for field number 0
gens	Alias for field number 1
steps_per_epoch	Alias for field number 3

Methods

count(...)
index((value, [start, ...)	Raises ValueError if the value is not present.

callbacks

Alias for field number 2

data

Alias for field number 0

gens

Alias for field number 1

steps_per_epoch

Alias for field number 3

class diluvian.training.EarlyAbort(monitor='val_loss', threshold_epoch=None, threshold_value=None)

Bases: keras.callbacks.Callback

Keras epoch end callback that aborts if a metric is above a threshold.

This is useful when convergence is sensitive to initial conditions and models are obviously not useful to continue training after only a few epochs. Unlike the early stopping callback, this is considered an abnormal termination and throws an exception so that behaviors like restarting with a new random seed are possible.

Methods

on_batch_begin(batch[, logs])
on_batch_end(batch[, logs])
on_epoch_begin(epoch[, logs])
on_epoch_end(epoch[, logs])
on_train_begin([logs])
on_train_end([logs])
set_model(model)
set_params(params)

on_epoch_end(epoch, logs=None)

exception diluvian.training.EarlyAbortException

Bases: exceptions.Exception

class diluvian.training.GeneratorReset(gens)

Bases: keras.callbacks.Callback

Keras epoch end callback to reset prediction copy kludges.

Methods

on_batch_begin(batch[, logs])
on_batch_end(batch[, logs])
on_epoch_begin(epoch[, logs])
on_epoch_end(epoch[, logs])
on_train_begin([logs])
on_train_end([logs])
set_model(model)
set_params(params)

on_epoch_end(epoch, logs=None)

class diluvian.training.GeneratorSubvolumeMetric(gens, metric_name)

Bases: keras.callbacks.Callback

Add a data generator’s subvolume metric to Keras’ metric logs.

Parameters:

gens : iterable of diluvian.training.MovingTrainingGenerator

metric_name : string

Methods

on_batch_begin(batch[, logs])
on_batch_end(batch[, logs])
on_epoch_begin(epoch[, logs])
on_epoch_end(epoch[, logs])
on_train_begin([logs])
on_train_end([logs])
set_model(model)
set_params(params)

on_epoch_end(epoch, logs=None)

class diluvian.training.MovingTrainingGenerator(subvolumes, batch_size, kludge, f_a_bins=None, reset_generators=True, subv_per_epoch=None, subv_metric_fn=None, subv_metric_threshold=False, subv_metric_args=None)

Bases: six.Iterator

Generate Keras moving FOV training tuples from a subvolume generator.

This generator expects a subvolume generator that will provide subvolumes larger than the network FOV, and will allow the output of training at one batch to generate moves within these subvolumes to produce training data for the subsequent batch.

Parameters:

subvolumes : generator of Subvolume

batch_size : int

kludge : dict

A kludge object to allow this generator to provide inputs and receive outputs from the network. See diluvian.training.patch_prediction_copy.

f_a_bins : sequence of float, optional

Bin boundaries for filling fractions. If provided, sample loss will be weighted to increase loss contribution from less-frequent f_a bins. Otherwise all samples are weighted equally.

reset_generators : bool

Whether to reset subvolume generators when this generator is reset. If true subvolumes will be sampled in the same order each epoch.

subv_per_epoch : int, optional

If specified, the generator will only return moves from this many subvolumes before being reset. Once this number of subvolumes is exceeded, the generator will yield garbage batches (this is necessary because Keras currently uses a fixed number of batches per epoch). If specified, once each subvolume is complete its total loss will be calculated.

subv_metric_fn : function, option

Metric function to run on subvolumes when subv_per_epoch is set.

subv_metric_threshold : bool, optional

Whether to threshold subvolume masks for metrics.

subv_metric_args : dict, optional

Keyword arguments that will be passed to the subvolume metric.

Methods

get_epoch_metric()
next()
reset()

get_epoch_metric()

reset()

diluvian.training.augment_subvolume_generator(subvolume_generator)

Apply data augmentations to a subvolume generator.

Parameters:subvolume_generator : diluvian.volumes.SubvolumeGenerator Returns:diluvian.volumes.SubvolumeGenerator

diluvian.training.build_training_gen(training_volumes)

diluvian.training.build_validation_gen(validation_volumes)

diluvian.training.get_output_margin(model_config)

diluvian.training.patch_prediction_copy(model)

Patch a Keras model to copy outputs to a kludge during training.

This is necessary for mask updates to a region during training.

Parameters:model : keras.engine.Model

diluvian.training.plot_history(history)

diluvian.training.preprocess_subvolume_generator(subvolume_generator)

Apply non-augmentation preprocessing to a subvolume generator.

Parameters:subvolume_generator : diluvian.volumes.SubvolumeGenerator Returns:diluvian.volumes.SubvolumeGenerator

diluvian.training.train_network(model_file=None, volumes=None, model_output_filebase=None, model_checkpoint_file=None, tensorboard=False, viewer=False, metric_plot=False)

diluvian.training.validate_model(model_file, volumes)

diluvian.util module

class diluvian.util.Roundrobin(*iterables, **kwargs)

Bases: six.Iterator

Iterate over a collection of iterables, pulling one item from each in a cycle.

Based on a generator function recipe credited to George Sakkis on the python docs itertools recipes.

Examples

>>> list(Roundrobin('ABC', 'D', 'EF'))
['A', 'D', 'E', 'B', 'F', 'C']

Methods

next()
reset()

reset()

class diluvian.util.WrappedViewer(voxel_coordinates=None, **kwargs)

Bases: neuroglancer.viewer.Viewer

Methods

add(\*args, \*\*kwargs)
get_encoded_state()
get_json_state()
get_server_url()
get_viewer_url()
open_in_browser()
print_view_prompt()
register_volume(volume)

get_json_state()

open_in_browser()

print_view_prompt()

diluvian.util.binary_confusion_matrix(y, y_pred)

diluvian.util.binary_crossentropy(y, y_pred, eps=1e-15)

diluvian.util.binary_f_score(y, y_pred, beta=1.0)

diluvian.util.confusion_f_score(cm, beta)

diluvian.util.extend_keras_history(a, b)

diluvian.util.get_color_shader(channel, normalized=True)

diluvian.util.get_function(name)

diluvian.util.get_nonzero_aabb(a)

Get the axis-aligned bounding box of nonzero elements of a 3D array.

Parameters:

a : ndarray

A 3D NumPpy array.

Returns:

tuple of ndarray

diluvian.util.pad_dims(x)

Add single-dimensions to the beginning and end of an array.

diluvian.util.write_keras_history_to_csv(history, filename)

Write Keras history to a CSV file.

If the file already exists it will be overwritten.

Parameters:

history : keras.callbacks.History

filename : str

diluvian.volumes module

Volumes of raw image and labeled object data.

class diluvian.volumes.ClipSubvolumeImageGenerator(subvolume_generator, min_val=0.0, max_val=1.0)

Bases: six.Iterator

Clip subvolume image range (default between zero and one).

Useful to apply after a sequence of augmentations.

Parameters:

subvolume_generator : SubvolumeGenerator

min_val, max_val : float, optional

Attributes

shape

Methods

next()
reset()

reset()

shape

class diluvian.volumes.ContrastAugmentGenerator(subvolume_generator, return_both, axis, probability, scaling_mean, scaling_std, center_mean, center_std)

Bases: diluvian.volumes.SubvolumeAugmentGenerator

Repeats subvolumes from a subvolume generator with altered contrast.

For each subvolume in the original generator, this generator will yield the original subvolume and may yield a subvolume with image intensity contrast.

Currently this augmentation performs simple rescaling of intensity values, not histogram based methods. This simple approach still yields results resembling TEM artifacts. A single rescaling is chosen for all selected sections in each subvolume, not independently per selected section.

Parameters:

subvolume_generator : SubvolumeGenerator

return_both : bool

If true, return both the original and augmented volume in sequence. If false, return either with equal probability.

axis : int

Axis along which contrast may be altered. For example, 0 will alter contrast by z-sections.

probability : float

Independent probability that each plane of data along axis is altered.

scaling_mean, scaling_std, center_mean, center_std : float

Normal distribution parameters for the rescaling of intensity values.

Attributes

shape

Methods

augment_subvolume()
next()
reset()

augment_subvolume()

class diluvian.volumes.DimOrder

Bases: tuple

Attributes

X	Alias for field number 0
Y	Alias for field number 1
Z	Alias for field number 2

Methods

count(...)
index((value, [start, ...)	Raises ValueError if the value is not present.

X

Alias for field number 0

Y

Alias for field number 1

Z

Alias for field number 2

class diluvian.volumes.DownsampledVolume(parent, downsample)

Bases: diluvian.volumes.VolumeView

Wrap an existing volume for downsampled access.

Subvolume accesses to this volume will be downsampled, but continue to use the wrapped volume and its data at the original resolution.

Parameters:

parent : Volume

The volume to wrap.

downsample : iterable of int

Integral zoom levels to downsample the wrapped volume.

Attributes

mask_bounds
shape

Methods

SubvolumeBoundsGenerator(volume, shape[, ...])	Methods
downsample(resolution)
get_subvolume(bounds)
local_coord_to_world(a)
local_to_parent(a)
parent_to_local(a)
partition(partitioning, partition_index)
sparse_wrapper(\*args)
subvolume_bounds_generator([shape, label_margin])
subvolume_generator([bounds_generator])
world_coord_to_local(a)
world_mat_to_local(m)

get_subvolume(bounds)

local_to_parent(a)

parent_to_local(a)

shape

class diluvian.volumes.ErodedMaskGenerator(subvolume_generator, erosion_px)

Bases: six.Iterator

Attributes

shape

Methods

next()
reset()

reset()

shape

class diluvian.volumes.GaussianNoiseAugmentGenerator(subvolume_generator, return_both, axis, multiplicative, additive)

Bases: diluvian.volumes.SubvolumeAugmentGenerator

Repeats subvolumes from a subvolume generator with Gaussian noise.

For each subvolume in the original generator, this generator will yield two subvolumes: the original subvolume and the subvolume with multiplicative and additive Gaussian noise applied to the image data.

Parameters:

subvolume_generator : SubvolumeGenerator

return_both : bool

If true, return both the original and augmented volume in sequence. If false, return either with equal probability.

axis : int

Axis along which noise will be applied independently. For example, 0 will apply different noise to each z-section. -1 will apply uniform noise to the entire subvolume.

multiplicative : float

Standard deviation for 1-mean Gaussian multiplicative noise.

multiplicative : float

Standard deviation for 0-mean Gaussian additive noise.

Attributes

shape

Methods

augment_subvolume()
next()
reset()

augment_subvolume()

class diluvian.volumes.HDF5Volume(orig_file, image_dataset, label_dataset, mask_dataset, mask_bounds=None)

Bases: diluvian.volumes.Volume

A volume backed by data views to HDF5 file arrays.

Parameters:

orig_file : str

Filename of the HDF5 file to load.

image_dataaset : str

Full dataset path including groups to the raw image data array.

label_dataset : str

Full dataset path including groups to the object label data array.

Attributes

mask_bounds
shape

Methods

SubvolumeBoundsGenerator(volume, shape[, ...])	Methods
downsample(resolution)
from_toml(filename)
get_subvolume(bounds)
local_coord_to_world(a)
partition(partitioning, partition_index)
sparse_wrapper(\*args)
subvolume_bounds_generator([shape, label_margin])
subvolume_generator([bounds_generator])
to_memory_volume()
world_coord_to_local(a)
world_mat_to_local(m)
write_file(filename, resolution, \*\*kwargs)

static from_toml(filename)

to_memory_volume()

static write_file(filename, resolution, **kwargs)

class diluvian.volumes.ImageStackVolume(bounds, orig_resolution, translation, tile_width, tile_height, tile_format_url, zoom_level=0, missing_z=None, image_leaf_shape=None)

Bases: diluvian.volumes.Volume

A volume for block sparse access to image pyramids over HTTP.

Real: Physical coordinates, generally measured in nanometers World: pixel coordinates, starts at (0,0,0) and accounts for pixel resolution

often (4x4x40) nanometers per pixel

Local: Downsampled pixel space

Parameters:

bounds : iterable of int

Shape of the stack at zoom level 0 in pixels.

resolution : iterable of float

Resolution of the stack at zoom level 0 in nm.

tile_width, tile_height : int

Size of tiles in pixels

format_url : str

Format string for building tile URLs from tile parameters.

zoom_level : int, optional

Zoom level to use for this volume.

missing_z : iterable of int, optional

Voxel z-indices where data is not available.

image_leaf_shape : tuple of int or ndarray, optional

Shape of image octree leaves in voxels. Defaults to 10 stacked tiles.

label_leaf_shape : tuple of int or ndarray, optional

Shape of label octree leaves in voxels. Defaults to FFN model FOV.

Attributes

mask_bounds
resolution
shape

Methods

SparseSubvolumeBoundsGenerator(volume, margin)	Attributes
SubvolumeBoundsGenerator(volume, shape[, ...])	Methods
downsample(resolution)
from_catmaid_stack(stack_info, ...)
from_toml(filename)
get_subvolume(bounds)
image_populator(bounds)
local_coord_to_world(a)
partition(partitioning, partition_index)
real_coord_to_world(a)
sparse_wrapper(\*args)
subvolume_bounds_generator([sparse_margin])
subvolume_generator([bounds_generator])
world_coord_to_local(a)
world_coord_to_real(a)
world_mat_to_local(m)

class SparseSubvolumeBoundsGenerator(volume, margin)

Bases: six.Iterator

Attributes

shape

Methods

next()
reset()

reset()

shape

ImageStackVolume.downsample(resolution)

static ImageStackVolume.from_catmaid_stack(stack_info, tile_source_parameters)

ImageStackVolume.from_toml(filename)

ImageStackVolume.get_subvolume(bounds)

ImageStackVolume.image_populator(bounds)

ImageStackVolume.local_coord_to_world(a)

ImageStackVolume.real_coord_to_world(a)

ImageStackVolume.resolution

ImageStackVolume.subvolume_bounds_generator(sparse_margin=None, **kwargs)

ImageStackVolume.world_coord_to_local(a)

ImageStackVolume.world_coord_to_real(a)

class diluvian.volumes.MaskedArtifactAugmentGenerator(subvolume_generator, return_both, axis, probability, artifact_volume_file, cache)

Bases: diluvian.volumes.SubvolumeAugmentGenerator

Repeats subvolumes from a subvolume generator with artifact data added.

For each subvolume in the original generator, this generator will yield the original subvolume and may yield a subvolume with planes of image mixed with artifact data from a separate volume.

Parameters:

subvolume_generator : SubvolumeGenerator

return_both : bool

If true, return both the original and augmented volume in sequence. If false, return either with equal probability.

axis : int

probability : float

Independent probability that each plane of data along axis has artifacts.

artifact_volume_file : string

Filename of an TOML descriptor of an HDF5 dataset with image and mask data channels. Only the dataset named ‘Artifacts’ from this descriptor will be used. Mask data should be a float that will be interpreted as an alpha for blending image data from this artifact file with the original subvolume image data.

Attributes

shape

Methods

augment_subvolume()
next()
reset()

augment_subvolume()

class diluvian.volumes.MirrorAugmentGenerator(subvolume_generator, return_both, axis)

Bases: diluvian.volumes.SubvolumeAugmentGenerator

Repeats subvolumes from a subvolume generator mirrored along an axis.

For each subvolume in the original generator, this generator will yield two subvolumes: the original subvolume and the subvolume with the image, label mask, and seed mirrored along a given axis.

Parameters:

subvolume_generator : SubvolumeGenerator

return_both : bool

If true, return both the original and augmented volume in sequence. If false, return either with equal probability.

axis : int

Attributes

shape

Methods

augment_subvolume()
next()
reset()

augment_subvolume()

class diluvian.volumes.MissingDataAugmentGenerator(subvolume_generator, return_both, axis, probability, remove_label=False)

Bases: diluvian.volumes.SubvolumeAugmentGenerator

Repeats subvolumes from a subvolume generator with missing data planes.

For each subvolume in the original generator, this generator will yield the original subvolume and may yield a subvolume with missing planes of image and/or label mask data.

Parameters:

subvolume_generator : SubvolumeGenerator

return_both : bool

If true, return both the original and augmented volume in sequence. If false, return either with equal probability.

axis : int

probability : float

Independent probability that each plane of data along axis is missing.

remove_label : bool

Whether to also remove label mask data.

Attributes

shape

Methods

augment_subvolume()
next()
reset()

augment_subvolume()

class diluvian.volumes.NdarrayVolume(*args, **kwargs)

Bases: diluvian.volumes.Volume

A NumPy ndarray-backed volume.

Since all volumes assume image and label data are ndarray-like, this class exists mostly as a bookkeeping convenience to make actual ndarray volumes explicit.

Attributes

mask_bounds
shape

Methods

SubvolumeBoundsGenerator(volume, shape[, ...])	Methods
downsample(resolution)
get_subvolume(bounds)
local_coord_to_world(a)
partition(partitioning, partition_index)
sparse_wrapper(\*args)
subvolume_bounds_generator([shape, label_margin])
subvolume_generator([bounds_generator])
world_coord_to_local(a)
world_mat_to_local(m)

class diluvian.volumes.PartitionedVolume(parent, partitioning, partition_index)

Bases: diluvian.volumes.VolumeView

Wrap an existing volume for partitioned access.

Subvolume accesses to this volume will be offset and clipped to a partition of the wrapped volume.

Parameters:

parent : Volume

The volume to wrap.

partitioning : iterable of int

Number of partitions along each axis. Only one axis should be greater than 1.

partition_index : iterable of int

Index of the partition which this volume will represent.

Attributes

mask_bounds
shape

Methods

SubvolumeBoundsGenerator(volume, shape[, ...])	Methods
downsample(resolution)
get_subvolume(bounds)
local_coord_to_world(a)
local_to_parent(a)
parent_to_local(a)
partition(partitioning, partition_index)
sparse_wrapper(\*args)
subvolume_bounds_generator([shape, label_margin])
subvolume_generator([bounds_generator])
world_coord_to_local(a)
world_mat_to_local(m)

local_to_parent(a)

mask_bounds

parent_to_local(a)

shape

class diluvian.volumes.PermuteAxesAugmentGenerator(subvolume_generator, return_both, axes)

Bases: diluvian.volumes.SubvolumeAugmentGenerator

Repeats subvolumes from a subvolume generator with an axes permutation.

For each subvolume in the original generator, this generator will yield two subvolumes: the original subvolume and the subvolume with the image, label mask, and seed axes permuted according to a given axes order.

Parameters:

subvolume_generator : SubvolumeGenerator

return_both : bool

If true, return both the original and augmented volume in sequence. If false, return either with equal probability.

axes : sequence of int

Attributes

shape

Methods

augment_subvolume()
next()
reset()

augment_subvolume()

class diluvian.volumes.RelabelSeedComponentGenerator(subvolume_generator)

Bases: six.Iterator

Attributes

shape

Methods

next()
reset()

reset()

shape

class diluvian.volumes.SparseWrappedVolume(parent, image_leaf_shape=None, label_leaf_shape=None)

Bases: diluvian.volumes.VolumeView

Wrap a existing volume for memory cached block sparse access.

Attributes

mask_bounds
shape

Methods

SubvolumeBoundsGenerator(volume, shape[, ...])	Methods
downsample(resolution)
get_subvolume(bounds)
image_populator(bounds)
label_populator(bounds)
local_coord_to_world(a)
local_to_parent(a)
parent_to_local(a)
partition(partitioning, partition_index)
sparse_wrapper(\*args)
subvolume_bounds_generator([shape, label_margin])
subvolume_generator([bounds_generator])
world_coord_to_local(a)
world_mat_to_local(m)

image_populator(bounds)

label_populator(bounds)

class diluvian.volumes.Subvolume(image, label_mask, seed, label_id)

Bases: object

A subvolume of image data and an optional ground truth object mask.

Methods

f_a()	Calculate the mask filling fraction of this subvolume.
has_seed_in_mask()
has_uniform_seed_margin([seed_margin])	Test if a subvolume has a margin of uniform label around its seed.

f_a()

Calculate the mask filling fraction of this subvolume.

Returns:

float

Fraction of the subvolume voxels in the object mask.

has_seed_in_mask()

has_uniform_seed_margin(seed_margin=20.0)

Test if a subvolume has a margin of uniform label around its seed.

Parameters:

seed_margin : float, optional

The minimum acceptable margin of uniform target label around the seed voxel (in nm, default 20.0).

Returns:

bool

True if the rectangular margin around the seed position is uniform.

image

label_id

label_mask

seed

class diluvian.volumes.SubvolumeAugmentGenerator(subvolume_generator, return_both)

Bases: six.Iterator

Base class for subvolume generator augmenters.

Parameters:

subvolume_generator : SubvolumeGenerator

return_both : bool

If true, return both the original and augmented volume in sequence. If false, return either with equal probability.

Attributes

shape

Methods

augment_subvolume()
next()
reset()

augment_subvolume()

reset()

shape

class diluvian.volumes.SubvolumeBounds(start=None, stop=None, seed=None, label_id=None, label_margin=None)

Bases: object

Sufficient parameters to extract a subvolume from a volume.

Methods

iterable_from_csv(filename)
iterable_to_csv(bounds, filename)

classmethod iterable_from_csv(filename)

classmethod iterable_to_csv(bounds, filename)

label_id

label_margin

seed

start

stop

class diluvian.volumes.SubvolumeGenerator(volume, bounds_generator)

Bases: six.Iterator

Combines a volume and a subvolume bounds generator into a generator.

Parameters:

volume : Volume

bounds_generator : SubvolumeBoundsGenerator

Attributes

shape

Methods

next()
reset()

reset()

shape

class diluvian.volumes.Volume(resolution, image_data=None, label_data=None, mask_data=None)

Bases: object

Attributes

mask_bounds
shape

Methods

SubvolumeBoundsGenerator(volume, shape[, ...])	Methods
downsample(resolution)
get_subvolume(bounds)
local_coord_to_world(a)
partition(partitioning, partition_index)
sparse_wrapper(\*args)
subvolume_bounds_generator([shape, label_margin])
subvolume_generator([bounds_generator])
world_coord_to_local(a)
world_mat_to_local(m)

DIM = DimOrder(X=2, Y=1, Z=0)

class SubvolumeBoundsGenerator(volume, shape, label_margin=None)

Bases: six.Iterator

Methods

next()
reset()

reset()

Volume.downsample(resolution)

Volume.get_subvolume(bounds)

Volume.local_coord_to_world(a)

Volume.mask_bounds

Volume.partition(partitioning, partition_index)

Volume.shape

Volume.sparse_wrapper(*args)

Volume.subvolume_bounds_generator(shape=None, label_margin=None)

Volume.subvolume_generator(bounds_generator=None, **kwargs)

Volume.world_coord_to_local(a)

Volume.world_mat_to_local(m)

class diluvian.volumes.VolumeView(parent, *args, **kwargs)

Bases: diluvian.volumes.Volume

Attributes

mask_bounds
shape

Methods

SubvolumeBoundsGenerator(volume, shape[, ...])	Methods
downsample(resolution)
get_subvolume(bounds)
local_coord_to_world(a)
local_to_parent(a)
parent_to_local(a)
partition(partitioning, partition_index)
sparse_wrapper(\*args)
subvolume_bounds_generator([shape, label_margin])
subvolume_generator([bounds_generator])
world_coord_to_local(a)
world_mat_to_local(m)

get_subvolume(bounds)

local_coord_to_world(a)

local_to_parent(a)

mask_bounds

parent_to_local(a)

shape

world_coord_to_local(a)

world_mat_to_local(m)

diluvian.volumes.partition_volumes(volumes, downsample=True)

Paritition volumes into training and validation based on configuration.

Uses the regexes mapping partition sizes and indices in diluvian.config.TrainingConfig by applying them to matching volumes based on name.

Parameters:

volumes : dict

Dictionary mapping volume name to diluvian.volumes.Volume.

downsample : bool, optional

Whether to downsample partitions automatically.

Returns:

training_volumes, validation_volumes : dict

Dictionary mapping volume name to partitioned, downsampled volumes.

Module contents