PatchCreator(input_sources, patch_shape, target_sources=None, offset=(0, 0, 0), cube_prios=None, aniso_factor=2, target_discrete_ix=None, target_dtype=<class 'numpy.int64'>, train=True, warp_prob=False, warp_kwargs=None, epoch_size=100, transform=<elektronn3.data.transforms.transforms.Identity object>, in_memory=False, cube_meta=<elektronn3.data.cnndata._DefaultCubeMeta object>)¶
Dataset iterator class that creates 3D image patches from HDF5 files.
It implements the PyTorch
Datasetinterface and is meant to be used with a PyTorch
DataLoader(or the modified
elektronn3.training.trainer.train_utils.DelayedDataLoader, if it is used with
The main idea of this class is to automate input and target patch creation for training convnets for semantic image segmentation. Patches are sliced from random locations in the supplied HDF5 files (
target_h5data). Optionally, the source coordinates from which patches are sliced are obtained by random warping with affine or perspective transformations for efficient augmentation and avoiding border artifacts (see
warp_kwargs). Note that whereas other warping-based image augmentation systems usually warp images themselves, elektronn3 performs warping transformations on the coordinates from which image patches are sliced and obtains voxel values by interpolating between actual image voxels at the warped source locations (which are not confined to the original image’s discrete coordinate grid). (TODO: A visualization would be very helpful here to make this more clear) For more information about this warping mechanism see
Currently, only 3-dimensional image data sets are supported, but 2D support is also planned.
str]]) – Sequence of
(filename, hdf5_key)tuples, where each item specifies the filename and the HDF5 dataset key under which the input data is stored.
str]]]) – Sequence of
(filename, hdf5_key)tuples, where each item specifies the filename and the HDF5 dataset key under which the target data is stored.
int]) – Desired spatial shape of the samples that the iterator delivers by slicing from the data set files. Since this determines the size of input samples that are fed into the neural network, this is a very important value to tune. Making it too large can result in slow training and excessive memory consumption, but if it is too small, it can hinder the perceptive ability of the neural network because the samples it “sees” get too small to extract meaningful features. Adequate values for
patch_shapeare highly dependent on the data set (“How large are typical ROIs? How large does an image patch need to be so you can understand the input?”) and also depend on the neural network architecture to be used (If the effective receptive field of the network is small, larger patch sizes won’t help much).
int]) – Shape of the offset by which each the targets are cropped on each side. This needs to be set if the outputs of the network you train with are smaller than its inputs. For example, if the spatial shape of your inputs is
patch_shape=(48, 96, 96)the spatial shape of your outputs is
out_shape=(32, 56, 56), you should set
offset=(8, 20, 20), because
offset = (patch_shape - out_shape) / 2should always hold true.
float]]) – List of per-cube priorities, where a higher priority means that it is more likely that a sample comes from this cube.
int) – Depth-anisotropy factor of the data set. E.g. if your data set has half resolution in the depth dimension, set
aniso_factor=2. If all dimensions have the same resolution, set
int]]) – List of target channels that contain discrete values. By default (
None), every channel is is seen as discrete (this is generally the case for classification tasks). This information is used to decide what kind of interpolation should be used for reading target data: - discrete targets are obtained by nearest-neighbor interpolation - non-discrete (continuous) targets are linearly interpolated.
dtype) – dtype that target tensors should be cast to.
bool) – Determines if samples come from training or validation data. If
True, training data is returned. If
False, validation data is returned.
float]) – ratio of training samples that should be obtained using geometric warping augmentations.
Any]]) – kwargs that are passed through to
elektronn3.data.coord_transforms.get_warped_slice(). See the docs of this function for information on kwargs options. Can be empty.
int) – Determines the length (
__len__) of the
epoch_sizecan be set to an arbitrary value and doesn’t have any effect on the content of produced training samples. It is recommended to set it to a suitable value for one “training phase”, so after each
epoch_sizebatches, validation/logging/plotting are performed by the training loop that uses this data set (e.g.
Callable) – Transformation function to be applied to
(inp, target)samples (for normalization, data augmentation etc.). The signature is always
inp, target = transform(inp, target), where
numpy.ndarray``s. In some transforms ``targetcan also be set to
None. In this case it is ignored and only
inpis processed. To combine multiple transforms, use
elektronn3.data.transforms. for some implementations.
bool) – If
True, all data set files are immediately loaded into host memory and are permanently kept there as numpy arrays. If this is disabled (default), file contents are always read from the HDF5 files to produce samples. (Note: This does not mean it’s slower, because file contents are transparently cached by h5py, see http://docs.h5py.org/en/latest/high/file.html#chunk-cache).
Check if all files are accessible.
- Return type
- Return type
warp_cut(inp_src, target_src, warp_prob, warp_kwargs)¶
Cuts a warped slice out of the input and target arrays. The same random warping transformation is each applied to both input and target.
Warping is randomly applied with the probability defined by the
warp_probparameter (see below).
inp_src (h5py.Dataset) – Input image source (in HDF5)
target_src (h5py.Dataset) – Target image source (in HDF5)
warp_prob (float or bool) – False/True disable/enable warping completely. If
warp_probis a float, it is used as the ratio of inputs that should be warped. E.g. 0.5 means approx. every second call to this function actually applies warping to the image-target pair.
warp_kwargs (dict) – kwargs that are passed through to
elektronn2.data.coord_transforms.get_warped_slice(). Can be empty.
- Return type
inp (np.ndarray) – (Warped) input image slice
target_src (np.ndarray) – (Warped) target slice
- Return type
Reconstruction2d(*args: Any, **kwargs: Any)¶
Simple dataset for 2d reconstruction for auto-encoders etc..
Segmentation2d(*args: Any, **kwargs: Any)¶
Simple dataset for 2d segmentation.
Expects a list of
target_paths[i]is the target of
input_paths[i]for all i.
SimpleNeuroData2d(inp_path=None, target_path=None, train=True, inp_key='raw', target_key='lab', pool=(1, 1, 1), transform=<elektronn3.data.transforms.transforms.Identity object>, out_channels=None)¶
2D Dataset class for neuro_data_cdhw, reading from a single HDF5 file.
Delivers 2D image slices from the (H, W) plane at given D indices. Not scalable, keeps everything in memory. This is just a minimalistic proof of concept.