medpy.features.intensity.local_histogram

medpy.features.intensity.local_histogram(image, bins=19, rang='image', cutoffp=(0.0, 100.0), size=None, footprint=None, output=None, mode='ignore', origin=0, mask=slice(None, None, None))

Computes multi-dimensional histograms over a region around each voxel.

Supply an image and (optionally) a mask and get the local histogram of local neighbourhoods around each voxel. These neighbourhoods are cubic with a sidelength of size in voxels or, when a shape instead of an integer is passed to size, of this shape.

If not argument is passed to output, the returned array will be of dtype float.

Voxels along the image border are treated as defined by mode. The possible values are the same as for scipy.ndimage filter without the ‘’constant’’ mode. Instead “ignore” is the default and additional mode, which sets that the area outside of the image are ignored when computing the histogram.

When a mask is supplied, the local histogram is extracted only for the voxels where the mask is True. But voxels from outside the mask can be incorporated in the compuation of the histograms.

The range of the histograms can be set via the rang argument. The ‘image’ keyword can be supplied, to use the same range for all local histograms, extracted from the images max and min intensity values. Alternatively, an own range can be supplied in the form of a tuple of two numbers. Values outside the range of the histogram are ignored.

Setting a proper range is important, as all voxels that lie outside of the range are ignored i.e. do not contribute to the histograms as if they would not exists. Some of the local histograms can therefore be constructed from less than the expected number of voxels.

Taking the histogram range from the whole image is sensitive to outliers. Supplying percentile values to the cutoffp argument, these can be filtered out when computing the range. This keyword is ignored if rang is not set to ‘image’.

Setting the rang to None causes local ranges to be used i.e. the ranges of the histograms are computed only over the local area covered by them and are hence not comparable. This behaviour should normally not be taken.

The local histograms are normalized by dividing them through the number of elements in the bins.

Parameters:

imagearray_like or list/tuple of array_like

A single image or a list/tuple of images (for multi-spectral case).

binsinteger

The number of histogram bins.

rang‘image’ or tuple of numbers or None

The range of the histograms, can be supplied manually, set to ‘image’ to use global or set to None to use local ranges.

cutoffptuple of numbers

The cut-off percentiles to exclude outliers, only processed if rang is set to ‘image’.

sizescalar or tuple of integers

See footprint, below

footprintarray

Either size or footprint must be defined. size gives the shape that is taken from the input array, at every element position, to define the input to the filter function. footprint is a boolean array that specifies (implicitly) a shape, but also which of the elements within this shape will get passed to the filter function. Thus size=(n,m) is equivalent to footprint=np.ones((n,m)). We adjust size to the number of dimensions of the input array, so that, if the input array is shape (10,10,10), and size is 2, then the actual size used is (2,2,2).

output ndarray or dtype

The output parameter passes an array in which to store the filter output.

mode{‘reflect’, ‘ignore’, ‘nearest’, ‘mirror’, ‘wrap’}

The mode parameter determines how the array borders are handled. Default is ‘ignore’

originnumber

The origin parameter controls the placement of the filter. Default 0.

maskarray_like

A binary mask for the image.

Returns:

local_histogramndarray

The bin values of the local histograms for each voxel as a multi-dimensional image.