gentex package¶
Table of Contents
gentex.comat¶
The gentex or general texture analysis package provides a suite of routines that combine standard texture analysis methods and entropy/statistical complexity analysis methods to provide a number of the standard algorithms required for generating complexity/texture measure estimates from multimodal imaging data. These include:
Generation of multidimensional feature spaces from multimodal ‘image’ data (i.e. multiple ‘co-registered’ 1,2,3, or 4 dimensional data sets, e.g. multiple ‘co-registered’ time series, multimodal image data, space/time data..) via the use of a set of image templates, including:
single voxels
linear sequences in cardinal directions (ref.)
notches in cardinal directions (ref.)
light cones in cardinal directions and 45 degree angles (ref.)
Clustering methods for generating disrete (‘grey’) levels from the constructed feature space (the levels are then typically mapped to the original image space at the anchor points of the templates)
Building co-occurrence matrices from a discrete level ‘image’ or a pair of discrete level ‘images’, where the discrete level ‘images’ are typically generated via feature space clustering of the original multimodal data sets (time series, images, space/time data…)
Estimation of various complexity/texture measures from the co-occurrence matrices.
-
gentex.comat.
cmad
(images, masks, distance, angles, levels)¶ Uses the comat or comat_2T functions to generate co-occurence matrices at the specified anlge(s) and distance(s) provided, which is more in the spirit of the original Haralick papers on texture analysis. So far this only makes sense for 2 and 3 dimensions (well 4 might make sense but…)
- Parameters
- images: 1 or 2 element 1d python array of 1-4 dimensional ndarray(s)
of dtype int consisting of an input image(s).
- masks: 1 or 2 element 1d python array of 1-4 dimensional ndarray(s)
of dtype int consisting of an input mask(s).Determines which voxels to use for building co-occurence matrix
- distance: float
distance in image to use as offset for calculating co-occurrence matrix
- angles: float
1 or 2 element 1d python array of angle(s) to use for direction to voxel in calculating co-occurrence matrix. For 2D images the only angle, angles[0], corresponds to the standard angle from the x-axis in polar co-ordinates. For 3D images, angles[0] corresponds to the angle theta in spherical co-ordinates, i.e. the angle from the z-axis, and angles[1] corresponds to phi, i.e. the angle in the x-y plane.
- levelsint
1 or 2 element 1d python array with number of discrete levels in the image(s) (256 for an 8-bit image but any number of cluster values for general templated images)
- Returns
- 2D ndarray
The grey-level co-occurrence histogram. The value P[i,j] is the number of times that gray-level j occurs at the offset specified by distance and thetas, from gray-level i.
-
gentex.comat.
comat
(image, mask, coords, levels=255)¶ Calculates the co-occurrence histogram of an image given an offset.
- Parameters
- image: 1-4 dimensional ndarray of dtype int
Input image.
- mask: 1-4 dimensional ndarray of dtype int
Input mask (same size as image, 0,1 array) Determines which voxels to use for building co-occurence matrix
- coords1D ndarray
coordinate offset array with the appropriate number of dimensions (1-4) for building cooccurence matrix.
- levelsint
The input image should contain integers in [0, levels-1], where levels indicate the number of discrete image or grey levels counted (256 for an 8-bit image but any number of cluster values for general templated images)
- Returns
- 2D ndarray
The grey-level co-occurrence histogram. The value P[i,j] is the number of times that gray-level j occurs at offset coords from gray-level i.
-
gentex.comat.
comat_2T
(image1, mask1, image2, mask2, coords, levels1=255, levels2=255)¶ Calculate the co-occurrence histogram from 2 images given an offset.
- Parameters
- image1: 1-4 dimensional ndarray of dtype int
Input image 1.
- mask1: 1-4 dimensional ndarray of dtype int
Input mask 1 (same size as image, 0,1 array) Determines which voxels to use for building co-occurence matrix
- image2: 1-4 dimensional ndarray of dtype int
Input image 2.
- mask2: 1-4 dimensional ndarray of dtype int
Input mask 2 (same size as image, 0,1 array)
- coords1D ndarray
coordinate offset array with the appropriate number of dimensions (1-4) for building cooccurence matrix.
levels1 : int
- levels2int
The input images should contain integers in [0, levels(1,2)-1], where levels indicate the number of discrete image or grey levels counted (256 for an 8-bit image but any number of cluster values for general templated images)
- Returns
- 2D ndarray
The grey-level co-occurrence histogram. The value P[i,j] is the number of times that gray-level j occurs at offset coords from gray-level i.
-
gentex.comat.
comat_2T_mult
(image1, mask1, image2, mask2, coordset, levels1=255, levels2=255)¶ Generates and sums co-occurrence histograms from 2 images given a set of offsets.
- Parameters
- image1: 1-4 dimensional ndarray of dtype int
Input image 1.
- mask1: 1-4 dimensional ndarray of dtype int
Input mask 1 (same size as image, 0,1 array) Determines which voxels to use for building co-occurence matrix
- image2: 1-4 dimensional ndarray of dtype int
Input image 2.
- mask2: 1-4 dimensional ndarray of dtype int
Input mask 2 (same size as image, 0,1 array)
- coordset1D ndarray of coordinate offset sets
Array of coordinate offset arrays with the appropriate number of dimensions (1-4) for building cooccurence matrices.
levels1 : int
- levels2int
The input images should contain integers in [0, levels(1,2)-1], where levels indicate the number of discrete image or grey levels counted (256 for an 8-bit image but any number of cluster values for general templated images)
- Returns
- 2D ndarray
The grey-level co-occurrence histogram. The value P[i,j] is the number of times that gray-level j occurs at offset coords from gray-level i.
-
gentex.comat.
comat_mult
(image, mask, coordset, levels=255)¶ Generates and sums co-occurrence histograms of an image given a set of offsets.
- Parameters
- image: 1-4 dimensional ndarray of dtype int
Input image.
- mask: 1-4 dimensional ndarray of dtype int
Input mask (same size as image, 0,1 array) Determines which voxels to use for building co-occurence matrix
- coordset1D ndarray of coordinate offset sets
array of coordinate offset arrays with the appropriate number of dimensions (1-4) for building cooccurence matrices.
- levelsint
The input image should contain integers in [0, levels-1], where levels indicate the number of discrete image or grey levels counted (256 for an 8-bit image but any number of cluster values for general templated images)
- Returns
- 2D ndarray
The summed grey-level co-occurrence histogram. The value P[i,j] is the number of times that gray-level j occurs at offset coords from gray-level i summed over all offsets passed to comat_mult.
gentex.template¶
-
class
gentex.template.
Template
(type, sizes, dimension, inclusion, handedness=None, axbase=None, anchoff=None, shift=None)¶ Class template for generating lists of template voxels
- Parameters
- type: string
Required by constructor. The type of template currently available types are:
‘RectBox’ - rectangular box (1,2,3,4 dimensions) template origin is center of box
‘RectShell’ - shell of rectangular box (1,2,3,4 dimensions) template origin is center of shell
‘Ellipsoid’ - ellispoid (1,2,3,4 dimensions) template origin is center of ellipsoid
‘EllipsoidShell’ - ellipsoidal shell (1,2,3,4 dimensions) template origin is center of shell
‘Line’ - linear template template origin is first point of line
‘Notch’ - notch template template origin is point about which notch is built
‘Cone’ - cone template template origin is start of half cone
- sizes: 1D int array (can be empty)
Attributes of sizes required for constructing template
- dimension: int
Dimension of template
- inclusion: bool
Whether or not to include anchor point (i.e. [0], [0,0],…)
- handedness: 1D int array
If there are axial asymetries in the template (e.g. Notch) can pass in a vector with +1 for ‘right’ and -1 for ‘left’ (default is [1], or [1,1], or…)
- axbase: List of ints (each list of length = dimension)
Basis vector specifying axis, when appropriate, for direction of template (can be empty) - component lengths will be ignored; only whether the component is zero or nonzero, and the sign will be considered (i.e. only co-ordinate axes and ‘45 degree’ lines will be considered as template axes), so e.g:
[1,0] ~ [10,0] ~ x-axis in 2D [0,1,0] ~ [0,33,0] ~ y-axis in 3D [1,-1] ~ [30,-20] ~ [108,-1] ~ 135 degree axis in 2
if axbase is empty template will pick axes according to following conventions:
templates requiring single axis specification (e.g. line, notch, cone) will always use positivedirection of first dimension
templates requiring multiple axis specification, e.g. rectangular parallelipipeds and ellipsoids will choose:
largest dimension (e.g. semi-major axis) in positive direction of first dimension
next largest dimension (e.g. semi-minor axis) in positive direction of second dimension
etc.
- anchoff: list of ints
Offset of anchor point from template [0,0,0] in template (usually assume [0,0,0])
- shift: List of int
List of ints to use if you want to shift all points in offset array - useful, e.g. if you want to build cooccurence arrays from offset templates - build one template (set of offsets with no shift and another with an appropriate shift; those can each be passed to the feature space cluster algorithm, then those to the cooccurence matrix builder, and that to the texture measure generator.
gentex.texmeas¶
gentex.texmeas package
-
class
gentex.texmeas.
Texmeas
(comat, measure='Statistical Complexity', coordmom=0, probmom=0, rllen=0, clusmom=0, clusp=0.001, samelev=True, betas=[-20, 20, 40])¶ Class texmeas for generating texture measures from co-occurrence matrix
- Parameters
- comat: ndarray
Non-normalized co-occurrence matrix - chi-squared conditional distribution comparisons require the actual number of counts so don’t normalize this before sending in
- measure: string
Texture measure (default = ‘Statistical Complexity’). Choice of:
‘CM Entropy’
‘EM Entropy’
‘Statistical Complexity’
‘Energy Uniformity’
‘Maximum Probability’
‘Contrast’
‘Inverse Difference Moment’
‘Correlation’
‘Probability of Run Length’
‘Epsilon Machine Run Length’
‘Run Length Asymmetry’
‘Homogeneity’
‘Cluster Tendency’
‘Multifractal Spectrum Energy Range’
‘Multifractal Spectrum Entropy Range’
- coordmo: int
Moment of coordinate differences in co-occurrence matrix needed for calculating ‘Contrast’ and ‘Inverse Difference Moment’ (default=0)
- probmom: int
Moment of individual cooccurence probabilities needed for calculating ‘Contrast’ and ‘Inverse Difference Moment’ (default=0)
- rllen: int
Length of run length used for generating probability of a run length (the higher this probability the larger the constant patches on the scale used for generating the co-occurence matrix) or the epsilon machine run length (default=0)
- clusmom: int
Moment used for generating cooccurence cluster tendency (default=0)
- samelev: bool
Whether to treat the rows and columns in the cooccurence matrix as identical ‘states’ (the methods are very general so this needn’t be the case, e.g. different template shapes from different images with different quantization levels could be used to generate the cooccurence matrix which could be of arbitrary shape)
default = True assumes the cooccurrence matrix is square and the rows and columns correspond to the same ‘state’
- betas: array
An array of 3 values, the lower limit, the upper limit and the number of steps to use as the ‘inverse temperature’ range for estimating the multifractal spectrum from an epsilon machine - getting the range right for an ‘arbitrary’ epsilon machine is tricky and is expected to be reset over a number of trials before getting a full spectrum estimate. For details on the rationale and algorithm see:
K. Young and J. P. Crutchfield, ‘Fluctuation Spectroscopy’, Chaos, Solitons, and Fractals 4 (1993) 5-39.
- Attributes
- emclus: int
Number of clusters (‘states’) found when estimating an epsilon machine from the co-occurrence matrix.
- emest: bool
Whether or not an epsilon machine has been estimated yet
- emmat: float
The estimated epsilon machine as a standard Markov process transition matrix.
- condo: 2d-array
Co-occurrence matrix renormalized as a rowise matrix of conditional probabilites - built as part of epsilon machine estimation
- emclasses: list
List of which of the values in emclus each row in condo (and hence the cooccurence matrix) belongs to
- clusp: float
Chisquared p value to use for clustering epsilon machine rows
- val: float
Value of most recently calculated texture measure
- mfsspec: array
Array containing the multifractal spectral estimates obtained over the range of ‘inverse temperatures’ provided in betas
- currval: string
One of the listed measures method which constitutes the current value in val
Methods
calc_measure
(self[, measure, coordmom, …])Calculates the appropriate texture measure and puts the value in the class variable val and updates the class variable currval with the passed string
est_em
(self)Estimate an epsilon machine from a co-occurrence matrix with #rows = #cols, done implicitly whenever one of the related complexity/entropy measures (EM Entropy, Statistical Complexity, Epsilon Machine Run Length) are calculated.
est_multi_frac_spec
(self)TODO
-
calc_measure
(self, measure='Statistical Complexity', coordmom=0, probmom=0, rllen=0, clusmom=0, samelev=True)¶ Calculates the appropriate texture measure and puts the value in the class variable val and updates the class variable currval with the passed string
For a discussion of Haralick co-occurrence style texture measures see: R. M. Haralick, ‘Statistical and structural approaches to texture’. Proceedings of the IEEE May 1979, 67(5). 786-804.
- Parameters
- measure: string
One of the following measure methods (default = ‘Statistical Complexity’):
‘CM Entropy’
‘EM Entropy’
‘Statistical Complexity’
‘Energy Uniformity’
‘Maximum Probability’
‘Contrast’
‘Inverse Difference Moment’
‘Correlation’
‘Probability of Run Length’
‘Epsilon Machine Run Length’
‘Run Length Asymmetry’
‘Homogeneity’
‘Cluster Tendency’
‘Multifractal Spectrum Energy Range’
‘Multifractal Spectrum Entropy Range’
-
est_em
(self)¶ Estimate an epsilon machine from a co-occurrence matrix with #rows = #cols, done implicitly whenever one of the related complexity/entropy measures (EM Entropy, Statistical Complexity, Epsilon Machine Run Length) are calculated.
For info on epsilon machines and the related measures see:
Young, Y. Chen, J. Kornak, G. B. Matson, N. Schuff, ‘Summarizing complexity in high dimensions’, Phys Rev Lett. (2005) Mar 11;94(9):098701.
Shalizi and J. P. Crutchfield, ‘Computational Mechanics: Pattern and Prediction, Structure and Simplicity’, Journal of Statistical Physics 104 (2001) 819–881.
Young and J. P. Crutchfield, ‘Fluctuation Spectroscopy’, Chaos, Solitons, and Fractals 4 (1993) 5-39.
Crutchfield and K. Young, ‘Computation at the Onset of Chaos’, in Entropy, Complexity, and Physics of Information, W. Zurek, editor, SFI Studies in the Sciences of Complexity, VIII, Addison-Wesley, Reading, Massachusetts (1990) 223-269.
Shalizi and J. P. Crutchfield, ‘Computational Mechanics: Pattern and Prediction, Structure and Simplicity’, Journal of Statistical Physics 104 (2001) 819–881.
-
est_multi_frac_spec
(self)¶ TODO